CFCharacterSet.h

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