Docbook2Wiki: Initial conversion from Docbook

2008-03-07T12:56:06Z

Initial conversion from Docbook

New page

{{Learning Cocoa with Objective-C/TOC}}
Now that we have filled your head with lots of theory about object-oriented programming, we'll look into some of the essential parts of Cocoa's Foundation framework. In this chapter we cover strings, collections, and memory management. Once you have a firm grasp on these topics, you'll be ready for the raison d'être of Cocoa: GUI programming.

The nature of these topics doesn't lend itself to a nifty, all-inclusive code example that shows everything in action at once. So, instead of contriving a single, awkward example, we're just going to work through a set of simple code samples to illustrate the concepts presented. We'll also augment the use of these samples with some usage of the debugger.

== Strings ==

So far, we have worked with strings using the <tt>@" . . . "</tt> construct in various method and function calls. This construct is convenient when working with strings. When interpreted by the compiler, it is translated into an <tt>NSString</tt> object that is based on the 7-bit ASCII-encoded string (also known as a "C string") between the quotes. For example, the statement:

NSString * lush = @'''"'''Lush'''"''';

is functionally equivalent to:

<nowiki>NSString * lush = [[NSString alloc] initWithCString:</nowiki>'''"'''Lush'''"'''];

<tt>NSString</tt> objects are not limited to the ASCII character set; they can handle any character contained in the Unicode character set, allowing most of the world's living languages to be represented. Unicode is a 16-bit-wide character set, but can be represented in 8-bits using the UTF-8 encoding.

=== Basic String Operations ===

<tt>NSString</tt> provides several methods that are handy when working with strings. A few of these methods are as follows:

;<tt>- (int)'''length'''</tt>
: Returns the number of Unicode characters in the string object upon which it is called.

<dl>
<dt><tt>- (const char *)'''cString'''</tt>
<dd>Returns a representation of the string as a C string in the default encoding. This method is helpful when you need to operate with C-based functions, such as those found in traditional Unix system calls.

<div class="warning">
'''Warning'''

It's important to note that since C strings are 7-bit, and the <tt>NSString</tt> class can handle the full Unicode character set, not all <tt>NSString</tt> objects can be represented as C strings.
</div>
</dl>
;<tt>- (const char *)</tt> <tt>'''UTF8String'''</tt>
: Returns a representation of the string as a UTF-8 representation. UTF-8 allows the transmission of Unicode characters over channels that support 8-bit encodings. All of the lower levels of Mac OS X — including the HFS+ and UFS filesystems, as well as the BSD system routines — can handle <tt>char *</tt> arguments in the UTF-8 encoding.
;<tt>- (NSString *)'''stringByAppendingString:'''(NSString *)aString</tt>
: Returns a new string object by appending the given string to the string upon which the method is called.

To explore these methods, we'll create a simple program using the following steps:

<ol>
<li><div>In Project Builder, create a new Foundation Tool (File → New Project → Tool → Foundation Tool) named "strings", and save it in your ''~/LearningCocoa''folder.

<div class="tip">
'''Tip'''

You may have noticed that sometimes our project names start with a lowercase letter and sometimes with an uppercase letter. The common practice in naming applications is that command-line applications should be lowercase and GUI applications should be initial capitalized. We'll use this practice through this book.
</div>
</div></li>

<li><div>Open the ''main.m''file, located in the "Source" group, and modify it to match the code shown in [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-EX-1|Example 4-1]].

<div id="learncocoa2-CHP-4-EX-1">
'''Example 4-1. Working with strings'''

<nowiki>int main (int argc, const char * argv[]) {
NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];

</nowiki>''' NSString * artist = @"Underworld"; // a'''

''' NSLog(@"%@ has length: %d", artist, [artist length]) // b'''

[pool release];
return 0;
}
</div>

The code we added in [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-EX-1|Example 4-1]] performs the following tasks:

# Declares an object of type <tt>NSString</tt>, named <tt>artist</tt>, and sets it to the value <tt>"Underworld"</tt>
# Obtains the <tt>length</tt> of the string and prints it using the <tt>NSLog</tt> function
</div></li>

<li><div>Build and run ([[Image:Learning Cocoa with Objective-C_I_4_tt84.png|]]-R) the application. You will be prompted to save the ''main.m''file, and then Project Builder will compile and the run the code. You should see the following output in Project Builder's console:

2002-06-17 23:29:32.344 strings[1147] Underworld has length: 10

As we have seen before, the <tt>NSLog</tt> function prints the current date and time, the program name, and the process ID (PID) of the program, as well as the output that we told it to print. In the output, we see that the <tt>artist</tt> object was substituted for the <tt>%@</tt> token and that the return value from the <tt>length</tt> method was substituted for the <tt>%d</tt> token. Remember, you can use any of the standard <tt>printf</tt> substitution tokens in the format string, in addition to the <tt>%@</tt> token.
</div></li>

</ol>

==== Setting breakpoints and debugging ====

Instead of adding code to the strings tool, we will use the debugger to explore the <tt>UTF8String</tt> and <tt>stringByAppendingString</tt> methods. This will give you some practice using the debugger, while you learn about these methods.

<ol>
<li><div>Set a breakpoint between the <tt>NSLog</tt> function and the <tt>[pool release]</tt> line of code in ''main.m''. Remember to set a breakpoint, click in the column on the left side of the code editor. If you want to move the breakpoint, click and drag the breakpoint to its new location. In our code, this breakpoint is at line 8. An example of the breakpoint set is shown in [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-FIG-1|Figure 4-1]].

<div id="learncocoa2-CHP-4-FIG-1">
'''Figure 4-1. Setting a breakpoint in the main.m file'''

[[Image:Learning Cocoa with Objective-C_I_4_tt86.png|Setting a breakpoint in the main.m file]]
</div>
</div></li>

<li><div>Build and debug the application (Build → Build and Debug, or [[Image:Learning Cocoa with Objective-C_I_4_tt87.png|]]-Y). Execution will start and then pause at the breakpoint we set, highlighting the line at which it stopped in a salmon colored bar.
</div></li>

<li><div>Click on the Console tab above the variable viewer to open up the debugger console, as shown in [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-FIG-2|Figure 4-2]]. You should see that the <tt>NSLog</tt> function outputs its string.

<div id="learncocoa2-CHP-4-FIG-2">
'''Figure 4-2. Program execution paused at breakpoint'''

[[Image:Learning Cocoa with Objective-C_I_4_tt88.png|Program execution paused at breakpoint]]
</div>

<div class="tip">
'''Tip'''

The debugger console behaves similarly to working with the Terminal application. You enter a command, hit Return, and the result of the command is shown on the next line. Just like the default shell in the Terminal, the debugger maintains a history of commands that you can access by hitting the up and down arrows on your keyboard.
</div>
</div></li>

