String.subproj/CFString.h

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