CFNumber Reference

Derived from	CFPropertyList : CFType
Framework	CoreFoundation/CoreFoundation.h
Companion guide	Property List Programming Topics for Core Foundation
Declared in	CFNumber.h

Overview

CFNumber encapsulates C scalar (numeric) types. It provides functions for setting and accessing the value as any basic C type. It also provides a compare function to determine the ordering of two CFNumber objects. CFNumber objects are used to wrap numerical values for use in Core Foundation property lists and collections.

CFNumber objects are not intended as a replacement for C scalar values and should not be used in APIs or implementations where scalar values are more appropriate and efficient.

CFNumber is “toll-free bridged” with its Cocoa Foundation counterpart, NSNumber. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. Therefore, in a method where you see an NSNumber * parameter, you can pass in a CFNumberRef, and in a function where you see a CFNumberRef parameter, you can pass in an NSNumber instance. This fact also applies to concrete subclasses of NSNumber. See “Toll-Free Bridged Types” for more information on toll-free bridging.

Functions by Task

Creating a Number

Getting Information About Numbers

Comparing Numbers

Getting the CFNumber Type ID

Functions

CFNumberCompare

Compares two CFNumber objects and returns a comparison result.

CFComparisonResult CFNumberCompare (
   CFNumberRef number,
   CFNumberRef otherNumber,
   void *context
);

Parameters

number: The first CFNumber object to compare.
otherNumber: The second CFNumber object to compare.
context: Pass NULL.

Return Value

A CFComparisonResult constant that indicates whether number is equal to, less than, or greater than otherNumber.

Discussion

When comparing two CFNumber objects using this function, one or both objects can represent a special-case number such as signed 0, signed infinity, or NaN.

The following rules apply:

Negative 0 compares less than positive 0.
Positive infinity compares greater than everything except itself, to which it compares equal.
Negative infinity compares less than everything except itself, to which it compares equal.
If both numbers are NaN, then they compare equal.
If only one of the numbers is NaN, then the NaN compares greater than the other number if it is negative, and smaller than the other number if it is positive.

Availability

Available in iOS 2.0 and later.

Related Sample Code

Core Audio Utility Classes

Declared In

CFNumber.h

CFNumberCreate

Creates a CFNumber object using a specified value.

CFNumberRef CFNumberCreate (
   CFAllocatorRef allocator,
   CFNumberType theType,
   const void *valuePtr
);

Parameters

allocator: The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the default allocator.
theType: A constant that specifies the data type of the value to convert. See Number Types for a list of possible values.
valuePtr: A pointer to the value for the returned number object.

Return Value

A new number with the value specified by valuePtr. Ownership follows the Create Rule.

Discussion

The theType parameter is not necessarily preserved when creating a new CFNumber object. The CFNumber object will be created using whatever internal storage type the creation function deems appropriate. Use the function CFNumberGetType to find out what type the CFNumber object used to store your value.

Availability

Available in iOS 2.0 and later.

Related Sample Code

Declared In

CFNumber.h

CFNumberGetByteSize

Returns the number of bytes used by a CFNumber object to store its value.

CFIndex CFNumberGetByteSize (
   CFNumberRef number
);

Parameters

number: The CFNumber object to examine.

Return Value

The size in bytes of the value contained in number.

Discussion

Because a CFNumber object might store a value using a type different from that of the original value with which it was created, this function may return a size different from the size of the original value's type.

Availability

Available in iOS 2.0 and later.

Declared In

CFNumber.h

CFNumberGetType

Returns the type used by a CFNumber object to store its value.

CFNumberType CFNumberGetType (
   CFNumberRef number
);

Parameters

number: The CFNumber object to examine.

Return Value

A constant that indicates the data type of the value contained in number. See Number Types for a list of possible values.

Discussion

The type specified in the call to CFNumberCreate is not necessarily preserved when a new CFNumber object is created—it uses whatever internal storage type the creation function deems appropriate.

Availability

Available in iOS 2.0 and later.

Declared In

CFNumber.h

CFNumberGetTypeID

Returns the type identifier for the CFNumber opaque type.

CFTypeID CFNumberGetTypeID (
   void
);

Return Value

The type identifier for the CFNumber opaque type.

Availability

Available in iOS 2.0 and later.

Related Sample Code

Core Audio Utility Classes

Declared In

CFNumber.h

CFNumberGetValue

Obtains the value of a CFNumber object cast to a specified type.

Boolean CFNumberGetValue (
   CFNumberRef number,
   CFNumberType theType,
   void *valuePtr
);

Parameters

number: The CFNumber object to examine.
theType: A constant that specifies the data type to return. See Number Types for a list of possible values.
valuePtr: On return, contains the value of number.

Return Value

true if the operation was successful, otherwise false.

Discussion

If the argument type differs from the return type, and the conversion is lossy or the return value is out of range, then this function passes back an approximate value in valuePtr and returns false.

Availability

Available in iOS 2.0 and later.

Related Sample Code

Declared In

CFNumber.h

CFNumberIsFloatType

