String.subproj/CFString.h

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