CF-550.tar.gz

[apple/cf.git] / CFString.h

diff --git a/CFString.h b/CFString.h
index 7fdd126c04853979bec95b8bef6a0d4d867795a4..89abd364551103d030882b8573ac23f2217d1b63 100644 (file)
--- a/CFString.h
+++ b/CFString.h
@@ -1,5 +1,5 @@
 /*
 /*

- * Copyright (c) 2008 Apple Inc. All rights reserved.
+ * Copyright (c) 2009 Apple Inc. All rights reserved.

  *
  * @APPLE_LICENSE_HEADER_START@
  * 
  *
  * @APPLE_LICENSE_HEADER_START@
  * 


@@ -21,7 +21,7 @@
  * @APPLE_LICENSE_HEADER_END@
  */
 /*     CFString.h
  * @APPLE_LICENSE_HEADER_END@
  */
 /*     CFString.h

-       Copyright (c) 1998-2007, Apple Inc. All rights reserved.
+       Copyright (c) 1998-2009, Apple Inc. All rights reserved.

 */
 
 #if !defined(__COREFOUNDATION_CFSTRING__)
 */
 
 #if !defined(__COREFOUNDATION_CFSTRING__)


@@ -40,10 +40,12 @@ CF_EXTERN_C_BEGIN
 /*
 Please note: CFStrings are conceptually an array of Unicode characters.
 However, in general, how a CFString stores this array is an implementation
 /*
 Please note: CFStrings are conceptually an array of Unicode characters.
 However, in general, how a CFString stores this array is an implementation

-detail. For instance, CFString might choose to use an array of 8-bit characters;
-to store its contents; or it might use multiple blocks of memory; or whatever.
-Furthermore, the implementation might change depending on the default
-system encoding, the user's language, the OS, or even a given release.
+detail. For instance, CFString might choose to use an array of 8-bit characters
+to store its contents, or it might use multiple blocks of memory, or whatever.
+This is especially true since CFString is toll-free bridged with NSString, enabling
+any NSString instance to be used as a CFString. Furthermore, the implementation
+may change depending on the default system encoding, the user's language, 
+or even a release or update of the OS.

 
 What this means is that you should use the following advanced functions with care:
 
 
 What this means is that you should use the following advanced functions with care:
 


@@ -62,20 +64,19 @@ exception mentioned further below.)
 In your usages of these functions, if you get a NULL return, use the non-Ptr version
 of the functions as shown in this example:
 
 In your usages of these functions, if you get a NULL return, use the non-Ptr version
 of the functions as shown in this example:
 

-  Str255 buffer;
-  StringPtr ptr = CFStringGetPascalStringPtr(str, encoding);
+  char buffer[BUFSIZE];
+  const char *ptr = CFStringGetCStringPtr(str, encoding);

   if (ptr == NULL) {
   if (ptr == NULL) {

-      if (CFStringGetPascalString(str, buffer, 256, encoding)) ptr = buffer;
+      if (CFStringGetCString(str, buffer, BUFSIZE, encoding)) ptr = buffer;

   }
 
   }
 

-Note that CFStringGetPascalString() or CFStringGetCString() calls might still fail --- but
+Note that CFStringGetCString() or CFStringGetPascalString() calls might still fail --- but

 that will happen in two circumstances only: The conversion from the UniChar contents of CFString
 to the specified encoding fails, or the buffer is too small. If they fail, that means
 the conversion was not possible.
 
 that will happen in two circumstances only: The conversion from the UniChar contents of CFString
 to the specified encoding fails, or the buffer is too small. If they fail, that means
 the conversion was not possible.
 

-If you need a copy of the buffer in the above example, you might consider simply
-calling CFStringGetPascalString() in all cases --- CFStringGetPascalStringPtr()
-is simply an optimization.
+If you need a copy of the buffer in the above example, you might consider simply calling
+CFStringGetCString() in all cases --- CFStringGetCStringPtr() is simply an optimization.

 
 In addition, the following functions, which create immutable CFStrings from developer
 supplied buffers without copying the buffers, might have to actually copy
 
 In addition, the following functions, which create immutable CFStrings from developer
 supplied buffers without copying the buffers, might have to actually copy


@@ -125,7 +126,7 @@ enum {
     kCFStringEncodingUnicode = 0x0100, /* kTextEncodingUnicodeDefault  + kTextEncodingDefaultFormat (aka kUnicode16BitFormat) */
     kCFStringEncodingUTF8 = 0x08000100, /* kTextEncodingUnicodeDefault + kUnicodeUTF8Format */
     kCFStringEncodingNonLossyASCII = 0x0BFF /* 7bit Unicode variants used by Cocoa & Java */
     kCFStringEncodingUnicode = 0x0100, /* kTextEncodingUnicodeDefault  + kTextEncodingDefaultFormat (aka kUnicode16BitFormat) */
     kCFStringEncodingUTF8 = 0x08000100, /* kTextEncodingUnicodeDefault + kUnicodeUTF8Format */
     kCFStringEncodingNonLossyASCII = 0x0BFF /* 7bit Unicode variants used by Cocoa & Java */