Determines whether a CFNumber object contains a value stored as one of the defined floating point types.

Boolean CFNumberIsFloatType (
   CFNumberRef number
);

Parameters

number: The CFNumber object to examine.

Return Value

true if number's value is one of the defined floating point types, otherwise false. The valid floating point types are listed in Number Types.

Availability

Available in iOS 2.0 and later.

Declared In

CFNumber.h

Data Types

CFNumberRef

A reference to a CFNumber object.

typedef const struct __CFNumber *CFNumberRef;

Availability

Available in iOS 2.0 and later.

Declared In

CFNumber.h

Constants

Number Types

Flags used by CFNumber to indicate the data type of a value.

enum CFNumberType {
   kCFNumberSInt8Type = 1,
   kCFNumberSInt16Type = 2,
   kCFNumberSInt32Type = 3,
   kCFNumberSInt64Type = 4,
   kCFNumberFloat32Type = 5,
   kCFNumberFloat64Type = 6,
   kCFNumberCharType = 7,
   kCFNumberShortType = 8,
   kCFNumberIntType = 9,
   kCFNumberLongType = 10,
   kCFNumberLongLongType = 11,
   kCFNumberFloatType = 12,
   kCFNumberDoubleType = 13,
   kCFNumberCFIndexType = 14,
   kCFNumberNSIntegerType = 15,
   kCFNumberCGFloatType = 16,
   kCFNumberMaxType = 16
};
typedef enum CFNumberType CFNumberType;

Constants

kCFNumberSInt8Type

Eight-bit, signed integer. The SInt8 data type is defined in MacTypes.h.

Available in iOS 2.0 and later.

Declared in CFNumber.h.

kCFNumberSInt16Type

Sixteen-bit, signed integer. The SInt16 data type is defined in MacTypes.h.

Available in iOS 2.0 and later.

Declared in CFNumber.h.

kCFNumberSInt32Type

Thirty-two-bit, signed integer. The SInt32 data type is defined in MacTypes.h.

Available in iOS 2.0 and later.

Declared in CFNumber.h.

kCFNumberSInt64Type

Sixty-four-bit, signed integer. The SInt64 data type is defined in MacTypes.h.

Available in iOS 2.0 and later.

Declared in CFNumber.h.

kCFNumberFloat32Type

Thirty-two-bit real. The Float32 data type is defined in MacTypes.h.

Available in iOS 2.0 and later.

Declared in CFNumber.h.

kCFNumberFloat64Type

Sixty-four-bit real. The Float64 data type is defined in MacTypes.h and conforms to the 64-bit IEEE 754 standard.

Available in iOS 2.0 and later.

Declared in CFNumber.h.

kCFNumberCharType

Basic C char type.

Available in iOS 2.0 and later.

Declared in CFNumber.h.

kCFNumberShortType

Basic C short type.

Available in iOS 2.0 and later.

Declared in CFNumber.h.

kCFNumberIntType

Basic C int type.

Available in iOS 2.0 and later.

Declared in CFNumber.h.

kCFNumberLongType

Basic C long type.

Available in iOS 2.0 and later.

Declared in CFNumber.h.

kCFNumberLongLongType

Basic C long long type.

Available in iOS 2.0 and later.

Declared in CFNumber.h.

kCFNumberFloatType

Basic C float type.

Available in iOS 2.0 and later.

Declared in CFNumber.h.

kCFNumberDoubleType

Basic C double type.

Available in iOS 2.0 and later.

Declared in CFNumber.h.

kCFNumberCFIndexType

CFIndex value.

Available in iOS 2.0 and later.

Declared in CFNumber.h.

kCFNumberNSIntegerType

NSInteger value.

Available in iOS 2.0 and later.

Declared in CFNumber.h.

kCFNumberCGFloatType

CGFloat value.

Available in iOS 2.0 and later.

Declared in CFNumber.h.

kCFNumberMaxType

Same as kCFNumberCGFloatType.

Note that on OS X v10.4, kCFNumberMaxType was the same as kCFNumberCFIndexType .

Available in iOS 2.0 and later.

Declared in CFNumber.h.

Discussion

The type specified in the call to CFNumberCreate is not necessarily preserved when creating a new CFNumber object. A CFNumber object uses whatever internal storage type the creation function deems appropriate. Use the CFNumberGetType function to find out what type the CFNumber object used to store your value.

Predefined Values

CFNumber provides some predefined number values.

const CFNumberRef kCFNumberNaN;
const CFNumberRef kCFNumberNegativeInfinity;
const CFNumberRef kCFNumberPositiveInfinity;

Constants

kCFNumberNaN

“Not a Number.” This value is often the result of an invalid operation, such as the square-root of a negative number.

Available in iOS 2.0 and later.

Declared in CFNumber.h.

kCFNumberNegativeInfinity

Designates a negative infinity value.

Available in iOS 2.0 and later.

Declared in CFNumber.h.

kCFNumberPositiveInfinity

Designates a positive infinity value.

Available in iOS 2.0 and later.

Declared in CFNumber.h.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.