11.1. Dictionaries and Property Lists

Property lists are flat files on disk, but are represented in your application as a dictionary with keys and values. The NSDictionary class provides the methods needed to read and write property lists to and from disk, and can realize key and value pairs without implementing any complex parsing functions by the developer. The NSMutableDictionary class builds on top of this to provide a mechanism to add and remove individual key/value pairs.

11.1.1. Creating a Dictionary

Dictionaries can be created in a number of ways. The simplest way is to use the NSMutableDictionary class:

NSMutableDictionary *dict = [ [ NSMutableDictionary alloc ] init ];

11.1.2. Managing Keys

Once you have created the dictionary, you can add individual key/value pairs to it using the setValue method:

[ dict setValue: @"myValue" forKey: @"myKey" ];

You can also set any object as the value of a key using the setObject method:

[ dict setObject: myObject forKey: @"myKey" ];

To remove a key/value pair, use the removeObjectForKey method:

[ dict removeObjectForKey: @"myKey" ];

Use the removeAllObjects method to remove all key/value pairs:

[ dict removeAllObjects ];

11.1.3. Writing Property Lists

Property lists are written to disk when you invoke the dictionary's writeToFile method. The dictionary class automatically converts its data into an XML format and writes it to the path specified:

[ dict writeToFile: path atomically: YES ];

If the file is written atomically, the property list is written to a temporary file first, then renamed to the path specified. This is useful if other parts of your application might be reading the property list, and can help prevent crashing should another thread load a partially written property list.

11.1.4. Reading Property Lists

To read back a property list that you've previously stored, the NSDictionary class provides a dictionaryWithContentsOfFile method. This allows you to load the property list directly into a dictionary class without any knowledge of the property file's format, and without any parsing.

To read a property list file into a dictionary object, create the dictionary object using the initWithContentsOfFile method:

NSString path = [ NSString stringWithFormat:
    @"%@/Library/Preferences/bookmarks.plist", NSHomeDirectory()
];
NSMutableDictionary *dict = [ [ NSMutableDictionary alloc ]
    initWithContentsOfFile: path
];

If the dictionary object already exists in memory, use the setDictionary method to replace the contents of the dictionary with that of the file:

 

[ dict setDictionary: [ NSDictionary dictionaryWithContentsOfFile: path ] ];

                                          

From here, you can work on the dictionary using the methods you've already learned.

11.1.5. Further Study

  • Have a look at NSDictionary.h prototypes. You'll find these in /System/Library/Frameworks/Foundation.framework/Headers.

  • Take the ShootStuffUp example from Chapter 10 and write code to read and write the example's settings on disk. Use this to automatically adjust the controls when the example loads.