A category can be used to split a class over multiple .h/.m file pairs. If a class threatens to become long and unwieldy, yet it clearly needs to be a single class, you can define the basic part of it (including instance variables) in one file pair, and then add another file pair defining a category on your own class to contain further methods.

Cocoa itself does this. A good example is NSString. NSString is defined as part of the Foundation framework, and its basic methods are declared in NSString.h. Here we find that NSString itself, with no category, has just two methods, length and characterAtIndex:, because these are regarded as the minimum that a string needs to do in order to be a string. Additional methods (those that create a string, deal with a string’s encoding, split a string, search in a string, and so on) are clumped into categories. The interface for many of these categories appears in this same file, NSString.h. But a string may serve as a file pathname, so we also find a category on NSString in NSPathUtilities.h, where methods are declared for splitting a pathname string into its constituents and the like. Then, in NSURL.h, there’s another NSString category, declaring a couple of methods for dealing with percent-escaping in a URL string. Finally, off in a completely different framework (UIKit), UIStringDrawing.h adds yet another NSString category, with methods for drawing a string in a graphics context.

This organization won’t matter to you as a programmer, because an NSString is an NSString, no matter how it acquires its methods, but it can matter when you consult the documentation. The NSString methods declared in NSString.h, NSPathUtilities.h, and NSURL.h are documented in the NSString class documentation page, but the NSString methods declared in UIStringDrawing.h are not, presumably because they originate in a different framework. Instead, they appear in a separate document, NSString UIKit Additions Reference. As a result, the string drawing methods can be difficult to discover, especially as the NSString class documentation doesn’t link to the other document. I regard this as a major flaw in the structure of the Cocoa documentation. A third-party utility such as AppKiDo can be helpful here.

A class extension is a nameless category that exists solely as an interface section, like this:

@interface MyClass ()
// stuff goes here
@end

Typically, the only classes that will be permitted to “see” a class extension will be the class that’s being extended or a subclass of that class. If only the former is the case, the class extension will usually appear directly in the class’s implementation file, like this:

// MyClass.m:

@interface MyClass ()
// stuff goes here
@end

@implementation MyClass {
    // ivars
}
// methods
@end

That’s such a common arrangement that Xcode’s project template files actually give you a class extension in certain classes. For example, our Empty Window project comes with a class extension at the start of ViewController.m — take a look and see!

I’m sure you’re leaping out of your chair with eagerness to know what on earth sort of “stuff” could possibly go into a class extension to make it so useful that it appears in a template file. Unfortunately, in modern Objective-C the answer has mostly to do with property declarations, which I don’t discuss until Chapter 12. So your curiosity will have to remain unsatisfied until then.

A class extension used to be the standard solution to the problem of method definition order. One method in an implementation section couldn’t call another method in that same implementation section unless either the definition or a method declaration for that other method preceded it. It’s finicky work trying to arrange all the method definitions in the right order, so the obvious solution is a method declaration. A method declaration can go only into an interface section. But to put a method declaration into the interface section in this class’s header file is annoying — it means we must switch to another file — and, even worse, it makes that method public; any class that imports that header file can now see and call this method. That’s fine if this method is supposed to be public; but what if we wanted to keep it private? The solution: a class extension at the start of this class’s implementation file. Put the method declarations into that class extension; all the methods in the implementation section can now see those method declarations and can call one another, but no other class can see them.

However, since LLVM compiler version 3.1 (Xcode 4.3) that trick has been unnecessary: methods (and functions) in a class implementation can see and call one another regardless of order.

NSRange is a struct of importance in dealing with some of the classes I’m about to discuss. Its components are integers (NSUInteger), location and length. For example, a range whose location is 1 starts at the second element of something (because element counting is always zero-based), and if its length is 2 it designates this element and the next. Cocoa also supplies various convenience methods for dealing with a range; you’ll use NSMakeRange frequently. (Note that the name, NSMakeRange, is backward compared to names like CGPointMake and CGRectMake.)

NSNotFound is a constant integer indicating that some requested element was not found. For example, if you ask for the index of a certain object in an NSArray and the object isn’t present in the array, the result is NSNotFound. The result could not be 0 to indicate the absence of the object, because 0 would indicate the first element of the array. Nor could it be nil, because nil is 0 (and in any case is not appropriate when an integer is expected). The true numeric value of NSNotFound is of no concern to you; always compare against NSNotFound itself, to learn whether a result is a meaningful index.