-#if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_4
+#if MAC_OS_X_VERSION_10_4 <= MAC_OS_X_VERSION_MAX_ALLOWED

     ,
     kCFStringEncodingUTF16 = 0x0100, /* kTextEncodingUnicodeDefault + kUnicodeUTF16Format (alias of kCFStringEncodingUnicode) */
     kCFStringEncodingUTF16BE = 0x10000100, /* kTextEncodingUnicodeDefault + kUnicodeUTF16BEFormat */
     ,
     kCFStringEncodingUTF16 = 0x0100, /* kTextEncodingUnicodeDefault + kUnicodeUTF16Format (alias of kCFStringEncodingUnicode) */
     kCFStringEncodingUTF16BE = 0x10000100, /* kTextEncodingUnicodeDefault + kUnicodeUTF16BEFormat */


@@ -134,15 +135,17 @@ enum {
     kCFStringEncodingUTF32 = 0x0c000100, /* kTextEncodingUnicodeDefault + kUnicodeUTF32Format */
     kCFStringEncodingUTF32BE = 0x18000100, /* kTextEncodingUnicodeDefault + kUnicodeUTF32BEFormat */
     kCFStringEncodingUTF32LE = 0x1c000100 /* kTextEncodingUnicodeDefault + kUnicodeUTF32LEFormat */
     kCFStringEncodingUTF32 = 0x0c000100, /* kTextEncodingUnicodeDefault + kUnicodeUTF32Format */
     kCFStringEncodingUTF32BE = 0x18000100, /* kTextEncodingUnicodeDefault + kUnicodeUTF32BEFormat */
     kCFStringEncodingUTF32LE = 0x1c000100 /* kTextEncodingUnicodeDefault + kUnicodeUTF32LEFormat */

-#endif /* MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_4 */
+#endif /* MAC_OS_X_VERSION_10_4 <= MAC_OS_X_VERSION_MAX_ALLOWED */

 };
 typedef CFStringEncoding CFStringBuiltInEncodings;
 
 };
 typedef CFStringEncoding CFStringBuiltInEncodings;
 

+

 /* CFString type ID */
 CF_EXPORT
 CFTypeID CFStringGetTypeID(void);
 
 /* CFString type ID */
 CF_EXPORT
 CFTypeID CFStringGetTypeID(void);
 

-/* Macro to allow creation of compile-time constant strings; the argument should be a constant string.
+/* CFSTR() allows creation of compile-time constant CFStringRefs; the argument 
+should be a constant C-string.

 
 CFSTR(), not being a "Copy" or "Create" function, does not return a new
 reference for you. So, you should not release the return value. This is
 
 CFSTR(), not being a "Copy" or "Create" function, does not return a new
 reference for you. So, you should not release the return value. This is


@@ -154,17 +157,32 @@ properly nested fashion, just like any other CF type. That is, if you pass
 a CFSTR() return value to a function such as SetMenuItemWithCFString(), the
 function can retain it, then later, when it's done with it, it can release it.
 
 a CFSTR() return value to a function such as SetMenuItemWithCFString(), the
 function can retain it, then later, when it's done with it, it can release it.
 

-At this point non-7 bit characters (that is, characters > 127) in CFSTR() are not 
-supported and using them will lead to unpredictable results. This includes escaped
-(\nnn) characters whose values are > 127. Even if it works for you in testing, 
-it might not work for a user with a different language preference.
+Non-7 bit characters (that is, above 127) in CFSTR() are supported, although care must
+be taken in dealing with files containing them. If you can trust your editor and tools
+to deal with non-ASCII characters in the source code, then you can use them directly 
+in CFSTR(); otherwise, you can represent such characters with their escaped octal 
+equivalents in the encoding the compiler will use to interpret them (for instance, 
+O-umlaut is \303\226 in UTF-8). UTF-8 is the recommended encoding here, 
+since it is the default choice with Mac OS X developer tools.

 */
 */

