| /* |
| * Copyright (c) 2008-2009 Brent Fulgham <bfulgham@gmail.org>. All rights reserved. |
| * |
| * This source code is a modified version of the CoreFoundation sources released by Apple Inc. under |
| * the terms of the APSL version 2.0 (see below). |
| * |
| * For information about changes from the original Apple source release can be found by reviewing the |
| * source control system for the project at https://sourceforge.net/svn/?group_id=246198. |
| * |
| * The original license information is as follows: |
| * |
| * Copyright (c) 2008 Apple Inc. All rights reserved. |
| * |
| * @APPLE_LICENSE_HEADER_START@ |
| * |
| * This file contains Original Code and/or Modifications of Original Code |
| * as defined in and that are subject to the Apple Public Source License |
| * Version 2.0 (the 'License'). You may not use this file except in |
| * compliance with the License. Please obtain a copy of the License at |
| * http://www.opensource.apple.com/apsl/ and read it before using this |
| * file. |
| * |
| * The Original Code and all software distributed under the License are |
| * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER |
| * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, |
| * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, |
| * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. |
| * Please see the License for the specific language governing rights and |
| * limitations under the License. |
| * |
| * @APPLE_LICENSE_HEADER_END@ |
| */ |
| /* CFCharacterSet.h |
| Copyright (c) 1999-2007, Apple Inc. All rights reserved. |
| */ |
| |
| /*! |
| @header CFCharacterSet |
| CFCharacterSet represents a set, or a bag, of Unicode characters. |
| The API consists of 3 groups: |
| 1) creation/manipulation of CFCharacterSet instances, |
| 2) query of a single Unicode character membership, |
| and 3) bitmap representation related (reading/writing). |
| Conceptually, CFCharacterSet is a 136K byte bitmap array of |
| which each bit represents a Unicode code point. It could |
| contain the Unicode characters in ISO 10646 Basic Multilingual |
| Plane (BMP) and characters in Plane 1 through Plane 16 |
| accessible via surrogate paris in the Unicode Transformation |
| Format, 16-bit encoding form (UTF-16). In other words, it can |
| store values from 0x00000 to 0x10FFFF in the Unicode |
| Transformation Format, 32-bit encoding form (UTF-32). However, |
| in general, how CFCharacterSet stores the information is an |
| implementation detail. Note even CFData used for the external |
| bitmap representation rarely has 136K byte. For detailed |
| discussion of the external bitmap representation, refer to the |
| comments for CFCharacterSetCreateWithBitmapRepresentation below. |
| Note that the existance of non-BMP characters in a character set |
| does not imply the membership of the corresponding surrogate |
| characters. For example, a character set with U+10000 does not |
| match with U+D800. |
| */ |
| |
| #if !defined(__COREFOUNDATION_CFCHARACTERSET__) |
| #define __COREFOUNDATION_CFCHARACTERSET__ 1 |
| |
| #include <CoreFoundation/CFBase.h> |
| #include <CoreFoundation/CFData.h> |
| |
| CF_EXTERN_C_BEGIN |
| |
| /*! |
| @typedef CFCharacterSetRef |
| This is the type of a reference to immutable CFCharacterSets. |
| */ |
| typedef const struct __CFCharacterSet * CFCharacterSetRef; |
| |
| /*! |
| @typedef CFMutableCharacterSetRef |
| This is the type of a reference to mutable CFMutableCharacterSets. |
| */ |
| typedef struct __CFCharacterSet * CFMutableCharacterSetRef; |
| |
| /*! |
| @typedef CFCharacterSetPredefinedSet |
| Type of the predefined CFCharacterSet selector values. |
| */ |
| |
| enum { |
| kCFCharacterSetControl = 1, /* Control character set (Unicode General Category Cc and Cf) */ |
| kCFCharacterSetWhitespace, /* Whitespace character set (Unicode General Category Zs and U0009 CHARACTER TABULATION) */ |
| kCFCharacterSetWhitespaceAndNewline, /* Whitespace and Newline character set (Unicode General Category Z*, U000A ~ U000D, and U0085) */ |
| kCFCharacterSetDecimalDigit, /* Decimal digit character set */ |
| kCFCharacterSetLetter, /* Letter character set (Unicode General Category L* & M*) */ |
| kCFCharacterSetLowercaseLetter, /* Lowercase character set (Unicode General Category Ll) */ |
| kCFCharacterSetUppercaseLetter, /* Uppercase character set (Unicode General Category Lu and Lt) */ |
| kCFCharacterSetNonBase, /* Non-base character set (Unicode General Category M*) */ |
| kCFCharacterSetDecomposable, /* Canonically decomposable character set */ |
| kCFCharacterSetAlphaNumeric, /* Alpha Numeric character set (Unicode General Category L*, M*, & N*) */ |
| kCFCharacterSetPunctuation, /* Punctuation character set (Unicode General Category P*) */ |
| #if MAC_OS_X_VERSION_10_2 <= MAC_OS_X_VERSION_MAX_ALLOWED |
| kCFCharacterSetCapitalizedLetter = 13, /* Titlecase character set (Unicode General Category Lt) */ |
| #endif |
| #if MAC_OS_X_VERSION_10_3 <= MAC_OS_X_VERSION_MAX_ALLOWED |
| kCFCharacterSetSymbol = 14, /* Symbol character set (Unicode General Category S*) */ |
| #endif |
| #if MAC_OS_X_VERSION_10_5 <= MAC_OS_X_VERSION_MAX_ALLOWED |
| kCFCharacterSetNewline = 15, /* Newline character set (U000A ~ U000D, U0085, U2028, and U2029) */ |
| #endif |
| kCFCharacterSetIllegal = 12/* Illegal character set */ |
| }; |
| typedef CFIndex CFCharacterSetPredefinedSet; |
| |
| /*! |
| @function CFCharacterSetGetTypeID |
| Returns the type identifier of all CFCharacterSet instances. |
| */ |
| CF_EXPORT |
| CFTypeID CFCharacterSetGetTypeID(void); |
| |
| /*! |
| @function CFCharacterSetGetPredefined |
| Returns a predefined CFCharacterSet instance. |
| @param theSetIdentifier The CFCharacterSetPredefinedSet selector |
| which specifies the predefined character set. If the |
| value is not in CFCharacterSetPredefinedSet, the behavior |
| is undefined. |
| @result A reference to the predefined immutable CFCharacterSet. |
| This instance is owned by CF. |
| */ |
| CF_EXPORT |
| CFCharacterSetRef CFCharacterSetGetPredefined(CFCharacterSetPredefinedSet theSetIdentifier); |
| |
| /*! |
| @function CFCharacterSetCreateWithCharactersInRange |
| Creates a new immutable character set with the values from the given range. |
| @param alloc The CFAllocator which should be used to allocate |
| memory for the array and its storage for values. This |
| parameter may be NULL in which case the current default |
| CFAllocator is used. If this reference is not a valid |
| CFAllocator, the behavior is undefined. |
| @param theRange The CFRange which should be used to specify the |
| Unicode range the character set is filled with. It |
| accepts the range in 32-bit in the UTF-32 format. The |
| valid character point range is from 0x00000 to 0x10FFFF. |
| If the range is outside of the valid Unicode character |
| point, the behavior is undefined. |
| @result A reference to the new immutable CFCharacterSet. |
| */ |
| CF_EXPORT |
| CFCharacterSetRef CFCharacterSetCreateWithCharactersInRange(CFAllocatorRef alloc, CFRange theRange); |
| |
| /*! |
| @function CFCharacterSetCreateWithCharactersInString |
| Creates a new immutable character set with the values in the given string. |
| @param alloc The CFAllocator which should be used to allocate |
| memory for the array and its storage for values. This |
| parameter may be NULL in which case the current default |
| CFAllocator is used. If this reference is not a valid |
| CFAllocator, the behavior is undefined. |
| @param theString The CFString which should be used to specify |
| the Unicode characters the character set is filled with. |
| If this parameter is not a valid CFString, the behavior |
| is undefined. |
| @result A reference to the new immutable CFCharacterSet. |
| */ |
| CF_EXPORT |
| CFCharacterSetRef CFCharacterSetCreateWithCharactersInString(CFAllocatorRef alloc, CFStringRef theString); |
| |
| /*! |
| @function CFCharacterSetCreateWithBitmapRepresentation |
| Creates a new immutable character set with the bitmap representtion in the given data. |
| @param alloc The CFAllocator which should be used to allocate |
| memory for the array and its storage for values. This |
| parameter may be NULL in which case the current default |
| CFAllocator is used. If this reference is not a valid |
| CFAllocator, the behavior is undefined. |
| @param theData The CFData which should be used to specify the |
| bitmap representation of the Unicode character points |
| the character set is filled with. The bitmap |
| representation could contain all the Unicode character |
| range starting from BMP to Plane 16. The first 8192 bytes |
| of the data represent the BMP range. The BMP range 8192 |
| bytes can be followed by zero to sixteen 8192 byte |
| bitmaps, each one with the plane index byte prepended. |
| For example, the bitmap representing the BMP and Plane 2 |
| has the size of 16385 bytes (8192 bytes for BMP, 1 byte |
| index + 8192 bytes bitmap for Plane 2). The plane index |
| byte, in this case, contains the integer value two. If |
| this parameter is not a valid CFData or it contains a |
| Plane index byte outside of the valid Plane range |
| (1 to 16), the behavior is undefined. |
| @result A reference to the new immutable CFCharacterSet. |
| */ |
| CF_EXPORT |
| CFCharacterSetRef CFCharacterSetCreateWithBitmapRepresentation(CFAllocatorRef alloc, CFDataRef theData); |
| |
| #if MAC_OS_X_VERSION_10_2 <= MAC_OS_X_VERSION_MAX_ALLOWED |
| /*! |
| @function CFCharacterSetCreateInvertedSet |
| Creates a new immutable character set that is the invert of the specified character set. |
| @param alloc The CFAllocator which should be used to allocate |
| memory for the array and its storage for values. This |
| parameter may be NULL in which case the current default |
| CFAllocator is used. If this reference is not a valid |
| CFAllocator, the behavior is undefined. |
| @param theSet The CFCharacterSet which is to be inverted. If this |
| parameter is not a valid CFCharacterSet, the behavior is |
| undefined. |
| @result A reference to the new immutable CFCharacterSet. |
| */ |
| CF_EXPORT CFCharacterSetRef CFCharacterSetCreateInvertedSet(CFAllocatorRef alloc, CFCharacterSetRef theSet); |
| |
| /*! |
| @function CFCharacterSetIsSupersetOfSet |
| Reports whether or not the character set is a superset of the character set specified as the second parameter. |
| @param theSet The character set to be checked for the membership of theOtherSet. |
| If this parameter is not a valid CFCharacterSet, the behavior is undefined. |
| @param theOtherset The character set to be checked whether or not it is a subset of theSet. |
| If this parameter is not a valid CFCharacterSet, the behavior is undefined. |
| */ |
| CF_EXPORT Boolean CFCharacterSetIsSupersetOfSet(CFCharacterSetRef theSet, CFCharacterSetRef theOtherset); |
| |
| /*! |
| @function CFCharacterSetHasMemberInPlane |
| Reports whether or not the character set contains at least one member character in the specified plane. |
| @param theSet The character set to be checked for the membership. If this |
| parameter is not a valid CFCharacterSet, the behavior is undefined. |
| @param thePlane The plane number to be checked for the membership. |
| The valid value range is from 0 to 16. If the value is outside of the valid |
| plane number range, the behavior is undefined. |
| */ |
| CF_EXPORT Boolean CFCharacterSetHasMemberInPlane(CFCharacterSetRef theSet, CFIndex thePlane); |
| #endif |
| |
| /*! |
| @function CFCharacterSetCreateMutable |
| Creates a new empty mutable character set. |
| @param allocator The CFAllocator which should be used to allocate |
| memory for the array and its storage for values. This |
| parameter may be NULL in which case the current default |
| CFAllocator is used. If this reference is not a valid |
| CFAllocator, the behavior is undefined. |
| @result A reference to the new mutable CFCharacterSet. |
| */ |
| CF_EXPORT |
| CFMutableCharacterSetRef CFCharacterSetCreateMutable(CFAllocatorRef alloc); |
| |
| #if MAC_OS_X_VERSION_10_3 <= MAC_OS_X_VERSION_MAX_ALLOWED |
| /*! |
| @function CFCharacterSetCreateCopy |
| Creates a new character set with the values from the given character set. This function tries to compact the backing store where applicable. |
| @param allocator The CFAllocator which should be used to allocate |
| memory for the array and its storage for values. This |
| parameter may be NULL in which case the current default |
| CFAllocator is used. If this reference is not a valid |
| CFAllocator, the behavior is undefined. |
| @param theSet The CFCharacterSet which is to be copied. If this |
| parameter is not a valid CFCharacterSet, the behavior is |
| undefined. |
| @result A reference to the new CFCharacterSet. |
| */ |
| CF_EXPORT |
| CFCharacterSetRef CFCharacterSetCreateCopy(CFAllocatorRef alloc, CFCharacterSetRef theSet) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; |
| #endif |
| |
| /*! |
| @function CFCharacterSetCreateMutableCopy |
| Creates a new mutable character set with the values from the given character set. |
| @param allocator The CFAllocator which should be used to allocate |
| memory for the array and its storage for values. This |
| parameter may be NULL in which case the current default |
| CFAllocator is used. If this reference is not a valid |
| CFAllocator, the behavior is undefined. |
| @param theSet The CFCharacterSet which is to be copied. If this |
| parameter is not a valid CFCharacterSet, the behavior is |
| undefined. |
| @result A reference to the new mutable CFCharacterSet. |
| */ |
| CF_EXPORT |
| CFMutableCharacterSetRef CFCharacterSetCreateMutableCopy(CFAllocatorRef alloc, CFCharacterSetRef theSet); |
| |
| /*! |
| @function CFCharacterSetIsCharacterMember |
| Reports whether or not the Unicode character is in the character set. |
| @param theSet The character set to be searched. If this parameter |
| is not a valid CFCharacterSet, the behavior is undefined. |
| @param theChar The Unicode character for which to test against the |
| character set. Note that this function takes 16-bit Unicode |
| character value; hence, it does not support access to the |
| non-BMP planes. |
| @result true, if the value is in the character set, otherwise false. |
| */ |
| CF_EXPORT |
| Boolean CFCharacterSetIsCharacterMember(CFCharacterSetRef theSet, UniChar theChar); |
| |
| #if MAC_OS_X_VERSION_10_2 <= MAC_OS_X_VERSION_MAX_ALLOWED |
| /*! |
| @function CFCharacterSetIsLongCharacterMember |
| Reports whether or not the UTF-32 character is in the character set. |
| @param theSet The character set to be searched. If this parameter |
| is not a valid CFCharacterSet, the behavior is undefined. |
| @param theChar The UTF-32 character for which to test against the |
| character set. |
| @result true, if the value is in the character set, otherwise false. |
| */ |
| CF_EXPORT Boolean CFCharacterSetIsLongCharacterMember(CFCharacterSetRef theSet, UTF32Char theChar); |
| #endif |
| |
| /*! |
| @function CFCharacterSetCreateBitmapRepresentation |
| Creates a new immutable data with the bitmap representation from the given character set. |
| @param allocator The CFAllocator which should be used to allocate |
| memory for the array and its storage for values. This |
| parameter may be NULL in which case the current default |
| CFAllocator is used. If this reference is not a valid |
| CFAllocator, the behavior is undefined. |
| @param theSet The CFCharacterSet which is to be used create the |
| bitmap representation from. Refer to the comments for |
| CFCharacterSetCreateWithBitmapRepresentation for the |
| detailed discussion of the bitmap representation format. |
| If this parameter is not a valid CFCharacterSet, the |
| behavior is undefined. |
| @result A reference to the new immutable CFData. |
| */ |
| CF_EXPORT |
| CFDataRef CFCharacterSetCreateBitmapRepresentation(CFAllocatorRef alloc, CFCharacterSetRef theSet); |
| |
| /*! |
| @function CFCharacterSetAddCharactersInRange |
| Adds the given range to the charaacter set. |
| @param theSet The character set to which the range is to be added. |
| If this parameter is not a valid mutable CFCharacterSet, |
| the behavior is undefined. |
| @param theRange The range to add to the character set. It accepts |
| the range in 32-bit in the UTF-32 format. The valid |
| character point range is from 0x00000 to 0x10FFFF. If the |
| range is outside of the valid Unicode character point, |
| the behavior is undefined. |
| */ |
| CF_EXPORT |
| void CFCharacterSetAddCharactersInRange(CFMutableCharacterSetRef theSet, CFRange theRange); |
| |
| /*! |
| @function CFCharacterSetRemoveCharactersInRange |
| Removes the given range from the charaacter set. |
| @param theSet The character set from which the range is to be |
| removed. If this parameter is not a valid mutable |
| CFCharacterSet, the behavior is undefined. |
| @param theRange The range to remove from the character set. |
| It accepts the range in 32-bit in the UTF-32 format. |
| The valid character point range is from 0x00000 to 0x10FFFF. |
| If the range is outside of the valid Unicode character point, |
| the behavior is undefined. |
| */ |
| CF_EXPORT |
| void CFCharacterSetRemoveCharactersInRange(CFMutableCharacterSetRef theSet, CFRange theRange); |
| |
| /*! |
| @function CFCharacterSetAddCharactersInString |
| Adds the characters in the given string to the charaacter set. |
| @param theSet The character set to which the characters in the |
| string are to be added. If this parameter is not a |
| valid mutable CFCharacterSet, the behavior is undefined. |
| @param theString The string to add to the character set. |
| If this parameter is not a valid CFString, the behavior |
| is undefined. |
| */ |
| CF_EXPORT |
| void CFCharacterSetAddCharactersInString(CFMutableCharacterSetRef theSet, CFStringRef theString); |
| |
| /*! |
| @function CFCharacterSetRemoveCharactersInString |
| Removes the characters in the given string from the charaacter set. |
| @param theSet The character set from which the characters in the |
| string are to be remove. If this parameter is not a |
| valid mutable CFCharacterSet, the behavior is undefined. |
| @param theString The string to remove from the character set. |
| If this parameter is not a valid CFString, the behavior |
| is undefined. |
| */ |
| CF_EXPORT |
| void CFCharacterSetRemoveCharactersInString(CFMutableCharacterSetRef theSet, CFStringRef theString); |
| |
| /*! |
| @function CFCharacterSetUnion |
| Forms the union with the given character set. |
| @param theSet The destination character set into which the |
| union of the two character sets is stored. If this |
| parameter is not a valid mutable CFCharacterSet, the |
| behavior is undefined. |
| @param theOtherSet The character set with which the union is |
| formed. If this parameter is not a valid CFCharacterSet, |
| the behavior is undefined. |
| */ |
| CF_EXPORT |
| void CFCharacterSetUnion(CFMutableCharacterSetRef theSet, CFCharacterSetRef theOtherSet); |
| |
| /*! |
| @function CFCharacterSetIntersect |
| Forms the intersection with the given character set. |
| @param theSet The destination character set into which the |
| intersection of the two character sets is stored. |
| If this parameter is not a valid mutable CFCharacterSet, |
| the behavior is undefined. |
| @param theOtherSet The character set with which the intersection |
| is formed. If this parameter is not a valid CFCharacterSet, |
| the behavior is undefined. |
| */ |
| CF_EXPORT |
| void CFCharacterSetIntersect(CFMutableCharacterSetRef theSet, CFCharacterSetRef theOtherSet); |
| |
| /*! |
| @function CFCharacterSetInvert |
| Inverts the content of the given character set. |
| @param theSet The character set to be inverted. |
| If this parameter is not a valid mutable CFCharacterSet, |
| the behavior is undefined. |
| */ |
| CF_EXPORT |
| void CFCharacterSetInvert(CFMutableCharacterSetRef theSet); |
| |
| CF_EXTERN_C_END |
| |
| #endif /* ! __COREFOUNDATION_CFCHARACTERSET__ */ |
| |
