In addition to archiving and NSData’s binary read and write methods, there are a few more methods for transferring data to and from the filesystem. One of them, Core Data, is coming up in Chapter 23. A couple of others are worth mentioning here.
You have access to the standard file I/O functions from the C library. These functions look like this:
FILE *inFile = fopen("textfile", "rt"); char *buffer = malloc(someSize); fread(buffer, byteCount, 1, inFile); FILE *outFile = fopen("binaryfile", "w"); fwrite(buffer, byteCount, 1, outFile);
However, you will not see these functions used much because there are more convenient ways of reading and writing binary and text data. Using NSData works well for binary data. For text data, NSString has two instance methods writeToFile:atomically:encoding:error: and initWithContentsOfFile:. They are used as follows:
// A local variable to store an error object if one comes back
NSError *err;
NSString *someString = @"Text Data";
BOOL success = [someString writeToFile:@"/some/path/file"
atomically:YES
encoding:NSUTF8StringEncoding
error:&err];
if (!success) {
NSLog(@"Error writing file: %@", [err localizedDescription]);
}
NSString *myEssay = [[NSString alloc] initWithContentsOfFile:@"/some/path/file"
encoding:NSUTF8StringEncoding
error:&err];
if (!myEssay) {
NSLog(@"Error reading file: %@", [err localizedDescription]);
}
What is that NSError object? Some methods might fail for a variety of reasons. For example, writing to the filesystem might fail because the path is invalid or the user does not have permission to write to the specified path. An NSError object contains the reason for a failure. You can send the message localizedDescription to an instance of NSError for a human-readable description of the error. This is something you can show to the user or print to a debug console.
The syntax for getting back an NSError instance is a little strange. An error object is only created if an error occurred; otherwise, there is no need for the object. When a method can return an error through one of its arguments, you create a local variable that is a pointer to an NSError object. Notice that you do not instantiate the error object – that is the job of the method you are calling. Instead, you pass the address of your pointer variable (&err) to the method that might generate an error. If an error occurs in the implementation of that method, an NSError instance is created, and your pointer is set to point at that new object. If you do not care about the error object, you can always pass nil.
Sometimes you want to show the error to the user. This is typically done with a UIAlertView (Figure 18.10).
Creating a UIAlertView looks like this:
NSString *x = [[NSString alloc] initWithContentsOfFile:@"/some/path/file"
encoding:NSUTF8StringEncoding
error:&err];
if (!x) {
UIAlertView *a = [[UIAlertView alloc] initWithTitle:@"Read Failed"
message:[err localizedDescription]
delegate:nil
cancelButtonTitle:@"OK"
otherButtonTitles:nil];
[a show];
}
Note that in many languages, anything unexpected results in an exception being thrown. Among Objective-C programmers, exceptions are nearly always used to indicate programmer error. When an exception is thrown, the information about what went wrong is in an NSException object. That information is usually just a hint to the programmer like “You tried to access the 7th object in this array, but there are only two.” The symbols for the call stack (as it appeared when the exception was thrown) are also in the NSException.
When do you use NSException and when do you use NSError? If you are writing a method that should only be called with an odd number as an argument, throw an exception if it is called with an even number – the caller is making an error and you want to help that programmer find the error in his ways. If you are writing a method that wants to read the contents of a particular directory, but does not have the necessary privileges, create an NSError and pass it back to the caller to indicate why you were unable to fulfill this very reasonable request.
Like NSString, the classes NSDictionary and NSArray have writeToFile: and initWithContentsOfFile: methods. To write collection objects to the filesystem with these methods, the collection objects must contain only property list serializable objects. The only objects that are property list serializable are NSString, NSNumber, NSDate, NSData, NSArray, and NSDictionary. When an NSArray or NSDictionary is written to the filesystem with these methods, an XML property list is created. An XML property list is a collection of tagged values:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <array> <dict> <key>firstName</key> <string>Christian</string> <key>lastName</key> <string>Keur</string> </dict> <dict> <key>firstName</key> <string>Joe</string> <key>lastName</key> <string>Conway</string> </dict> <dict> <key>firstName</key> <string>Aaron</string> <key>lastName</key> <string>Hillegass</string> </dict> </array> </plist>
XML property lists are a convenient way to store data because they can be read on nearly any system. Many web service applications use property lists as input and output. The code for writing and reading a property list looks like this:
NSMutableDictionary *d = [NSMutableDictionary dictionary]; d[@"String"] = @"A string"; [d writeToFile:@"/some/path/file" atomically:YES]; NSMutableDictionary *anotherD = [[NSMutableDictionary alloc] initWithContentsOfFile:@"/some/path/file"];