+#if TARGET_OS_WIN32
+#undef __CONSTANT_CFSTRINGS__
+#endif
+

 #ifdef __CONSTANT_CFSTRINGS__
 #define CFSTR(cStr)  ((CFStringRef) __builtin___CFStringMakeConstantString ("" cStr ""))
 #else
 #define CFSTR(cStr)  __CFStringMakeConstantString("" cStr "")
 #endif
 
 #ifdef __CONSTANT_CFSTRINGS__
 #define CFSTR(cStr)  ((CFStringRef) __builtin___CFStringMakeConstantString ("" cStr ""))
 #else
 #define CFSTR(cStr)  __CFStringMakeConstantString("" cStr "")
 #endif
 

+#if defined(__GNUC__) && (__GNUC__*10+__GNUC_MINOR__ >= 42) && !defined(__INTEL_COMPILER) && (TARGET_OS_MAC || TARGET_OS_EMBEDDED)
+#define CF_FORMAT_FUNCTION(F,A) __attribute__((format(CFString, F, A)))
+#define CF_FORMAT_ARGUMENT(A) __attribute__((format_arg(A)))
+#else
+#define CF_FORMAT_FUNCTION(F,A)
+#define CF_FORMAT_ARGUMENT(A)
+#endif
+

 /*** Immutable string creation functions ***/
 
 /* Functions to create basic immutable strings. The provided allocator is used for all memory activity in these functions.
 /*** Immutable string creation functions ***/
 
 /* Functions to create basic immutable strings. The provided allocator is used for all memory activity in these functions.


@@ -208,7 +226,7 @@ CFStringRef CFStringCreateWithPascalStringNoCopy(CFAllocatorRef alloc, ConstStr2
 CF_EXPORT
 CFStringRef CFStringCreateWithCStringNoCopy(CFAllocatorRef alloc, const char *cStr, CFStringEncoding encoding, CFAllocatorRef contentsDeallocator);
 
 CF_EXPORT
 CFStringRef CFStringCreateWithCStringNoCopy(CFAllocatorRef alloc, const char *cStr, CFStringEncoding encoding, CFAllocatorRef contentsDeallocator);
 

-#if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_4
+#if MAC_OS_X_VERSION_10_4 <= MAC_OS_X_VERSION_MAX_ALLOWED

 /* 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
 */
 CF_EXPORT
 /* 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
 */
 CF_EXPORT


@@ -229,10 +247,10 @@ CFStringRef CFStringCreateCopy(CFAllocatorRef alloc, CFStringRef theString);
 /* These functions create a CFString from the provided printf-like format string and arguments.
 */
 CF_EXPORT
 /* These functions create a CFString from the provided printf-like format string and arguments.
 */
 CF_EXPORT

-CFStringRef CFStringCreateWithFormat(CFAllocatorRef alloc, CFDictionaryRef formatOptions, CFStringRef format, ...);
+CFStringRef CFStringCreateWithFormat(CFAllocatorRef alloc, CFDictionaryRef formatOptions, CFStringRef format, ...) CF_FORMAT_FUNCTION(3,4);

 
 CF_EXPORT
 
 CF_EXPORT

-CFStringRef CFStringCreateWithFormatAndArguments(CFAllocatorRef alloc, CFDictionaryRef formatOptions, CFStringRef format, va_list arguments);
+CFStringRef CFStringCreateWithFormatAndArguments(CFAllocatorRef alloc, CFDictionaryRef formatOptions, CFStringRef format, va_list arguments) CF_FORMAT_FUNCTION(3,0);

 
 /* 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.
 */
 
 /* 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.
 */


