Handling External Representations of Strings

When you want the character data represented by a CFString object to persist, either as a file on disk or as data sent over a network, you should first convert the CFString object to a CFData object using the function CFStringCreateExternalRepresentation . The CFData object is called an "external representation" of the CFString object; if the encoding is Unicode, the function automatically inserts a BOM (byte order marker) in the data to specify endianness. You can convert an external-representation CFData object back to a CFString object with the CFStringCreateFromExternalRepresentation function.

Listing 14 shows how the external-representation functions might be used. The last parameter of the CFStringCreateExternalRepresentation function specifies a loss byte , the value to be assigned to characters that cannot be converted to the specified encoding. If the loss byte is zero (as in the example below) and conversion errors occur, the result of the function is NULL . This feature is similar to that provided by the CFStringGetBytes function; however the CFStringCreateExternalRepresentation function is more convenient since it gives you a CFData object.

Listing 14 Using the external-representation functions
CFDataRef appendTimeToLog(CFDataRef log) { CFMutableStringRef mstr; CFStringRef str; CFDataRef newLog; CFGregorianDate date = CFAbsoluteTimeGetGregorianDate(CFAbsoluteTimeGetCurrent(), CFTimeZoneCopySystem()); str = CFStringCreateFromExternalRepresentation(NULL, log, CFStringGetSystemEncoding()); CFShow(str); mstr = CFStringCreateMutableCopy(NULL, 0, str); CFStringAppendFormat(mstr, NULL, CFSTR("Received at %d/%d/%d %.2d:%.2d:%2.0f\n"), date.month, date.day, date.year, date.hour, date.minute, date.second); CFShow(mstr); newLog = CFStringCreateExternalRepresentation(NULL, mstr, CFStringGetSystemEncoding(), '?'); CFRelease(str); CFRelease(mstr); CFShow(newLog); return newLog; }

This code generates output similar to the following snippet:

 Master Log 
  
 Master Log 
  
 Received at 7/20/1999 19:23:16 
  
 <CFData 0x103c0 [0x69bce158]>{length = 43, capacity = 43, bytes = 0x4d6173746572204c6f670a0a52656365 ... 393a32333a31360a} 

As the example shows, the CFString object in its external representation is immutable, regardless of its mutability status before being stored as a CFData object. If you want to modify the CFString object returned from CFStringCreateFromExternalRepresentation , you need to make a mutable copy of it.

Instead of using the CFStringCreateFromExternalRepresentation function to create a CFString object and then access the characters in the object, you can use CFData functions to get at the characters directly. Listing 4 shows how this is done using the CFData functions CFDataGetLength and CFDataGetBytePtr functions.


© 1999 Apple Computer, Inc. – (Last Updated 07 September 99)