CFCharacterSet.h

   1 /*
   2  * Copyright (c) 2012 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-2011, 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     kCFCharacterSetCapitalizedLetter = 13, /* Titlecase character set (Unicode General Category Lt) */
  92     kCFCharacterSetSymbol = 14, /* Symbol character set (Unicode General Category S*) */
  93 #if MAC_OS_X_VERSION_10_5 <= MAC_OS_X_VERSION_MAX_ALLOWED
  94     kCFCharacterSetNewline = 15, /* Newline character set (U000A ~ U000D, U0085, U2028, and U2029) */
  95 #endif
  96     kCFCharacterSetIllegal = 12/* Illegal character set */
  97 };
  98 typedef CFIndex CFCharacterSetPredefinedSet;
  99
 100 /*!
 101         @function CFCharacterSetGetTypeID
 102         Returns the type identifier of all CFCharacterSet instances.
 103 */
 104 CF_EXPORT
 105 CFTypeID CFCharacterSetGetTypeID(void);
 106
 107 /*!
 108         @function CFCharacterSetGetPredefined
 109         Returns a predefined CFCharacterSet instance.
 110         @param theSetIdentifier The CFCharacterSetPredefinedSet selector
 111                 which specifies the predefined character set.  If the
 112                 value is not in CFCharacterSetPredefinedSet, the behavior
 113                 is undefined.
 114         @result A reference to the predefined immutable CFCharacterSet.
 115                 This instance is owned by CF.
 116 */
 117 CF_EXPORT
 118 CFCharacterSetRef CFCharacterSetGetPredefined(CFCharacterSetPredefinedSet theSetIdentifier);
 119
 120 /*!
 121         @function CFCharacterSetCreateWithCharactersInRange
 122         Creates a new immutable character set with the values from the given range.
 123         @param alloc The CFAllocator which should be used to allocate
 124                 memory for the array and its storage for values. This
 125                 parameter may be NULL in which case the current default
 126                 CFAllocator is used. If this reference is not a valid
 127                 CFAllocator, the behavior is undefined.
 128         @param theRange The CFRange which should be used to specify the
 129                 Unicode range the character set is filled with.  It
 130                 accepts the range in 32-bit in the UTF-32 format.  The
 131                 valid character point range is from 0x00000 to 0x10FFFF.
 132                 If the range is outside of the valid Unicode character
 133                 point, the behavior is undefined.
 134         @result A reference to the new immutable CFCharacterSet.
 135 */
 136 CF_EXPORT
 137 CFCharacterSetRef CFCharacterSetCreateWithCharactersInRange(CFAllocatorRef alloc, CFRange theRange);
 138
 139 /*!
 140         @function CFCharacterSetCreateWithCharactersInString
 141         Creates a new immutable character set with the values in the given string.
 142         @param alloc The CFAllocator which should be used to allocate
 143                 memory for the array and its storage for values. This
 144                 parameter may be NULL in which case the current default
 145                 CFAllocator is used. If this reference is not a valid
 146                 CFAllocator, the behavior is undefined.
 147         @param theString The CFString which should be used to specify
 148                 the Unicode characters the character set is filled with.
 149                 If this parameter is not a valid CFString, the behavior
 150                 is undefined.
 151         @result A reference to the new immutable CFCharacterSet.
 152 */
 153 CF_EXPORT
 154 CFCharacterSetRef CFCharacterSetCreateWithCharactersInString(CFAllocatorRef alloc, CFStringRef theString);
 155
 156 /*!
 157         @function CFCharacterSetCreateWithBitmapRepresentation
 158         Creates a new immutable character set with the bitmap representtion in the given data.
 159         @param alloc The CFAllocator which should be used to allocate
 160                 memory for the array and its storage for values. This
 161                 parameter may be NULL in which case the current default
 162                 CFAllocator is used. If this reference is not a valid
 163                 CFAllocator, the behavior is undefined.
 164         @param theData The CFData which should be used to specify the
 165                 bitmap representation of the Unicode character points
 166                 the character set is filled with.  The bitmap
 167                 representation could contain all the Unicode character
 168                 range starting from BMP to Plane 16.  The first 8192 bytes
 169                 of the data represent the BMP range.  The BMP range 8192
 170                 bytes can be followed by zero to sixteen 8192 byte
 171                 bitmaps, each one with the plane index byte prepended.
 172                 For example, the bitmap representing the BMP and Plane 2
 173                 has the size of 16385 bytes (8192 bytes for BMP, 1 byte
 174                 index + 8192 bytes bitmap for Plane 2).  The plane index
 175                 byte, in this case, contains the integer value two.  If
 176                 this parameter is not a valid CFData or it contains a
 177                 Plane index byte outside of the valid Plane range
 178                 (1 to 16), the behavior is undefined.
 179         @result A reference to the new immutable CFCharacterSet.
 180 */
 181 CF_EXPORT
 182 CFCharacterSetRef CFCharacterSetCreateWithBitmapRepresentation(CFAllocatorRef alloc, CFDataRef theData);
 183
 184 /*!
 185         @function CFCharacterSetCreateInvertedSet
 186         Creates a new immutable character set that is the invert of the specified character set.
 187         @param alloc The CFAllocator which should be used to allocate
 188                         memory for the array and its storage for values. This
 189                         parameter may be NULL in which case the current default
 190                         CFAllocator is used. If this reference is not a valid
 191                         CFAllocator, the behavior is undefined.
 192         @param theSet The CFCharacterSet which is to be inverted.  If this
 193                                 parameter is not a valid CFCharacterSet, the behavior is
 194                         undefined.
 195         @result A reference to the new immutable CFCharacterSet.
 196 */
 197 CF_EXPORT CFCharacterSetRef CFCharacterSetCreateInvertedSet(CFAllocatorRef alloc, CFCharacterSetRef theSet);
 198
 199 /*!
 200         @function CFCharacterSetIsSupersetOfSet
 201         Reports whether or not the character set is a superset of the character set specified as the second parameter.
 202         @param theSet  The character set to be checked for the membership of theOtherSet.
 203                 If this parameter is not a valid CFCharacterSet, the behavior is undefined.
 204         @param theOtherset  The character set to be checked whether or not it is a subset of theSet.
 205                 If this parameter is not a valid CFCharacterSet, the behavior is undefined.
 206 */
 207 CF_EXPORT Boolean CFCharacterSetIsSupersetOfSet(CFCharacterSetRef theSet, CFCharacterSetRef theOtherset);
 208
 209 /*!
 210         @function CFCharacterSetHasMemberInPlane
 211         Reports whether or not the character set contains at least one member character in the specified plane.
 212         @param theSet  The character set to be checked for the membership.  If this
 213                 parameter is not a valid CFCharacterSet, the behavior is undefined.
 214         @param thePlane  The plane number to be checked for the membership.
 215                 The valid value range is from 0 to 16.  If the value is outside of the valid
 216                 plane number range, the behavior is undefined.
 217 */
 218 CF_EXPORT Boolean CFCharacterSetHasMemberInPlane(CFCharacterSetRef theSet, CFIndex thePlane);
 219
 220 /*!
 221         @function CFCharacterSetCreateMutable
 222         Creates a new empty mutable character set.
 223         @param allocator The CFAllocator which should be used to allocate
 224                 memory for the array and its storage for values. This
 225                 parameter may be NULL in which case the current default
 226                 CFAllocator is used. If this reference is not a valid
 227                 CFAllocator, the behavior is undefined.
 228         @result A reference to the new mutable CFCharacterSet.
 229 */
 230 CF_EXPORT
 231 CFMutableCharacterSetRef CFCharacterSetCreateMutable(CFAllocatorRef alloc);
 232
 233 /*!
 234         @function CFCharacterSetCreateCopy
 235         Creates a new character set with the values from the given character set.  This function tries to compact the backing store where applicable.
 236         @param allocator The CFAllocator which should be used to allocate
 237                 memory for the array and its storage for values. This
 238                 parameter may be NULL in which case the current default
 239                 CFAllocator is used. If this reference is not a valid
 240                 CFAllocator, the behavior is undefined.
 241         @param theSet The CFCharacterSet which is to be copied.  If this
 242                 parameter is not a valid CFCharacterSet, the behavior is
 243                 undefined.
 244         @result A reference to the new CFCharacterSet.
 245 */
 246 CF_EXPORT
 247 CFCharacterSetRef CFCharacterSetCreateCopy(CFAllocatorRef alloc, CFCharacterSetRef theSet);
 248
 249 /*!
 250         @function CFCharacterSetCreateMutableCopy
 251         Creates a new mutable character set with the values from the given character set.
 252         @param allocator The CFAllocator which should be used to allocate
 253                 memory for the array and its storage for values. This
 254                 parameter may be NULL in which case the current default
 255                 CFAllocator is used. If this reference is not a valid
 256                 CFAllocator, the behavior is undefined.
 257         @param theSet The CFCharacterSet which is to be copied.  If this
 258                 parameter is not a valid CFCharacterSet, the behavior is
 259                 undefined.
 260         @result A reference to the new mutable CFCharacterSet.
 261 */
 262 CF_EXPORT
 263 CFMutableCharacterSetRef CFCharacterSetCreateMutableCopy(CFAllocatorRef alloc, CFCharacterSetRef theSet);
 264
 265 /*!
 266         @function CFCharacterSetIsCharacterMember
 267         Reports whether or not the Unicode character is in the character set.
 268         @param theSet The character set to be searched. If this parameter
 269                 is not a valid CFCharacterSet, the behavior is undefined.
 270         @param theChar The Unicode character for which to test against the
 271                 character set.  Note that this function takes 16-bit Unicode
 272                 character value; hence, it does not support access to the
 273                 non-BMP planes.
 274         @result true, if the value is in the character set, otherwise false.
 275 */
 276 CF_EXPORT
 277 Boolean CFCharacterSetIsCharacterMember(CFCharacterSetRef theSet, UniChar theChar);
 278
 279 /*!
 280         @function CFCharacterSetIsLongCharacterMember
 281         Reports whether or not the UTF-32 character is in the character set.
 282         @param theSet The character set to be searched. If this parameter
 283                          is not a valid CFCharacterSet, the behavior is undefined.
 284         @param theChar The UTF-32 character for which to test against the
 285                         character set.
 286         @result true, if the value is in the character set, otherwise false.
 287 */
 288 CF_EXPORT Boolean CFCharacterSetIsLongCharacterMember(CFCharacterSetRef theSet, UTF32Char theChar);
 289
 290 /*!
 291         @function CFCharacterSetCreateBitmapRepresentation
 292         Creates a new immutable data with the bitmap representation from the given character set.
 293         @param allocator The CFAllocator which should be used to allocate
 294                 memory for the array and its storage for values. This
 295                 parameter may be NULL in which case the current default
 296                 CFAllocator is used. If this reference is not a valid
 297                 CFAllocator, the behavior is undefined.
 298         @param theSet The CFCharacterSet which is to be used create the
 299                 bitmap representation from.  Refer to the comments for
 300                 CFCharacterSetCreateWithBitmapRepresentation for the
 301                 detailed discussion of the bitmap representation format.
 302                 If this parameter is not a valid CFCharacterSet, the
 303                 behavior is undefined.
 304         @result A reference to the new immutable CFData.
 305 */
 306 CF_EXPORT
 307 CFDataRef CFCharacterSetCreateBitmapRepresentation(CFAllocatorRef alloc, CFCharacterSetRef theSet);
 308
 309 /*!
 310         @function CFCharacterSetAddCharactersInRange
 311         Adds the given range to the charaacter set.
 312         @param theSet The character set to which the range is to be added.
 313                 If this parameter is not a valid mutable CFCharacterSet,
 314                 the behavior is undefined.
 315         @param theRange The range to add to the character set.  It accepts
 316                 the range in 32-bit in the UTF-32 format.  The valid
 317                 character point range is from 0x00000 to 0x10FFFF.  If the
 318                 range is outside of the valid Unicode character point,
 319                 the behavior is undefined.
 320 */
 321 CF_EXPORT
 322 void CFCharacterSetAddCharactersInRange(CFMutableCharacterSetRef theSet, CFRange theRange);
 323
 324 /*!
 325         @function CFCharacterSetRemoveCharactersInRange
 326         Removes the given range from the charaacter set.
 327         @param theSet The character set from which the range is to be
 328                 removed.  If this parameter is not a valid mutable
 329                 CFCharacterSet, the behavior is undefined.
 330         @param theRange The range to remove from the character set.
 331                 It accepts the range in 32-bit in the UTF-32 format.
 332                 The valid character point range is from 0x00000 to 0x10FFFF.
 333                 If the range is outside of the valid Unicode character point,
 334                 the behavior is undefined.
 335 */
 336 CF_EXPORT
 337 void CFCharacterSetRemoveCharactersInRange(CFMutableCharacterSetRef theSet, CFRange theRange);
 338
 339 /*!
 340         @function CFCharacterSetAddCharactersInString
 341         Adds the characters in the given string to the charaacter set.
 342         @param theSet The character set to which the characters in the
 343                 string are to be added.  If this parameter is not a
 344                 valid mutable CFCharacterSet, the behavior is undefined.
 345         @param theString The string to add to the character set.
 346                 If this parameter is not a valid CFString, the behavior
 347                 is undefined.
 348 */
 349 CF_EXPORT
 350 void CFCharacterSetAddCharactersInString(CFMutableCharacterSetRef theSet,  CFStringRef theString);
 351
 352 /*!
 353         @function CFCharacterSetRemoveCharactersInString
 354         Removes the characters in the given string from the charaacter set.
 355         @param theSet The character set from which the characters in the
 356                 string are to be remove.  If this parameter is not a
 357                 valid mutable CFCharacterSet, the behavior is undefined.
 358         @param theString The string to remove from the character set.
 359                 If this parameter is not a valid CFString, the behavior
 360                 is undefined.
 361 */
 362 CF_EXPORT
 363 void CFCharacterSetRemoveCharactersInString(CFMutableCharacterSetRef theSet, CFStringRef theString);
 364
 365 /*!
 366         @function CFCharacterSetUnion
 367         Forms the union with the given character set.
 368         @param theSet The destination character set into which the
 369                 union of the two character sets is stored.  If this
 370                 parameter is not a valid mutable CFCharacterSet, the
 371                 behavior is undefined.
 372         @param theOtherSet The character set with which the union is
 373                 formed.  If this parameter is not a valid CFCharacterSet,
 374                 the behavior is undefined.
 375 */
 376 CF_EXPORT
 377 void CFCharacterSetUnion(CFMutableCharacterSetRef theSet, CFCharacterSetRef theOtherSet);
 378
 379 /*!
 380         @function CFCharacterSetIntersect
 381         Forms the intersection with the given character set.
 382         @param theSet The destination character set into which the
 383                 intersection of the two character sets is stored.
 384                 If this parameter is not a valid mutable CFCharacterSet,
 385                 the behavior is undefined.
 386         @param theOtherSet The character set with which the intersection
 387                 is formed.  If this parameter is not a valid CFCharacterSet,
 388                 the behavior is undefined.
 389 */
 390 CF_EXPORT
 391 void CFCharacterSetIntersect(CFMutableCharacterSetRef theSet, CFCharacterSetRef theOtherSet);
 392
 393 /*!
 394         @function CFCharacterSetInvert
 395         Inverts the content of the given character set.
 396         @param theSet The character set to be inverted.
 397                 If this parameter is not a valid mutable CFCharacterSet,
 398                 the behavior is undefined.
 399 */
 400 CF_EXPORT
 401 void CFCharacterSetInvert(CFMutableCharacterSetRef theSet);
 402
 403 CF_EXTERN_C_END
 404
 405 #endif /* ! __COREFOUNDATION_CFCHARACTERSET__ */
 406