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