@@ -301,25 +319,29 @@ CF_EXPORT
 const UniChar *CFStringGetCharactersPtr(CFStringRef theString);                                        /* May return NULL at any time; be prepared for NULL */
 
 /* The primitive conversion routine; allows you to convert a string piece at a time
 const UniChar *CFStringGetCharactersPtr(CFStringRef theString);                                        /* May return NULL at any time; be prepared for NULL */
 
 /* The primitive conversion routine; allows you to convert a string piece at a time

-   into a fixed size buffer. Returns number of characters converted. 
+       into a fixed size buffer. Returns number of characters converted. 

    Characters that cannot be converted to the specified encoding are represented
    Characters that cannot be converted to the specified encoding are represented

-   with the byte specified by lossByte; if lossByte is 0, then lossy conversion
-   is not allowed and conversion stops, returning partial results.
+       with the byte specified by lossByte; if lossByte is 0, then lossy conversion
+       is not allowed and conversion stops, returning partial results.

    Pass buffer==NULL if you don't care about the converted string (but just the convertability,
    Pass buffer==NULL if you don't care about the converted string (but just the convertability,

-   or number of bytes required). 
+       or number of bytes required). 

    maxBufLength indicates the maximum number of bytes to generate. It is ignored when buffer==NULL.
    Does not zero-terminate. If you want to create Pascal or C string, allow one extra byte at start or end. 
    Setting isExternalRepresentation causes any extra bytes that would allow 
    maxBufLength indicates the maximum number of bytes to generate. It is ignored when buffer==NULL.
    Does not zero-terminate. If you want to create Pascal or C string, allow one extra byte at start or end. 
    Setting isExternalRepresentation causes any extra bytes that would allow 

-   the data to be made persistent to be included; for instance, the Unicode BOM.
+       the data to be made persistent to be included; for instance, the Unicode BOM. Note that
+       CFString prepends UTF encoded data with the Unicode BOM <http://www.unicode.org/faq/utf_bom.html> 
+       when generating external representation if the target encoding allows. It's important to note that
+       only UTF-8, UTF-16, and UTF-32 define the handling of the byte order mark character, and the "LE"
+       and "BE" variants of UTF-16 and UTF-32 don't.

 */
 CF_EXPORT
 CFIndex CFStringGetBytes(CFStringRef theString, CFRange range, CFStringEncoding encoding, UInt8 lossByte, Boolean isExternalRepresentation, UInt8 *buffer, CFIndex maxBufLen, CFIndex *usedBufLen);
 
 /* Convenience functions String <-> Data. These generate "external" formats, that is, formats that
 */
 CF_EXPORT
 CFIndex CFStringGetBytes(CFStringRef theString, CFRange range, CFStringEncoding encoding, UInt8 lossByte, Boolean isExternalRepresentation, UInt8 *buffer, CFIndex maxBufLen, CFIndex *usedBufLen);
 
 /* Convenience functions String <-> Data. These generate "external" formats, that is, formats that

-   can be written out to disk. For instance, if the encoding is Unicode, CFStringCreateFromExternalRepresentation()
-   pays attention to the BOM character (if any) and does byte swapping if necessary.
-   Similarly CFStringCreateExternalRepresentation() will always include a BOM character if the encoding is
-   Unicode. See above for description of lossByte.
+   can be written out to disk. For instance, if the encoding is Unicode,
+   CFStringCreateFromExternalRepresentation() pays attention to the BOM character (if any) 
+   and does byte swapping if necessary. Similarly CFStringCreateExternalRepresentation() will  
+   include a BOM character if appropriate. See CFStringGetBytes() for more on this and lossByte.

 */
 CF_EXPORT
 CFStringRef CFStringCreateFromExternalRepresentation(CFAllocatorRef alloc, CFDataRef data, CFStringEncoding encoding); /* May return NULL on conversion error */
 */
 CF_EXPORT
 CFStringRef CFStringCreateFromExternalRepresentation(CFAllocatorRef alloc, CFDataRef data, CFStringEncoding encoding); /* May return NULL on conversion error */