<li><div>Type in <tt>print-object artist</tt> at the <tt>(gdb)</tt> prompt in the debugger console. You may have to click in the debugger console to give it focus, so that you can enter commands.

(gdb) '''print-object artist'''

When you enter this command, the debugger outputs the following:

Underworld
</div></li>

</ol>

In addition to simply printing objects, we can print the result of any message that we can send to an object. This functionality is incredibly useful when trying to find the various states of an object while using the debugger.

<ol>
<li><div>Enter in the following into the debugger console:

(gdb) '''print-object [artist description]'''

The following result, matching what we just saw in Step 4, will be printed:

Underworld
</div></li>

<li><div>Let's see the <tt>stringByAppendingString</tt> method in action. Enter the following into the debugger console:

(gdb) '''print-object [artist stringByAppendingString:@": Pearl's Girl"]'''

The debugger outputs the following result of the method call:

Underworld: Pearl's Girl
</div></li>

<li><div>You can also send messages to <tt>NSString</tt> objects created using the <tt>@"..."</tt> construct. Enter the following into the debugger console:

(gdb) '''print-object [@"The artist is: " stringByAppendingString:artist]'''

The debugger outputs:

The artist is: Underworld
</div></li>

</ol>

The next debugger command we will learn is the <tt>print</tt> command. This command prints out C types instead of objects. We will use the <tt>print</tt> command to evaluate the return values of the <tt>length</tt> and <tt>UTF8String</tt> methods.

<ol>
<li><div>Enter the following into the debugger console:

(gdb) '''print (int) [artist length]'''

The debugger outputs:

$1 = 10

The <tt>$1</tt> symbol is a temporary variable that holds the results of the message, and the <tt>10</tt> denotes the number of characters (or <tt>length</tt>) in the <tt>artist</tt> object. Note that we needed to cast the return type from the <tt>length</tt> message so that the <tt>print</tt> command could operate. Try this again without the <tt>(int)</tt> cast.
</div></li>

<li><div>To see the <tt>UTF8String</tt> method in action, enter the following:

(gdb) '''print (char *) [artist UTF8String]'''

The debugger outputs something similar to the following:

$2 = 0x9f738 "Underworld\000"...

This is the null-terminated <tt>char *</tt> string representation, in UTF-8 encoding, of our <tt>artist</tt> string.

To quit the debugger, you can either click the stop button or enter <tt>quit</tt> at the <tt>(gdb)</tt> prompt.
</div></li>

</ol>

<div class="sidebar">
'''Debugger Command Cheat Sheet'''

There's a lot more that the debugger can do. Here are a few of our favorite debugger commands. Try them out to see what they do.

;<tt>call [exp]</tt>
: Calls the given function on an object.
;<tt>print [exp]</tt>
: Prints the primitive value of the expression given.
;<tt>print-object [exp]</tt>
: Prints the value of the object returned by the expression.
;<tt>set [variable] = [exp]</tt>
: Sets the variable to the value of the expression. For example, we can reset the artist variable to a new string by using the expression <tt>set</tt> <tt/> <tt>artist = @"New Artist".</tt>
;<tt>whatis [variable]</tt>
: Prints the kind, or type, of a variable.
;<tt>help</tt>
: Prints out a list of the commands available while using the debugger.
</div>

=== Working with Portions of a String ===

When working with strings, it often is necessary to extract data from them. The <tt>NSString</tt> class provides the following methods for finding and obtaining substrings:

;<tt>- (NSRange)'''rangeOfString:'''(NSString *)aString</tt>
: Returns an <tt>NSRange</tt> struct that contains the <tt>location</tt> and <tt>length</tt> of the first occurrence of the given string
;<tt>- (NSString *)'''substringFromIndex:'''(unsigned)index</tt>
: Returns a string object that contains the characters of the receiver, from the index given to the end of the string
;<tt>- (NSString *)'''substringToIndex:'''(unsigned)index</tt>
: Returns a string object that contains the characters of the receiver, from the beginning of the string to the index given
;<tt>- (NSString *)'''substringWithRange:'''(NSRange)range</tt>
: Returns a string object that contains the characters of the receiver, within the range specified

To explore these methods, we'll create a simple program (that works with just substrings) using the following steps:

<ol>
<li><div>In Project Builder, create a new Foundation Tool (File → New Project → Tool → Foundation Tool) named "substrings", and save it in your ''~/LearningCocoa''folder.
</div></li>

<li><div>Open the ''main.m''file, located in the "Source" group, and modify it to match the code shown in [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-EX-2|Example 4-2]].

<div id="learncocoa2-CHP-4-EX-2">
'''Example 4-2. Working with substrings'''

<nowiki>int main (int argc, const char * argv[]) {
NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];

</nowiki>''' NSString * song = @"Let Forever Be,The Chemical Brothers"; // a'''
''' NSRange range = [song rangeOfString:@ ","]; // b'''
''' printf("comma location: %i\n", range.location); // c'''

''' NSString * title = [song substringToIndex:range.location]; // d'''
''' NSString * artist ='''
''' [song substringFromIndex:range.location + range.length]; // e'''

''' printf("title: %s\n", [title UTF8String]); // f'''
''' printf("artist: %s\n", [artist UTF8String]); // g'''

[pool release];
return 0;
}
</div>

The code we added in [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-EX-2|Example 4-2]] performs the following tasks:

# Declares a string object named <tt>song</tt> and sets it.
# Obtains the range of the comma in the <tt>song</tt> string.
# Prints the location of the comma. Notice that we are using the standard C <tt>printf</tt> function here. We will use <tt>printf</tt> instead of <tt>NSLog</tt> in many of the upcoming exercises, so the output from our programs won't be cluttered with timestamps and PIDs. Note that, unlike the <tt>NSLog</tt> function, we have to be sure to include the <tt>\n</tt> character to print out the new line.
# Declares a string named <tt>title</tt> and sets it to the substring, from the start of the <tt>song</tt> string to the location of the comma.
# Declares a string named artist and sets it to the substring, from the comma to the end of the <tt>song</tt> string. We use the <tt>range.location</tt> <tt>+</tt> <tt>range.length</tt> construction so that we find the index just after the comma value. If we just used the location of the comma, it would show up in our substring.
# Prints the <tt>title</tt> to the console, using the UTF-8 representation of the string. Notice that we are using the <tt>printf %s</tt> token.
# Prints the <tt>artist</tt> to the console, using the UTF-8 representation of the string.
</div></li>

<li><div>Build and run ([[Image:Learning Cocoa with Objective-C_I_4_tt101.png|]]-R) the application. You will be prompted to save your files, and then Project Builder will compile and run the code. You should see the following output in the console:

comma location: 14
title: Let Forever Be
artist: The Chemical Brothers
</div></li>

</ol>

=== Mutable Strings ===

Once created, instances of the <tt>NSString</tt> class cannot be changed; they are ''immutable''. If you want to change the contents of an <tt>NSString</tt> object, you must create a new one, as we saw using the <tt>stringByAppendingString</tt> method. In programs that manipulate strings extensively, this would become cumbersome quickly. To let you modify the contents of a string, Cocoa provides the <tt>NSMutableString</tt> class.

<div class="tip">
'''Tip'''

If you have programmed in Java, <tt>NSMutableString</tt> can be considered analogous to the <tt>java.lang.StringBuffer</tt> class.
</div>

Some of the methods that you frequently will use with mutable strings are the following:

;<tt>- (void)'''appendString:'''(NSString *)aString</tt>
: Adds the characters of the given string to those already in the mutable string object upon which the method is called.
;<tt>- (void)'''deleteCharactersInRange:'''(NSRange)range</tt>
: Deletes the characters in a given range.
;<tt>- (void)</tt> <tt>'''insertString:'''</tt> <tt>(NSString *)aString '''atIndex:'''(unsigned index)</tt>
: Inserts the characters of the given string into the mutable string at the location specified by the index. All of the characters from the insertion point to the end of the mutable string are shifted to accommodate the new characters.

To explore these methods, we'll create yet another simple program, using the following steps:

<ol>
<li><div>In Project Builder, create a new Foundation Tool (File → New Project → Tool → Foundation Tool) named "mutablestrings", and save it in your ''~/LearningCocoa''folder.
</div></li>

<li><div>Open the ''main.m''file, located in the "Source" group, and modify it to match the following code:

<nowiki>int main (int argc, const char * argv[]) {
NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
</nowiki>'''<nowiki> NSMutableString * song = [[NSMutableString alloc] init]; // a</nowiki>'''
''' [song appendString:@"Deaf Leppard"]; // b'''
''' printf("%s\n", [song UTF8String]); // c'''

''' NSRange range = [song rangeOfString:@"Deaf"]; // d'''
''' [song replaceCharactersInRange:range withString:@"Def"]; // e'''
''' printf("%s\n", [song UTF8String]); // f'''

''' [song insertString:@"Animal by " atIndex:0]; // g'''
''' printf("%s\n", [song UTF8String]); // h'''

''' [song release]; // i'''

[pool release];
return 0;
}

The code we added performs the following tasks:

# Creates a new empty mutable string named <tt>song</tt>.
# Appends the contents of the "Deaf Leppard" string to the <tt>song</tt> mutable string.
# Prints the <tt>song</tt> mutable string to the console.
# Gets the range of the "Deaf" substring.
# Replaces the "Deaf" substring with "Def" to correct the misspelling.
# Prints the <tt>song</tt> mutable string to the console.
# Inserts the string "Animal by" at the beginning the mutable string.
# Once again prints the <tt>song</tt> mutable string.
# Releases the <tt>song</tt> object. Because we created the <tt>Song</tt> object using the <tt>alloc</tt> method, we are responsible forr releasing it. We'll explain more about how this works later in this chapter.
</div></li>

<li><div>Build and run ([[Image:Learning Cocoa with Objective-C_I_4_tt104.png|]]-R) the application. You should see the following output in the console:

Deaf Leppard
Def Leppard
Animal by Def Leppard
</div></li>

</ol>

<div class="sidebar">
'''Mutability Versus Immutability'''

Why does Cocoa provide both mutable and immutable versions of strings and the collection classes? The answer is that there are tradeoffs to both kinds of objects. An immutable object, once created, can't change. This means that a higher performing implementation can be used. Mutable objects, on the other hand, aren't nearly so amenable to performance tuning, as there is overhead involved in keeping them "editable."

In addition, immutable objects are inherently thread-safe and can be passed to code worked on by other programmers without fear that the contents of the object will be modified. When creating your own code, you should favor immutable objects unless you need the ability to change the contents of an object.
</div>

=== Working with Files ===

A common use of strings is to work with paths to files in the filesystem. The <tt>NSString</tt> class provides several methods to manipulate strings as filesystem paths, extract a file name or an extension, resolve paths containing symbolic links, and even expand tilde expressions (such as ''~duncan/Library'') in paths. Some of the commonly used path manipulation methods are as follows:

;<tt>- (NSString *)'''lastPathComponent'''</tt>
: Returns the last path component of the receiver. For example, if you call this method on the string <tt>~/LearningCocoa/substrings/main.m</tt>, it will return <tt>main.m</tt>.
;<tt>- (NSString *)'''pathExtension'''</tt>
: Returns the extension, if any, of a file path. For example, if you call this method on the string <tt>main.m</tt>, it will return the value <tt>m</tt>.
;<tt>- (NSString *)'''stringByStandardizingPath'''</tt>
: Returns a string with all extraneous path components removed or resolved. This method will resolve the initial tilde expression, as well as any <tt>..</tt> or <tt>./</tt> symbols, to actual directories.

In addition to working with paths, you can also create string objects using the contents of a file and write string objects to files using the following methods:

;<tt>- (NSString *)'''stringWithContentsOfFile:'''(NSString *)path</tt>
: Creates a new string by reading characters from the file specified by the path argument.
;<tt>- (BOOL)'''writeToFile:'''(NSString *)path '''atomically:'''(BOOL)flag</tt>
: Writes the contents of the string to the given file. The <tt>atomically</tt> flag indicates whether the file should be written safely to an auxiliary file, then copied into place. Most of the time, this setting makes no difference. The only time it matters is if the system crashes when the file is being flushed to disk.

To see these methods in action, follow the following steps:

<ol>
<li><div>In Project Builder, create a new Foundation Tool (File → New Project → Tool → Foundation Tool) named "filestrings", and save it in your ''~/LearningCocoa''folder.
</div></li>

<li><div>Open the ''main.m''file, located in the "Source" group, and modify it to match the code shown in [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-EX-3|Example 4-3]].

<div id="learncocoa2-CHP-4-EX-3">
'''Example 4-3. Reading files into strings'''

<nowiki>int main (int argc, const char * argv[]) {
NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];

</nowiki>''' NSString * filename = @"~/LearningCocoa/filestrings/main.m"; // a'''

''' filename = [filename stringByStandardizingPath]; // b'''

''' printf("%s\n", [filename UTF8String]); // c'''

''' NSString * source = [NSString stringWithContentsOfFile:filename]; // d'''

''' printf("%s\n", [source UTF8String]); // e'''

[pool release];
return 0;
}
</div>

The code we added in [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-EX-3|Example 4-3]] performs the following tasks:

