Objective-C Tutorial: NSArray

August 26th, 2009 Posted by: - posted under:Tutorials

Here at iCodeblog, we have been showing you guys how to create many different types of applications from the ground up. Well, today I decided to do something different and get down to some of the nitty gritty of a structure we rely heavily on in objective-C.

The NSArray is a huge workhorse that we use quite frequently without even thinking about it. The NSArray class isn’t just your ordinary array. Not only does it provide random access, but it also dynamically re-sizes when you add new objects to it and has many methods to make our lives easier. While I won’t go over every method in NSArray (there are quite a few), I will discuss some of the more important ones that are most commonly used. Let’s take a closer look at this class.

Factory Methods

Factory methods are static methods that build new instances of NSArrays from given parameters and return them. The table below details on all of the factory methods for the NSArray class.

+ (id)array Creates and returns an empty array
+ (id)arrayWithArray:(NSArray *)anArray Creates and returns an array containing the objects in another given array.
+ (id)arrayWithContentsOfFile:(NSString *)aPath Creates and returns an array containing the contents of the file specified by a given path. * The file must be of type .plist for this method to work
+ (id)arrayWithContentsOfURL:(NSURL *)aURL Similar to arrayWithContentsOfFile except it will load the .plist remotely from a given website. This would be a very simple way to get data from a web service.
+ (id)arrayWithObject:(id)anObject Creates and returns an array containing a given object. This will just be a 1 element array
+ (id)arrayWithObjects:(id)firstObj, … This method is used when you have multiple objects on hand and want easily insert them into an array. Make sure the last element you add is nil or this method won’t work.
+ (id)arrayWithObjects:(const id *)objects count:(NSUInteger)count Creates and returns an array that includes a given number of objects from a given C array.

Here is some example usage of building NSArrays with these factory methods…

// I am using strings, but you can add just about any object to an NSArray
 
// Creates an NSArray with one object
NSArray  * myArray = [NSArray arrayWithObject:@"foo"];
 
// Creates an NSArray with multiple objects. Don't forget to add nil as the last object
NSArray  * myArray2 = [NSArray arrayWithObjects:@"foo",@"bar",@"baz",nil];
 
// Creates an NSArray from another NSArray
NSArray * myArray3 = [NSArray arrayWithArray:myArray2];
 
// This will create an NSArray from data on iCodeBlog.  Go ahead and try it out, this file exists on our servers and contains valid data.
NSArray * myArray4 = [NSArray arrayWithContentsOfURL:[NSURL URLWithString:@"http://icodeblog.com/wp-content/uploads/2009/08/foo.plist"]];

You can also choose not to use factory methods and just use the normal NSArray initializers. They are pretty much the same as the factory methods only you do the allocation yourself. An example of this might be:

NSArray * foo = [[NSArray alloc] initWithObjects:@"foo",@"bar",@"baz",nil];

Accessing The NSArray

Apple has provided us with many great methods for getting data out of an NSArray as well as information about it. Here is a table of methods and their descriptions.

- (BOOL)containsObject:(id)anObject Returns true if a given object is found in the array, false otherwise
- (NSUInteger)count Returns the size of the array
- (id)lastObject Returns the last object in the array (the one with the highest index)
- (id)objectAtIndex:(NSUInteger)index Gives you random access to the array. Returns the object at a given index.

These are just a few of the accessor methods of NSArray and most likely the only ones you will need to use.

Searching The Array

If you are looking for the index of an object in an array, there is really only one method you need to use. That method is indexOfObject: . An example of usage might be:

NSString * f = @"foo";
NSString * b = @"bar";
NSString * z = @"baz";
NSArray  * myArray2 = [NSArray arrayWithObjects:f,b,z,nil];
NSInteger idx = [myArray2 indexOfObject:b];
// This would return 1 (since NSArrays are 0 - indexed)

This is much cleaner code than looping over the entire array to find an object. It’s probably more efficient too as Apple is pretty clean in how they code things.

Sending Message To Objects In The Array

Ok, so this is pretty cool. Say you have an array of objects that all need to do something. For example, an array of bullets, and you want all of the bullets to move forward one pixel. Rather than looping over each bullet object in the bullets array and calling [bullet move], you can do it in one method call on the array. This method is called – (void)makeObjectsPerformSelector:(SEL)aSelector and here is an example of usage.

// Lets pretend the bullet object has a method called move
// and there is an array of 50 bullets
 
[bullets makeObjectsPerformSelector:@selector(move)];

And that’s it… The move method will now be called on every bullet object in the array with this one method call. Very clean and easy to use. Now, if the method you want to call takes an argument, there is the – (void)makeObjectsPerformSelector:(SEL)aSelector withObject:(id)anObject method. This will allow you to pass an object to each method being called.

Sorting Arrays

Apple has provided us with some very slick ways to sort an NSArray. I will not go into too much detail here as I have a full tutorial planned dedicated to sorting arrays. For now, I will just show you how to sort an NSArray of NSStrings. The method we will be using is sortedArrayUsingSelector. Here is the example usage.

NSArray *sortedArray =
    [myArray2 sortedArrayUsingSelector:@selector(caseInsensitiveCompare:)];
    // This will return a sorted array that looks like [@"bar",@"baz",@"foo"]

You can plug in any of the string compare functions there to compare the strings. If you are sorting an NSArray of custom objects (like users), you can overwrite the compare method for that object and pass compare in for the selector. Just make sure you remember the : at the end of the method.

Looping Through Arrays

So if you are reading this, I assume you have seen a for loop before. ex: for(int x=0; x < … This would most likely not be a good way to enumerate an NSArray as Apple has provided a much nice way for doing so. There are some situations where this method would be preferred (like when u need to calculate the indices or something). But in most cases, you will want to use the special for loop provided by Apple. If you have ever coded PHP, it is much like the foreach loop. Here is an example:

for(NSString * myStr in myArray2) {
    NSLog(myStr);
}

This will loop over myArray2 and pring each element in that array. Very clean and efficient.

Saving Arrays For Later

There is an Array of ways to save data on the iPhone (Pun intended). One way is to simply dump the array to a file. This will write out the NSArray to a plist file on disk that can be loaded later using the arrayWithContentsOfFile method of NSArray. That method is rightfully named writeToFile. The example usage for it is as follows.

NSArray  * myArray2 = [NSArray arrayWithObjects:@"foo",@"bar",@"baz",nil];
[myArray2 writeToFile:filePath atomically:YES];

And there you have it! You are probably wondering what the atomically variable means. Me too… Just kidding. If YES, the file will be written to a temp location and then renamed to its final destination. This is put in place to guarantee that the file won’t be corrupted even if the system crashes (rename will be much faster than write). Why is this needed you ask? Consider this scenario.

You want to write a huge array to disk to save it for later. When your app starts it checks the disk to see if this file exists, if it does it loads an NSArray from it. If it doesn’t it creates a new NSArray. Say the last time the app ran, the system crashed while the file was being written. If atomically was set to NO, the original file would be corrupt and now the application would be loading corrupt data every time it starts from now on (most likely causing a crash). However, if you set atomically to YES, the temp file would get corrupted and the app would never see it. That way, the next time the app starts it will create a new fresh NSArray and all will be good.

Good rule of thumb, set atomically to YES.

That concludes our tutorial on NSArray. If you have any questions or comments, feel free to post them in the comments section or write me on twitter.