If a search returns a range and the thing sought is not present, the location component of the resulting NSRange will be NSNotFound.

NSString, which has already been used rather liberally in examples earlier in this book, is the Cocoa object version of a string. You can create an NSString through a number of class methods and initializers, or by using the NSString literal notation @"...", which is really a compiler directive. Particularly important is stringWithFormat:, which lets you convert numbers to strings and combine strings; see Chapter 9, where I discussed format strings in connection with NSLog. Here are some strings in action:

int x = 5;
NSString* s = @"widgets";
NSString* s2 = [NSString stringWithFormat:@"You have %i %@.", x, s];

NSString has a modern, Unicode-based idea of what a string can consist of. A string’s “elements” are its characters, whose count is its length. These are not bytes, because the numeric representation of a Unicode character could be multiple bytes, depending on the encoding. Nor are they glyphs, because a composed character sequence that prints as a single “letter” can consist of multiple characters. Thus the length of an NSRange indicating a single “character” might be greater than 1.

An NSString can be searched using various rangeOf... methods, which return an NSRange. In addition, NSScanner lets you walk through a string looking for pieces that fit certain criteria; for example, with NSScanner (and NSCharacterSet) you can skip past everything in a string that precedes a number and then extract the number. The rangeOfString: family of search methods lets you look for a substring; it can specify an option NSRegularExpressionSearch, which lets you search using a regular expression, and regular expressions are also supported as a separate class, NSRegularExpression (which uses NSTextCheckingResult to describe match results).

In this example from one of my apps, the user has tapped a button whose title is something like “5 by 4” or “4 by 3”. I want to know both numbers; one tells me how many rows the layout is to have, the other how many columns. I use an NSScanner to locate the two numbers in the title:

NSString* s = [as buttonTitleAtIndex:ix];
NSScanner* sc = [NSScanner scannerWithString:s];
int rows, cols;
[sc scanInt:&rows];
[sc scanUpToCharactersFromSet:[NSCharacterSet decimalDigitCharacterSet]
                   intoString:nil];
[sc scanInt:&cols];

Here’s how I might do the same thing using a regular expression:

NSString* s = [as buttonTitleAtIndex:ix];
int rowcol[2]; int* prowcol = rowcol;
NSError* err = nil;
NSRegularExpression* r =
    [NSRegularExpression regularExpressionWithPattern:@"\\d"
                                              options:0
                                                error:&err];
// error-checking omitted
for (NSTextCheckingResult* match in
    [r matchesInString:s options:0 range:NSMakeRange(0, [s length])])
        *prowcol++ = [[s substringWithRange: [match range]] intValue];

The syntax seems oddly tortured, though, because we must convert each match from an NSTextCheckingResult to a range, then to a substring of our original string, and finally to an integer.

More sophisticated automated textual analysis is supported by some additional classes, such as NSDataDetector, an NSRegularExpression subclass that efficiently finds certain types of string expression such as a URL or a phone number, and NSLinguisticTagger, which actually attempts to analyze text into its grammatical parts of speech.

An NSString object’s string is immutable. You can use a string to generate another string in various ways, such as by appending another string or by extracting a substring, but you can’t alter the string itself. For that, you need NSString’s subclass, NSMutableString.

NSString has convenience utilities for working with a file path string, and is often used in conjunction with NSURL, which is another Foundation class worth looking into. NSString and some other classes discussed in this section provide methods for writing out to a file’s contents or reading in a file’s contents; when they do, the file can be specified either as an NSString file path or as an NSURL (Chapter 36).

An NSString carries no font and size information. Interface objects that display strings (such as UILabel) have a font property that is a UIFont; but this determines the single font and size in which the string will display. Before iOS 6, display of styled text — where different runs of text have different style attributes (size, font, color, and so forth) — was quite challenging. The NSAttributedString class, embodying a string along with style runs, required the use of Core Text (Chapter 23), and you had to lay out the styled text by drawing it yourself; you couldn’t display styled text in any standard interface object.

Starting in iOS 6, however, NSAttributedString is a full-fledged Objective-C class, with methods and supporting classes that allow you to style text and paragraphs easily in sophisticated ways — and the built-in interface objects that display text can display styled text. This is a major improvement.

