Objective-C 2.0 provides a language feature that allows you to enumerate over the contents of a collection — which means to process each element of the collection sequentially. This is called fast enumeration, and it became available in Mac OS X 10.5 (Leopard) with version 2.0 of Objective-C. (This book is based on using Mac OS 10.6 and OS 3.0 on the iPhone.) Enumeration uses the for in feature (a variation on a for loop).

What enumeration effectively does is sequentially march though an array, starting at the first element and returning each element for you to do "something with." The "something with" you will want to do in this case involves using that element as an argument in the spendDollars: message.

For example, this code marches through the array and sends the spendDollars: message using each element in the array (an NSNumber "transaction"), eliminating the need for a spendDollars: message statement for transaction.

for (NSNumber *aTransaction in europeTransactions) {
  [europeBudget spendDollars:[aTransaction doubleValue]];
}

Here's the way this works:

The identifier aTransaction can be any name you choose. NSNumber is the type of the object in the array (or it can be id, as I show in Chapter 1 of this minibook).

You may also have noticed that [europeBudget spendDollars: aTransaction] is enclosed in braces. The braces signify a block. (Blocks are described with scoping instance variables in Chapter 1 of this minibook.)

To be more formal (put on a tie to read this), the construct you just used is called for in, and it looks like

for ( Type aVariable in expression ) { statements }

or

Type aVariable;
for ( aVariable in expression ) { statements }

where you fill in what's italicized. There is one catch, however: You are not permitted to change any of the elements during the iteration, which means you can go through the array more than once without worry.

What you have accomplished here is that no matter how many cash transactions you create for Europe, you'll only need one spendDollars: message. While that's pretty good, you can see, in Chapter 2 of this book, how to extend that so that you need only one spend message for every transaction (both cash and change and any other transaction you can come up with) statement for all the countries you visit.

Actually, NSMutableArray is a subclass of NSArray, which manages a static array — after you've created it, you can't add objects to it or remove objects from it. For example, if you create an array with a single NSNumber to represent a transaction, you can't later add another NSNumber object that represents another transaction to that array. While only allowing a single transaction may be good for your budget, it's not very flexible.

NSArrays give you less overhead at a cost of less flexibility. So if you don't need to be able to add and remove objects, NSArrays are the preferred choice. If you want to use an NSArray, you have to initialize it with the objects you want in it when you create it.

So instead of

NSMutableArray *europeTransactions =
            [[NSMutableArray alloc] initWithCapacity:1];
 [europeTransactions addObject:europeDollarTransaction];

you would do the following:

NSArray *europeTransactions =
          [[NSArray alloc] initWithObjects:
          [[NSNumber alloc] initWithDouble:100.00],
          nil];

Even though you added only one object to the fixed array, initWithObjects: allows you to initialize the array with as many objects as you want, separating them with commas and terminating the list with nil as you can see.

Arrays are also a part of the C language. Although you'll probably end up using array objects most of the time, you may also find uses for C arrays (and you can see them used in Apple's documentation and code samples).

Arrays in C store elements just as an NSArray does (although they must be of the same type), and you can think about them as an ordered list as well. That means, for example, that you can store five values of type int in an array without having to declare five different variables, each one with a different identifier.

To declare a C array, use

double europeTransactionsArray [2];

Now you have an array with enough room for two doubles, effectively similar to the NSMutableArray you created previously; but this one is of fixed size, just like an NSArray. It's really just like having a set of the same variable types, one right after another.

To access a specific element of the array, use

europeTransactionsArray[0] = 100.00;

This line places 100.00 in the first element in an array. (Again, element 1 is at index 0.)

You can also initialize arrays when you create them. For example

double europeTransactionsArray [2] = {100.00, 200.00};

creates a two-element array of doubles. You can access an element in the arrays as though it is a normal variable by doing the following:

transaction1 = europeTransactionsArray[0];

One useful aspect of arrays is the ability to use multidimensional arrays. For example

int twoDArray[3][3] = {{1,2,3}, {4,5,6}, {7,8,9}};

