Concepts in Objective-C Programming

Toll-Free Bridging

There are a number of data types in the Core Foundation framework and the Foundation framework that can be used interchangeably. This capability, called toll-free bridging, means that you can use the same data type as the parameter to a Core Foundation function call or as the receiver of an Objective-C message. For example, NSLocale (see NSLocale Class Reference) is interchangeable with its Core Foundation counterpart, CFLocale (see CFLocale Reference). Therefore, in a method where you see an NSLocale * parameter, you can pass a CFLocaleRef, and in a function where you see a CFLocaleRef parameter, you can pass an NSLocale instance. You cast one type to the other to suppress compiler warnings, as illustrated in the following example.

Note from the example that the memory management functions and methods are also interchangeable—you can use CFRelease with a Cocoa object and release and autorelease with a Core Foundation object.

Note: When using garbage collection, there are important differences to how memory management works for Cocoa objects and Core Foundation objects. See Using Core Foundation with Garbage Collection for details.

Toll-free bridging has been available since OS X v10.0. Table 13-1 provides a list of the data types that are interchangeable between Core Foundation and Foundation. For each pair, the table also lists the version of OS X in which toll-free bridging between them became available.

Table 13-1 Data types that can be used interchangeably between Core Foundation and Foundation

Core Foundation type

Foundation class

Availability

CFArrayRef

NSArray

OS X v10.0

CFAttributedStringRef

NSAttributedString

OS X v10.4

CFCalendarRef

NSCalendar

OS X v10.4

CFCharacterSetRef

NSCharacterSet

OS X v10.0

CFDataRef

NSData

OS X v10.0

CFDateRef

NSDate

OS X v10.0

CFDictionaryRef

NSDictionary

OS X v10.0

CFErrorRef

NSError

OS X v10.5

CFLocaleRef

NSLocale

OS X v10.4

CFMutableArrayRef

NSMutableArray

OS X v10.0

CFMutableAttributedStringRef

NSMutableAttributedString

OS X v10.4

CFMutableCharacterSetRef

NSMutableCharacterSet

OS X v10.0

CFMutableDataRef

NSMutableData

OS X v10.0

CFMutableDictionaryRef

NSMutableDictionary

OS X v10.0

CFMutableSetRef

NSMutableSet

OS X v10.0

CFMutableStringRef

NSMutableString

OS X v10.0

CFNumberRef

NSNumber

OS X v10.0

CFReadStreamRef

NSInputStream

OS X v10.0

CFRunLoopTimerRef

NSTimer

OS X v10.0

CFSetRef

NSSet

OS X v10.0

CFStringRef

NSString

OS X v10.0

CFTimeZoneRef

NSTimeZone

OS X v10.0

CFURLRef

NSURL

OS X v10.0

CFWriteStreamRef

NSOutputStream

OS X v10.0

Note: Not all data types are toll-free bridged, even though their names might suggest that they are. For example, NSRunLoop is not toll-free bridged to CFRunLoop, NSBundle is not toll-free bridged to CFBundle, and NSDateFormatter is not toll-free bridged to CFDateFormatter.