# Creates a string object, named <tt>filename</tt>, that contains the path to the ''main.m''source file of this project. Note that you must save your project in your ''~/LearningCocoa''folder for this example to work. If you are saving your projects to some other location, you will need to edit the path appropriately.
# Sets the <tt>filename</tt> variable to a standardized path. This will resolve the <tt>~/</tt> characters to your home directory.
# Prints the resolved <tt>filename</tt> variable.
# Creates a new string, named <tt>source</tt>, with the contents of the ''main.m''source file.
# Prints the <tt>source</tt> string to the console.
</div></li>

<li><div>Build and run ([[Image:Learning Cocoa with Objective-C_I_4_tt106.png|]]-R) the application. You should see output similar to the following appear in the console:

<nowiki>/Users/duncan/LearningCocoa/filestrings/main.m
#import <Foundation/Foundation.h>

int main (int argc, const char * argv[]) {
NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];

NSString * filename = @"~/LearningCocoa/filestrings/main.m";
filename = [filename stringByStandardizingPath];
printf("%s\n", [filename UTF8String]);

NSString * source = [NSString stringWithContentsOfFile:filename];
printf("%s\n", [source UTF8String]);

[pool release];
return 0;
}</nowiki>
</div></li>

</ol>

We'll explore the <tt>lastPathComponent</tt> and <tt>pathExtension</tt> methods using the debugger.

<ol>
<li><div>Set a breakpoint between the last <tt>printf</tt> statement and the <tt>[pool release];</tt> line. If you typed the code exactly as shown in [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-EX-3|Example 4-3]], the breakpoint will be on line 12.
</div></li>

<li><div>Build and debug the application ([[Image:Learning Cocoa with Objective-C_I_4_tt108.png|]]-Y). Execution will start and then pause at the breakpoint.
</div></li>

<li><div>Click on the Console tab above the variable viewer to open up the debugger console.
</div></li>

<li><div>Type in the following at the <tt>(gdb)</tt> prompt:

(gdb) '''print-object [filename'''
'''lastPathComponent]'''

When you enter this command, the debugger should output the following:

main.m
</div></li>

<li><div>Type in the following at the <tt>(gdb)</tt> prompt:

(gdb) '''print-object [filename'''
'''pathExtension]'''

When you enter this command, you should see the following:

m
</div></li>

<li><div>Quit the debugger; use the Stop button, or type in <tt>quit</tt> at the <tt>(gdb)</tt> prompt and hit return.
</div></li>

</ol>

Now that we've covered quite a few things that you can do with strings, it's time to look at Cocoa's collection classes.

== Collections ==

Cocoa provides several classes in the Foundation Kit whose purpose is to hold and organize instances of other classes. These are called the ''collection classes''. There are three primary flavors of collections in Cocoa: ''arrays'' , ''sets'' , and ''dictionaries'' . These classes, shown in [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-FIG-3|Figure 4-3]], are extremely useful in Cocoa application development, and their influence can be found throughout the Cocoa class libraries.

<div id="learncocoa2-CHP-4-FIG-3">
'''Figure 4-3. Cocoa collection classes'''

[[Image:Learning Cocoa with Objective-C_I_4_tt113.png|Cocoa collection classes]]
</div>

Collection classes, like strings, come in two forms: ''mutable'' and ''immutable'' . Immutable classes allow you to add items when the collection is created, but no further changes are allowed. On the other hand, mutable classes allow you to add and remove objects programmatically after the collection is created.

Much of the power of collection classes comes from their ability to manipulate the objects they contain. Not every collection object can perform every function, but in general, collection objects can do the following:

* Derive their initial contents from files and URLs, as well as other collections of objects
* Add, remove, locate, and sort contents
* Compare their contents with other collection objects
* Enumerate over their contents
* Send a message to the objects that they contain
* Archive their contents to a file on disk and retrieve it later<ref>Objects placed into an array must implement certain methods to support this functionality. All of the Foundation classes that you are likely to add to a collection are already prepared for this.</ref>

=== Arrays ===

Arrays—instances of the <tt>NSArray</tt> class—are ordered collections of objects indexed by integers. Like C-based arrays, the first object in an array is located at index 0. Unlike C- and Java-based arrays whose size is set when they are created, Cocoa mutable array objects can grow as needed to accommodate inserted objects.

The <tt>NSArray</tt> class provides the following methods to work with the contents of an array:

;<tt>- (unsigned)'''count'''</tt>
: Returns the number of objects currently in the array.
;<tt>- (id)'''objectAtIndex:'''(unsigned)index</tt>
: Returns the object located in the array at the index given. Like C- and Java-based arrays, Cocoa array indexes start at 0.
;<tt>- (BOOL)'''containsObject:'''(id)anObject</tt>
: Indicates whether a given object is present in the array.

To practice working with arrays do as follows:

<ol>
<li><div>In Project Builder, create a new Foundation Tool (File → New Project → Tool → Foundation Tool) named "arrays", and save it in your ''~/LearningCocoa''folder.
</div></li>

<li><div>Open the ''main.m''file, located in the "Source" group, and modify it to match the following code:

<nowiki>int main (int argc, const char * argv[]) {
NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
</nowiki>''' NSString * string = @"one two buckle my shoe"; // a'''
''' NSArray * array = [string componentsSeparatedByString:@" "]; // b'''
''' int count = [array count]; // c'''
''' int i;'''
''' for ( i = 0; i < count; i++ ) {'''
'''<nowiki> printf("%i: %s\n", i, [[array objectAtIndex:i] UTF8String]); // d</nowiki>'''
''' }'''

[pool release];
return 0;
}

The code we added performs the following tasks:

# Declares a new string.
# Creates an array of string objects using the <tt>componentsSeparatedByString:</tt> method of the <tt>NSString</tt> class. Note that in the first example of this chapter, where we looked for the range of the comma to split the spring, we could have used this method to get the two strings.
# Obtains the count of the array to use in the <tt>for</tt> loop.
# Prints each item of the array to the console.
</div></li>

<li><div>Build and run ([[Image:Learning Cocoa with Objective-C_I_4_tt115.png|]]-R) the application. You should see output similar to the following appear in the console:

0: one
1: two
2: buckle
3: my
4: shoe
</div></li>

</ol>

==== Using the debugger to explore NSArray ====

We'll explore a few more <tt>NSArray</tt> methods using the debugger:

<ol>
<li><div>Set a breakpoint after the <tt>for</tt> loop. If you typed in the code exactly as noted previously, including the spaces and the comments that are part of the ''main.m'' file template, the breakpoint will be on line 15.
</div></li>

