Fetches a range of the characters from a string into a byte buffer after converting the characters to a specified encoding.


CFIndex CFStringGetBytes(CFStringRef theString, CFRange range, CFStringEncoding encoding, UInt8 lossByte, Boolean isExternalRepresentation, UInt8 *buffer, CFIndex maxBufLen, CFIndex *usedBufLen);



The string upon which to operate.


The range of characters in theString to process. The specified range must not exceed the length of the string.


The string encoding of the characters to copy to the byte buffer. 8, 16, and 32-bit encodings are supported.


A character (for example, '?') that should be substituted for characters that cannot be converted to the specified encoding. Pass 0 if you do not want lossy conversion to occur.


true if you want the result to be in an “external representation” format, otherwise false. In an “external representation” format, the result may contain a byte order marker (BOM) specifying endianness and this function might have to perform byte swapping.


The byte buffer into which the converted characters are written. The buffer can be allocated on the heap or stack. Pass NULL if you do not want conversion to take place but instead want to know if conversion will succeed (the function result is greater than 0) and, if so, how many bytes are required (usedBufLen).


The size of buffer and the maximum number of bytes that can be written to it.


On return, the number of converted bytes actually in buffer. You may pass NULL if you are not interested in this information.

Return Value

The number of characters converted.


This function is the basic encoding-conversion function for CFString objects. As with the other functions that get the character contents of CFString objects, it allows conversion to a supported 8-bit encoding. Unlike most of those other functions, it also allows “lossy conversion.” The function permits the specification of a “loss byte” in a parameter; if a character cannot be converted this character is substituted and conversion proceeds. (With the other functions, conversion stops at the first error and the operation fails.)

Because this function takes a range and returns the number of characters converted, it can be called repeatedly with a small fixed size buffer and different ranges of the string to do the conversion incrementally.

This function also handles any necessary manipulation of character data in an “external representation” format. This format makes the data portable and persistent (disk-writable); in Unicode it often includes a BOM (byte order marker) that specifies the endianness of the data.

The CFStringCreateExternalRepresentation function also handles external representations and performs lossy conversions. The complementary function CFStringCreateWithBytes creates a string from the characters in a byte buffer.

See Also

Accessing Characters


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


Returns the Unicode character at a specified location in a string.


Copies a range of the Unicode characters from a string to a user-provided buffer.


Quickly obtains a pointer to the contents of a string as a buffer of Unicode characters.


Returns the Unicode character at a specific location in an in-line buffer.


Copies the character contents of a string to a local C string buffer after converting the characters to a given encoding.


Quickly obtains a pointer to a C-string buffer containing the characters of a string in a given encoding.


Returns the number (in terms of UTF-16 code pairs) of Unicode characters in a string.


Copies the character contents of a CFString object to a local Pascal string buffer after converting the characters to a requested encoding.


Quickly obtains a pointer to a Pascal buffer containing the characters of a string in a given encoding.


Returns the range of the composed character sequence at a specified index.


Initializes an in-line buffer to use for efficient access of a CFString object's characters.