declares and initializes an array that has two dimensions, like a tic-tac-toe board. You can make three-dimensional arrays, and even arrays with more than three dimensions.

Although there are no multidimensional array objects in Objective-C per se, you could have an array of arrays that accomplish the same thing. Arrays of arrays are used extensively in Mac and iPhone programming, and you can find them used in some of the samples on their respective Dev Center sites.

The following code shows the previous example of a two-dimensional array in C, and the code it takes to simulate that two-dimensional array in Objective-C.

int main() {

  int twoDArray[3][3] = {{1,2,3}, {4,5,6}, {7,8,9}};
  NSLog (@"twoDArray[2][2] is %i", twoDArray[2][2]);

  NSArray *array1 = [[NSArray alloc] initWithObjects:
                     [[NSNumber alloc] initWithInt:1],
                     [[NSNumber alloc] initWithInt:2],
                     [[NSNumber alloc] initWithInt:3],
                     nil];
  NSArray *array2 = [[NSArray alloc] initWithObjects:
                     [[NSNumber alloc] initWithInt:4],
                     [[NSNumber alloc] initWithInt:5],
                     [[NSNumber alloc] initWithInt:6],
                     nil];

  NSArray *array3 = [[NSArray alloc] initWithObjects:
                     [[NSNumber alloc] initWithInt:7],
                     [[NSNumber alloc] initWithInt:8],
                     [[NSNumber alloc] initWithInt:9],
                     nil];

  NSArray *arrayOfArrays = [[NSArray alloc] initWithObjects:
                     array1, array2, array3,  nil];
  NSLog (@"NSArray of NSArrays equivalent is %i",
   [[[arrayOfArrays objectAtIndex:2] objectAtIndex:2]
   intValue]);
}

The result is

twoDArray[2][2] is 9
NSArray of NSArrays equivalent is 9

Arrays can be passed as a parameter in C. To accept arrays as parameters, the only thing that you have to do when declaring the function is to specify that its argument is an array by using its identifier and a pair of void brackets []. For example, the function

void someFunction (int arg[])

accepts a parameter that is an array of ints.

So dictionaries are like arrays, in that they are simply a container for other objects. Dictionaries are made up of pairs of keys and values, and a key-value pair within a dictionary is called an entry. Both the key and the value must be objects, so each entry consists of one object that is the key (usually an NSString) and a second object that is that key's value (which can be anything, but in a property list must be a property list object). Within a dictionary, the keys are unique.