<li><div>Build and debug ([[Image:Learning Cocoa with Objective-C_I_4_tt117.png|]]-Y) the application. Execution will start and then pause at the breakpoint we set.
</div></li>

<li><div>Click on the Console tab to open up the debugger console.
</div></li>

<li><div>Type in the following at the <tt>(gdb)</tt> prompt:

(gdb) '''print-object [array objectAtIndex:4]'''

You should see the following output:

shoe
</div></li>

<li><div>Type in the following:

(gdb) '''print (int) [array containsObject:@"buckle"];'''

You should see the following output:

$1 = 1

This indicates that the array did contain the string we specified. Try using a string that isn't in the array, and see what the return value is. You should see a return value of <tt>0</tt>.
</div></li>

<li><div>Quit the debugger, and close the project.
</div></li>

</ol>

=== Mutable Arrays ===

The <tt>NSMutableArray</tt> class provides the functionality needed to manage a modifiable array of objects. This class extends the <tt>NSArray</tt> class by adding insertion and deletion operations. These operations include the following methods:

;<tt>- (void)'''addObject:'''(id)anObject</tt>
: Inserts the given object to the end of the receiving array.
;<tt>- (void)'''insertObject:'''(id)anObject '''atIndex:'''(unsigned index)</tt>
: Inserts the given object to the receiving array at the index specified. All objects beyond the index are shifted down one slot to make room.
;<tt>- (void)'''removeObjectAtIndex:'''(unsigned index)</tt>
: Removes the object from the receiving array located at the index and shifts all of the objects beyond the index up one slot to fill the gap.
;<tt>- (void)'''removeObject:'''(id)anObject</tt>
: Removes all occurrences of an object in the receiving array. The gaps left by the objects are removed by shifting the remaining objects.

The following steps will explore these methods:

<ol>
<li><div>In Project Builder, create a new Foundation Tool (File → New Project → Tool → Foundation Tool) named "mutablearrays", and save it in your ''~/LearningCocoa''folder.
</div></li>

<li><div>Open the ''main.m''file, located in the "Source" group, and modify it to match the code shown in [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-EX-4|Example 4-4]].

<div id="learncocoa2-CHP-4-EX-4">
'''Example 4-4. Working with mutable arrays'''

<nowiki>int main (int argc, const char * argv[]) {
NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];

</nowiki>'''<nowiki> NSMutableArray * array = [[NSMutableArray alloc] init]; // a</nowiki>'''

''' [array addObject:@"sheryl crow"]; // b'''

''' [array addObject:@"just wants to have fun"]; // c'''

'''<nowiki> printf("%s\n", [[array description] UTF8String]); // d</nowiki>'''

''' [array release]; // e'''

[pool release];
return 0;
}
</div>

The code we added in [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-EX-4|Example 4-4]] performs the following tasks:

# Creates a new mutable array
# Adds an object to the array
# Adds another object to the array
# Prints the array
# Releases the array, since we created it using the <tt>alloc</tt> method
</div></li>

<li><div>Build and run ([[Image:Learning Cocoa with Objective-C_I_4_tt122.png|]]-R) the application. You should see the following output in the console:

("sheryl crow", "just wants to have fun")
</div></li>

</ol>

==== Exploring NSMutableArray with the debugger ====

We'll further explore the <tt>NSMutableArray</tt> class using the debugger:

<ol>
<li><div>Set a breakpoint before the line of code that releases the array (line 10).
</div></li>

<li><div>Build and debug ([[Image:Learning Cocoa with Objective-C_I_4_tt124.png|]]-Y) the application. Execution will start and then pause at the breakpoint.
</div></li>

<li><div>Click on the Console tab to open up the debugger console.
</div></li>

<li><div>First, we insert an object into the array after the first object. Then we'll print it out to see the modified array. Type in the following:

(gdb) '''call (void) [array insertObject:@"santa monica" atIndex:1]'''
(gdb) '''print-object array'''

The following output should appear.

<NSCFArray 0x94be0>(
sheryl crow,
santa monica,
just wants to have fun
)
</div></li>

<li><div>Now remove one of the objects:

(gdb) '''call (void) [array removeObject:@"just wants to have fun"]'''
(gdb) '''print-object array'''

The following will be output:

<NSCFArray 0x94be0>(
sheryl crow,
santa monica
)
</div></li>

<li><div>Quit the debugger, and close the project.
</div></li>

</ol>

=== Arrays and the Address Book ===

As a quick example of how to use arrays in a situation that isn't so contrived, we will use an API introduced in Mac OS X 10.2—the Address Book API. The Address Book serves as a central contact database that can be used by all applications on the system. The hope is that you won't need a separate contact database for your mailer, for your fax software, etc. Already, the applications that ship with Mac OS X, such as Mail and iChat, utilize the Address Book. The Address Book application is shown in [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-FIG-4|Figure 4-4]].

<div id="learncocoa2-CHP-4-FIG-4">
'''Figure 4-4. The Address Book'''

[[Image:Learning Cocoa with Objective-C_I_4_tt129.png|The Address Book]]
</div>

Use the following steps to guide you in this exploration:

<ol>
<li><div>Launch the Address Book application (it is installed in your Dock by default; you can find it in the ''/Applications''folderotherwise), and make sure that you have some contacts defined.
</div></li>

<li><div>In Project Builder, create a new Foundation Tool (File → New Project → Tool → Foundation Tool) named "addresses", and save it to your ''~/LearningCocoa''folder.
</div></li>

<li><div>Add the Address Book framework to the project by selecting the Project → Add Frameworks menu item. A dialog box will open, asking you to select the framework to add. It should open up to the ''/System/Library/Frameworks''folder. If not, navigate to that folder, and select the ''AddressBook.framework''folderto add to the project. After you click the Add button, a sheet will appear to control how the framework should be added. The settings shown will be fine, and all you need to do is click the Add button again.

This step ensures that Project Builder links against the AddressBook framework, as well as the Foundation framework, when it builds our application.
</div></li>

<li><div>Open the ''main.m'' file, and modify it to match the following code:

#import <Foundation/Foundation.h>
'''#import <AddressBook/AddressBook.h> // a'''<nowiki>

int main (int argc, const char * argv[]) {
NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
</nowiki>''' ABAddressBook * book = [ABAddressBook sharedAddressBook]; // b'''
''' NSArray * people = [book people]; // c'''

''' int count = [people count];'''
''' int i;'''
''' for (i = 0; i < count; i++) {'''
''' ABPerson * person = [people objectAtIndex:i]; // d'''
''' NSString * firstName = [person valueForProperty:@"First"]; // e'''
''' NSString * lastName = [person valueForProperty:@"Last"]; // f'''
''' printf("%s %s\n",'''
''' [lastName UTF8String],'''
''' [firstName UTF8String]); // g'''
''' }'''

[pool release];
return 0;
}

