As you might 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 10 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 Stringz:
#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 do not instantiate it.
// The NSError instance will only be created if there is, in fact, an error.
NSError *error;
// 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 does not 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 do not create, or instantiate, an NSError object to assign to that pointer.
Why not? You want to avoid creating an unnecessary error object if there is 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 is no object yet to pass. However, unlike the passing by reference you did in Chapter 10, where you passed the reference of a primitive C variable, here you are passing the address of a pointer variable. In essence, you are passing the address of another address (which may become the address of an NSError object).
To revisit our international espionage analogy from Chapter 10, 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 is 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. Many programmers would say “The method expects a pointer to a pointer to an NSError.” However, that sounds more confusing than it needs to be. In our opinion, this is more descriptive: “The method expects an address where it can put 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. Do not try to access the NSError unless the return value indicates that an error occurred; if the NSError object does not actually exist, trying to access it will crash your program.