Fetches a range of the characters from a string into a byte buffer after converting the characters to a specified encoding.
- iOS 2.0+
- macOS 10.0+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 2.0+
- Core Foundation
The string upon which to operate.
The range of characters in
theto 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
0if you do not want lossy conversion to occur.
trueif 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
NULLif 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 (
The size of
bufferand the maximum number of bytes that can be written to it.
On return, the number of converted bytes actually in
buffer. You may pass
NULLif you are not interested in this information.
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.
CFString function also handles external representations and performs lossy conversions. The complementary function
CFString creates a string from the characters in a byte buffer.