The code we added performs the following tasks:

# Imports the AddressBook API set. Without this line, the compiler cannot compile the ''main.m''file, because it won't be able to find the definitions for the Address Book classes.
# Obtains the Address Book for the logged-in user.
# Obtains an array containing all of the people in the Address Book.
# Loops through the people to obtain an <tt>ABPerson</tt> object. The <tt>ABPerson</tt> class provides the methods to work with the various attributes that a person record has in the Address Book database.
# Gets the first name of the person.
# Gets the last name of the person.
# Prints the name of the person out to the console.

<div class="tip">
'''Tip'''

For more information about the various classes in the AddressBook framework, see the files in ''/Developer/Documentation/AdditionalTechnologies/AddressBook''.
</div>
</div></li>

<li><div>Build and run ([[Image:Learning Cocoa with Objective-C_I_4_tt131.png|]]-R) the application. You should see a list of your contacts output in the console. Here's a sample from our run of the application, using the contacts pictured in [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-FIG-4|Figure 4-4]]:

Davidson James Duncan
Hunter Jason
Ronconi Eleo
Horwat Justyna
Driscoll Jim
Davidson Ted
Branham Christine
Behlendorf Brian
O'Reilly Tim
Toporek Chuck
Czigany Susan
</div></li>

</ol>

We haven't gone into great detail on the use of the AddressBook, but just a little knowledge on arrays has already let you work with this important user data. By the time you're done with this book, just think how dangerous you will be! But no matter how dangerous you get, you should remember to use the Address Book API when you create an application that needs to keep track of contacts. Also, you'll be able to build some pretty neat apps using this data. For example, I'm considering building an application that automatically prints Christmas cards to send to all the contacts that I consider to be friends.

=== Sets ===

Sets—implemented by the <tt>NSSet</tt> and <tt>NSMutableSet</tt> classes—are an unordered collection of objects in which each object can appear only once. A set can be used instead of an array when the order of elements in the collection is not important, but when testing to see if an object is part of the set (usually referred to as "testing for membership"), speed is important. Testing to see if an object is a member of a set is faster than testing against an array.

=== Dictionaries ===

Dictionaries—implemented in the <tt>NSDictionary</tt> class—store and retrieve objects using ''key-value'' pairs. Each key-value pair in a dictionary is called an ''entry'' . The keys in a dictionary form a set; a key can be used only once in a dictionary. Although the key is usually a string (an <tt>NSString</tt> object), most objects can be used as keys.<ref>The object used as a key must respond to the <tt>isEqual:</tt> message and conform to the <tt>NSCopying</tt> protocol. Since we have not covered protocols yet, the rule of thumb is that any Cocoa object provided in the Foundation framework can be used as a key. Other objects may not work.</ref> To enable the retrieval of a value at a later time, the key of the key-value pair should be immutable or treated as immutable. If the key changes after being used to put a value in the dictionary, the value might not be retrievable. The <tt>NSDictionary</tt> class provides the following methods to work with the contents of an array:

;<tt>- (unsigned)'''count'''</tt>
: Returns the number of objects currently in the dictionary
;<tt>- (id)'''objectForKey:'''(id)aKey</tt>
: Returns the object that is indexed using the given key in the dictionary
;<tt>- (NSArray *)'''allKeys'''</tt>
: Returns an array containing all of the keys in the dictionary

To practice working with dictionaries:

<ol>
<li><div>In Project Builder, create a new Foundation Tool (File → New Project → Tool → Foundation Tool) named "dictionaries", and save it in your ''~/LearningCocoa''folder.
</div></li>

<li><div>Open the ''main.m''file, located in the "Source" group, and modify it to match the code shown in [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-EX-5|Example 4-5]].

<div id="learncocoa2-CHP-4-EX-5">
'''Example 4-5. Working with dictionaries'''

<nowiki>int main (int argc, const char * argv[]) {
NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];

</nowiki>''' NSArray * keys ='''
''' [@"one two three four five" componentsSeparatedByString:@" "]; // a'''
''' NSArray * values ='''
''' [@"alpha bravo charlie delta echo" componentsSeparatedByString:@" "]; // b'''

'''<nowiki> NSDictionary * dict = [[NSDictionary alloc] initWithObjects:values</nowiki>'''
''' forKeys:keys]; // c'''

'''<nowiki> printf("%s\n", [[dict description] UTF8String]); // d</nowiki>'''
[pool release];
return 0;
}
</div>

The code we added in [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-EX-5|Example 4-5]] performs the following tasks:

# Creates a new array based on a space-delimited string. This set of objects will serve as the keys for the dictionary.
# Creates a new array that will serve as the values of the dictionary.
# Creates a new dictionary with our keys and values.
# Prints the dictionary, so it can be examined.
</div></li>

<li><div>Build and run ([[Image:Learning Cocoa with Objective-C_I_4_tt133.png|]]-R) the application. You should see output similar to the following appear in the console:

{five = echo; four = delta; one = alpha; three = charlie; two = bravo; }
</div></li>

<li><div>This is a representation of the structure of the dictionary. Note that the elements are not stored in any particular order. Remember that the keys form a set in which uniqueness, not order, is critical.
</div></li>

</ol>

We'll explore this example further using the debugger.

<ol>
<li><div>Set a breakpoint after the <tt>printf</tt> statement. If you typed in the code exactly as listed earlier, the breakpoint will be on line 15.
</div></li>

<li><div>Build and debug ([[Image:Learning Cocoa with Objective-C_I_4_tt135.png|]]-Y) the application, open the debugger console, and type the following:

(gdb) '''print (int) [dict count]'''

The following will be output:

$1 = 5

This tells us that there are five elements in the collection.
</div></li>

<li><div>Type the following:

(gdb) '''print-object [dict objectForKey:@"three"]'''

The following will be output:

charlie
</div></li>

<li><div>Type the following:

(gdb) '''print-object [dict allKeys]'''

The following will be output:

<NSCFArray 0x97800>(
two,
four,
three,
one,
five
)
</div></li>

<li><div>Quit the debugger, and close the project.
</div></li>

</ol>

The strengths of the dictionary classes will become apparent when we discuss how they can hold and organize data that can be labeled, such as values extracted from text fields in a user interface. We'll show this in action in [[Learning Cocoa with Objective-C/Single-Window Applications/Models and Data Functionality|Chapter 9]], when we show how you can work with dictionaries to drive tables in user interfaces.

=== Mutable Dictionaries ===

The <tt>NSMutableDictionary</tt> class provides the functionality needed to manage a modifiable dictionary. This class extends the <tt>NSDictionary</tt> class by adding insertion and deletion operations. These operations include the following methods:

