CFCharacterSet.h

   1 /*
   2  * Copyright (c) 2010 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*      CFCharacterSet.h
  25         Copyright (c) 1999-2009, Apple Inc. All rights reserved.
  26 */
  27
  28 /*!
  29         @header CFCharacterSet
  30         CFCharacterSet represents a set, or a bag, of Unicode characters.
  31         The API consists of 3 groups:
  32         1) creation/manipulation of CFCharacterSet instances,
  33         2) query of a single Unicode character membership,
  34         and 3) bitmap representation related (reading/writing).
  35         Conceptually, CFCharacterSet is a 136K byte bitmap array of
  36         which each bit represents a Unicode code point.  It could
  37         contain the Unicode characters in ISO 10646 Basic Multilingual
  38         Plane (BMP) and characters in Plane 1 through Plane 16
  39         accessible via surrogate paris in the Unicode Transformation
  40         Format, 16-bit encoding form (UTF-16).  In other words, it can
  41         store values from 0x00000 to 0x10FFFF in the Unicode
  42         Transformation Format, 32-bit encoding form (UTF-32).  However,
  43         in general, how CFCharacterSet stores the information is an
  44         implementation detail.  Note even CFData used for the external
  45         bitmap representation rarely has 136K byte.  For detailed
  46         discussion of the external bitmap representation, refer to the
  47         comments for CFCharacterSetCreateWithBitmapRepresentation below.
  48         Note that the existance of non-BMP characters in a character set
  49         does not imply the membership of the corresponding surrogate
  50         characters.  For example, a character set with U+10000 does not
  51         match with U+D800.
  52 */
  53
  54 #if !defined(__COREFOUNDATION_CFCHARACTERSET__)
  55 #define __COREFOUNDATION_CFCHARACTERSET__ 1
  56
  57 #include <CoreFoundation/CFBase.h>
  58 #include <CoreFoundation/CFData.h>
  59
  60 CF_EXTERN_C_BEGIN
  61
  62 /*!
  63         @typedef CFCharacterSetRef
  64         This is the type of a reference to immutable CFCharacterSets.
  65 */
  66 typedef const struct __CFCharacterSet * CFCharacterSetRef;
  67
  68 /*!
  69         @typedef CFMutableCharacterSetRef
  70         This is the type of a reference to mutable CFMutableCharacterSets.
  71 */
  72 typedef struct __CFCharacterSet * CFMutableCharacterSetRef;
  73
  74 /*!
  75         @typedef CFCharacterSetPredefinedSet
  76         Type of the predefined CFCharacterSet selector values.
  77 */
  78
  79 enum {
  80     kCFCharacterSetControl = 1, /* Control character set (Unicode General Category Cc and Cf) */
  81     kCFCharacterSetWhitespace, /* Whitespace character set (Unicode General Category Zs and U0009 CHARACTER TABULATION) */
  82     kCFCharacterSetWhitespaceAndNewline,  /* Whitespace and Newline character set (Unicode General Category Z*, U000A ~ U000D, and U0085) */
  83     kCFCharacterSetDecimalDigit, /* Decimal digit character set */
  84     kCFCharacterSetLetter, /* Letter character set (Unicode General Category L* & M*) */
  85     kCFCharacterSetLowercaseLetter, /* Lowercase character set (Unicode General Category Ll) */
  86     kCFCharacterSetUppercaseLetter, /* Uppercase character set (Unicode General Category Lu and Lt) */
  87     kCFCharacterSetNonBase, /* Non-base character set (Unicode General Category M*) */
  88     kCFCharacterSetDecomposable, /* Canonically decomposable character set */
  89     kCFCharacterSetAlphaNumeric, /* Alpha Numeric character set (Unicode General Category L*, M*, & N*) */
  90     kCFCharacterSetPunctuation, /* Punctuation character set (Unicode General Category P*) */
  91 #if MAC_OS_X_VERSION_10_2 <= MAC_OS_X_VERSION_MAX_ALLOWED
  92     kCFCharacterSetCapitalizedLetter = 13, /* Titlecase character set (Unicode General Category Lt) */
  93 #endif
  94 #if MAC_OS_X_VERSION_10_3 <= MAC_OS_X_VERSION_MAX_ALLOWED
  95     kCFCharacterSetSymbol = 14, /* Symbol character set (Unicode General Category S*) */
  96 #endif
  97 #if MAC_OS_X_VERSION_10_5 <= MAC_OS_X_VERSION_MAX_ALLOWED
  98     kCFCharacterSetNewline = 15, /* Newline character set (U000A ~ U000D, U0085, U2028, and U2029) */
  99 #endif
 100     kCFCharacterSetIllegal = 12/* Illegal character set */
 101 };
 102 typedef CFIndex CFCharacterSetPredefinedSet;
 103
 104 /*!
 105         @function CFCharacterSetGetTypeID
 106         Returns the type identifier of all CFCharacterSet instances.
 107 */
 108 CF_EXPORT
 109 CFTypeID CFCharacterSetGetTypeID(void);
 110
 111 /*!
 112         @function CFCharacterSetGetPredefined
 113         Returns a predefined CFCharacterSet instance.
 114         @param theSetIdentifier The CFCharacterSetPredefinedSet selector
 115                 which specifies the predefined character set.  If the
 116                 value is not in CFCharacterSetPredefinedSet, the behavior
 117                 is undefined.
 118         @result A reference to the predefined immutable CFCharacterSet.
 119                 This instance is owned by CF.
 120 */
 121 CF_EXPORT
 122 CFCharacterSetRef CFCharacterSetGetPredefined(CFCharacterSetPredefinedSet theSetIdentifier);
 123
 124 /*!
 125         @function CFCharacterSetCreateWithCharactersInRange
 126         Creates a new immutable character set with the values from the given range.
 127         @param alloc The CFAllocator which should be used to allocate
 128                 memory for the array and its storage for values. This
 129                 parameter may be NULL in which case the current default
 130                 CFAllocator is used. If this reference is not a valid
 131                 CFAllocator, the behavior is undefined.
 132         @param theRange The CFRange which should be used to specify the
 133                 Unicode range the character set is filled with.  It
 134                 accepts the range in 32-bit in the UTF-32 format.  The
 135                 valid character point range is from 0x00000 to 0x10FFFF.
 136                 If the range is outside of the valid Unicode character
 137                 point, the behavior is undefined.
 138         @result A reference to the new immutable CFCharacterSet.
 139 */
 140 CF_EXPORT
 141 CFCharacterSetRef CFCharacterSetCreateWithCharactersInRange(CFAllocatorRef alloc, CFRange theRange);
 142
 143 /*!
 144         @function CFCharacterSetCreateWithCharactersInString
 145         Creates a new immutable character set with the values in the given string.
 146         @param alloc The CFAllocator which should be used to allocate
 147                 memory for the array and its storage for values. This
 148                 parameter may be NULL in which case the current default
 149                 CFAllocator is used. If this reference is not a valid
 150                 CFAllocator, the behavior is undefined.
 151         @param theString The CFString which should be used to specify
 152                 the Unicode characters the character set is filled with.
 153                 If this parameter is not a valid CFString, the behavior
 154                 is undefined.
 155         @result A reference to the new immutable CFCharacterSet.
 156 */
 157 CF_EXPORT
 158 CFCharacterSetRef CFCharacterSetCreateWithCharactersInString(CFAllocatorRef alloc, CFStringRef theString);
 159
 160 /*!
 161         @function CFCharacterSetCreateWithBitmapRepresentation
 162         Creates a new immutable character set with the bitmap representtion in the given data.
 163         @param alloc The CFAllocator which should be used to allocate
 164                 memory for the array and its storage for values. This
 165                 parameter may be NULL in which case the current default
 166                 CFAllocator is used. If this reference is not a valid
 167                 CFAllocator, the behavior is undefined.
 168         @param theData The CFData which should be used to specify the
 169                 bitmap representation of the Unicode character points
 170                 the character set is filled with.  The bitmap
 171                 representation could contain all the Unicode character
 172                 range starting from BMP to Plane 16.  The first 8192 bytes
 173                 of the data represent the BMP range.  The BMP range 8192
 174                 bytes can be followed by zero to sixteen 8192 byte
 175                 bitmaps, each one with the plane index byte prepended.
 176                 For example, the bitmap representing the BMP and Plane 2
 177                 has the size of 16385 bytes (8192 bytes for BMP, 1 byte
 178                 index + 8192 bytes bitmap for Plane 2).  The plane index
 179                 byte, in this case, contains the integer value two.  If
 180                 this parameter is not a valid CFData or it contains a
 181                 Plane index byte outside of the valid Plane range
 182                 (1 to 16), the behavior is undefined.
 183         @result A reference to the new immutable CFCharacterSet.
 184 */
 185 CF_EXPORT
 186 CFCharacterSetRef CFCharacterSetCreateWithBitmapRepresentation(CFAllocatorRef alloc, CFDataRef theData);
 187
 188 #if MAC_OS_X_VERSION_10_2 <= MAC_OS_X_VERSION_MAX_ALLOWED
 189 /*!
 190         @function CFCharacterSetCreateInvertedSet
 191         Creates a new immutable character set that is the invert of the specified character set.
 192         @param alloc The CFAllocator which should be used to allocate
 193                         memory for the array and its storage for values. This
 194                         parameter may be NULL in which case the current default
 195                         CFAllocator is used. If this reference is not a valid
 196                         CFAllocator, the behavior is undefined.
 197         @param theSet The CFCharacterSet which is to be inverted.  If this
 198                                 parameter is not a valid CFCharacterSet, the behavior is
 199                         undefined.
 200         @result A reference to the new immutable CFCharacterSet.
 201 */
 202 CF_EXPORT CFCharacterSetRef CFCharacterSetCreateInvertedSet(CFAllocatorRef alloc, CFCharacterSetRef theSet);
 203
 204 /*!
 205         @function CFCharacterSetIsSupersetOfSet
 206         Reports whether or not the character set is a superset of the character set specified as the second parameter.
 207         @param theSet  The character set to be checked for the membership of theOtherSet.
 208                 If this parameter is not a valid CFCharacterSet, the behavior is undefined.
 209         @param theOtherset  The character set to be checked whether or not it is a subset of theSet.
 210                 If this parameter is not a valid CFCharacterSet, the behavior is undefined.
 211 */
 212 CF_EXPORT Boolean CFCharacterSetIsSupersetOfSet(CFCharacterSetRef theSet, CFCharacterSetRef theOtherset);
 213
 214 /*!
 215         @function CFCharacterSetHasMemberInPlane
 216         Reports whether or not the character set contains at least one member character in the specified plane.
 217         @param theSet  The character set to be checked for the membership.  If this
 218                 parameter is not a valid CFCharacterSet, the behavior is undefined.
 219         @param thePlane  The plane number to be checked for the membership.
 220                 The valid value range is from 0 to 16.  If the value is outside of the valid
 221                 plane number range, the behavior is undefined.
 222 */
 223 CF_EXPORT Boolean CFCharacterSetHasMemberInPlane(CFCharacterSetRef theSet, CFIndex thePlane);
 224 #endif
 225
 226 /*!
 227         @function CFCharacterSetCreateMutable
 228         Creates a new empty mutable character set.
 229         @param allocator The CFAllocator which should be used to allocate
 230                 memory for the array and its storage for values. This
 231                 parameter may be NULL in which case the current default
 232                 CFAllocator is used. If this reference is not a valid
 233                 CFAllocator, the behavior is undefined.
 234         @result A reference to the new mutable CFCharacterSet.
 235 */
 236 CF_EXPORT
 237 CFMutableCharacterSetRef CFCharacterSetCreateMutable(CFAllocatorRef alloc);
 238
 239 #if MAC_OS_X_VERSION_10_3 <= MAC_OS_X_VERSION_MAX_ALLOWED
 240 /*!
 241         @function CFCharacterSetCreateCopy
 242         Creates a new character set with the values from the given character set.  This function tries to compact the backing store where applicable.
 243         @param allocator The CFAllocator which should be used to allocate
 244                 memory for the array and its storage for values. This
 245                 parameter may be NULL in which case the current default
 246                 CFAllocator is used. If this reference is not a valid
 247                 CFAllocator, the behavior is undefined.
 248         @param theSet The CFCharacterSet which is to be copied.  If this
 249                 parameter is not a valid CFCharacterSet, the behavior is
 250                 undefined.
 251         @result A reference to the new CFCharacterSet.
 252 */
 253 CF_EXPORT
 254 CFCharacterSetRef CFCharacterSetCreateCopy(CFAllocatorRef alloc, CFCharacterSetRef theSet) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 255 #endif
 256
 257 /*!
 258         @function CFCharacterSetCreateMutableCopy
 259         Creates a new mutable character set with the values from the given character set.
 260         @param allocator The CFAllocator which should be used to allocate
 261                 memory for the array and its storage for values. This
 262                 parameter may be NULL in which case the current default
 263                 CFAllocator is used. If this reference is not a valid
 264                 CFAllocator, the behavior is undefined.
 265         @param theSet The CFCharacterSet which is to be copied.  If this
 266                 parameter is not a valid CFCharacterSet, the behavior is
 267                 undefined.
 268         @result A reference to the new mutable CFCharacterSet.
 269 */
 270 CF_EXPORT
 271 CFMutableCharacterSetRef CFCharacterSetCreateMutableCopy(CFAllocatorRef alloc, CFCharacterSetRef theSet);
 272
 273 /*!
 274         @function CFCharacterSetIsCharacterMember
 275         Reports whether or not the Unicode character is in the character set.
 276         @param theSet The character set to be searched. If this parameter
 277                 is not a valid CFCharacterSet, the behavior is undefined.
 278         @param theChar The Unicode character for which to test against the
 279                 character set.  Note that this function takes 16-bit Unicode
 280                 character value; hence, it does not support access to the
 281                 non-BMP planes.
 282         @result true, if the value is in the character set, otherwise false.
 283 */
 284 CF_EXPORT
 285 Boolean CFCharacterSetIsCharacterMember(CFCharacterSetRef theSet, UniChar theChar);
 286
 287 #if MAC_OS_X_VERSION_10_2 <= MAC_OS_X_VERSION_MAX_ALLOWED
 288 /*!
 289         @function CFCharacterSetIsLongCharacterMember
 290         Reports whether or not the UTF-32 character is in the character set.
 291         @param theSet The character set to be searched. If this parameter
 292                          is not a valid CFCharacterSet, the behavior is undefined.
 293         @param theChar The UTF-32 character for which to test against the
 294                         character set.
 295         @result true, if the value is in the character set, otherwise false.
 296 */
 297 CF_EXPORT Boolean CFCharacterSetIsLongCharacterMember(CFCharacterSetRef theSet, UTF32Char theChar);
 298 #endif
 299
 300 /*!
 301         @function CFCharacterSetCreateBitmapRepresentation
 302         Creates a new immutable data with the bitmap representation from the given character set.
 303         @param allocator The CFAllocator which should be used to allocate
 304                 memory for the array and its storage for values. This
 305                 parameter may be NULL in which case the current default
 306                 CFAllocator is used. If this reference is not a valid
 307                 CFAllocator, the behavior is undefined.
 308         @param theSet The CFCharacterSet which is to be used create the
 309                 bitmap representation from.  Refer to the comments for
 310                 CFCharacterSetCreateWithBitmapRepresentation for the
 311                 detailed discussion of the bitmap representation format.
 312                 If this parameter is not a valid CFCharacterSet, the
 313                 behavior is undefined.
 314         @result A reference to the new immutable CFData.
 315 */
 316 CF_EXPORT
 317 CFDataRef CFCharacterSetCreateBitmapRepresentation(CFAllocatorRef alloc, CFCharacterSetRef theSet);
 318
 319 /*!
 320         @function CFCharacterSetAddCharactersInRange
 321         Adds the given range to the charaacter set.
 322         @param theSet The character set to which the range is to be added.
 323                 If this parameter is not a valid mutable CFCharacterSet,
 324                 the behavior is undefined.
 325         @param theRange The range to add to the character set.  It accepts
 326                 the range in 32-bit in the UTF-32 format.  The valid
 327                 character point range is from 0x00000 to 0x10FFFF.  If the
 328                 range is outside of the valid Unicode character point,
 329                 the behavior is undefined.
 330 */
 331 CF_EXPORT
 332 void CFCharacterSetAddCharactersInRange(CFMutableCharacterSetRef theSet, CFRange theRange);
 333
 334 /*!
 335         @function CFCharacterSetRemoveCharactersInRange
 336         Removes the given range from the charaacter set.
 337         @param theSet The character set from which the range is to be
 338                 removed.  If this parameter is not a valid mutable
 339                 CFCharacterSet, the behavior is undefined.
 340         @param theRange The range to remove from the character set.
 341                 It accepts the range in 32-bit in the UTF-32 format.
 342                 The valid character point range is from 0x00000 to 0x10FFFF.
 343                 If the range is outside of the valid Unicode character point,
 344                 the behavior is undefined.
 345 */
 346 CF_EXPORT
 347 void CFCharacterSetRemoveCharactersInRange(CFMutableCharacterSetRef theSet, CFRange theRange);
 348
 349 /*!
 350         @function CFCharacterSetAddCharactersInString
 351         Adds the characters in the given string to the charaacter set.
 352         @param theSet The character set to which the characters in the
 353                 string are to be added.  If this parameter is not a
 354                 valid mutable CFCharacterSet, the behavior is undefined.
 355         @param theString The string to add to the character set.
 356                 If this parameter is not a valid CFString, the behavior
 357                 is undefined.
 358 */
 359 CF_EXPORT
 360 void CFCharacterSetAddCharactersInString(CFMutableCharacterSetRef theSet,  CFStringRef theString);
 361
 362 /*!
 363         @function CFCharacterSetRemoveCharactersInString
 364         Removes the characters in the given string from the charaacter set.
 365         @param theSet The character set from which the characters in the
 366                 string are to be remove.  If this parameter is not a
 367                 valid mutable CFCharacterSet, the behavior is undefined.
 368         @param theString The string to remove from the character set.
 369                 If this parameter is not a valid CFString, the behavior
 370                 is undefined.
 371 */
 372 CF_EXPORT
 373 void CFCharacterSetRemoveCharactersInString(CFMutableCharacterSetRef theSet, CFStringRef theString);
 374
 375 /*!
 376         @function CFCharacterSetUnion
 377         Forms the union with the given character set.
 378         @param theSet The destination character set into which the
 379                 union of the two character sets is stored.  If this
 380                 parameter is not a valid mutable CFCharacterSet, the
 381                 behavior is undefined.
 382         @param theOtherSet The character set with which the union is
 383                 formed.  If this parameter is not a valid CFCharacterSet,
 384                 the behavior is undefined.
 385 */
 386 CF_EXPORT
 387 void CFCharacterSetUnion(CFMutableCharacterSetRef theSet, CFCharacterSetRef theOtherSet);
 388
 389 /*!
 390         @function CFCharacterSetIntersect
 391         Forms the intersection with the given character set.
 392         @param theSet The destination character set into which the
 393                 intersection of the two character sets is stored.
 394                 If this parameter is not a valid mutable CFCharacterSet,
 395                 the behavior is undefined.
 396         @param theOtherSet The character set with which the intersection
 397                 is formed.  If this parameter is not a valid CFCharacterSet,
 398                 the behavior is undefined.
 399 */
 400 CF_EXPORT
 401 void CFCharacterSetIntersect(CFMutableCharacterSetRef theSet, CFCharacterSetRef theOtherSet);
 402
 403 /*!
 404         @function CFCharacterSetInvert
 405         Inverts the content of the given character set.
 406         @param theSet The character set to be inverted.
 407                 If this parameter is not a valid mutable CFCharacterSet,
 408                 the behavior is undefined.
 409 */
 410 CF_EXPORT
 411 void CFCharacterSetInvert(CFMutableCharacterSetRef theSet);
 412
 413 CF_EXTERN_C_END
 414
 415 #endif /* ! __COREFOUNDATION_CFCHARACTERSET__ */
 416