CFStringCreateExternalRepresentation

Header: CFString.h Carbon status: Supported

Creates an "external representation" of a CFString object, that is, a CFData object.

CFDataRef CFStringCreateExternalRepresentation (
    CFAllocatorRef alloc, 
    CFStringRef theString, 
    CFStringEncoding encoding, 
    UInt8 lossByte
);
Parameter descriptions
alloc

Pass a reference to an allocator object or pass NULL to request the default allocator.

theString

Pass a reference to the CFString object used to create the CFData object.

encoding

Pass a constant that specifies the encoding of the characters in the NSData object.

lossByte

Pass the character value to be assigned to characters that cannot be converted to the requested encoding. Pass zero if you want conversion to stop at the first such error; if this happens, the result of the function is NULL.

function result

A reference to a CFData object that stores the characters of the CFString as an "external representation." The result is NULL if no loss byte was specified and the function could not convert the characters to the specified encoding.

DISCUSSION

The CFStringCreateExternalRepresentation function creates an "external representation" of a CFString object. In this form (and contained in a CFData object), the character data can be written to disk as a file or be sent out over a network. If the encoding of the characters in the data object is Unicode, the function inserts a BOM (byte order marker) to indicate endianness. The function allows the specification of a "loss byte" to represent characters that cannot be converted to the requested encoding.

When you create an external representation from a mutable CFString object, it loses this mutability characteristic when it is converted back to a CFString object.

The CFStringCreateFromExternalRepresentation function complements this function by creating a CFString object from an "external representation" CFData object.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later.


© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)