CFString.h

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