CFString

Overview

CFString provides a suite of efficient string-manipulation and string-conversion functions. It offers seamless Unicode support and facilitates the sharing of data between Cocoa and C-based programs. CFString objects are immutable—use CFMutable​String to create and manage a string that can be changed after it has been created.

CFString has two primitive functions, CFString​Get​Length(_:​) and CFString​Get​Character​At​Index(_:​_:​), that provide the basis for all other functions in its interface. The CFString​Get​Length function returns the total number (in terms of UTF-16 code pairs) of characters in the string. The CFString​Get​Character​At​Index function gives access to each character in the string by index, with index values starting at 0.

CFString provides functions for finding and comparing strings. It also provides functions for reading numeric values from strings, for combining strings in various ways, and for converting a string to different forms (such as encoding and case changes). A number of functions, for example CFString​Find​With​Options, allow you to specify a range over which to operate within a string. The specified range must not exceed the length of the string. Debugging options may help you to catch any errors that arise if a range does exceed a string’s length.

Like other Core Foundation types, you can hash CFStrings using the CFHash(_:​) function. You should never, though, store a hash value outside of your application and expect it to be useful if you read it back in later (hash values may change between different releases of the operating system).

CFString is “toll-free bridged” with its Cocoa Foundation counterpart, NSString. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. Therefore, in a method where you see an NSString * parameter, you can pass in a CFString​Ref, and in a function where you see a CFString​Ref parameter, you can pass in an NSString instance. This also applies to concrete subclasses of NSString. See Toll-Free Bridged Types for more information on toll-free bridging.

Symbols

Creating a CFString

func CFString​Create​Array​By​Separating​Strings(CFAllocator!, CFString!, CFString!)

Creates an array of CFString objects from a single CFString object.

func CFString​Create​By​Combining​Strings(CFAllocator!, CFArray!, CFString!)

Creates a single string from the individual CFString objects that comprise the elements of an array.

func CFString​Create​Copy(CFAllocator!, CFString!)

Creates an immutable copy of a string.

func CFString​Create​With​Bytes(CFAllocator!, Unsafe​Pointer<UInt8>!, CFIndex, CFString​Encoding, Bool)

Creates a string from a buffer containing characters in a specified encoding.

func CFString​Create​With​Bytes​No​Copy(CFAllocator!, Unsafe​Pointer<UInt8>!, CFIndex, CFString​Encoding, Bool, CFAllocator!)

Creates a string from a buffer, containing characters in a specified encoding, that might serve as the backing store for the new string.

func CFString​Create​With​Characters​No​Copy(CFAllocator!, Unsafe​Pointer<Uni​Char>!, CFIndex, CFAllocator!)

Creates a string from a buffer of Unicode characters that might serve as the backing store for the object.

func CFString​Create​With​CString​No​Copy(CFAllocator!, Unsafe​Pointer<Int8>!, CFString​Encoding, CFAllocator!)

Creates a CFString object from an external C string buffer that might serve as the backing store for the object.

func CFString​Create​With​Format​And​Arguments(CFAllocator!, CFDictionary!, CFString!, CVa​List​Pointer)

Creates an immutable string from a formatted string and a variable number of arguments (specified in a parameter of type va_list).

func CFString​Create​With​Pascal​String​No​Copy(CFAllocator!, Const​Str255Param!, CFString​Encoding, CFAllocator!)

Creates a CFString object from an external Pascal string buffer that might serve as the backing store for the object.

func CFString​Create​With​Substring(CFAllocator!, CFString!, CFRange)

Creates an immutable string from a segment (substring) of an existing string.

Searching Strings

func CFString​Create​Array​With​Find​Results(CFAllocator!, CFString!, CFString!, CFRange, CFString​Compare​Flags)

Searches a string for multiple occurrences of a substring and creates an array of ranges identifying the locations of these substrings within the target string.

func CFString​Find(CFString!, CFString!, CFString​Compare​Flags)

Searches for a substring within a string and, if it is found, yields the range of the substring within the object's characters.

func CFString​Find​With​Options(CFString!, CFString!, CFRange, CFString​Compare​Flags, Unsafe​Mutable​Pointer<CFRange>!)

Searches for a substring within a range of the characters represented by a string and, if the substring is found, returns its range within the object's characters.

func CFString​Get​Line​Bounds(CFString!, CFRange, Unsafe​Mutable​Pointer<CFIndex>!, Unsafe​Mutable​Pointer<CFIndex>!, Unsafe​Mutable​Pointer<CFIndex>!)

Given a range of characters in a string, obtains the line bounds—that is, the indexes of the first character and the final characters of the lines containing the range.

Comparing Strings

func CFString​Compare​With​Options(CFString!, CFString!, CFRange, CFString​Compare​Flags)

Compares a range of the characters in one string with that of another string.

func CFString​Compare​With​Options​And​Locale(CFString!, CFString!, CFRange, CFString​Compare​Flags, CFLocale!)

Compares a range of the characters in one string with another string using a given locale.

func CFString​Has​Prefix(CFString!, CFString!)

Determines if the character data of a string begin with a specified sequence of characters.

func CFString​Has​Suffix(CFString!, CFString!)

Determines if a string ends with a specified sequence of characters.

Accessing Characters

func CFString​Create​External​Representation(CFAllocator!, CFString!, CFString​Encoding, UInt8)

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

func CFString​Get​Bytes(CFString!, CFRange, CFString​Encoding, UInt8, Bool, Unsafe​Mutable​Pointer<UInt8>!, CFIndex, Unsafe​Mutable​Pointer<CFIndex>!)

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

func CFString​Get​Character​At​Index(CFString!, CFIndex)

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

func CFString​Get​Characters(CFString!, CFRange, Unsafe​Mutable​Pointer<Uni​Char>!)

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

