CFString.h

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