- Inherits from:
- NSObject
- Conforms to:
- NSCoding
- NSCopying
- NSMutableCopying
- NSObject (NSObject)
Declared in:
- Foundation/NSCharacterSet.h
An NSCharacterSet object represents a set of Unicode characters. NSString and NSScanner objects use NSCharacterSets to group characters together for searching operations, so that they can find any of a particular set of characters during a search. The cluster's two public classes, NSCharacterSet and NSMutableCharacterSet, declare the programmatic interface for static and dynamic character sets, respectively.
The objects you create using these classes are referred to as character set objects (and when no confusion will result, merely as character sets). Because of the nature of class clusters, character set objects aren't actual instances of the NSCharacterSet or NSMutableCharacterSet classes but of one of their private subclasses. Although a character set object's class is private, its interface is public, as declared by these abstract superclasses, NSCharacterSet and NSMutableCharacterSet. The character set classes adopt the NSCopying and NSMutableCopying protocols, making it convenient to convert a character set of one type to the other.
The NSCharacterSet class declares the programmatic interface for an object that manages a set of Unicode characters (see the NSString class cluster specification for information on Unicode). NSCharacterSet's principal primitive method, characterIsMember:, provides the basis for all other instance methods in its interface. A subclass of NSCharacterSet needs only to implement this method, plus mutableCopyWithZone:, for proper behavior. For optimal performance, a subclass should also override bitmapRepresentation which otherwise works by invoking characterIsMember: for every possible Unicode value.
NSCharacterSet defines class methods that return commonly used character sets, such as letters (uppercase or lowercase), decimal digits, whitespace, and so on. These "standard" character sets are always immutable, even if created by sending a message to NSMutableCharacterSet. See "Standard Character Sets and Unicode Definitions" below for more information on standard character sets.
You can use a standard character set as a starting point for building a custom set by making a mutable copy of it and changing that. (You can also start from scratch by creating a mutable character set with alloc and init and adding characters to it.) For example, this fragment creates a character set containing letters, digits, and basic punctuation:
NSMutableCharacterSet *workingSet; NSCharacterSet *finalCharSet; workingSet = [[NSCharacterSet alphanumericCharacterSet] mutableCopy]; [workingSet addCharactersInString:@";:,."]; finalCharSet = [workingSet copy]; [workingSet release];
For performance reasons (explained in "Using a Character Set" ), always finish by converting the working mutable character set into an immutable set. If you need to keep changing the character set after you've created it, of course, you should just use the mutable set.
If your application frequently uses a custom character set, you'll want to save its definition in a resource file and load that instead of explicitly adding individual characters each time you need to create the set. You can save a character set by getting its bitmap representation (an NSData object) and saving that object to a file:
NSString *filename; /* Assume this exists. */ NSString *absolutePath; NSData *charSetRep; BOOL result; absolutePath = [filename stringByStandardizingPath]; charSetRep = [finalCharSet bitmapRepresentation]; result = [charSetRep writeToFile:absolutePath atomically:YES];
Character set filenames by convention use the extension .bitmap. If you intend for others to use your character set files, you should follow this convention. To read a character set file with a .bitmap extension, simply use the characterSetWithContentsOfFile: method.
A character set object doesn't perform any tasks; it simply holds a set of character values to limit operations on strings. The NSString and NSScanner classes define methods that take NSCharacterSets as arguments to find any of several characters. For example, this code excerpt finds the range of the first uppercase letter in myString:
NSString *myString = @"some text in an NSString..."; NSRange letterRange; letterRange = [myString rangeOfCharacterFromSet:[NSCharacterSet uppercaseLetterCharacterSet]];
After this fragment executes, letterRange.location
is
equal to the index of the first "N" in "NSString" after rangeOfCharacterFromSet: is
invoked. If the first letter of the string were "S" then letterRange.location
would
be 0.
Because character sets often participate in performance-critical code, you should be aware of the aspects of their use that can affect the performance of your application. Mutable character sets are generally much more expensive than immutable character sets. They consume more memory and are costly to invert (an operation often performed in scanning a string). Because of this, you should follow these guidelines:
The standard character sets, such as that returned by letterCharacterSet, are formally defined in terms of the normative and informative categories established by the Unicode standard, such as Uppercase Letter, Combining Mark, and so on. The formal definition of a standard character set is in most cases given as one or more of the categories defined in the standard. For example, the set returned by lowercaseLetterCharacterSet include all characters in normative category Lowercase Letters, while the set returned by letterCharacterSet includes the characters in all of the Letter categories.
Note that the definitions of the categories themselves may
change with new versions of the Unicode standard. You can download
the files that define category membership from http://www.unicode.org/
.
NSCoding
- - encodeWithCoder:
- - initWithCoder:
NSCopying
- - copyWithZone:
NSMutableCopying
- - mutableCopyWithZone:
- Creating a standard character set
- + alphanumericCharacterSet
- + controlCharacterSet
- + decimalDigitCharacterSet
- + decomposableCharacterSet
- + illegalCharacterSet
- + letterCharacterSet
- + lowercaseLetterCharacterSet
- + nonBaseCharacterSet
- + punctuationCharacterSet
- + uppercaseLetterCharacterSet
- + whitespaceAndNewlineCharacterSet
- + whitespaceCharacterSet
- Creating a custom character set
- + characterSetWithBitmapRepresentation:
- + characterSetWithCharactersInString:
- + characterSetWithRange:
- Opening a character set file
- + characterSetWithContentsOfFile:
- Testing set membership
- - characterIsMember:
- Inverting a character set
- - invertedSet
- Getting a binary representation
- - bitmapRepresentation
+ (NSCharacterSet *)alphanumericCharacterSet
See Also: + letterCharacterSet, + decimalDigitCharacterSet
+ (NSCharacterSet *)characterSetWithBitmapRepresentation:(NSData
*)data
A raw bitmap representation of a character set is a byte array of 216 bits (that is, 8192 bytes). The value of the bit at position n represents the presence in the character set of the character with decimal Unicode value n. To add a character with decimal Unicode value n to a raw bitmap representation, use a statement such as:
unsigned char bitmapRep[8192]; bitmapRep[n >> 3] |= (((unsigned int)1) << (n & 7));
To remove that character:
bitmapRep[n >> 3] &= ~(((unsigned int)1) << (n & 7));
See Also: - bitmapRepresentation, + characterSetWithContentsOfFile:
+ (NSCharacterSet *)characterSetWithCharactersInString:(NSString
*)aString
+ (NSCharacterSet *)characterSetWithContentsOfFile:(NSString
*)path
.bitmap
. To
read a bitmap representation from any file, use NSData's dataWithContentsOfFile: method and
pass the result to characterSetWithBitmapRepresentation:.This method doesn't perform filename-based uniquing of the character sets it creates. To prevent duplication of character sets in memory, cache them and make them available through an API that checks whether the requested set has already been loaded.
+ (NSCharacterSet *)characterSetWithRange:(NSRange)aRange
This code excerpt creates a character set object containing the lowercase English alphabetic characters:
NSRange lcEnglishRange; NSCharacterSet *lcEnglishLetters; lcEnglishRange.location = (unsigned int)'a'; lcEnglishRange.length = 26; lcEnglishLetters = [NSCharacterSet characterSetWithRange:lcEnglishRange];
+ (NSCharacterSet *)controlCharacterSet
See Also: + illegalCharacterSet
+ (NSCharacterSet *)decimalDigitCharacterSet
See Also: + alphanumericCharacterSet
+ (NSCharacterSet *)decomposableCharacterSet
Note: This character set doesn't currently include the Hangul characters defined in version 2.0 of the Unicode standard. |
See Also: + nonBaseCharacterSet
+ (NSCharacterSet *)illegalCharacterSet
See Also: + controlCharacterSet
+ (NSCharacterSet *)letterCharacterSet
See Also: + alphanumericCharacterSet, + lowercaseLetterCharacterSet, + uppercaseLetterCharacterSet
+ (NSCharacterSet *)lowercaseLetterCharacterSet
See Also: + uppercaseLetterCharacterSet, + letterCharacterSet
+ (NSCharacterSet *)nonBaseCharacterSet
See Also: + decomposableCharacterSet
+ (NSCharacterSet *)punctuationCharacterSet
+ (NSCharacterSet *)uppercaseLetterCharacterSet
See Also: + lowercaseLetterCharacterSet, + letterCharacterSet
+ (NSCharacterSet *)whitespaceAndNewlineCharacterSet
See Also: + whitespaceCharacterSet
+ (NSCharacterSet *)whitespaceCharacterSet
See Also: + whitespaceAndNewlineCharacterSet
- (NSData *)bitmapRepresentation
A raw bitmap representation of a character set is a byte array of 216 bits (that is, 8192 bytes). The value of the bit at position n represents the presence in the character set of the character with decimal Unicode value n. To test for the presence of a character with decimal Unicode value n in a raw bitmap representation, use an expression such as:
unsigned char bitmapRep[8192]; if (bitmapRep[n >> 3] & (((unsigned int)1) << (n & 7))) { /* Character is present. */ }
See Also: + characterSetWithBitmapRepresentation:
- (BOOL)characterIsMember:(unichar)aCharacter
- (NSCharacterSet *)invertedSet
See Also: - invert (NSMutableCharacterSet)