func CFString​Get​Characters​Ptr(CFString!)

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

func CFString​Get​CString(CFString!, Unsafe​Mutable​Pointer<Int8>!, CFIndex, CFString​Encoding)

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

func CFString​Get​CString​Ptr(CFString!, CFString​Encoding)

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

func CFString​Get​Length(CFString!)

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

func CFString​Get​Pascal​String(CFString!, String​Ptr!, CFIndex, CFString​Encoding)

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

func CFString​Get​Pascal​String​Ptr(CFString!, CFString​Encoding)

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

func CFString​Get​Range​Of​Composed​Characters​At​Index(CFString!, CFIndex)

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

func CFString​Init​Inline​Buffer(CFString!, Unsafe​Mutable​Pointer<CFString​Inline​Buffer>!, CFRange)

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

Working With Hyphenation

func CFString​Is​Hyphenation​Available​For​Locale(CFLocale!)

Returns a Boolean value that indicates whether hyphenation data is available.

Working With Encodings

func CFString​Convert​Encoding​To​IANAChar​Set​Name(CFString​Encoding)

Returns the name of the IANA registry “charset” that is the closest mapping to a specified string encoding.

func CFString​Convert​Encoding​To​NSString​Encoding(CFString​Encoding)

Returns the Cocoa encoding constant that maps most closely to a given Core Foundation encoding constant.

func CFString​Convert​Encoding​To​Windows​Codepage(CFString​Encoding)

Returns the Windows codepage identifier that maps most closely to a given Core Foundation encoding constant.

func CFString​Convert​IANAChar​Set​Name​To​Encoding(CFString!)

Returns the Core Foundation encoding constant that is the closest mapping to a given IANA registry “charset” name.

func CFString​Convert​NSString​Encoding​To​Encoding(UInt)

Returns the Core Foundation encoding constant that is the closest mapping to a given Cocoa encoding.

func CFString​Convert​Windows​Codepage​To​Encoding(UInt32)

Returns the Core Foundation encoding constant that is the closest mapping to a given Windows codepage identifier.

func CFString​Get​Fastest​Encoding(CFString!)

Returns for a CFString object the character encoding that requires the least conversion time.

func CFString​Get​List​Of​Available​Encodings()

Returns a pointer to a list of string encodings supported by the current system.

func CFString​Get​Maximum​Size​For​Encoding(CFIndex, CFString​Encoding)

Returns the maximum number of bytes a string of a specified length (in Unicode characters) will take up if encoded in a specified encoding.

func CFString​Get​Most​Compatible​Mac​String​Encoding(CFString​Encoding)

Returns the most compatible Mac OS script value for the given input encoding.

func CFString​Get​Name​Of​Encoding(CFString​Encoding)

Returns the canonical name of a specified string encoding.

func CFString​Get​Smallest​Encoding(CFString!)

Returns the smallest encoding on the current system for the character contents of a string.

func CFString​Get​System​Encoding()

Returns the default encoding used by the operating system when it creates strings.

func CFString​Is​Encoding​Available(CFString​Encoding)

Determines whether a given Core Foundation string encoding is available on the current system.

Getting Numeric Values

func CFString​Get​Double​Value(CFString!)

Returns the primary double value represented by a string.

func CFString​Get​Int​Value(CFString!)

Returns the integer value represented by a string.

Getting String Properties

func CFShow​Str(CFString!)

Prints the attributes of a string during debugging.

func CFString​Get​Type​ID()

Returns the type identifier for the CFString opaque type.

String File System Representations

func CFString​Create​With​File​System​Representation(CFAllocator!, Unsafe​Pointer<Int8>!)

Creates a CFString from a zero-terminated POSIX file system representation.

func CFString​Get​File​System​Representation(CFString!, Unsafe​Mutable​Pointer<Int8>!, CFIndex)

Extracts the contents of a string as a NULL-terminated 8-bit string appropriate for passing to POSIX APIs.

func CFString​Get​Maximum​Size​Of​File​System​Representation(CFString!)

Determines the upper bound on the number of bytes required to hold the file system representation of the string.

Getting Paragraph Bounds

func CFString​Get​Paragraph​Bounds(CFString!, CFRange, Unsafe​Mutable​Pointer<CFIndex>!, Unsafe​Mutable​Pointer<CFIndex>!, Unsafe​Mutable​Pointer<CFIndex>!)

Given a range of characters in a string, obtains the paragraph bounds—that is, the indexes of the first character and the final characters of the paragraph(s) containing the range.

Managing Surrogates

func CFString​Get​Long​Character​For​Surrogate​Pair(Uni​Char, Uni​Char)

Returns a UTF-32 character that corresponds to a given pair of UTF-16 surrogate characters.

func CFString​Is​Surrogate​High​Character(Uni​Char)

Returns a Boolean value that indicates whether a given character is a high character in a surrogate pair.

func CFString​Is​Surrogate​Low​Character(Uni​Char)

Returns a Boolean value that indicates whether a given character is a low character in a surrogate pair.

Data Types

CFString​Encoding

An integer type for constants used to specify supported string encodings in various CFString functions.

CFString​Encodings

Index type for constants used to specify external string encodings.

CFString​Compare​Flags

A CFOption​Flags type for specifying options for string comparison .

CFString​Inline​Buffer

Defines the buffer and related fields used for in-line buffer access of characters in CFString objects.

CFString

A reference to a CFString object.

Constants

String Comparison Flags

Flags that specify how string comparisons are performed.

CFString​Built​In​Encodings

Encodings that are built-in on all platforms on which macOS runs.

Invalid String Encoding Flag

Special value returned from functions to indicate a string encoding that is not supported or recognized by CFString.

External String Encodings

CFString​Encoding constants for encodings that may be supported by CFString.