String drawing in a graphics context can be performed with methods provided through the UIStringDrawing category on NSString (see the String UIKit Additions Reference) and the NSStringDrawing category on NSAttributedString (see the NSAttributedString UIKit Additions Reference, new in iOS 6).

NSAttributedString, along with its supporting classes (NSMutableAttributedString, NSParagraphStyle, NSMutableParagraphStyle) and its drawing commands, is discussed in Chapter 23.

An NSDate is a date and time, represented internally as a number of seconds (NSTimeInterval) since some reference date. Calling [NSDate date] gives you a date object for the current date and time; other date operations may involve NSDateComponents and NSCalendar and can be a bit tricky because calendars are complicated (see the Date and Time Programming Guide; NSDateComponents examples appear in Chapter 25 and Chapter 32).

You will also likely be concerned with dates represented as strings. Creation and parsing of date strings involves NSDateFormatter, which uses a format string similar to NSString’s stringWithFormat. A complication is added by the fact that the exact string representation of a date component or format can depend upon the user’s locale, consisting of language, region format, and calendar settings. (Actually, locale considerations can also play a role in NSString format strings.)

In this example from one of my apps, I prepare the content of a UILabel reporting the date and time when our data was last updated. The app is not localized — the word “at” appearing in the string is always going to be in English — so I want complete control of the presentation of the date and time components as well. To get it, I have to insist upon a particular locale:

NSDateFormatter *df = [NSDateFormatter new];
if ([[NSLocale availableLocaleIdentifiers] indexOfObject:@"en_US"]
        != NSNotFound) {
    NSLocale* loc = [[NSLocale alloc] initWithLocaleIdentifier:@"en_US"];
    [df setLocale:loc]; // English month name and time zone name if possible
}
[df setDateFormat:@"'Updated' d MMMM yyyy 'at' h:mm a z"];
[self setRefreshControlTitle:[df stringFromDate: [NSDate date]]]; // just now

Locales are an interesting and complicated topic; to learn more, consult in your browser the documentation for ICU (International Components for Unicode), from which the iOS support for creating and parsing date strings is derived. To study what locales exist, use the locale explorer at http://demo.icu-project.org/icu-bin/locexp.

An NSNumber is an object that wraps a numeric value (including BOOL). Thus, you can use it to store and pass a number where an object is expected. An NSNumber is formed from an actual number with a method that specifies the numeric type; for example, you can call numberWithInt: to form a number from an int:

[[NSUserDefaults standardUserDefaults] registerDefaults:
    [NSDictionary dictionaryWithObjectsAndKeys:
        [NSNumber numberWithInt: 4],
        @"cardMatrixRows",
        [NSNumber numberWithInt: 3],
        @"cardMatrixColumns",
        nil]];

As I mentioned in Chapter 5, LLVM compiler version 4.0 (Xcode 4.4) brought with it a new syntax for forming a new NSNumber instance:

Thus, the preceding example can be rewritten like this:

[[NSUserDefaults standardUserDefaults] registerDefaults:
    [NSDictionary dictionaryWithObjectsAndKeys:
        @4,
        @"cardMatrixRows",
        @3,
        @"cardMatrixColumns",
        nil]];

(There is also a new NSDictionary literal syntax, so it will turn out, a few pages from now, that we can rewrite that code even more compactly.)

An NSNumber is not itself a number, however, so you still can’t use it in calculations or where an actual number is expected. Instead, you must explicitly extract the number from its NSNumber wrapper using the inverse of the method that wrapped the number to begin with. Knowing what that method was is up to you. So, for example, if an NSNumber wraps an int, you can call intValue to extract the int:

NSUserDefaults* ud = [NSUserDefaults standardUserDefaults];
int therows = [[ud objectForKey:@"cardMatrixRows"] intValue];
int thecols = [[ud objectForKey:@"cardMatrixColumns"] intValue];

Actually, this is such a common transformation when communicating with NSUserDefaults that it provides convenience methods. So I could have written the same thing this way:

NSUserDefaults* ud = [NSUserDefaults standardUserDefaults];
int therows = [ud integerForKey:@"cardMatrixRows"];
int thecols = [ud integerForKey:@"cardMatrixColumns"];

An NSNumber subclass, NSDecimalNumber, can be used in calculations, thanks to a bunch of arithmetic methods (or their C equivalent functions, which are faster). This is useful particularly for rounding, because there’s a handy way to specify exactly the desired rounding behavior.

