As you can imagine, all sorts of things can go wrong when you try to write a string to a file. For example, the user may not have write-access to the directory where the file would go. Or the directory may not exist at all. Or the filesystem may be full. For situations like these, where an operation may be impossible to complete, the method needs a way to return a description of what went wrong in addition to the boolean value for success or failure.
Recall from Chapter 9 that when you need a function to return something in addition to its return value, you can use pass-by-reference. You pass the function (or method) a reference to a variable where it can directly store or manipulate a value. The reference is the memory address for that variable.
For error handling, many methods take an NSError pointer by reference. Add error handling to the example above:
#import <Foundation/Foundation.h>
int main (int argc, const char * argv[]) {
@autoreleasepool {
NSMutableString *str = [[NSMutableString alloc] init];
for (int i = 0; i < 10; i++) {
[str appendString:@"Aaron is cool!n"];
}
// Declare a pointer to an NSError object, but don't instantiate it.
// The NSError instance will only be created if there is, in fact, an error.
NSError *error = nil;
// Pass the NSError pointer by reference to the NSString method
BOOL success = [str writeToFile:@"/tmp/cool.txt"
atomically:YES
encoding:NSUTF8StringEncoding
error:&error];
// Test the returned BOOL, and query the NSError if the write failed
if (success) {
NSLog(@"done writing /tmp/cool.txt");
} else {
NSLog(@"writing /tmp/cool.txt failed: %@", [error localizedDescription]);
}
}
return 0;
}
Build and run it. Now change the code to pass the write method a file path that doesn’t exist, like @"/too/darned/bad.txt". You should get a friendly error message.
Notice that you declare a pointer to an instance of NSError in this code, but you don’t create, or instantiate, an NSError object to assign to that pointer.
Why not? You want to avoid creating an unnecessary error object if there’s no error. If there is an error, writeToFile:atomically:encoding:error: will be responsible for creating a new NSError instance and then modifying the error pointer you declared to point to the new error object. Then you can ask that object what went wrong via your error pointer.
This conditional creation of the NSError requires you to pass a reference to error (&error) because there’s no object yet to pass. However, unlike the passing by reference you did in Chapter 9 where you passed the reference of a primitive C variable, here you’re passing the address of a pointer variable. In essence, you’re passing the address of another address (which may become the address of an NSError object).
To revisit our international espionage analogy from Chapter 9, you might tell your spy, “If anything goes wrong, make a complete report (much too large to put in the steel pipe) and hide it in a book at the library. I need to know where you hid it, so put the call number of the book in the steel pipe.” That is, you are giving the spy a location where she can put the address of an error report she created.
Here’s a look inside the NSString class where writeToFile:atomically:encoding:error: is declared:
- (BOOL)writeToFile:(NSString *)path atomically:(BOOL)useAuxiliaryFile encoding:(NSStringEncoding)enc error:(NSError **)error
Notice the double asterisk. When you call this method, you are supplying a pointer to a pointer to an instance of NSError.
Methods that pass an NSError by reference always return a value that indicates whether there was an error or not. This method, for example, returns NO if there is an error. Don’t try to access the NSError unless the return value indicates that an error occurred; if the NSError object doesn’t actually exist, trying to access it will crash your program.