;<tt>- (void)'''setObject:'''(id)anObject '''forKey:'''(id)aKey</tt>
: Adds an entry to the dictionary, consisting of the given key-value pair. If the key already exists in the dictionary, the previous object associated with that key is removed from the dictionary and replaced with the new object.
;<tt>- (void)removeObjectForKey:'''(id)aKey'''</tt>
: Removes the key and its associated value from the dictionary. <tt/>

<div class="sidebar">
'''Working with Numbers'''

Collections can hold only objects; they cannot hold C-based primitive types such as <tt>int</tt>, <tt>float</tt>, and <tt>long</tt>. However, there will be many cases where you will want to store primitive types in your collections. To allow these types to be manipulated as objects, Cocoa provides the <tt>NSNumber</tt> class. This class can wrap any C numeric type and defines a group of methods to set and access the value. In addition, it defines a <tt>compare:</tt> method, allowing two numbers to be compared with each other.
</div>

=== Storing Collections as Files ===

One of the nicer things about Cocoa's collection classes is that they support the writing and reading of collection data to and from files called ''property lists'' , or ''plist'' files. This lets you store your data easily and read it later. In fact, Mac OS X uses property lists extensively to store all kinds of data, such as user preferences, application settings, and system-configuration data. In upcoming chapters, we'll be working with user preferences (also known as ''defaults'') and we will see how Mac OS X uses plists in application bundles.

The methods to support this functionality are relatively simple. For the array and dictionary classes, these methods are as follows:

;<tt>- (id)'''initWithContentsOfFile:'''(NSString *)aPath</tt>
: Initializes a newly allocated array or dictionary with the contents of the file specified by the path argument
;<tt>- (BOOL)'''writeToFile:'''(NSString *)path '''atomically:'''(BOOL)flag</tt>
: Writes the contents of an array or dictionary to the file specified by the path argument

To practice working with collections and files do as follows:

<ol>
<li><div>In Project Builder, create a new Foundation Tool (File → New Project → Tool → Foundation Tool) named "collectionfiles", and save it in your ''~/LearningCocoa''folder.
</div></li>

<li><div>Open the ''main.m''file, and modify it to match [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-EX-6|Example 4-6]].

<div id="learncocoa2-CHP-4-EX-6">
'''Example 4-6. Working with property lists'''

<nowiki>#import <Foundation/Foundation.h>

int main (int argc, const char * argv[]) {
NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];

</nowiki>'''<nowiki> NSMutableArray * array = [[NSMutableArray alloc] init]; // a</nowiki>'''
''' [array addObject:@"San Francisco"]; // b'''
''' [array addObject:@"Houston"];'''
''' [array addObject:@"Tulsa"];'''
''' [array addObject:@"Juneau"];'''
''' [array addObject:@"Pheonix"];'''

''' [array writeToFile:@"cities.plist" atomically:YES]; // c'''

''' NSString * plist ='''
''' [NSString stringWithContentsOfFile:@"cities.plist"]; // d'''
''' printf("%s\n", [plist UTF8String]); // e'''

''' [array release]; // f'''

[pool release];
return 0;
}
</div>

The code we added in[[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-EX-6|Example 4-6]] does the following things:

# Creates a new mutable array.
# Adds a series of strings to the mutable array.
# Writes the array to a file named ''cities.plist''. Since this is not an absolute path, it will be written in the working directory of application. In our case, this file will be written in ''~/LearningCocoa/collectionfiles/build/cities.plist''.
# Creates a new string based on the contents of the file that we just wrote. Once again, we use a relative path.
# Prints the contents of the file to the console.
# Returns the array object that we created.
</div></li>

<li><div>Build and run ([[Image:Learning Cocoa with Objective-C_I_4_tt142.png|]]-R) the application. You should see output similar to the following appear in the console:

<nowiki><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.
com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<array>
<string>San Francisco</string>
<string>Houston</string>
<string>Tulsa</string>
<string>Juneau</string>
<string>Pheonix</string>
</array>
</plist></nowiki>

This is an XML representation of the array. This data can be edited with a text editor, transmitted across the Internet, or turned back into a collection of strings in another Cocoa program.
</div></li>

</ol>

<div class="sidebar">
'''Property Lists'''

Mac OS X uses ''property lists'', frequently referred to as ''plists'', to organize data into a form that is meaningfully structured, easily transportable, and storable. Property list files are saved in an XML format for easy editing and transportability.

You can see many examples of ''plist'' files in your ''~/Library/Preferences'' folder. Property lists organize data into named values and lists of values using several types directly represented as the following Cocoa objects: <tt>NSString</tt>, <tt>NSNumber</tt>, <tt>Boolean</tt>, <tt>NSDate</tt>, <tt>NSData</tt>, <tt>NSArray</tt>, and <tt>NSDictionary</tt>. They make it easy for applications to store preference data and, the case of the ''Info.plist'' file in an application bundle, communicate information about an application to the system. To take a look at how applications can use pliststo store configuration information, look at the ''plist'' file for the menu bar clock.

# Open the ''~/Library/Preferences'' folder, and locate the ''com.apple.MenuBarClock.plist'' file.
# Double-click on thefile to open it with the Property List Editor application (located in the ''/Developer/Applications'' folder).

The Property List Editor application can be used to browse the tree of properties. You can also hit the Dump button to see the XML representation of the property list. Be careful not to save any edits you make, as you can severely confuse an application by making the wrong changes here.
</div>

== Memory Management ==

Memory management is an important subject in programming. Quite a few of the problems encountered by novice application developers are caused by poor memory management. When an object is created and passed around among various "consumer" objects in an application, which object is responsible for disposing of it and when? If an object is not deallocated when it is no longer needed, memory leaks. If the object is deallocated too soon, problems may occur in other objects that assume its existence, and the application will most likely crash.

The Foundation framework defines a mechanism and a policy that ensures that objects are deallocated only when they are no longer needed. We have hinted at it before, but now it is time to explain things.

The policy is quite simple: you are responsible for disposing of all objects that you own. You own objects that you create, either by allocating or copying them. You also own (or share ownership in) objects that you retain. The flip side of this rule is that you should never release an object that you have not retained or created; doing so will free the object prematurely, resulting in bugs that are hard to track down, even though the fix is simple.

=== Object Initialization and Deallocation ===

As discussed in [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/Object-Oriented Programming with Objective-C|Chapter 3]], an object is usually created using the <tt>alloc</tt> method and is initialized using the <tt>init</tt> method (or a variant of the <tt>init</tt> method). When an array's <tt>init</tt> method is invoked, the method initializes the array's instance variables to default values and completes other startup tasks. For example:

<nowiki>NSArray * array = [[NSArray alloc] init];</nowiki>