NSValue is NSNumber’s superclass. Use it for wrapping nonnumeric C values such as structs. Convenience methods provided through the NSValueUIGeometryExtensions category on NSValue (see the NSValue UIKit Additions Reference) allow easy wrapping and unwrapping of CGPoint, CGSize, CGRect, CGAffineTransform, UIEdgeInsets, and UIOffset; additional categories allow easy wrapping and unwrapping of CATransform3D, CMTime, CMTimeMapping, CMTimeRange, MKCoordinate, and MKCoordinateSpan.

You are unlikely to need to store any other kind of C value in an NSValue, but you can if you need to.

NSData is a general sequence of bytes; basically, it’s just a buffer, a chunk of memory. It is immutable; the mutable version is its subclass NSMutableData.

In practice, NSData tends to arise in two main ways:

The foregoing types will quickly come to seem to you like basic data types, but of course they are actually object types — which means that they are pointers (Chapter 3) Therefore you cannot compare them using the C operators for testing equality as you would with actual numbers. That’s because, in the case of object types, the C operators compare the pointers, not the object content of the instances. For example:

NSString* s1 = [NSString stringWithFormat:@"%@, %@", @"Hello", @"world"];
NSString* s2 = [NSString stringWithFormat:@"%@, %@", @"Hello", @"world"];
if (s1 == s2) // false
    // ...

The two strings are equivalent (@"Hello, world") but are not the same object. (The example is deliberately elaborate because Cocoa’s efficient management of string literals sees to it that two strings initialized directly as @"Hello, world" are the same object, which wouldn’t illustrate the point I’m making.) It is up to individual classes to implement a test for equality. The general test, isEqual:, is inherited from NSObject and overridden, but some classes also define more specific and efficient tests. Thus, the correct way to perform the above test is like this:

if ([s1 isEqualToString: s2])

Similarly, it is up to individual classes to supply ordered comparison methods. The standard method is called compare:, and returns one of three constants: NSOrderedAscending (the receiver is less than the argument), NSOrderedSame (the receiver is equal to the argument), or NSOrderedDescending (the receiver is greater than the argument); for an example, see Example 3.2.

NSIndexSet expresses a collection of unique whole numbers; its purpose is to express element numbers of an ordered collection, such as an NSArray. Thus, for instance, to retrieve multiple objects simultaneously from an array, you specify the desired indexes as an NSIndexSet. It is also used with other things that are array-like; for example, you pass an NSIndexSet to a UITableView to indicate what sections to insert or delete.

To take a specific example, let’s say you want to speak of elements 1, 2, 3, 4, 8, 9, and 10 of an NSArray. NSIndexSet expresses this notion in some compact implementation that can be readily queried. The actual implementation is opaque, but you can imagine that in this case the set might consist of two NSRange structs, {1,4} and {8,3}, and NSIndexSet’s methods actually invite you to think of an NSIndexSet as composed of ranges.

An NSIndexSet is immutable; its mutable subclass is NSMutableIndexSet. You can form a simple NSIndexSet consisting of just one contiguous range directly, by passing an NSRange to indexSetWithIndexesInRange:; but to form a more complex index set you’ll need to use NSMutableIndexSet so that you can append additional ranges.

To walk through (enumerate) the index values or ranges specified by an NSIndexSet, call enumerateIndexesUsingBlock: or enumerateRangesUsingBlock: or their variants.

An NSArray is an ordered collection of objects. Its length is its count, and a particular object can be obtained by index number using objectAtIndex:. The index of the first object is zero, so the index of the last object is count minus one.

Starting with LLVM compiler version 4.0 (Xcode 4.5), it is no longer necessary to call objectAtIndex:; instead, you can use a notation reminiscent of C and other languages that have arrays, namely, append square brackets containing the index number to the array reference (subscripting).

So, for example, if pep contains @"Manny", @"Moe", and @"Jack", then pep[2] yields @"Jack"; it is equivalent to [pep objectAtIndex:2]. Okay, I lied; actually, pep[2] is equivalent to [pep objectAtIndexedSubscript:2]. That’s because the subscripting notation causes any reference to which the subscript is appended to be sent objectAtIndexedSubscript:. This in turn means that any class can implement objectAtIndexedSubscript: and become eligible for subscripting notation — including your classes. Note that this method must be publicly declared for the compiler to permit the subscripting notation.

