CFString.h

   1 /*
   2  * Copyright (c) 2015 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*      CFString.h
  25         Copyright (c) 1998-2014, Apple Inc. All rights reserved.
  26 */
  27
  28 #if !defined(__COREFOUNDATION_CFSTRING__)
  29 #define __COREFOUNDATION_CFSTRING__ 1
  30
  31 #include <CoreFoundation/CFBase.h>
  32 #include <CoreFoundation/CFArray.h>
  33 #include <CoreFoundation/CFData.h>
  34 #include <CoreFoundation/CFDictionary.h>
  35 #include <CoreFoundation/CFCharacterSet.h>
  36 #include <CoreFoundation/CFLocale.h>
  37 #include <stdarg.h>
  38
  39 CF_IMPLICIT_BRIDGING_ENABLED
  40 CF_EXTERN_C_BEGIN
  41
  42 /*
  43 Please note: CFStrings are conceptually an array of Unicode characters.
  44 However, in general, how a CFString stores this array is an implementation
  45 detail. For instance, CFString might choose to use an array of 8-bit characters
  46 to store its contents, or it might use multiple blocks of memory, or whatever.
  47 This is especially true since CFString is toll-free bridged with NSString, enabling
  48 any NSString instance to be used as a CFString. Furthermore, the implementation
  49 may change depending on the default system encoding, the user's language,
  50 or even a release or update of the OS.
  51
  52 What this means is that you should use the following advanced functions with care:
  53
  54   CFStringGetPascalStringPtr()
  55   CFStringGetCStringPtr()
  56   CFStringGetCharactersPtr()
  57
  58 These functions are provided for optimization only. They will either return the desired
  59 pointer quickly, in constant time, or they return NULL. They might choose to return NULL
  60 for many reasons; for instance it's possible that for users running in different
  61 languages these sometimes return NULL; or in a future OS release the first two might
  62 switch to always returning NULL. Never observing NULL returns in your usages of these
  63 functions does not mean they won't ever return NULL. (But note the CFStringGetCharactersPtr()
  64 exception mentioned further below.)
  65
  66 In your usages of these functions, if you get a NULL return, use the non-Ptr version
  67 of the functions as shown in this example:
  68
  69   char buffer[BUFSIZE];
  70   const char *ptr = CFStringGetCStringPtr(str, encoding);
  71   if (ptr == NULL) {
  72       if (CFStringGetCString(str, buffer, BUFSIZE, encoding)) ptr = buffer;
  73   }
  74
  75 Note that CFStringGetCString() or CFStringGetPascalString() calls might still fail --- but
  76 that will happen in two circumstances only: The conversion from the UniChar contents of CFString
  77 to the specified encoding fails, or the buffer is too small. If they fail, that means
  78 the conversion was not possible.
  79
  80 If you need a copy of the buffer in the above example, you might consider simply calling
  81 CFStringGetCString() in all cases --- CFStringGetCStringPtr() is simply an optimization.
  82
  83 In addition, the following functions, which create immutable CFStrings from developer
  84 supplied buffers without copying the buffers, might have to actually copy
  85 under certain circumstances (If they do copy, the buffer will be dealt with by the
  86 "contentsDeallocator" argument.):
  87
  88   CFStringCreateWithPascalStringNoCopy()
  89   CFStringCreateWithCStringNoCopy()
  90   CFStringCreateWithCharactersNoCopy()
  91
  92 You should of course never depend on the backing store of these CFStrings being
  93 what you provided, and in other no circumstance should you change the contents
  94 of that buffer (given that would break the invariant about the CFString being immutable).
  95
  96 Having said all this, there are actually ways to create a CFString where the backing store
  97 is external, and can be manipulated by the developer or CFString itself:
  98
  99   CFStringCreateMutableWithExternalCharactersNoCopy()
 100   CFStringSetExternalCharactersNoCopy()
 101
 102 A "contentsAllocator" is used to realloc or free the backing store by CFString.
 103 kCFAllocatorNull can be provided to assure CFString will never realloc or free the buffer.
 104 Developer can call CFStringSetExternalCharactersNoCopy() to update
 105 CFString's idea of what's going on, if the buffer is changed externally. In these
 106 strings, CFStringGetCharactersPtr() is guaranteed to return the external buffer.
 107
 108 These functions are here to allow wrapping a buffer of UniChar characters in a CFString,
 109 allowing the buffer to passed into CFString functions and also manipulated via CFString
 110 mutation functions. In general, developers should not use this technique for all strings,
 111 as it prevents CFString from using certain optimizations.
 112 */
 113
 114 /* Identifier for character encoding; the values are the same as Text Encoding Converter TextEncoding.
 115 */
 116 typedef UInt32 CFStringEncoding;
 117
 118 /* Platform-independent built-in encodings; always available on all platforms.
 119    Call CFStringGetSystemEncoding() to get the default system encoding.
 120 */
 121 #define kCFStringEncodingInvalidId (0xffffffffU)
 122 typedef CF_ENUM(CFStringEncoding, CFStringBuiltInEncodings) {
 123     kCFStringEncodingMacRoman = 0,
 124     kCFStringEncodingWindowsLatin1 = 0x0500, /* ANSI codepage 1252 */
 125     kCFStringEncodingISOLatin1 = 0x0201, /* ISO 8859-1 */
 126     kCFStringEncodingNextStepLatin = 0x0B01, /* NextStep encoding*/
 127     kCFStringEncodingASCII = 0x0600, /* 0..127 (in creating CFString, values greater than 0x7F are treated as corresponding Unicode value) */
 128     kCFStringEncodingUnicode = 0x0100, /* kTextEncodingUnicodeDefault  + kTextEncodingDefaultFormat (aka kUnicode16BitFormat) */
 129     kCFStringEncodingUTF8 = 0x08000100, /* kTextEncodingUnicodeDefault + kUnicodeUTF8Format */
 130     kCFStringEncodingNonLossyASCII = 0x0BFF, /* 7bit Unicode variants used by Cocoa & Java */
 131
 132     kCFStringEncodingUTF16 = 0x0100, /* kTextEncodingUnicodeDefault + kUnicodeUTF16Format (alias of kCFStringEncodingUnicode) */
 133     kCFStringEncodingUTF16BE = 0x10000100, /* kTextEncodingUnicodeDefault + kUnicodeUTF16BEFormat */
 134     kCFStringEncodingUTF16LE = 0x14000100, /* kTextEncodingUnicodeDefault + kUnicodeUTF16LEFormat */
 135
 136     kCFStringEncodingUTF32 = 0x0c000100, /* kTextEncodingUnicodeDefault + kUnicodeUTF32Format */
 137     kCFStringEncodingUTF32BE = 0x18000100, /* kTextEncodingUnicodeDefault + kUnicodeUTF32BEFormat */
 138     kCFStringEncodingUTF32LE = 0x1c000100 /* kTextEncodingUnicodeDefault + kUnicodeUTF32LEFormat */
 139 };
 140
 141
 142 /* CFString type ID */
 143 CF_EXPORT
 144 CFTypeID CFStringGetTypeID(void);
 145
 146 /* CFSTR() allows creation of compile-time constant CFStringRefs; the argument
 147 should be a constant C-string.
 148
 149 CFSTR(), not being a "Copy" or "Create" function, does not return a new
 150 reference for you. So, you should not release the return value. This is
 151 much like constant C or Pascal strings --- when you use "hello world"
 152 in a program, you do not free it.
 153
 154 However, strings returned from CFSTR() can be retained and released in a
 155 properly nested fashion, just like any other CF type. That is, if you pass
 156 a CFSTR() return value to a function such as SetMenuItemWithCFString(), the
 157 function can retain it, then later, when it's done with it, it can release it.
 158
 159 Non-7 bit characters (that is, above 127) in CFSTR() are supported, although care must
 160 be taken in dealing with files containing them. If you can trust your editor and tools
 161 to deal with non-ASCII characters in the source code, then you can use them directly
 162 in CFSTR(); otherwise, you can represent such characters with their escaped octal
 163 equivalents in the encoding the compiler will use to interpret them (for instance,
 164 O-umlaut is \303\226 in UTF-8). UTF-8 is the recommended encoding here,
 165 since it is the default choice with Mac OS X developer tools.
 166 */
 167 #if TARGET_OS_WIN32 || TARGET_OS_LINUX
 168 #undef __CONSTANT_CFSTRINGS__
 169 #endif
 170
 171 #ifdef __CONSTANT_CFSTRINGS__
 172 #define CFSTR(cStr)  ((CFStringRef) __builtin___CFStringMakeConstantString ("" cStr ""))
 173 #else
 174 #define CFSTR(cStr)  __CFStringMakeConstantString("" cStr "")
 175 #endif
 176
 177 #if defined(__GNUC__) && (__GNUC__*10+__GNUC_MINOR__ >= 42) && defined(__APPLE_CC__) && (__APPLE_CC__ > 1) && !defined(__INTEL_COMPILER) && (TARGET_OS_MAC || TARGET_OS_EMBEDDED)
 178 #define CF_FORMAT_FUNCTION(F,A) __attribute__((format(CFString, F, A)))
 179 #define CF_FORMAT_ARGUMENT(A) __attribute__((format_arg(A)))
 180 #else
 181 #define CF_FORMAT_FUNCTION(F,A)
 182 #define CF_FORMAT_ARGUMENT(A)
 183 #endif
 184
 185 /*** Immutable string creation functions ***/
 186
 187 /* Functions to create basic immutable strings. The provided allocator is used for all memory activity in these functions.
 188 */
 189
 190 /* The following four functions copy the provided buffer into CFString's internal storage. */
 191 CF_EXPORT
 192 CFStringRef CFStringCreateWithPascalString(CFAllocatorRef alloc, ConstStr255Param pStr, CFStringEncoding encoding);
 193
 194 CF_EXPORT
 195 CFStringRef CFStringCreateWithCString(CFAllocatorRef alloc, const char *cStr, CFStringEncoding encoding);
 196
 197 /* The following takes an explicit length, and allows you to specify whether the data is an external format --- that is, whether to pay attention to the BOM character (if any) and do byte swapping if necessary
 198 */
 199 CF_EXPORT
 200 CFStringRef CFStringCreateWithBytes(CFAllocatorRef alloc, const UInt8 *bytes, CFIndex numBytes, CFStringEncoding encoding, Boolean isExternalRepresentation);
 201
 202 CF_EXPORT
 203 CFStringRef CFStringCreateWithCharacters(CFAllocatorRef alloc, const UniChar *chars, CFIndex numChars);
 204
 205
 206 /* These functions try not to copy the provided buffer. The buffer will be deallocated
 207 with the provided contentsDeallocator when it's no longer needed; to not free
 208 the buffer, specify kCFAllocatorNull here. As usual, NULL means default allocator.
 209
 210 NOTE: Do not count on these buffers as being used by the string;
 211 in some cases the CFString might free the buffer and use something else
 212 (for instance if it decides to always use Unicode encoding internally).
 213
 214 NOTE: If you are not transferring ownership of the buffer to the CFString
 215 (for instance, you supplied contentsDeallocator = kCFAllocatorNull), it is your
 216 responsibility to assure the buffer does not go away during the lifetime of the string.
 217 If the string is retained or copied, its lifetime might extend in ways you cannot
 218 predict. So, for strings created with buffers whose lifetimes you cannot
 219 guarantee, you need to be extremely careful --- do not hand it out to any
 220 APIs which might retain or copy the strings.
 221 */
 222 CF_EXPORT
 223 CFStringRef CFStringCreateWithPascalStringNoCopy(CFAllocatorRef alloc, ConstStr255Param pStr, CFStringEncoding encoding, CFAllocatorRef contentsDeallocator);
 224
 225 CF_EXPORT
 226 CFStringRef CFStringCreateWithCStringNoCopy(CFAllocatorRef alloc, const char *cStr, CFStringEncoding encoding, CFAllocatorRef contentsDeallocator);
 227
 228 /* The following takes an explicit length, and allows you to specify whether the data is an external format --- that is, whether to pay attention to the BOM character (if any) and do byte swapping if necessary
 229 */
 230 CF_EXPORT
 231 CFStringRef CFStringCreateWithBytesNoCopy(CFAllocatorRef alloc, const UInt8 *bytes, CFIndex numBytes, CFStringEncoding encoding, Boolean isExternalRepresentation, CFAllocatorRef contentsDeallocator);
 232
 233 CF_EXPORT
 234 CFStringRef CFStringCreateWithCharactersNoCopy(CFAllocatorRef alloc, const UniChar *chars, CFIndex numChars, CFAllocatorRef contentsDeallocator);
 235
 236 /* Create copies of part or all of the string.
 237 */
 238 CF_EXPORT
 239 CFStringRef CFStringCreateWithSubstring(CFAllocatorRef alloc, CFStringRef str, CFRange range);
 240
 241 CF_EXPORT
 242 CFStringRef CFStringCreateCopy(CFAllocatorRef alloc, CFStringRef theString);
 243
 244 /* These functions create a CFString from the provided printf-like format string and arguments.
 245 */
 246 CF_EXPORT
 247 CFStringRef CFStringCreateWithFormat(CFAllocatorRef alloc, CFDictionaryRef formatOptions, CFStringRef format, ...) CF_FORMAT_FUNCTION(3,4);
 248
 249 CF_EXPORT
 250 CFStringRef CFStringCreateWithFormatAndArguments(CFAllocatorRef alloc, CFDictionaryRef formatOptions, CFStringRef format, va_list arguments) CF_FORMAT_FUNCTION(3,0);
 251
 252 /* Functions to create mutable strings. "maxLength", if not 0, is a hard bound on the length of the string. If 0, there is no limit on the length.
 253 */
 254 CF_EXPORT
 255 CFMutableStringRef CFStringCreateMutable(CFAllocatorRef alloc, CFIndex maxLength);
 256
 257 CF_EXPORT
 258 CFMutableStringRef CFStringCreateMutableCopy(CFAllocatorRef alloc, CFIndex maxLength, CFStringRef theString);
 259
 260 /* This function creates a mutable string that has a developer supplied and directly editable backing store.
 261 The string will be manipulated within the provided buffer (if any) until it outgrows capacity; then the
 262 externalCharactersAllocator will be consulted for more memory. When the CFString is deallocated, the
 263 buffer will be freed with the externalCharactersAllocator. Provide kCFAllocatorNull here to prevent the buffer
 264 from ever being reallocated or deallocated by CFString. See comments at top of this file for more info.
 265 */
 266 CF_EXPORT
 267 CFMutableStringRef CFStringCreateMutableWithExternalCharactersNoCopy(CFAllocatorRef alloc, UniChar *chars, CFIndex numChars, CFIndex capacity, CFAllocatorRef externalCharactersAllocator);
 268
 269 /*** Basic accessors for the contents ***/
 270
 271 /* Number of 16-bit Unicode characters in the string.
 272 */
 273 CF_EXPORT
 274 CFIndex CFStringGetLength(CFStringRef theString);
 275
 276 /* Extracting the contents of the string. For obtaining multiple characters, calling
 277 CFStringGetCharacters() is more efficient than multiple calls to CFStringGetCharacterAtIndex().
 278 If the length of the string is not known (so you can't use a fixed size buffer for CFStringGetCharacters()),
 279 another method is to use is CFStringGetCharacterFromInlineBuffer() (see further below).
 280 */
 281 CF_EXPORT
 282 UniChar CFStringGetCharacterAtIndex(CFStringRef theString, CFIndex idx);
 283
 284 CF_EXPORT
 285 void CFStringGetCharacters(CFStringRef theString, CFRange range, UniChar *buffer);
 286
 287
 288 /*** Conversion to other encodings ***/
 289
 290 /* These two convert into the provided buffer; they return false if conversion isn't possible
 291 (due to conversion error, or not enough space in the provided buffer).
 292 These functions do zero-terminate or put the length byte; the provided bufferSize should include
 293 space for this (so pass 256 for Str255). More sophisticated usages can go through CFStringGetBytes().
 294 These functions are equivalent to calling CFStringGetBytes() with
 295 the range of the string; lossByte = 0; and isExternalRepresentation = false;
 296 if successful, they then insert the leading length or terminating zero, as desired.
 297 */
 298 CF_EXPORT
 299 Boolean CFStringGetPascalString(CFStringRef theString, StringPtr buffer, CFIndex bufferSize, CFStringEncoding encoding);
 300
 301 CF_EXPORT
 302 Boolean CFStringGetCString(CFStringRef theString, char *buffer, CFIndex bufferSize, CFStringEncoding encoding);
 303
 304 /* These functions attempt to return in O(1) time the desired format for the string.
 305 Note that although this means a pointer to the internal structure is being returned,
 306 this can't always be counted on. Please see note at the top of the file for more
 307 details.
 308 */
 309 CF_EXPORT
 310 ConstStringPtr CFStringGetPascalStringPtr(CFStringRef theString, CFStringEncoding encoding);    /* May return NULL at any time; be prepared for NULL */
 311
 312 CF_EXPORT
 313 const char *CFStringGetCStringPtr(CFStringRef theString, CFStringEncoding encoding);            /* May return NULL at any time; be prepared for NULL */
 314
 315 CF_EXPORT
 316 const UniChar *CFStringGetCharactersPtr(CFStringRef theString);                                 /* May return NULL at any time; be prepared for NULL */
 317
 318 /* The primitive conversion routine; allows you to convert a string piece at a time
 319        into a fixed size buffer. Returns number of characters converted.
 320    Characters that cannot be converted to the specified encoding are represented
 321        with the byte specified by lossByte; if lossByte is 0, then lossy conversion
 322        is not allowed and conversion stops, returning partial results.
 323    Pass buffer==NULL if you don't care about the converted string (but just the convertability,
 324        or number of bytes required).
 325    maxBufLength indicates the maximum number of bytes to generate. It is ignored when buffer==NULL.
 326    Does not zero-terminate. If you want to create Pascal or C string, allow one extra byte at start or end.
 327    Setting isExternalRepresentation causes any extra bytes that would allow
 328        the data to be made persistent to be included; for instance, the Unicode BOM. Note that
 329        CFString prepends UTF encoded data with the Unicode BOM <http://www.unicode.org/faq/utf_bom.html>
 330        when generating external representation if the target encoding allows. It's important to note that
 331        only UTF-8, UTF-16, and UTF-32 define the handling of the byte order mark character, and the "LE"
 332        and "BE" variants of UTF-16 and UTF-32 don't.
 333 */
 334 CF_EXPORT
 335 CFIndex CFStringGetBytes(CFStringRef theString, CFRange range, CFStringEncoding encoding, UInt8 lossByte, Boolean isExternalRepresentation, UInt8 *buffer, CFIndex maxBufLen, CFIndex *usedBufLen);
 336
 337 /* Convenience functions String <-> Data. These generate "external" formats, that is, formats that
 338    can be written out to disk. For instance, if the encoding is Unicode,
 339    CFStringCreateFromExternalRepresentation() pays attention to the BOM character (if any)
 340    and does byte swapping if necessary. Similarly CFStringCreateExternalRepresentation() will
 341    include a BOM character if appropriate. See CFStringGetBytes() for more on this and lossByte.
 342 */
 343 CF_EXPORT
 344 CFStringRef CFStringCreateFromExternalRepresentation(CFAllocatorRef alloc, CFDataRef data, CFStringEncoding encoding);  /* May return NULL on conversion error */
 345
 346 CF_EXPORT
 347 CFDataRef CFStringCreateExternalRepresentation(CFAllocatorRef alloc, CFStringRef theString, CFStringEncoding encoding, UInt8 lossByte); /* May return NULL on conversion error */
 348
 349 /* Hints about the contents of a string
 350 */
 351 CF_EXPORT
 352 CFStringEncoding CFStringGetSmallestEncoding(CFStringRef theString);    /* Result in O(n) time max */
 353
 354 CF_EXPORT
 355 CFStringEncoding CFStringGetFastestEncoding(CFStringRef theString);     /* Result in O(1) time max */
 356
 357 /* General encoding info
 358 */
 359 CF_EXPORT
 360 CFStringEncoding CFStringGetSystemEncoding(void);               /* The default encoding for the system; untagged 8-bit characters are usually in this encoding */
 361
 362 CF_EXPORT
 363 CFIndex CFStringGetMaximumSizeForEncoding(CFIndex length, CFStringEncoding encoding);   /* Max bytes a string of specified length (in UniChars) will take up if encoded */
 364
 365
 366 /*** FileSystem path conversion functions ***/
 367
 368 /* Extract the contents of the string as a NULL-terminated 8-bit string appropriate for passing to POSIX APIs (for example, normalized for HFS+).  The string is zero-terminated. false will be returned if the conversion results don't fit into the buffer.  Use CFStringGetMaximumSizeOfFileSystemRepresentation() if you want to make sure the buffer is of sufficient length.
 369 */
 370 CF_EXPORT
 371 Boolean CFStringGetFileSystemRepresentation(CFStringRef string, char *buffer, CFIndex maxBufLen);
 372
 373 /* Get the upper bound on the number of bytes required to hold the file system representation for the string. This result is returned quickly as a very rough approximation, and could be much larger than the actual space required. The result includes space for the zero termination. If you are allocating a buffer for long-term keeping, it's recommended that you reallocate it smaller (to be the right size) after calling CFStringGetFileSystemRepresentation().
 374 */
 375 CF_EXPORT
 376 CFIndex CFStringGetMaximumSizeOfFileSystemRepresentation(CFStringRef string);
 377
 378 /* Create a CFString from the specified zero-terminated POSIX file system representation.  If the conversion fails (possible due to bytes in the buffer not being a valid sequence of bytes for the appropriate character encoding), NULL is returned.
 379 */
 380 CF_EXPORT
 381 CFStringRef CFStringCreateWithFileSystemRepresentation(CFAllocatorRef alloc, const char *buffer);
 382
 383
 384 /*** Comparison functions. ***/
 385
 386 /* Find and compare flags; these are OR'ed together and provided as CFStringCompareFlags in the various functions.
 387 */
 388 typedef CF_OPTIONS(CFOptionFlags, CFStringCompareFlags) {
 389     kCFCompareCaseInsensitive = 1,
 390     kCFCompareBackwards = 4,            /* Starting from the end of the string */
 391     kCFCompareAnchored = 8,             /* Only at the specified starting point */
 392     kCFCompareNonliteral = 16,          /* If specified, loose equivalence is performed (o-umlaut == o, umlaut) */
 393     kCFCompareLocalized = 32,           /* User's default locale is used for the comparisons */
 394     kCFCompareNumerically = 64,         /* Numeric comparison is used; that is, Foo2.txt < Foo7.txt < Foo25.txt */
 395     kCFCompareDiacriticInsensitive CF_ENUM_AVAILABLE(10_5, 2_0) = 128, /* If specified, ignores diacritics (o-umlaut == o) */
 396     kCFCompareWidthInsensitive CF_ENUM_AVAILABLE(10_5, 2_0) = 256, /* If specified, ignores width differences ('a' == UFF41) */
 397     kCFCompareForcedOrdering CF_ENUM_AVAILABLE(10_5, 2_0) = 512 /* If specified, comparisons are forced to return either kCFCompareLessThan or kCFCompareGreaterThan if the strings are equivalent but not strictly equal, for stability when sorting (e.g. "aaa" > "AAA" with kCFCompareCaseInsensitive specified) */
 398 };
 399
 400 /* The main comparison routine; compares specified range of the first string to (the full range of) the second string.
 401    locale == NULL indicates canonical locale (the return value from CFLocaleGetSystem()).
 402    kCFCompareNumerically, added in 10.2, does not work if kCFCompareLocalized is specified on systems before 10.3
 403    kCFCompareBackwards and kCFCompareAnchored are not applicable.
 404    rangeToCompare applies to the first string; that is, only the substring of theString1 specified by rangeToCompare is compared against all of theString2.
 405 */
 406 CF_EXPORT
 407 CFComparisonResult CFStringCompareWithOptionsAndLocale(CFStringRef theString1, CFStringRef theString2, CFRange rangeToCompare, CFStringCompareFlags compareOptions, CFLocaleRef locale) CF_AVAILABLE(10_5, 2_0);
 408
 409 /* Comparison convenience. Uses the current user locale (the return value from CFLocaleCopyCurrent()) if kCFCompareLocalized. Refer to CFStringCompareWithOptionsAndLocale() for more info.
 410 */
 411 CF_EXPORT
 412 CFComparisonResult CFStringCompareWithOptions(CFStringRef theString1, CFStringRef theString2, CFRange rangeToCompare, CFStringCompareFlags compareOptions);
 413
 414 /* Comparison convenience suitable for passing as sorting functions.
 415    kCFCompareNumerically, added in 10.2, does not work if kCFCompareLocalized is specified on systems before 10.3
 416    kCFCompareBackwards and kCFCompareAnchored are not applicable.
 417 */
 418 CF_EXPORT
 419 CFComparisonResult CFStringCompare(CFStringRef theString1, CFStringRef theString2, CFStringCompareFlags compareOptions);
 420
 421 /* CFStringFindWithOptionsAndLocale() returns the found range in the CFRange * argument; you can pass NULL for simple discovery check.
 422    locale == NULL indicates canonical locale (the return value from CFLocaleGetSystem()).
 423    If stringToFind is the empty string (zero length), nothing is found.
 424    Ignores the kCFCompareNumerically option.
 425    Only the substring of theString specified by rangeToSearch is searched for stringToFind.
 426 */
 427 CF_EXPORT
 428 Boolean CFStringFindWithOptionsAndLocale(CFStringRef theString, CFStringRef stringToFind, CFRange rangeToSearch, CFStringCompareFlags searchOptions, CFLocaleRef locale, CFRange *result) CF_AVAILABLE(10_5, 2_0);
 429
 430 /* Find convenience. Uses the current user locale (the return value from CFLocaleCopyCurrent()) if kCFCompareLocalized. Refer to CFStringFindWithOptionsAndLocale() for more info.
 431 */
 432 CF_EXPORT
 433 Boolean CFStringFindWithOptions(CFStringRef theString, CFStringRef stringToFind, CFRange rangeToSearch, CFStringCompareFlags searchOptions, CFRange *result);
 434
 435 /* CFStringCreateArrayWithFindResults() returns an array of CFRange pointers, or NULL if there are no matches.
 436    Overlapping instances are not found; so looking for "AA" in "AAA" finds just one range.
 437    Post 10.1: If kCFCompareBackwards is provided, the scan is done from the end (which can give a different result), and
 438       the results are stored in the array backwards (last found range in slot 0).
 439    If stringToFind is the empty string (zero length), nothing is found.
 440    kCFCompareAnchored causes just the consecutive instances at start (or end, if kCFCompareBackwards) to be reported. So, searching for "AB" in "ABABXAB..." you just get the first two occurrences.
 441    Ignores the kCFCompareNumerically option.
 442    Only the substring of theString specified by rangeToSearch is searched for stringToFind.
 443 */
 444 CF_EXPORT
 445 CFArrayRef CFStringCreateArrayWithFindResults(CFAllocatorRef alloc, CFStringRef theString, CFStringRef stringToFind, CFRange rangeToSearch, CFStringCompareFlags compareOptions);
 446
 447 /* Find conveniences; see comments above concerning empty string and options.
 448 */
 449 CF_EXPORT
 450 CFRange CFStringFind(CFStringRef theString, CFStringRef stringToFind, CFStringCompareFlags compareOptions);
 451
 452 CF_EXPORT
 453 Boolean CFStringHasPrefix(CFStringRef theString, CFStringRef prefix);
 454
 455 CF_EXPORT
 456 Boolean CFStringHasSuffix(CFStringRef theString, CFStringRef suffix);
 457
 458 /*!
 459         @function CFStringGetRangeOfComposedCharactersAtIndex
 460         Returns the range of the composed character sequence at the specified index.
 461         @param theString The CFString which is to be searched.  If this
 462                                 parameter is not a valid CFString, the behavior is
 463                         undefined.
 464         @param theIndex The index of the character contained in the
 465                         composed character sequence.  If the index is
 466                         outside the index space of the string (0 to N-1 inclusive,
 467                         where N is the length of the string), the behavior is
 468                         undefined.
 469         @result The range of the composed character sequence.
 470 */
 471 CF_EXPORT CFRange CFStringGetRangeOfComposedCharactersAtIndex(CFStringRef theString, CFIndex theIndex);
 472
 473 /*!
 474         @function CFStringFindCharacterFromSet
 475         Query the range of the first character contained in the specified character set.
 476         @param theString The CFString which is to be searched.  If this
 477                                 parameter is not a valid CFString, the behavior is
 478                         undefined.
 479         @param theSet The CFCharacterSet against which the membership
 480                         of characters is checked.  If this parameter is not a valid
 481                         CFCharacterSet, the behavior is undefined.
 482         @param range The range of characters within the string to search. If
 483                         the range location or end point (defined by the location
 484                         plus length minus 1) are outside the index space of the
 485                         string (0 to N-1 inclusive, where N is the length of the
 486                         string), the behavior is undefined. If the range length is
 487                         negative, the behavior is undefined. The range may be empty
 488                         (length 0), in which case no search is performed.
 489         @param searchOptions The bitwise-or'ed option flags to control
 490                         the search behavior.  The supported options are
 491                         kCFCompareBackwards andkCFCompareAnchored.
 492                         If other option flags are specified, the behavior
 493                         is undefined.
 494         @param result The pointer to a CFRange supplied by the caller in
 495                         which the search result is stored.  Note that the length
 496                         of this range can be more than 1, if for instance the
 497                         result is a composed character. If a pointer to an invalid
 498                         memory is specified, the behavior is undefined.
 499         @result true, if at least a character which is a member of the character
 500                         set is found and result is filled, otherwise, false.
 501 */
 502 CF_EXPORT Boolean CFStringFindCharacterFromSet(CFStringRef theString, CFCharacterSetRef theSet, CFRange rangeToSearch, CFStringCompareFlags searchOptions, CFRange *result);
 503
 504 /* Find range of bounds of the line(s) that span the indicated range (startIndex, numChars),
 505    taking into account various possible line separator sequences (CR, CRLF, LF, and Unicode NextLine, LineSeparator, ParagraphSeparator).
 506    All return values are "optional" (provide NULL if you don't want them)
 507      lineBeginIndex: index of first character in line
 508      lineEndIndex: index of first character of the next line (including terminating line separator characters)
 509      contentsEndIndex: index of the first line separator character
 510    Thus, lineEndIndex - lineBeginIndex is the number of chars in the line, including the line separators
 511          contentsEndIndex - lineBeginIndex is the number of chars in the line w/out the line separators
 512 */
 513 CF_EXPORT
 514 void CFStringGetLineBounds(CFStringRef theString, CFRange range, CFIndex *lineBeginIndex, CFIndex *lineEndIndex, CFIndex *contentsEndIndex);
 515
 516 /* Same as CFStringGetLineBounds(), however, will only look for paragraphs. Won't stop at Unicode NextLine or LineSeparator characters.
 517 */
 518 CF_EXPORT
 519 void CFStringGetParagraphBounds(CFStringRef string, CFRange range, CFIndex *parBeginIndex, CFIndex *parEndIndex, CFIndex *contentsEndIndex) CF_AVAILABLE(10_5, 2_0);
 520
 521 /*!
 522         @function CFStringGetHyphenationLocationBeforeIndex
 523         Retrieve the first potential hyphenation location found before the specified location.
 524         @param string The CFString which is to be hyphenated.  If this
 525                                 parameter is not a valid CFString, the behavior is
 526                         undefined.
 527         @param location An index in the string.  If a valid hyphen index is returned, it
 528                         will be before this index.
 529         @param limitRange The range of characters within the string to search. If
 530                         the range location or end point (defined by the location
 531                         plus length minus 1) are outside the index space of the
 532                         string (0 to N-1 inclusive, where N is the length of the
 533                         string), the behavior is undefined. If the range length is
 534                         negative, the behavior is undefined. The range may be empty
 535                         (length 0), in which case no hyphen location is generated.
 536         @param options Reserved for future use.
 537         @param locale Specifies which language's hyphenation conventions to use.
 538                         This must be a valid locale.  Hyphenation data is not available
 539                         for all locales.  You can use CFStringIsHyphenationAvailableForLocale
 540                         to test for availability of hyphenation data.
 541         @param character The suggested hyphen character to insert.  Pass NULL if you
 542                         do not need this information.
 543         @result an index in the string where it is appropriate to insert a hyphen, if
 544                         one exists; else kCFNotFound
 545 */
 546 CF_EXPORT
 547 CFIndex CFStringGetHyphenationLocationBeforeIndex(CFStringRef string, CFIndex location, CFRange limitRange, CFOptionFlags options, CFLocaleRef locale, UTF32Char *character) CF_AVAILABLE(10_7, 4_2);
 548
 549 CF_EXPORT
 550 Boolean CFStringIsHyphenationAvailableForLocale(CFLocaleRef locale) CF_AVAILABLE(10_7, 4_3);
 551
 552 /*** Exploding and joining strings with a separator string ***/
 553
 554 CF_EXPORT
 555 CFStringRef CFStringCreateByCombiningStrings(CFAllocatorRef alloc, CFArrayRef theArray, CFStringRef separatorString);   /* Empty array returns empty string; one element array returns the element */
 556
 557 CF_EXPORT
 558 CFArrayRef CFStringCreateArrayBySeparatingStrings(CFAllocatorRef alloc, CFStringRef theString, CFStringRef separatorString);    /* No separators in the string returns array with that string; string == sep returns two empty strings */
 559
 560
 561 /*** Parsing non-localized numbers from strings ***/
 562
 563 CF_EXPORT
 564 SInt32 CFStringGetIntValue(CFStringRef str);            /* Skips whitespace; returns 0 on error, MAX or -MAX on overflow */
 565
 566 CF_EXPORT
 567 double CFStringGetDoubleValue(CFStringRef str); /* Skips whitespace; returns 0.0 on error */
 568
 569
 570 /*** MutableString functions ***/
 571
 572 /* CFStringAppend("abcdef", "xxxxx") -> "abcdefxxxxx"
 573    CFStringDelete("abcdef", CFRangeMake(2, 3)) -> "abf"
 574    CFStringReplace("abcdef", CFRangeMake(2, 3), "xxxxx") -> "abxxxxxf"
 575    CFStringReplaceAll("abcdef", "xxxxx") -> "xxxxx"
 576 */
 577 CF_EXPORT
 578 void CFStringAppend(CFMutableStringRef theString, CFStringRef appendedString);
 579
 580 CF_EXPORT
 581 void CFStringAppendCharacters(CFMutableStringRef theString, const UniChar *chars, CFIndex numChars);
 582
 583 CF_EXPORT
 584 void CFStringAppendPascalString(CFMutableStringRef theString, ConstStr255Param pStr, CFStringEncoding encoding);
 585
 586 CF_EXPORT
 587 void CFStringAppendCString(CFMutableStringRef theString, const char *cStr, CFStringEncoding encoding);
 588
 589 CF_EXPORT
 590 void CFStringAppendFormat(CFMutableStringRef theString, CFDictionaryRef formatOptions, CFStringRef format, ...) CF_FORMAT_FUNCTION(3,4);
 591
 592 CF_EXPORT
 593 void CFStringAppendFormatAndArguments(CFMutableStringRef theString, CFDictionaryRef formatOptions, CFStringRef format, va_list arguments) CF_FORMAT_FUNCTION(3,0);
 594
 595 CF_EXPORT
 596 void CFStringInsert(CFMutableStringRef str, CFIndex idx, CFStringRef insertedStr);
 597
 598 CF_EXPORT
 599 void CFStringDelete(CFMutableStringRef theString, CFRange range);
 600
 601 CF_EXPORT
 602 void CFStringReplace(CFMutableStringRef theString, CFRange range, CFStringRef replacement);
 603
 604 CF_EXPORT
 605 void CFStringReplaceAll(CFMutableStringRef theString, CFStringRef replacement); /* Replaces whole string */
 606
 607 /* Replace all occurrences of target in rangeToSearch of theString with replacement.
 608    Pays attention to kCFCompareCaseInsensitive, kCFCompareBackwards, kCFCompareNonliteral, and kCFCompareAnchored.
 609    kCFCompareBackwards can be used to do the replacement starting from the end, which could give a different result.
 610      ex. AAAAA, replace AA with B -> BBA or ABB; latter if kCFCompareBackwards
 611    kCFCompareAnchored assures only anchored but multiple instances are found (the instances must be consecutive at start or end)
 612      ex. AAXAA, replace A with B -> BBXBB or BBXAA; latter if kCFCompareAnchored
 613    Returns number of replacements performed.
 614 */
 615 CF_EXPORT
 616 CFIndex CFStringFindAndReplace(CFMutableStringRef theString, CFStringRef stringToFind, CFStringRef replacementString, CFRange rangeToSearch, CFStringCompareFlags compareOptions);
 617
 618
 619 /* This function will make the contents of a mutable CFString point directly at the specified UniChar array.
 620    It works only with CFStrings created with CFStringCreateMutableWithExternalCharactersNoCopy().
 621    This function does not free the previous buffer.
 622    The string will be manipulated within the provided buffer (if any) until it outgrows capacity; then the
 623      externalCharactersAllocator will be consulted for more memory.
 624    See comments at the top of this file for more info.
 625 */
 626 CF_EXPORT
 627 void CFStringSetExternalCharactersNoCopy(CFMutableStringRef theString, UniChar *chars, CFIndex length, CFIndex capacity);       /* Works only on specially created mutable strings! */
 628
 629 /* CFStringPad() will pad or cut down a string to the specified size.
 630    The pad string is used as the fill string; indexIntoPad specifies which character to start with.
 631      CFStringPad("abc", " ", 9, 0) ->  "abc      "
 632      CFStringPad("abc", ". ", 9, 1) -> "abc . . ."
 633      CFStringPad("abcdef", ?, 3, ?) -> "abc"
 634
 635      CFStringTrim() will trim the specified string from both ends of the string.
 636      CFStringTrimWhitespace() will do the same with white space characters (tab, newline, etc)
 637      CFStringTrim("  abc ", " ") -> "abc"
 638      CFStringTrim("* * * *abc * ", "* ") -> "*abc "
 639 */
 640 CF_EXPORT
 641 void CFStringPad(CFMutableStringRef theString, CFStringRef padString, CFIndex length, CFIndex indexIntoPad);
 642
 643 CF_EXPORT
 644 void CFStringTrim(CFMutableStringRef theString, CFStringRef trimString);
 645
 646 CF_EXPORT
 647 void CFStringTrimWhitespace(CFMutableStringRef theString);
 648
 649 CF_EXPORT
 650 void CFStringLowercase(CFMutableStringRef theString, CFLocaleRef locale);
 651
 652 CF_EXPORT
 653 void CFStringUppercase(CFMutableStringRef theString, CFLocaleRef locale);
 654
 655 CF_EXPORT
 656 void CFStringCapitalize(CFMutableStringRef theString, CFLocaleRef locale);
 657
 658 /*!
 659         @typedef CFStringNormalizationForm
 660         This is the type of Unicode normalization forms as described in
 661         Unicode Technical Report #15. To normalize for use with file
 662         system calls, use CFStringGetFileSystemRepresentation().
 663 */
 664 typedef CF_ENUM(CFIndex, CFStringNormalizationForm) {
 665         kCFStringNormalizationFormD = 0, // Canonical Decomposition
 666         kCFStringNormalizationFormKD, // Compatibility Decomposition
 667         kCFStringNormalizationFormC, // Canonical Decomposition followed by Canonical Composition
 668         kCFStringNormalizationFormKC // Compatibility Decomposition followed by Canonical Composition
 669 };
 670
 671 /*!
 672         @function CFStringNormalize
 673         Normalizes the string into the specified form as described in
 674         Unicode Technical Report #15.
 675         @param theString  The string which is to be normalized.  If this
 676                 parameter is not a valid mutable CFString, the behavior is
 677                 undefined.
 678         @param theForm  The form into which the string is to be normalized.
 679                 If this parameter is not a valid CFStringNormalizationForm value,
 680                 the behavior is undefined.
 681 */
 682 CF_EXPORT void CFStringNormalize(CFMutableStringRef theString, CFStringNormalizationForm theForm);
 683
 684
 685 /*!
 686         @function CFStringFold
 687         Folds the string into the form specified by the flags.
 688                 Character foldings are operations that convert any of a set of characters
 689                 sharing similar semantics into a single representative from that set.
 690                 This function can be used to preprocess strings that are to be compared,
 691                 searched, or indexed.
 692                 Note that folding does not include normalization, so it is necessary
 693                 to use CFStringNormalize in addition to CFStringFold in order to obtain
 694                 the effect of kCFCompareNonliteral.
 695         @param theString  The string which is to be folded.  If this parameter is not
 696                 a valid mutable CFString, the behavior is undefined.
 697         @param theFlag  The equivalency flags which describes the character folding form.
 698                 Only those flags containing the word "insensitive" are recognized here; other flags are ignored.
 699                 Folding with kCFCompareCaseInsensitive removes case distinctions in accordance with the mapping
 700                 specified by ftp://ftp.unicode.org/Public/UNIDATA/CaseFolding.txt.  Folding with
 701                 kCFCompareDiacriticInsensitive removes distinctions of accents and other diacritics.  Folding
 702                 with kCFCompareWidthInsensitive removes character width distinctions by mapping characters in
 703                 the range U+FF00-U+FFEF to their ordinary equivalents.
 704         @param theLocale The locale tailoring the character folding behavior. If NULL,
 705                 it's considered to be the system locale returned from CFLocaleGetSystem().
 706                 If non-NULL and not a valid CFLocale object, the behavior is undefined.
 707 */
 708
 709 CF_EXPORT
 710 void CFStringFold(CFMutableStringRef theString, CFStringCompareFlags theFlags, CFLocaleRef theLocale) CF_AVAILABLE(10_5, 2_0);
 711
 712 /* Perform string transliteration.  The transformation represented by transform is applied to the given range of string, modifying it in place. Only the specified range will be modified, but the transform may look at portions of the string outside that range for context. NULL range pointer causes the whole string to be transformed. On return, range is modified to reflect the new range corresponding to the original range. reverse indicates that the inverse transform should be used instead, if it exists. If the transform is successful, true is returned; if unsuccessful, false. Reasons for the transform being unsuccessful include an invalid transform identifier, or attempting to reverse an irreversible transform.
 713
 714 You can pass one of the predefined transforms below, or any valid ICU transform ID as defined in the ICU User Guide. Note that we do not support arbitrary set of ICU transform rules.
 715 */
 716 CF_EXPORT
 717 Boolean CFStringTransform(CFMutableStringRef string, CFRange *range, CFStringRef transform, Boolean reverse);
 718
 719 /* Transform identifiers for CFStringTransform()
 720 */
 721 CF_EXPORT const CFStringRef kCFStringTransformStripCombiningMarks;
 722 CF_EXPORT const CFStringRef kCFStringTransformToLatin;
 723 CF_EXPORT const CFStringRef kCFStringTransformFullwidthHalfwidth;
 724 CF_EXPORT const CFStringRef kCFStringTransformLatinKatakana;
 725 CF_EXPORT const CFStringRef kCFStringTransformLatinHiragana;
 726 CF_EXPORT const CFStringRef kCFStringTransformHiraganaKatakana;
 727 CF_EXPORT const CFStringRef kCFStringTransformMandarinLatin;
 728 CF_EXPORT const CFStringRef kCFStringTransformLatinHangul;
 729 CF_EXPORT const CFStringRef kCFStringTransformLatinArabic;
 730 CF_EXPORT const CFStringRef kCFStringTransformLatinHebrew;
 731 CF_EXPORT const CFStringRef kCFStringTransformLatinThai;
 732 CF_EXPORT const CFStringRef kCFStringTransformLatinCyrillic;
 733 CF_EXPORT const CFStringRef kCFStringTransformLatinGreek;
 734 CF_EXPORT const CFStringRef kCFStringTransformToXMLHex;
 735 CF_EXPORT const CFStringRef kCFStringTransformToUnicodeName;
 736 CF_EXPORT const CFStringRef kCFStringTransformStripDiacritics CF_AVAILABLE(10_5, 2_0);
 737
 738
 739 /*** General encoding related functionality ***/
 740
 741 /* This returns availability of the encoding on the system
 742 */
 743 CF_EXPORT
 744 Boolean CFStringIsEncodingAvailable(CFStringEncoding encoding);
 745
 746 /* This function returns list of available encodings.  The returned list is terminated with kCFStringEncodingInvalidId and owned by the system.
 747 */
 748 CF_EXPORT
 749 const CFStringEncoding *CFStringGetListOfAvailableEncodings(void);
 750
 751 /* Returns name of the encoding; non-localized.
 752 */
 753 CF_EXPORT
 754 CFStringRef CFStringGetNameOfEncoding(CFStringEncoding encoding);
 755
 756 /* ID mapping functions from/to Cocoa NSStringEncoding.  Returns kCFStringEncodingInvalidId if no mapping exists.
 757 */
 758 CF_EXPORT
 759 unsigned long CFStringConvertEncodingToNSStringEncoding(CFStringEncoding encoding);
 760
 761 CF_EXPORT
 762 CFStringEncoding CFStringConvertNSStringEncodingToEncoding(unsigned long encoding);
 763
 764 /* ID mapping functions from/to Microsoft Windows codepage (covers both OEM & ANSI).  Returns kCFStringEncodingInvalidId if no mapping exists.
 765 */
 766 CF_EXPORT
 767 UInt32 CFStringConvertEncodingToWindowsCodepage(CFStringEncoding encoding);
 768
 769 CF_EXPORT
 770 CFStringEncoding CFStringConvertWindowsCodepageToEncoding(UInt32 codepage);
 771
 772 /* ID mapping functions from/to IANA registery charset names.  Returns kCFStringEncodingInvalidId if no mapping exists.
 773 */
 774 CF_EXPORT
 775 CFStringEncoding CFStringConvertIANACharSetNameToEncoding(CFStringRef theString);
 776
 777 CF_EXPORT
 778 CFStringRef  CFStringConvertEncodingToIANACharSetName(CFStringEncoding encoding);
 779
 780 /* Returns the most compatible MacOS script value for the input encoding */
 781 /* i.e. kCFStringEncodingMacRoman -> kCFStringEncodingMacRoman */
 782 /*      kCFStringEncodingWindowsLatin1 -> kCFStringEncodingMacRoman */
 783 /*      kCFStringEncodingISO_2022_JP -> kCFStringEncodingMacJapanese */
 784 CF_EXPORT
 785 CFStringEncoding CFStringGetMostCompatibleMacStringEncoding(CFStringEncoding encoding);
 786
 787
 788
 789 /* The next two functions allow fast access to the contents of a string,
 790    assuming you are doing sequential or localized accesses. To use, call
 791    CFStringInitInlineBuffer() with a CFStringInlineBuffer (on the stack, say),
 792    and a range in the string to look at. Then call CFStringGetCharacterFromInlineBuffer()
 793    as many times as you want, with a index into that range (relative to the start
 794    of that range). These are INLINE functions and will end up calling CFString only
 795    once in a while, to fill a buffer.  CFStringGetCharacterFromInlineBuffer() returns 0 if
 796    a location outside the original range is specified.
 797 */
 798 #define __kCFStringInlineBufferLength 64
 799 typedef struct {
 800     UniChar buffer[__kCFStringInlineBufferLength];
 801     CFStringRef theString;
 802     const UniChar *directUniCharBuffer;
 803     const char *directCStringBuffer;
 804     CFRange rangeToBuffer;              /* Range in string to buffer */
 805     CFIndex bufferedRangeStart;         /* Start of range currently buffered (relative to rangeToBuffer.location) */
 806     CFIndex bufferedRangeEnd;           /* bufferedRangeStart + number of chars actually buffered */
 807 } CFStringInlineBuffer;
 808
 809 #if defined(CF_INLINE)
 810 CF_INLINE void CFStringInitInlineBuffer(CFStringRef str, CFStringInlineBuffer *buf, CFRange range) {
 811     buf->theString = str;
 812     buf->rangeToBuffer = range;
 813     buf->directCStringBuffer = (buf->directUniCharBuffer = CFStringGetCharactersPtr(str)) ? NULL : CFStringGetCStringPtr(str, kCFStringEncodingASCII);
 814     buf->bufferedRangeStart = buf->bufferedRangeEnd = 0;
 815 }
 816
 817 CF_INLINE UniChar CFStringGetCharacterFromInlineBuffer(CFStringInlineBuffer *buf, CFIndex idx) {
 818     if (idx < 0 || idx >= buf->rangeToBuffer.length) return 0;
 819     if (buf->directUniCharBuffer) return buf->directUniCharBuffer[idx + buf->rangeToBuffer.location];
 820     if (buf->directCStringBuffer) return (UniChar)(buf->directCStringBuffer[idx + buf->rangeToBuffer.location]);
 821     if (idx >= buf->bufferedRangeEnd || idx < buf->bufferedRangeStart) {
 822         if ((buf->bufferedRangeStart = idx - 4) < 0) buf->bufferedRangeStart = 0;
 823         buf->bufferedRangeEnd = buf->bufferedRangeStart + __kCFStringInlineBufferLength;
 824         if (buf->bufferedRangeEnd > buf->rangeToBuffer.length) buf->bufferedRangeEnd = buf->rangeToBuffer.length;
 825         CFStringGetCharacters(buf->theString, CFRangeMake(buf->rangeToBuffer.location + buf->bufferedRangeStart, buf->bufferedRangeEnd - buf->bufferedRangeStart), buf->buffer);
 826     }
 827     return buf->buffer[idx - buf->bufferedRangeStart];
 828 }
 829
 830 #else
 831 /* If INLINE functions are not available, we do somewhat less powerful macros that work similarly (except be aware that the buf argument is evaluated multiple times).
 832 */
 833 #define CFStringInitInlineBuffer(str, buf, range) \
 834     do {(buf)->theString = str; (buf)->rangeToBuffer = range; (buf)->directCStringBuffer = ((buf)->directUniCharBuffer = CFStringGetCharactersPtr(str)) ? NULL : CFStringGetCStringPtr(str, kCFStringEncodingASCII);} while (0)
 835
 836 #define CFStringGetCharacterFromInlineBuffer(buf, idx) \
 837     (((idx) < 0 || (idx) >= (buf)->rangeToBuffer.length) ? 0 : ((buf)->directUniCharBuffer ? (buf)->directUniCharBuffer[(idx) + (buf)->rangeToBuffer.location] : ((buf)->directCStringBuffer ? (UniChar)((buf)->directCStringBuffer[(idx) + (buf)->rangeToBuffer.location]) : CFStringGetCharacterAtIndex((buf)->theString, (idx) + (buf)->rangeToBuffer.location))))
 838
 839 #endif /* CF_INLINE */
 840
 841
 842
 843 /* UTF-16 surrogate support
 844  */
 845 CF_INLINE Boolean CFStringIsSurrogateHighCharacter(UniChar character) {
 846     return ((character >= 0xD800UL) && (character <= 0xDBFFUL) ? true : false);
 847 }
 848
 849 CF_INLINE Boolean CFStringIsSurrogateLowCharacter(UniChar character) {
 850     return ((character >= 0xDC00UL) && (character <= 0xDFFFUL) ? true : false);
 851 }
 852
 853 CF_INLINE UTF32Char CFStringGetLongCharacterForSurrogatePair(UniChar surrogateHigh, UniChar surrogateLow) {
 854     return (UTF32Char)(((surrogateHigh - 0xD800UL) << 10) + (surrogateLow - 0xDC00UL) + 0x0010000UL);
 855 }
 856
 857 // Maps a UTF-32 character to a pair of UTF-16 surrogate characters. The buffer pointed by surrogates has to have space for at least 2 UTF-16 characters. Returns true if mapped to a surrogate pair.
 858 CF_INLINE Boolean CFStringGetSurrogatePairForLongCharacter(UTF32Char character, UniChar *surrogates) {
 859     if ((character > 0xFFFFUL) && (character < 0x110000UL)) { // Non-BMP character
 860         character -= 0x10000;
 861         if (NULL != surrogates) {
 862             surrogates[0] = (UniChar)((character >> 10) + 0xD800UL);
 863             surrogates[1] = (UniChar)((character & 0x3FF) + 0xDC00UL);
 864         }
 865         return true;
 866     } else {
 867         if (NULL != surrogates) *surrogates = (UniChar)character;
 868         return false;
 869     }
 870 }
 871
 872 /* Rest of the stuff in this file is private and should not be used directly
 873 */
 874 /* For debugging only; output goes to stderr
 875    Use CFShow() to printf the description of any CFType;
 876    Use CFShowStr() to printf detailed info about a CFString
 877 */
 878 CF_EXPORT
 879 void CFShow(CFTypeRef obj);
 880
 881 CF_EXPORT
 882 void CFShowStr(CFStringRef str);
 883
 884 /* This function is private and should not be used directly */
 885 CF_EXPORT
 886 CFStringRef  __CFStringMakeConstantString(const char *cStr) CF_FORMAT_ARGUMENT(1);      /* Private; do not use */
 887
 888 CF_EXTERN_C_END
 889 CF_IMPLICIT_BRIDGING_DISABLED
 890
 891 #endif /* ! __COREFOUNDATION_CFSTRING__ */