So where do you find methods that you need? Apple maintains a class reference for each class in its APIs. The class reference lists all of the methods of a class and basic information on how to use them.
In Xcode, select Help → Documentation and API Reference. This will open Xcode’s documentation browser.
In the search field at the top of the window, enter NSString.
(You can also access the documentation via Apple’s developer website. To get to the NSString class reference, simply search for “NSString class reference.” The first result returned is usually the NSString reference page at developer.apple.com.)
In the righthand pane is the table of contents for the NSString class reference. The Overview describes the NSString class in general. There are also headings that list the class methods and instance methods. If you know the name of the method you are looking for, then you can find it by name under one of these headings and read all about its details.
Reveal the contents of the Class Methods category. Find and select stringWithFormat: from the list to see useful information about this method, like descriptions of its parameters and return value.
If you need to do something with an object but do not know of a specific method, then the best place to start is the Tasks heading. One task that developers often need to accomplish with NSString is searching one string to see if it contains a certain substring. A substring is a string that may make up part or all of another string.
For instance, say you read in a comma-delimited list of names as an NSString object. Now you need to check if a particular name is in the list. That single name would be a substring of the larger string.
Reveal the contents under the Tasks heading. Find and select Finding Characters and Substrings. This will reveal several potentially useful methods.
In the real world, you would browse through the details of candidate methods until you found one that would work. For this example, we will give you a head start: click rangeOfString: in the list of methods to see its details (Figure 16.4).
You can see that rangeOfString: has one parameter that is an instance of NSString. This is the “substring” for which you want to search – the single name to find in the list of names.
You can also see that this method returns an NSRange. What is an NSRange? Click NSRange to view its definition (Figure 16.5).
NSRange is a typedef for a struct, like you used in Chapter 11.
It has two members, location and length, that you can use to pinpoint a substring within a string.
However, in the current problem, you only want to see if the name occurs in the list or not. To figure out how to do this, press the back button at the top lefthand corner of the documentation browser to return to the previous page. Then find the Return Value section in the rangeOfString: documentation. This section states that when the passed-in substring does not occur, rangeOfString: returns an NSRange whose location is the constant NSNotFound.
Thus, to determine whether the name is in the list of names, you can simply check the return value’s location member. The code would look something like this:
NSString listOfNames = @"..."; // a long list of names
NSString name = @"Ward";
NSRange match = [listOfNames rangeOfString:name];
if (match.location == NSNotFound) {
NSLog(@"No match found!");
// Other actions to be taken
} else {
NSLog(@"Match found!");
// Other actions to be taken
}