You can form an NSArray in various ways, but typically you’ll start by supplying a list of the objects it is to contain. As I mentioned in Chapter 3, a new Objective-C literal syntax (starting with LLVM compiler version 4.0, Xcode 4.4 or later) lets you wrap this list in @[...] as a way of generating the NSArray:

NSArray* pep = @[@"Manny", @"Moe", @"Jack"];

An NSArray is immutable. This doesn’t mean you can’t mutate any of the objects it contains; it means that once the NSArray is formed you can’t remove an object from it, insert an object into it, or replace an object at a given index. To do those things, you can derive a new array consisting of the original array plus or minus some objects, or use NSArray’s subclass, NSMutableArray.

NSMutableArray’s addObject: and replaceObjectAtIndex:withObject: are supplemented by the same subscripting notation that applies to NSArray. In this case, though, the subscripted reference is an lvalue — you’re assigning to it:

pep[3] = @"Zelda";

That causes the NSMutableArray to be sent setObject:atIndexedSubscript:. The way NSMutableArray implements this, if pep has three elements, pep[3] = @"Zelda" is equivalent to addObject: (you’re appending to the end of the array); if pep has more than three elements, it’s equivalent to replaceObjectAtIndex:withObject:. (If pep has fewer than three elements, an exception is thrown.)

You can walk through (enumerate) every object in an array with the for...in construct described in Chapter 1. (You’ll get an exception if you try to mutate an array while enumerating it.)

You can seek an object within an array with indexOfObject: or indexOfObjectIdenticalTo:; the former’s idea of equality is to call isEqual:, whereas the latter uses pointer equality.

Those familiar with other languages may miss such utility array functions as map, which builds a new array of the results of calling a method on each object in the array. (makeObjectsPerformSelector: requires a selector that returns no value, and enumerateObjectsUsingBlock: requires a block function that returns no value.) The usual workaround is to make an empty mutable array and then enumerate the original array, calling a method and appending each result to the mutable array (Example 10.1). It is also sometimes possible to use key–value coding as a map substitute (see Chapter 12).

NSMutableArray* marr = [NSMutableArray array];
for (id obj in myArray) {
    id result = [obj doSomething];
    [marr addObject: result];
}

You can filter an array to produce a new array consisting of just those objects meeting a test that can be described as an NSPredicate:

NSArray* pep = @[@"Manny", @"Moe", @"Jack"];
NSPredicate* p = [NSPredicate predicateWithFormat:@"self BEGINSWITH[cd] 'm'"];
NSArray* ems = [pep filteredArrayUsingPredicate:p];

To search or filter an array on a more customized test, you can walk through the array applying the test and adding those that meet it to an NSMutableArray (similar to Example 10.1). And there are many methods that give you the ability to search or filter an array using a block:

NSArray* pep = @[@"Manny", @"Moe", @"Jack"];
NSArray* ems =
    [pep objectsAtIndexes: [pep indexesOfObjectsPassingTest:
     ^BOOL(id obj, NSUInteger idx, BOOL *stop) {
         return ([(NSString*)obj rangeOfString:@"m"
             options:NSCaseInsensitiveSearch].location == 0);
    }]];

You can derive a sorted version of the array, supplying the sorting rules in various ways, or if it’s a mutable array, you can sort it directly; see Example 3.1 and Example 3.2.

An NSSet is an unordered collection of distinct objects. “Distinct” means that no two objects in a set can return YES when they are compared using isEqual:. Learning whether an object is present in a set is much more efficient than seeking it in an array, and you can ask whether one set is a subset of, or intersects, another set. You can walk through (enumerate) a set with the for...in construct, though the order is of course undefined. You can filter a set, as you can an array. Indeed, much of what you can do with a set is parallel to what you can do with an array, except that of course you can’t do anything with a set that involves the notion of ordering.

To escape even that restriction, you can use an ordered set. An ordered set (NSOrderedSet) is very like an array, and the methods for working with it are very similar to the methods for working with an array — NSOrderedSet even implements objectAtIndexedSubscript:, so you can fetch an element by subscripting. But an ordered set’s elements must be distinct. Handing an array over to an ordered set uniques the array, meaning that order is maintained but only the first occurrence of an equal object is moved to the set. An ordered set provides many of the advantages of sets: for example, as with an NSSet, learning whether an object is present in an ordered set is much more efficient than for an array, and you can readily take the union, intersection, or difference with another set. Since the distinctness restriction will often prove no restriction at all (because the elements were going to be distinct anyway), it is likely that programmers will want to get into the habit of using NSOrderedSet instead of NSArray wherever possible.

