NSCharacterSet Class Cluster

Class Cluster Description

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.

Building a Character Set

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.

Using a Character Set

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:

• Create as few mutable character sets as possible.

• Cache character sets (in a global dictionary, perhaps) instead of continually recreating them.

• When creating a custom set that doesn't need to change after creation, make an immutable copy of the final character set for actual use, and dispose of the working mutable character set. Alternatively, create a character set file as described in ""Building a Character Set"" and store it in your application's main bundle.

• Similarly, avoid archiving character set objects; store them in character set files instead. Archiving can result in a character set being duplicated in different archive files, resulting in wasted disk space and duplicates in memory for each separate archive read.

Standard Character Sets and Unicode Definitions

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/.

NSCharacterSet

Inherits From:
NSObject

Conforms To:
NSCoding
NSCopying
NSMutableCopying
NSObject (NSObject)

Declared In:
Foundation/NSCharacterSet.h

Class Description

Adopted Protocols

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

+ characterSetWithRange:

+ characterSetWithCharactersInString:

+ characterSetWithBitmapRepresentation:

Opening a character set file

+ characterSetWithContentsOfFile:

Testing set membership

- characterIsMember:

Inverting a character set

- invertedSet

Getting a binary representation

- bitmapRepresentation

Class Methods

alphanumericCharacterSet

Returns a character set containing the characters in the categories Letters, Marks, and Numbers. Informally, this is the set of all characters used as basic units of alphabets, syllabaries, ideographs, and digits.

See also: + letterCharacterSet, + decimalDigitCharacterSet

characterSetWithBitmapRepresentation:

Returns a character set containing characters determined by the bitmap representation data. This method is useful for creating a character set object with data from a file or other external data source.

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:

characterSetWithCharactersInString:

Returns a character set containing the characters in aString. Returns an empty character set if aString is empty.

characterSetWithContentsOfFile:

Returns a character set read from the bitmap representation stored in the file at path, which must end with the extension .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.

characterSetWithRange:

Returns a character set containing characters whose Unicode values are given by aRange. aRange.location is the value of the first character, and aRange.location + aRange.length - 1 is the value of the last. Returns an empty character set if aRange.length is 0.

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];

controlCharacterSet

Returns a character set containing the characters in the categories of Control or Format Characters. These are specifically the Unicode values U+0000 to U+001F and U+007F to U+009F.

See also: + illegalCharacterSet

decimalDigitCharacterSet

Returns a character set containing the characters in the category of Decimal Numbers. Informally, this is the set of all characters used to represent the decimal values 0 through 9. These include, for example, the decimal digits of the Indic scripts and Arabic.

See also: + alphanumericCharacterSet

decomposableCharacterSet

Returns a character set containing all individual Unicode characters that can also be represented as composed character sequences (such as for letters with accents), by the definition of "standard decomposition" in version 1.1 of the Unicode character encoding standard. These include compatibility characters as well as precomposed characters.