You use a key to look up the corresponding value. This works like your real-world dictionary, where the word is the key, and its definition is the value. (Do you suppose that's why this particular container class is called a dictionary?)

So, for example, if you have an NSDictionary that stores the currency symbol for each currency, you can ask that dictionary for the currency symbol (value) for the euro (key).

Although you can use any kind of object as a key in an NSDictionary, keys associated with property list objects in a dictionary have to be strings (I cover property list objects in "Using Property Lists" in this chapter). You can also have any kind of object for a value, but again if you're using them in a property list, they all have to be property list objects as well.

The same rules hold for arrays. You can use one to hold Transaction objects, but if you want to write and read an array as a property list file, the array can hold only property list objects.

NSDictionary has a couple of basic methods you'll surely be using regularly:

In addition, the methods writeToFile:atomically: and initWithContentsOfFile: cause a dictionary to write a representation of itself to a file and to read itself in from a file, respectively.

Just as with an array, a dictionary can be static (NSDictionary) or mutable (NSMutableDictionary). NSMutableDictionary adds a couple of additional basic methods — setObjectForKey: and removeObjectForKey:, which enable you to add and remove entries, respectively.

To create a dictionary — say, one that lets you look up the currency symbol for a given country — use the following:

NSDictionary *appDictionary = [[NSDictionary alloc]
 initWithObjectsAndKeys:
         @"€", @"Europe", @"£", @"England", nil];

This creates a dictionary with two keys, Europe and England. (To get the currency symbols, in Xcode select Edit

initWithObjectsAndKeys: takes an alternating sequence of objects and keys, terminated by a nil value. (As you can probably guess, just as with an array, you can't store a nil value in an NSDictionary.)

This step creates the dictionary that you see in Figure 4-1.

Figure 4-1. The app- Dictionary.

To look up the value for a key in a dictionary, you send the objectForKey: message bolded in the following:

NSLog(@"The currency symbol for the euro is %@",
 [appDictionary objectForKey:@"Europe"]);

In this case, you use the key Europe to look up the currency symbol in the appDictionary. And lo and behold what you get is

The currency symbol for the euro is €

By the way, if there's no key — for Antarctica for example — objectForKey: returns nil, which gives you the opportunity to respond to the user or do whatever you might want to about it.

On Mac OS X v10.5 and later, NSDictionary supports fast enumeration just like its cousin NSArray. You can, for example, iterate through a dictionary by using the for in construct to go through the keys of a dictionary.

for (id key in appDictionary) {
  NSLog(@"key: %@, value: %@", key,
                       [appDictionary objectForKey:key]);
  }

These lines of code will go through every key in the dictionary, returning the key in the key variable, allowing you to look up that entry using the objectForKey: method.

key: Europe, value: €
key: England, value: £

Dictionaries can be used most effectively with property lists to create a "dictionary of dictionaries", as I show in the next section.

Property lists are perfect for storing small amounts of data that consist primarily of strings and numbers (as you can see in the plist in Figure 4-2, the Europe and England currency symbols are strings). What adds to their appeal is the ability to easily read them into your programs, use or even modify the data, and then write them back out again. That's because Cocoa provides a small set of objects that have that behavior built in.

These objects are called property list objects. There are two kinds of property list objects:

One thing that differentiates property list object containers (NSArray, NSDictionary), besides their ability to hold other objects, is that they both have methods called writeToFile::, which write the property list to a file, and a corresponding initWithContentsOfFile:, which initializes the object with the content of a file. So, if you create an array or dictionary and fill it chock-full of objects of the property list type, all you have to do to save it to a file is tell it to go save itself or create an array or dictionary and then tell it to initialize itself from a file.

Given the versatility of property lists, you're sure to turn to them time and again. For example, you can use a plist (property list) with the vacation budget app to store the currency symbol for each country in a file, so that you can later read the file into a mutable dictionary.

Here's how you'd incorporate a plist into your Xcode project:

To see how you access the plist from your program, see the bold lines of code in Listing 4-1, which is a reworking of the Vacation.m implementation (from Chapter 3 of this minibook) that locates the plist and reads its contents into a mutable dictionary.

#import <Foundation/Foundation.h>
#import "Destination.h"

int main (int argc, const char * argv[]) {

  NSAutoreleasePool * pool = [[NSAutoreleasePool alloc]
   init];
  NSString* appDataPath  =
        @"/Users/neal/Desktop/Example 15A/AppData.plist";
  NSMutableDictionary *appDictionary = [[NSMutableDictionary
   alloc] initWithContentsOfFile:appDataPath];
  NSString* europeSymbol = [[NSString alloc]
   initWithFormat:@"%@",
          [appDictionary valueForKey:@"Europe"]];
  NSString* englandSymbol = [[NSString alloc]
   initWithFormat:@"%@",
          [appDictionary valueForKey:@"England"]];

  NSString* europeText = [[NSString alloc]
                        initWithFormat:@"%@", @"Europe"];
  Destination* europe = [[Destination alloc]
   initWithCountry:europeText andBudget:1000.00
   withExchangeRate:1.25];
  [europeText release];
  NSString* englandText = [[NSString alloc]
   initWithFormat:@"%@", @"England"];
  Destination* england = [[Destination alloc]
   initWithCountry:englandText andBudget:2000.00
   withExchangeRate:1.50];
  [englandText release];


  for (int n = 1; n < 2; n++) {
    double transaction = n*100.00;
    NSLog (@"Sending a $%.2f cash transaction",
   transaction);
    [europe spendCash:transaction];

   NSLog(@"Remaining budget $%.2f", [europe leftToSpend]);
NSLog (@"Sending a $%.2f cash transaction", transaction);
   [england spendCash:transaction];
   NSLog(@"Remaining budget $%.2f", [england leftToSpend]);
 }

[europe setExchangeRate:1.30];
[england setExchangeRate:1.40];

 int n =1;
 while (n < 4) {
   double transaction = n*100.00;

NSLog (@"Sending a %@%.2f credit card transaction",
   europeSymbol, transaction);
    [europe chargeCreditCard:transaction];
    NSLog(@"Remaining budget $%.2f", [europe leftToSpend]);
    NSLog (@"Sending a %@%.2f credit card transaction",
   englandSymbol , transaction);
    [england chargeCreditCard:transaction];
    NSLog(@"Remaining budget $%.2f", [england leftToSpend]);
    n++;
 }
 NSString *returnedCountry = [england country];
 NSLog (@"You have deleted the %@ part of your trip",
  returnedCountry);
 [returnedCountry release];
 [england release];

 [pool drain];
 return 0;
}

The first bold line of code in Listing 4-1 tells the file system where the AppData file is.

NSString* appDataPath =
      @"/Users/neal/Desktop/Example 15A/AppData.plist";

The file is on the desktop (/Users/neal/Desktop) in a folder called Example 15A (/Example 15A), and the name of the file is AppData.plist (/AppData.plist), which is what you named it way back in Step 4 in "Adding a property list to your project." This is known as a path. A path is a string that contains the location and name of a file. Yours, of course, will be in the folder in which your project is located. You have to change that (unless your name is "neal") to reflect your unique configuration.

You need to change the path every time you change the location or name of a folder your project is in.

Next, Listing 4-1 shows how to create a mutable dictionary and read the file into it using the initWithContentsOfFile: method (it needs to be mutable if you want to modify or update it). The next bit of boldness reads as follows:

NSMutableDictionary *appDictionary =
          [[NSMutableDictionary alloc]   initWithContentsOfFi
   le:appDataPath];

In the previous section, the code first specified where the file was located (appDataPath). Now it sends a message to the NSMutableDictionary to initialize itself with that file.

The next set of bold lines of code from Listing 4-1 access the key Europe and create and initialize a string europeSymbol with its value. I do the same thing for England and englandSymbol.

NSString* europeSymbol = [[NSString alloc] initWithFormat:
   @"%@", [appDictionary valueForKey:@"Europe"]];
NSString* englandSymbol = [[NSString alloc]
           initWithFormat:@"%@",
           [appDictionary valueForKey:@"England"]];

The valueForKey: method looks for the key you give it (@"England"). If it finds the key, the corresponding value is returned (in this case, £), if it can't find the key, it returns nil.

The rest of the bold lines of code in Listing 4-1 add the right currency symbol to the NSLog statements for the currency you are using — $ for your dollar-based transactions and the amount of your budget remaining, and europeSymbol (€) and englandSymbol (£) for credit card transactions in euros and pounds, respectively.

Using your new "dictionary of a dictionary" is a little more complex than using a simple dictionary. Admittedly, though, the first thing you make it do is read in the plist and create a dictionary, just as you did with the simple dictionary in the last version:

NSMutableDictionary* appDataDictionary=[[NSMutableDictionary
   alloc] initWithContentsOfFile:appDataPath];

This time, however, the Europe and England keys have a value of another dictionary instead of a currency symbol. So you treat them as NSDictionary objects. The following code takes the value for both the Europe and England keys and assigns it to pointers to those dictionaries.

NSDictionary* europeDictionary = [appDataDictionary
   valueForKey:@"Europe"];
NSDictionary* englandDictionary = [appDataDictionary
   valueForKey:@"England"];

Now, you can access the dictionary just as you did before using the key Symbol to get the currency symbol and store it in the variables europeSymbol and englandSymbol.

NSString* europeSymbol = [[NSString alloc]
           initWithFormat:@"%@",
           [europeDictionary valueForKey:@"Symbol"]];
NSString* englandSymbol = [[NSString alloc]
           initWithFormat:@"%@",
           [englandDictionary valueForKey:@"Symbol"]];

The methods that add entries to dictionaries (as well as arrays) make copies of each key argument and add the copy to the dictionary. The value object, on the other hand, receives a retain message to ensure that it won't be de-allocated before the dictionary is finished with it.

To save the budget data, start by declaring two variables to hold the budget balances for Europe and England:

float europeBudget = 1000;
float englandBudget = 2000;

NSMutableDictionary* budgetsDictionary =[appDataDictionary
   valueForKey:@"Budgets"];

if (budgetsDictionary) {
   ...
}
  else {

NSNumber* europeBalance = [[NSNumber alloc]
                          initWithFloat: europeBudget];
NSNumber* englandBalance = [[NSNumber alloc]
                         initWithFloat: englandBudget];
budgetsDictionary = [[NSMutableDictionary alloc] initWithO
   bjectsAndKeys:europeBalance, @"Europe", englandBalance,
   @"England", nil];

if (budgetsDictionary) {
  europeBudget = [[budgetsDictionary valueForKey:@"Europe"]
   floatValue];
  englandBudget = [[budgetsDictionary valueForKey:@"England"]
   floatValue];
  }

NSLog(@"You have $%.2f to spend in Europe",
         europeBudget);
NSLog(@"You have $%.2f to spend in England", englandBudget);

Destination* europe = [[Destination alloc]
           initWithCountry: europeText
           andBudget:europeBudget withExchangeRate:1.25];
Destination* england = [[Destination alloc]
          initWithCountry:englandText
          andBudget:englandBudget withExchangeRate:1.50];

Every time you run your program, you save what's left of your budget by using setObject:forKey:. If you use setObject:forKey: on a key that's already there, it replaces the old value with the new one. (If you want to take a key out of a mutable dictionary, use the removeObjectForKey: method.) Remember, these methods work only for NSMutableDictionary objects.

First you create the europeBalance and englandBalance as objects.

NSNumber* europeBalance = [[NSNumber alloc]
          initWithFloat:[europe leftToSpend]];
NSNumber* englandBalance = [[NSNumber alloc]
          initWithFloat:[england leftToSpend]];

Now that you have europeBalance and englandBalance as objects, you update the dictionary you created earlier when you read in the plist.

[budgetsDictionary setObject:europeBalance
                                 forKey:@"Europe"];
[budgetsDictionary setObject:englandBalance
                                 forKey:@"England"];

Now for the exciting part. After you update the Budgets dictionary, you write the whole file back to the plist file using the path you defined earlier (appDataPath).

[appDataDictionary writeToFile:appDataPath
                                          atomically:YES];

Well, actually you don't write it; in fact, you don't do any work at all. writeToFile:: is an NSDictionary method and does what it implies. You're actually directing the dictionary to write itself to a file. The atomically parameter tells it to first write the data to an auxiliary file and when that is successful, rename it to the path you specified. This writing to an auxiliary file procedure guarantees that the file won't be corrupted even if the system crashes during the write operation.

Now that you've written it out, you can use the new updated dictionary when you read it back in.

The bold lines of code in Listing 4-2 keep a running balance and save it in a new dictionary in the plist.

#import <Foundation/Foundation.h>
#import "Destination.h"

int main (int argc, const char * argv[]) {

  NSAutoreleasePool * pool = [[NSAutoreleasePool alloc]
   init];

NSString* appDataPath  = @"/Users/neal/Desktop/Example 15 C/
   AppData.plist";
  NSMutableDictionary* appDataDictionary=[[NSMutableDiction
   ary alloc]initWithContentsOfFile:appDataPath];
  NSDictionary* europeDictionary = [appDataDictionary
   valueForKey:@"Europe"];
  NSDictionary* englandDictionary = [appDataDictionary
   valueForKey:@"England"];
  NSString* europeSymbol = [[NSString alloc]
   initWithFormat:@"%@", [europeDictionary
   valueForKey:@"Symbol"]];
  NSString* englandSymbol = [[NSString alloc]
   initWithFormat:@"%@", [englandDictionary
   valueForKey:@"Symbol"]];

  float europeBudget = 1000;
  float englandBudget = 2000;
  NSMutableDictionary* budgetsDictionary = [appDataDictionary
   valueForKey:@"Budgets"] ;
  if (budgetsDictionary) {
    europeBudget = [[budgetsDictionary valueForKey:@"Europe"]
   floatValue];
    englandBudget = [[budgetsDictionary
   valueForKey:@"England"] floatValue];
  }
  else {
    NSNumber* europeBalance = [[NSNumber alloc]
   initWithFloat:  europeBudget];
    NSNumber* englandBalance = [[NSNumber alloc]
   initWithFloat:  englandBudget];
    budgetsDictionary = [[NSMutableDictionary alloc]
   initWithObjectsAndKeys:
          europeBalance,@"Europe",
          englandBalance,@"England", nil];
    [appDataDictionary setObject: budgetsDictionary
           forKey: @"Budgets"];
  }
    NSLog(@"You have $%.2f to spend in Europe", europeBudget
   );
    NSLog(@"You have $%.2f to spend in England",
   englandBudget );

NSString* europeText = [[NSString alloc] initWithFormat:
   @"%@", @"Europe"];

  Destination* europe = [[Destination alloc]
   initWithCountry:europeText andBudget:europeBudget
   withExchangeRate:1.25];
  [europeText release];
  NSString* englandText = [[NSString alloc]
   initWithFormat:@"%@", @"England"];

  Destination* england = [[Destination alloc]
          initWithCountry:englandText
          andBudget:englandBudget withExchangeRate: 1.50];
  [englandText release];

  for (int n = 1; n <  2; n++) {
    double transaction = n*100.00;
    NSLog (@"Sending a $%.2f cash transaction", transaction);
    [europe spendCash:transaction];
    NSLog(@"Remaining budget $%.2f", [europe leftToSpend]);
    NSLog(@"Sending a $%.2f cash transaction", transaction);
    [england spendCash:transaction];
    NSLog(@"Remaining budget $%.2f", [england leftToSpend]);
  }

  [europe setExchangeRate:1.30];
  [england setExchangeRate:1.40];

  int n =1;
  while (n < 4) {
  double transaction = n*100.00;
  NSLog (@"Sending a %@%.2f credit card transaction",
   europeSymbol, transaction);
  [europe chargeCreditCard:transaction];
  NSLog(@"Remaining budget $%.2f", [europe leftToSpend]);
  NSLog (@"Sending a %@%.2f credit card transaction",
   englandSymbol, transaction);
  [england chargeCreditCard:transaction];
  NSLog(@"Remaining budget $%.2f", [england leftToSpend]);
  n++;
  }

  NSNumber* europeBalance = [[NSNumber alloc]
   initWithFloat:[europe leftToSpend]];
  NSNumber* englandBalance = [[NSNumber alloc]
   initWithFloat:[england leftToSpend]];
  [budgetsDictionary setObject: europeBalance
   forKey:@"Europe"];
  [budgetsDictionary setObject: englandBalance
   forKey:@"England"];
  [appDataDictionary writeToFile:appDataPath atomically:YES];

NSString *returnedCountry = [england country];
  NSLog (@"You have deleted the %@ part of your trip",
   returnedCountry);
  [returnedCountry release];
  [england release];
  [pool drain];
  return 0;
}

Of course, after you build and run this project a few times, you find yourself deeply in debt. If you close and then reopen the project, you'll actually see the new entry in the AppData plist. Delete it in the dictionary by using the Xcode Property List editor by selecting the Budgets dictionary entry and pressing Delete, and then choosing File

If you don't see the Budgets dictionary in the plist and you don't want to go to the trouble of closing and then opening the project, click in any Key or Value field in the AppData plist and add and then delete a space. (You really haven't changed anything, but that's the point.) Then choose File