An NSSet is immutable. You can derive one NSSet from another by adding or removing elements, or you can use its subclass, NSMutableSet. Similarly, NSOrderedSet has its mutable counterpart, NSMutableOrderedSet (which implements setObject:atIndexedSubscript:). There is no penalty for adding to, or inserting into, a mutable set an object that the set already contains; nothing is added (and so the distinctness rule is enforced), but there’s no error.

NSCountedSet, a subclass of NSMutableSet, is a mutable unordered collection of objects that are not necessarily distinct (this concept is usually referred to as a bag). It is implemented as a set plus a count of how many times each element has been added.

An NSDictionary is an unordered collection of key–value pairs. The key is usually an NSString, though it doesn’t have to be. The value can be any object. An NSDictionary is immutable; its mutable subclass is NSMutableDictionary.

The keys of a dictionary are distinct (using isEqual: for comparison). If you add a key–value pair to an NSMutableDictionary, then if that key is not already present, the pair is simply added, but if the key is already present, then the corresponding value is replaced.

The fundamental use of an NSDictionary is to request an entry’s value by key (using objectForKey:); if no such key exists, the result is nil, so this is also the way to find out whether a key is present. A dictionary is thus an easy, flexible data storage device, an object-based analogue to a struct. Cocoa often uses a dictionary to provide you with an extra packet of named values, as in the userInfo of an NSNotification, the options parameter of application:didFinishLaunchingWithOptions:, and so on.

The same Objective-C modernizations that brought us array literals and subscripting have brought us dictionary literals and subscripting. In addition to forming a dictionary from an array of objects and an array of keys (dictionaryWithObjects:forKeys:) or as a nil-terminated list of alternating objects and keys (dictionaryWithObjectsAndKeys:), a dictionary may be formed literally as a comma-separated list of key–value pairs, each key followed by a colon and the value, and wrapped in @{...}. Thus, recall our earlier NSUserDefaults example:

[[NSUserDefaults standardUserDefaults] registerDefaults:
    [NSDictionary dictionaryWithObjectsAndKeys:
        @4,
        @"cardMatrixRows",
        @3,
        @"cardMatrixColumns",
        nil]];

That can be rewritten like this:

[[NSUserDefaults standardUserDefaults] registerDefaults:
    @{@"cardMatrixRows":@4, @"cardMatrixColumns":@3}];

To fetch a value from a dictionary by its key, instead of calling objectForKey:, you can now subscript the key in square brackets to the dictionary reference: dict[key]. Similarly, to add a key–value pair to an NSMutableDictionary, instead of calling setObject:forKey:, you can assign to the subscripted dictionary reference. Parallel to NSArray, this is accomplished behind the scenes by calling objectForKeyedSubscript: and setObject:forKeyedSubscript:, and your own classes can declare these methods and be eligible for keyed subscripting notation.

Data structures such as an array of dictionaries, a dictionary of dictionaries, and so forth, are extremely common, and will often lie at the heart of an app’s functionality. Here’s an example from one of my own apps. The app bundle contains a text file laid out like this:

chapterNumber [tab] pictureName [return]
chapterNumber [tab] pictureName [return]

As the app launches, I load this text file and parse it into a dictionary, each entry of which has the following structure:

key: (chapterNumber, as an NSNumber)
value: [Mutable Array]
    (pictureName)
    (pictureName)
    ...

Thus, as we walk the text file, we end up with all pictures for a chapter collected under the number of that chapter. This makes it easy for me later to present all the pictures for a given chapter. For each line of the text file, if the dictionary entry for that chapter number doesn’t exist, we create it, with an empty mutable array as its value. Whether that dictionary entry existed or not, it does now, and its value is a mutable array, so we append the picture name to that mutable array. Observe how this single typical example (Example 10.2) brings together many of the Foundation classes discussed in this section.

NSString* f = [[NSBundle mainBundle] pathForResource:@"index" ofType:@"txt"];
NSError* err = nil;
NSString* s = [NSString stringWithContentsOfFile:f
                                        encoding:NSUTF8StringEncoding
                                           error:&err];