When done with an object that you created, you send the <tt>release</tt> message to the object. If no other objects have registered an interest in the object, it will be deallocated and removed from memory.

When an object is deallocated, the <tt>dealloc</tt> method is invoked, giving the object an opportunity to release objects it has created, free allocated memory, and so on. We saw this in action in Chapter 3, when we added the <tt>dealloc</tt> method to the <tt>Song</tt> class.

=== Reference Counting ===

To allow multiple objects to register interest in another object and yet have this object removed from memory when no other objects are interested in it, each object in Cocoa has an associated reference count. When you allocate or copy an object, its reference count is automatically set to 1. This indicates that the object is in use in one place. When you pass the object to other objects, wanting to make sure the object stays around for their use, they can use the <tt>retain</tt> method to increment the reference counter.

To visualize this, imagine that we have an object being held in three different arrays, as shown in [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-FIG-5|Figure 4-5]]. Each array retains the object to make sure that it remains available for its use. Therefore, the object has a reference count of 3.

<div id="learncocoa2-CHP-4-FIG-5">
'''Figure 4-5. Reference counting'''

[[Image:Learning Cocoa with Objective-C_I_4_tt145.png|Reference counting]]
</div>

Whenever you are done with an object, you send a release message to decrement the reference count. When the reference count reaches 0, the release method will invoke the object's <tt>dealloc</tt> method that destroys the object. [[Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit#learncocoa2-CHP-4-FIG-6|Figure 4-6]] shows an object being removed progressively from a set of arrays. When it is no longer needed, its retain count is set to 0, and the object is deallocated.

<div id="learncocoa2-CHP-4-FIG-6">
'''Figure 4-6. Releasing of an object'''

[[Image:Learning Cocoa with Objective-C_I_4_tt146.png|Releasing of an object]]
</div>

=== Autorelease Pools ===

According to the policy of disposing of all objects you create, if the owner of an object must release the object within its programmatic scope, how can the owner give that object to other objects? Or, said another way, how do you release an object you would like to return to the caller of a method? Once you return from a method, there's no way to go back and release the object.

The answer is provided by the <tt>autorelease</tt> method built into the <tt>NSObject</tt> class, in conjunction with the functionality of the <tt>NSAutoReleasePool</tt> class. The <tt>autorelease</tt> method marks the receiver for later release by an <tt>NSAutoreleasePool</tt>. This enables an object to live beyond the scope of the owning object so that other objects can use it. This mechanism explains why you have seen dozens of code examples that contain the following lines:

<nowiki>NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
...code...
[pool release]; </nowiki>

Each application puts in place at least one autorelease pool (for each thread of control that is running in the application) and can have many more. You put an object in the pool by sending the object an <tt>autorelease</tt> message. In the case of an application's event cycle, when code finishes executing and control returns to the application object, the application object sends a <tt>release</tt> message to the autorelease pool, and the pool sends a release message to each object it contains. Any object that reaches a reference count of 0 automatically deallocates itself.

When an object is used solely within the scope of a method that creates it, you can deallocate it immediately by sending it a <tt>release</tt> message. Otherwise, use the <tt>autorelease</tt> message for all objects you create and hand off to other objects so that they can choose whether to retain them.

You shouldn't release objects that you receive from other objects, unless you have first retained them for some reason. Doing so will cause their reference count to reach 0 prematurely, and the system will destroy the object, thinking that no other object depends on it. When objects that do depend on the destroyed object try to access it, the application will most likely crash. These kinds of bugs can be hard to track down, even though their cause and fix are simple.

You can assume that a received object remains valid within the method in which it was received and will remain valid for the event loop that is handling it. If you want to keep it as an instance variable, you should send it a <tt>retain</tt> message and then autorelease it when you are done using it.

=== Retaining Objects in Accessor Methods ===

One of the primary places where you will need to be aware of memory management is in the accessor methods of your classes. At first glance, it is obvious that you will want to release an old object reference and retain the new one. However, because code that calls a class's setter method might call it multiple times with the same object as an argument, the order in which you release and retain the object references is important.

As a rule, you want to retain the new object before releasing the old one. This ensures that everything works as anticipated, even if the new and old objects are the same. If you reverse these steps, and if the new and old objects are actually the same, the object might be removed permanently from memory before being retained.

Here is the ''retain, then release'' rule expressed in code:

- (void)setProperty:(id)newProperty
{
[newProperty retain];
[property release];
property = newProperty;
}

There are other ways to ensure connections in setter methods, many of which are valid and appropriate for certain situations. However, this is the simplest possible pattern we can give that will always work. We will use this pattern throughout the book.

=== Rules of Thumb ===

The important things to remember about memory management in Cocoa distill down to these rules of thumb:

# Objects created by <tt>alloc</tt> or <tt>copy</tt> have a retain count of 1.
# Assume that objects obtained by any other method have a retain count of 1 and reside in the autorelease pool. If you want to keep it beyond the current scope of execution, then you must retain it.
# When you add an object to a collection, it is retained. When you remove an object from a collection, it is released. Releasing a collection object (such as an <tt>NSArray</tt>) releases all objects stored in it as well.
# Make sure that there are as many <tt>release</tt> or <tt>autorelease</tt> messages sent to objects as there are <tt>alloc</tt>, <tt>copy</tt>, <tt>mutableCopy</tt>, or <tt>retain</tt> messages sent. In other words, make sure that the code you write is balanced.
# Retain, then release objects in setter methods.
# <tt>NSString</tt> objects created using the <tt>@" . . . "</tt> construct are effectively constants in the program. Sending retain or release messages to them has no effect. This explains why we haven't been releasing the strings created with the <tt>@" . . . "</tt> construct.

If you apply these rules of thumb consistently and keep the retain counts of your objects balanced, you can manage memory in your applications effectively.

== Exercises ==

# Investigate the <tt>lowercase</tt> and <tt>uppercase</tt> methods of <tt>NSString</tt> using the debugger.
# Write a Foundation Tool command-line application that prints the contents of any filename given to it.
# Read the documentation on your hard drive about the <tt>NSArray</tt>, <tt>NSSet</tt>, and <tt>NSDictionary</tt> classes.
# Modify the arrays example application so that it saves the contents of the array to a file.
# Write an example that saves a dictionary to disk. Don't just use string objects in the array, but use some other objects like dictionaries and numbers so that you can see how Cocoa saves different types out to XML property lists.
# Examine the code we've written so far with an eye for how memory is managed. (A bug regarding memory management has been left in one of the examples.)
== Notes ==

<references/>

Learning Cocoa with Objective-C/Cocoa Overview and Foundation/The Cocoa Foundation Kit - Revision history

Docbook2Wiki: Initial conversion from Docbook