@@ -364,8 +386,7 @@ CFStringRef CFStringCreateWithFileSystemRepresentation(CFAllocatorRef alloc, con
 
 /*** Comparison functions. ***/
 
 
 /*** Comparison functions. ***/
 

-/* Find and compare flags; these are OR'ed together as compareOptions or searchOptions in the various functions. 
-   This typedef doesn't appear in the functions; instead the argument is CFOptionFlags. 
+/* Find and compare flags; these are OR'ed together and provided as CFStringCompareFlags in the various functions. 

 */
 enum { 
     kCFCompareCaseInsensitive = 1,     
 */
 enum { 
     kCFCompareCaseInsensitive = 1,     


@@ -374,12 +395,12 @@ enum {
     kCFCompareNonliteral = 16,         /* If specified, loose equivalence is performed (o-umlaut == o, umlaut) */
     kCFCompareLocalized = 32,          /* User's default locale is used for the comparisons */
     kCFCompareNumerically = 64         /* Numeric comparison is used; that is, Foo2.txt < Foo7.txt < Foo25.txt */
     kCFCompareNonliteral = 16,         /* If specified, loose equivalence is performed (o-umlaut == o, umlaut) */
     kCFCompareLocalized = 32,          /* User's default locale is used for the comparisons */
     kCFCompareNumerically = 64         /* Numeric comparison is used; that is, Foo2.txt < Foo7.txt < Foo25.txt */

-#if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_5
+#if MAC_OS_X_VERSION_10_5 <= MAC_OS_X_VERSION_MAX_ALLOWED

     ,
     kCFCompareDiacriticInsensitive = 128, /* If specified, ignores diacritics (o-umlaut == o) */
     kCFCompareWidthInsensitive = 256, /* If specified, ignores width differences ('a' == UFF41) */
     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) */
     ,
     kCFCompareDiacriticInsensitive = 128, /* If specified, ignores diacritics (o-umlaut == o) */
     kCFCompareWidthInsensitive = 256, /* If specified, ignores width differences ('a' == UFF41) */
     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) */

-#endif /* MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_5 */
+#endif /* MAC_OS_X_VERSION_10_5 <= MAC_OS_X_VERSION_MAX_ALLOWED */

 };
 typedef CFOptionFlags CFStringCompareFlags;
 
 };
 typedef CFOptionFlags CFStringCompareFlags;
 