// error-checking omitted
NSMutableDictionary* d = [NSMutableDictionary dictionary];
for (NSString* line in [s componentsSeparatedByString:@"\n"]) {
    NSArray* items = [line componentsSeparatedByString:@"\t"];
    NSInteger chnum = [items[0] integerValue];
    NSNumber* key = @(chnum);
    NSMutableArray* marr = d[key];
    if (!marr) { // no such key, create key–value pair
        marr = [NSMutableArray array];
        d[key] = marr;
    }
    // marr is now a mutable array, empty or otherwise
    NSString* picname = items[1];
    [marr addObject: picname];
}

You can get from an NSDictionary a list of keys, a sorted list of keys, or a list of values. You can walk through (enumerate) a dictionary by its keys with the for...in construct, though the order is of course undefined. A dictionary also supplies an objectEnumerator, which you can use with the for...in construct to walk through just the values. You can also walk through the key–value pairs together using a block, and you can even filter an NSDictionary by some test against its values.

NSNull does nothing but supply a pointer to a singleton object, [NSNull null]. Use this singleton object to stand for nil in situations where an actual object is required and nil is not permitted. For example, you can’t use nil as the value of an element of a collection (such as NSArray, NSSet, or NSDictionary), so you’d use [NSNull null] instead.

Despite what I said earlier about equality, you can test an object against [NSNull null] using the C equality operator, because this is a singleton instance and therefore pointer comparison works.

Beginners sometimes have difficulty with the Foundation’s immutable/mutable class pairs, so here are some hints.

The documentation may not make it completely obvious that the mutable classes obey and, if appropriate, override the methods of the immutable classes. Thus, for example, [NSArray array] generates an immutable array, but [NSMutableArray array] generates a mutable array. (You will look in vain for the expected [NSMutableArray mutableArray].) The same is true of all the initializers and convenience class methods for instantiation: they may all have “array” in their name, but when sent to NSMutableArray, they yield a mutable array.

That fact also answers the question of how to make an immutable array mutable, and vice versa. If arrayWithArray:, sent to the NSArray class, yields a new immutable array containing the same objects in the same order as the original array, then the same method, arrayWithArray:, sent to the NSMutableArray class, yields a mutable array containing the same objects in the same order as the original. Thus this single method can transform an array between immutable and mutable in either direction. You can also use copy (produces an immutable copy) and mutableCopy (produces a mutable copy).

All of the above applies equally, of course, to the other immutable/mutable class pairs. You will often want to work internally and temporarily with a mutable instance but then store (and possibly vend, as an instance variable) an immutable instance, thus protecting the value from being changed accidentally or behind your own back. What matters is not a variable’s declared class but what class the instance really is (polymorphism; see Chapter 5), so it’s good that you can easily switch between an immutable and a mutable version of the same data.

To test whether an instance is mutable or immutable, do not ask for its class. These immutable/mutable class pairs are all implemented as class clusters, which means that Cocoa uses a secret class, different from the documented class you work with. This secret class is subject to change without notice, because it’s none of your business and you should never have looked at it in the first place. Thus, code of this form is subject to breakage:

if ([NSStringFromClass([n class]) isEqualToString: @"NSCFArray"]) // wrong!

Instead, to learn whether an object is mutable, ask it whether it responds to a mutability method:

if ([n respondsToSelector:@selector(addObject:)]) // right

A property list is a string (XML) representation of data. The Foundation classes NSString, NSData, NSArray, and NSDictionary are the only classes that can be converted into a property list. Moreover, an NSArray or NSDictionary can be converted into a property list only if the only classes it collects are these classes, along with NSDate and NSNumber. (This is why, as mentioned earlier, you must convert a UIColor into an NSData in order to store it in user defaults; the user defaults is a property list.)

The primary use of a property list is to store data as a file. NSArray and NSDictionary provide convenience methods writeToFile:atomically: and writeToURL:atomically: that generate property list files given a pathname or file URL, respectively; they also provide inverse convenience methods that initialize an NSArray object or an NSDictionary object based on the property list contents of a given file. For this very reason, you are likely to start with one of these classes when you want to create a property list. (NSString and NSData, with their methods writeToFile:... and writeToURL:..., just write the data out as a file directly, not as a property list.)

When you initialize an NSArray or NSDictionary from a property list file in this way, the objects in the collection are all immutable. If you want them to be mutable, or if you want to convert an instance of one of the other property list classes to a property list, you’ll use the NSPropertyListSerialization class (see the Property List Programming Guide).