@@ -388,41 +409,37 @@ locale == NULL indicates canonical locale (the return value from CFLocaleGetSyst
 kCFCompareNumerically, added in 10.2, does not work if kCFCompareLocalized is specified on systems before 10.3
 kCFCompareBackwards and kCFCompareAnchored are not applicable.
 */
 kCFCompareNumerically, added in 10.2, does not work if kCFCompareLocalized is specified on systems before 10.3
 kCFCompareBackwards and kCFCompareAnchored are not applicable.
 */

-#if !defined (__WIN32__)
-#if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_5
+#if MAC_OS_X_VERSION_10_5 <= MAC_OS_X_VERSION_MAX_ALLOWED

 CF_EXPORT
 CF_EXPORT

-CFComparisonResult CFStringCompareWithOptionsAndLocale(CFStringRef theString1, CFStringRef theString2, CFRange rangeToCompare, CFOptionFlags compareOptions, CFLocaleRef locale) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
-#endif /* MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_5 */
-#endif //__WIN32__
+CFComparisonResult CFStringCompareWithOptionsAndLocale(CFStringRef theString1, CFStringRef theString2, CFRange rangeToCompare, CFStringCompareFlags compareOptions, CFLocaleRef locale) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
+#endif /* MAC_OS_X_VERSION_10_5 <= MAC_OS_X_VERSION_MAX_ALLOWED */

 
 /* Comparison convenience. Uses the current user locale (the return value from CFLocaleCopyCurrent()) if kCFCompareLocalized.
 */
 CF_EXPORT
 
 /* Comparison convenience. Uses the current user locale (the return value from CFLocaleCopyCurrent()) if kCFCompareLocalized.
 */
 CF_EXPORT

-CFComparisonResult CFStringCompareWithOptions(CFStringRef theString1, CFStringRef theString2, CFRange rangeToCompare, CFOptionFlags compareOptions);
+CFComparisonResult CFStringCompareWithOptions(CFStringRef theString1, CFStringRef theString2, CFRange rangeToCompare, CFStringCompareFlags compareOptions);

 
 /* Comparison convenience suitable for passing as sorting functions.
    kCFCompareNumerically, added in 10.2, does not work if kCFCompareLocalized is specified on systems before 10.3
    kCFCompareBackwards and kCFCompareAnchored are not applicable.
 */
 CF_EXPORT
 
 /* Comparison convenience suitable for passing as sorting functions.
    kCFCompareNumerically, added in 10.2, does not work if kCFCompareLocalized is specified on systems before 10.3
    kCFCompareBackwards and kCFCompareAnchored are not applicable.
 */
 CF_EXPORT

-CFComparisonResult CFStringCompare(CFStringRef theString1, CFStringRef theString2, CFOptionFlags compareOptions);
+CFComparisonResult CFStringCompare(CFStringRef theString1, CFStringRef theString2, CFStringCompareFlags compareOptions);

 
 /* CFStringFindWithOptionsAndLocale() returns the found range in the CFRange * argument; you can pass NULL for simple discovery check.
  locale == NULL indicates canonical locale (the return value from CFLocaleGetSystem()).
  If stringToFind is the empty string (zero length), nothing is found.
  Ignores the kCFCompareNumerically option.
 */
 
 /* CFStringFindWithOptionsAndLocale() returns the found range in the CFRange * argument; you can pass NULL for simple discovery check.
  locale == NULL indicates canonical locale (the return value from CFLocaleGetSystem()).
  If stringToFind is the empty string (zero length), nothing is found.
  Ignores the kCFCompareNumerically option.
 */

-#if !defined (__WIN32__)
-#if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_5
+#if MAC_OS_X_VERSION_10_5 <= MAC_OS_X_VERSION_MAX_ALLOWED

 CF_EXPORT
 CF_EXPORT

-Boolean CFStringFindWithOptionsAndLocale(CFStringRef theString, CFStringRef stringToFind, CFRange rangeToSearch, CFOptionFlags searchOptions, CFLocaleRef locale, CFRange *result) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
-#endif /* MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_5 */
-#endif //__WIN32__
+Boolean CFStringFindWithOptionsAndLocale(CFStringRef theString, CFStringRef stringToFind, CFRange rangeToSearch, CFStringCompareFlags searchOptions, CFLocaleRef locale, CFRange *result) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
+#endif /* MAC_OS_X_VERSION_10_5 <= MAC_OS_X_VERSION_MAX_ALLOWED */

 
 /* Find convenience. Uses the current user locale (the return value from CFLocaleCopyCurrent()) if kCFCompareLocalized.
 */
 CF_EXPORT
 
 /* Find convenience. Uses the current user locale (the return value from CFLocaleCopyCurrent()) if kCFCompareLocalized.
 */
 CF_EXPORT

-Boolean CFStringFindWithOptions(CFStringRef theString, CFStringRef stringToFind, CFRange rangeToSearch, CFOptionFlags searchOptions, CFRange *result);
+Boolean CFStringFindWithOptions(CFStringRef theString, CFStringRef stringToFind, CFRange rangeToSearch, CFStringCompareFlags searchOptions, CFRange *result);

 
 /* CFStringCreateArrayWithFindResults() returns an array of CFRange pointers, or NULL if there are no matches.
    Overlapping instances are not found; so looking for "AA" in "AAA" finds just one range.
 
 /* CFStringCreateArrayWithFindResults() returns an array of CFRange pointers, or NULL if there are no matches.
    Overlapping instances are not found; so looking for "AA" in "AAA" finds just one range.


@@ -433,12 +450,12 @@ Boolean CFStringFindWithOptions(CFStringRef theString, CFStringRef stringToFind,
    Ignores the kCFCompareNumerically option.
 */
 CF_EXPORT
    Ignores the kCFCompareNumerically option.
 */
 CF_EXPORT

-CFArrayRef CFStringCreateArrayWithFindResults(CFAllocatorRef alloc, CFStringRef theString, CFStringRef stringToFind, CFRange rangeToSearch, CFOptionFlags compareOptions);
+CFArrayRef CFStringCreateArrayWithFindResults(CFAllocatorRef alloc, CFStringRef theString, CFStringRef stringToFind, CFRange rangeToSearch, CFStringCompareFlags compareOptions);

 
 /* Find conveniences; see comments above concerning empty string and options.
 */
 CF_EXPORT
 
 /* Find conveniences; see comments above concerning empty string and options.
 */
 CF_EXPORT

-CFRange CFStringFind(CFStringRef theString, CFStringRef stringToFind, CFOptionFlags compareOptions);
+CFRange CFStringFind(CFStringRef theString, CFStringRef stringToFind, CFStringCompareFlags compareOptions);

 
 CF_EXPORT
 Boolean CFStringHasPrefix(CFStringRef theString, CFStringRef prefix);
 
 CF_EXPORT
 Boolean CFStringHasPrefix(CFStringRef theString, CFStringRef prefix);


@@ -491,7 +508,7 @@ CF_EXPORT CFRange CFStringGetRangeOfComposedCharactersAtIndex(CFStringRef theStr
        @result true, if at least a character which is a member of the character
                        set is found and result is filled, otherwise, false.
 */
        @result true, if at least a character which is a member of the character
                        set is found and result is filled, otherwise, false.
 */

-CF_EXPORT Boolean CFStringFindCharacterFromSet(CFStringRef theString, CFCharacterSetRef theSet, CFRange rangeToSearch, CFOptionFlags searchOptions, CFRange *result);
+CF_EXPORT Boolean CFStringFindCharacterFromSet(CFStringRef theString, CFCharacterSetRef theSet, CFRange rangeToSearch, CFStringCompareFlags searchOptions, CFRange *result);

 #endif
 
 /* Find range of bounds of the line(s) that span the indicated range (startIndex, numChars),
 #endif
 
 /* Find range of bounds of the line(s) that span the indicated range (startIndex, numChars),


@@ -549,10 +566,10 @@ CF_EXPORT
 void CFStringAppendCString(CFMutableStringRef theString, const char *cStr, CFStringEncoding encoding);
 
 CF_EXPORT
 void CFStringAppendCString(CFMutableStringRef theString, const char *cStr, CFStringEncoding encoding);
 
 CF_EXPORT

-void CFStringAppendFormat(CFMutableStringRef theString, CFDictionaryRef formatOptions, CFStringRef format, ...);
+void CFStringAppendFormat(CFMutableStringRef theString, CFDictionaryRef formatOptions, CFStringRef format, ...) CF_FORMAT_FUNCTION(3,4);

 
 CF_EXPORT
 
 CF_EXPORT

-void CFStringAppendFormatAndArguments(CFMutableStringRef theString, CFDictionaryRef formatOptions, CFStringRef format, va_list arguments);
+void CFStringAppendFormatAndArguments(CFMutableStringRef theString, CFDictionaryRef formatOptions, CFStringRef format, va_list arguments) CF_FORMAT_FUNCTION(3,0);

 
 CF_EXPORT
 void CFStringInsert(CFMutableStringRef str, CFIndex idx, CFStringRef insertedStr);
 
 CF_EXPORT
 void CFStringInsert(CFMutableStringRef str, CFIndex idx, CFStringRef insertedStr);


@@ -576,7 +593,7 @@ void CFStringReplaceAll(CFMutableStringRef theString, CFStringRef replacement);
    Returns number of replacements performed.
 */
 CF_EXPORT
    Returns number of replacements performed.
 */
 CF_EXPORT

-CFIndex CFStringFindAndReplace(CFMutableStringRef theString, CFStringRef stringToFind, CFStringRef replacementString, CFRange rangeToSearch, CFOptionFlags compareOptions);
+CFIndex CFStringFindAndReplace(CFMutableStringRef theString, CFStringRef stringToFind, CFStringRef replacementString, CFRange rangeToSearch, CFStringCompareFlags compareOptions);

 
 #endif
 
 
 #endif
 


@@ -659,7 +676,7 @@ typedef CFIndex CFStringNormalizationForm;
 CF_EXPORT void CFStringNormalize(CFMutableStringRef theString, CFStringNormalizationForm theForm);
 #endif
 
 CF_EXPORT void CFStringNormalize(CFMutableStringRef theString, CFStringNormalizationForm theForm);
 #endif
 

-#if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_5
+#if MAC_OS_X_VERSION_10_5 <= MAC_OS_X_VERSION_MAX_ALLOWED

 /*!
        @function CFStringFold
        Folds the string into the form specified by the flags.
 /*!
        @function CFStringFold
        Folds the string into the form specified by the flags.


@@ -686,12 +703,13 @@ CF_EXPORT void CFStringNormalize(CFMutableStringRef theString, CFStringNormaliza
 
 CF_EXPORT
 void CFStringFold(CFMutableStringRef theString, CFOptionFlags theFlags, CFLocaleRef theLocale) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
 
 CF_EXPORT
 void CFStringFold(CFMutableStringRef theString, CFOptionFlags theFlags, CFLocaleRef theLocale) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

-#endif /* MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_5 */
+#endif /* MAC_OS_X_VERSION_10_5 <= MAC_OS_X_VERSION_MAX_ALLOWED */

 
 /* 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.
 
 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.
 */
 
 /* 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.
 
 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.
 */

+CF_EXPORT

 Boolean CFStringTransform(CFMutableStringRef string, CFRange *range, CFStringRef transform, Boolean reverse) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
 
 /* Transform identifiers for CFStringTransform()
 Boolean CFStringTransform(CFMutableStringRef string, CFRange *range, CFStringRef transform, Boolean reverse) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
 
 /* Transform identifiers for CFStringTransform()


@@ -819,11 +837,38 @@ CF_INLINE UniChar CFStringGetCharacterFromInlineBuffer(CFStringInlineBuffer *buf
 
 
 
 
 
 

+/* UTF-16 surrogate support
+ */
+CF_INLINE Boolean CFStringIsSurrogateHighCharacter(UniChar character) {
+    return ((character >= 0xD800UL) && (character <= 0xDBFFUL) ? true : false);
+}
+
+CF_INLINE Boolean CFStringIsSurrogateLowCharacter(UniChar character) {
+    return ((character >= 0xDC00UL) && (character <= 0xDFFFUL) ? true : false);
+}
+
+CF_INLINE UTF32Char CFStringGetLongCharacterForSurrogatePair(UniChar surrogateHigh, UniChar surrogateLow) {
+    return ((surrogateHigh - 0xD800UL) << 10) + (surrogateLow - 0xDC00UL) + 0x0010000UL;
+}

 
 

+// 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.
+CF_INLINE Boolean CFStringGetSurrogatePairForLongCharacter(UTF32Char character, UniChar *surrogates) {
+    if ((character > 0xFFFFUL) && (character < 0x110000UL)) { // Non-BMP character
+        character -= 0x10000;
+        if (NULL != surrogates) {
+            surrogates[0] = (UniChar)((character >> 10) + 0xD800UL);
+            surrogates[1] = (UniChar)((character & 0x3FF) + 0xDC00UL);
+        }
+        return true;
+    } else {
+        if (NULL != surrogates) *surrogates = (UniChar)character;
+        return false;
+    }
+}

 
 /* Rest of the stuff in this file is private and should not be used directly
 */
 
 /* Rest of the stuff in this file is private and should not be used directly
 */

-/* For debugging only
+/* For debugging only; output goes to stderr

    Use CFShow() to printf the description of any CFType;
    Use CFShowStr() to printf detailed info about a CFString
 */
    Use CFShow() to printf the description of any CFType;
    Use CFShowStr() to printf detailed info about a CFString
 */


@@ -840,4 +885,3 @@ CFStringRef  __CFStringMakeConstantString(const char *cStr);        /* Private; do not
 CF_EXTERN_C_END
 
 #endif /* ! __COREFOUNDATION_CFSTRING__ */
 CF_EXTERN_C_END
 
 #endif /* ! __COREFOUNDATION_CFSTRING__ */

-