NSObject Protocol

The NSObject protocol specifies the basic API required for any Objective-C root class. As a protocol declares methods and properties that are not specific to any particular class, this design facilitates the definition of multiple root classes (even user-defined root classes). The methods declared by the NSObject protocol can be grouped into the following categories:

• Identifying classes and proxies
• Identifying and comparing objects
• Describing objects
• Object introspection
• Sending messages

The protocol also declares a set of obsolete methods used for manual memory management. Because ARC is the preferred memory management mechanism, these methods should no longer be used.

NSObject

The NSObject class is the root class of most Objective-C hierarchies; in fact, almost all of the Foundation Framework classes are subclasses of NSObject. It defines a set of class and instance methods that provide the following functionality:

• Basic object behaviors
• (Object, class) creation and initialization
• Dynamic (runtime system) features

You have used many of the NSObject methods in the preceding chapters, so by now you’re probably pretty familiar with some of the functionality this class provides. What you’ll do in the following paragraphs is examine some of the NSObject methods that I have yet to discuss in this book.

NSLog(@"%@", [NSArray description]);

[atom logInfo];
[atom performSelector:@selector(logInfo)];

[atom performSelector:@selector(logInfo) withObject:nil afterDelay:5.0];

+ (void)initialize
{
  if (self == [MyClass class])
  {
    // Initilization logic
  }
}

Atom *atom = [[Atom alloc] init];
Atom *atom = [Atom new];

NSProxy

The NSProxy class is an abstract root class used to implement the proxy pattern. It implements a minimal set of methods, thereby enabling almost all messages sent to it being captured and proxied to the target subject. NSProxy implements the methods declared by the NSObject protocol and declares two methods that must be implemented by subclasses:

- (void)forwardInvocation:(NSInvocation *)anInvocation;
- (NSMethodSignature *)methodSignatureForSelector:(SEL)aSelector;

Additionally, an NSProxy subclass (i.e., a concrete subclass) should declare and implement at least one init method to conform to Objective-C conventions for object creation and initialization. The Foundation Framework includes several concrete subclasses of NSProxy:

• NSDistantObject: Defines proxies for objects in other applications or threads.
• NSProtocolChecker: Defines an object that restricts the messages that can be sent to another object.

In Chapter 9, you implemented an NSProxy concrete subclass, AspectProxy, to provide cross-cutting (AOP) functionality around a proxied object. These examples illustrate just a few of the many uses for the NSProxy class.

NSString

NSString and NSMutableString provide the APIs for Objective-C objects that manage strings. The NSString class manages immutable strings, strings that are defined when they are created and, subsequently, can’t be changed. NSMutableString is the mutable (its contents can be edited) subclass of NSString.

NSMutableString adds methods above those defined by its superclass (NSString) to create and initialize a (mutable) string, and to modify a string.

- (int) intValue;
- (float) floatValue;
- (double) doubleValue;
- (long long) longLongValue;
- (bool) boolValue;
- (NSInteger) integerValue;

int myValue = [@"17" intValue];

NSScanner *scanner = [NSScanner scannerWithString:@"17"];
BOOL success = [scanner scanInt:&myValue];

NSString *greeting = @"Hello, World!";
NSRange worldRange = [greeting rangeWithString:@"World"];

NSCharacterSet *chars = [NSCharacterSet punctuationCharacterSet];
NSRange charRange = [@"Hello, World!" rangeOfCharacterFromSet:chars];

NSString *greeting = @"Hello, World!";
NSString *newGreeting = [greeting stringByReplacingOccurrencesOfString:@"World!"
                         withString:@"Earthlings!"];

NSComparisonResult order = [@"cat" compare:@"dog"];

int len = [@"Hello, World!" length];

BOOL hasPrefix = [@"Hello, World!" hasPrefix:@"Hello"];

NSMutableString *mgreet = [@"Hello" mutableCopy];
[mgreet appendString:@", World!"];

NSAttributedString

NSAttributedString and NSMutableAttributedString provide the APIs for Objective-C objects that manage strings and associated sets of attributes. The NSAttributedString class manages immutable strings, while the NSMutableAttributedString class manages mutable strings.

The methods provided for the NSAttributedString class enable the creation and initialization of strings, retrieval of string and attribute information, and enumerating over attributes in a string using a block object. The initWithString:attributes: method initializes an NSAttributeString instance with attributes, where the attributes are provided in an NSDictionary instance. The following code fragment creates and initializes an NSAttributedString with the string "Hello" and a single attribute (locale = en-US).

NSDictionary *attrs = @{@"locale":@"en-US"};
NSAttributedString *greeting = [[NSAttributedString alloc] initWithString:@"Hello"
                                                               attributes:attrs];

The next statement retrieves the value of the attribute (using the key "locale") from the attribute string and also sets the range of the attribute to the variable of type NSRange named range.

NSRange range;
id value = [greeting attribute:@"locale" atIndex:0 effectiveRange:&range];

NSString Literals

Objective-C provides language-level support for creating NSString literals using the @ symbol followed by a text string enclosed in double-quotes. The following statement creates an NSString object named book using an NSString literal.

NSString *book = @"Pro Objective-C";

NSString literals are compile-time constants. They are allocated at compile time and exist for the lifetime of the program.

Format Strings

The NSString class includes several methods for formatting string objects using a format string that is composed of ordinary text characters and zero or more format specifiers. A format specifier is a specification for converting an argument in a format string to a character string. Each format specifier begins with a % character that specifies a placeholder for an argument value, immediately followed by a character sequence that indicates the type of the argument. The list of format specifiers supported by the NSString formatting methods include those defined by the IEEE printf specification along with the format specifier '%@', which is used to format an Objective-C object. For example, the format string @"%d" expects an argument of integer type to be substituted for the format string. The NSString stringWithFormat: method and other related methods create and initialize NSString objects using format strings. The syntax for the stringWithFormat method is

+ (id)stringWithFormat:(NSString *)format, ...

Where format is the format string and ... specifies the comma-separated list of argument(s) to substitute into the format. The following example creates an NSString object assigned to the variable magicNumber with the text "Your number is 17".

NSString *magicNumber = [NSString stringWithFormat: @"Your number is %d", 17];

In this example the format string, @"Your number is %d", contains ordinary text and a single format specifier, %d, that is substituted for the argument 17. The next example creates a string formatted using the NSString object magicNumber.

NSString *description = [NSString stringWithFormat:
                         @"Description is %@", magicNumber];

The %@ format specifier substitutes the string returned by invoking either the descriptionWithLocale: (if available) or description method on the object.

The Foundation Framework includes several classes (NSFormatter, NSDateFormatter, NSNumberFormatter) that provide additional functionality for interpreting and creating NSString objects that represent other values.

NSValue

The NSValue class is a container for a single data item. It can hold both C and Objective-C data types (including primitives) of constant length and is typically used to allow an item to be stored in a collection object (NSArray, NSSet, etc.), because these require their elements to be objects. The code fragment in Listing 10-3 creates an NSValue instance from a value of type int.

Listing 10-3.  Creating an NSValue Instance

int ten = 10;
int *tenPtr = &ten;
NSValue *myInt = [NSValue value:&tenPtr withObjCType:@encode(int *)];

Note that the type is specified using an @encode directive. This value can now be stored in a collection object. The following statement retrieves the int value of the NSValue object and assigns this value to the variable result.

int result = *(int *)[myInt pointerValue];

NSNumber

The NSNumber class is a subclass of NSValue that functions as a container for primitive (scalar) types. It defines a set of methods for creating and accessing number objects as primitive types: signed/unsigned char, int, short int, long int, long long int, NSInteger, float, double, or BOOL types. NSNumber includes numerous class factory methods (whose names all begin with numberWith...) for creating and initializing an NSNumber with an input parameter of the specified primitive type. The following statement uses the numberWithDouble: method to create an NSNumber instance of type double and assign it to a variable named degrees2Radians.

NSNumber *degrees2Radians = [NSNumber numberWithDouble:(3.1415/180.0)];

NSNumber also includes initialization methods (whose names all begin with initWith...) to initialize an allocated NSNumber object with the input parameter value. The corresponding NSNumber ...Value methods (one for each of the supported types) can be used to retrieve a primitive value from an NSNumber object, for example:

double d2r = [degrees2Radians doubleValue];

NSNumber also includes a stringValue method to get the string representation of an NSNumber instance.

NSDecimalNumber

NSDecimalNumber is a subclass of NSNumber that is used to perform decimal arithmetic. It includes methods for creating and initializing decimal numbers, and methods for performing standard arithmetic operations (addition, subtraction, multiplication, division, etc.). It is especially useful for performing these operations on numbers where rounding errors can be significant (for example, with currency). Listing 10-4 adds two NSDecimalNumber objects and assigns the result to an NSDecimalNumber object named sum.

Listing 10-4.  Adding Two Numbers Using NSDecimalNumber

NSDecimalNumber *num1 = [NSDecimalNumber decimalNumberWithString:@"2.56"];
NSDecimalNumber *num2 = [NSDecimalNumber decimalNumberWithString:@"7.78"];
NSDecimalNumber *sum = [num1 decimalNumberByAdding:num2];

The NSDecimalNumber methods that perform arithmetic operations include parameters that can be used to specify how calculation errors and rounding are handled.

NSNumber Literals

Objective-C provides language-level support for creating NSNumber literals. Any character, numeric, or Boolean literal that is prefixed with an @ character evaluates to an NSNumber object initialized to that value. The following statements are equivalent:

NSNumber *num = [NSNumber numberWithInt:17];
NSNumber *num = @17;

NSNumber literals are created from scalar values, not expressions. In addition, NSNumber literals are evaluated at runtime; they are not compile-time constants and thus cannot be used to initialize static variables. In essence, the literal @17 is actually shorthand for the expression [NSNumber numberWithInt:17], an object message that is evaluated at runtime. More information on NSNumber literals is provided in Chapter 16, which explores Objective-C literals in depth.

Date and Time Support

The NSCalendar, NSDate, NSCalendarDate, NSDateComponents, and NSTimeZone classes provide support for date and time programming and formatting. An NSDate instance represents an absolute timestamp. The following statement creates a date that represents the current time.

NSDate *now = [[NSDate alloc] init];

The following statements compare two dates and return an NSComparisonResult that indicates whether the input date is later, the same, or earlier than the receiver’s dates.

NSTimeInterval secondsPerDay = 24 * 60 * 60;
NSDate *tomorrow = [now dateByAddingTimeInterval:secondsPerDay];
NSComparisonResult *result = [now compare:tomorrow];

The NSCalendar class encapsulates calendar information used to organize periods of time. It provides an implementation for several different calendars, including the Buddhist, Gregorian, Hebrew, Islamic, and Japanese calendars. The following statement returns a calendar for the current user’s chosen locale.

NSCalendar *currentCalendar = [NSCalendar currentCalendar];

The following statement creates a Gregorian calendar.

NSCalendar *gregorianCalendar = [[NSCalendar alloc]
                                initWithCalendarIdentifier:NSGregorianCalendar];

NSCalendar provides methods for retrieving the component elements of a date in a calendar, represented as NSDateComponents objects.

The NSDateComponents class represents the component elements of a date/time. It is used to set/get these elements, and also specify a time interval. The following statements retrieve date components from a current calendar object with monthly calendar units.

NSDate *date = [NSDate date];
NSDateComponents *components = [currentCalendar components:NSMonthCalendarUnit
                                                    fromDate:date];

NSCache

In computer programming, a cache is a mechanism that stores data so that future requests for the same data can be retrieved more quickly. They are commonly used to store objects that are expensive to re-create. The Foundation Framework NSCache class provides an in-memory system cache for the temporary storage of objects that are expensive to re-create. In addition to managing cache values, the class includes methods for managing the cache size, managing discarded objects, and managing the cache delegate. A cache delegate conforms to the NSCacheDelegate protocol, and is sent messages when an object is about to be evicted or removed from the cache. An NSCache instance stores key-value pairs, similar to an NSDictionary (to be discussed later in this chapter). It differs in that it provides autoremoval policies, and thus manages memory utilization. The following code fragment creates an NSCache instance, sets the number of objects the cache can hold, and then adds an object to the cache.

NSCache *cache = [[NSCache alloc] init];
[cache setCountLimit:500];
[cache setObject:@"Hello, World!" forKey:@"greeting"];

NSArray

NSArray and NSMutableArray manage ordered collections of objects that do not have to be of the same type. NSArray is immutable (the objects assigned to the array at initialization cannot be removed, although there contents can be changed). NSMutableArray allows adding or removing objects in a collection. The operations supported by NSArray include array creation and initialization, query (obtaining information about the array or retrieving its elements), finding an object in an array, object messaging to array elements, comparing arrays, and sorting an array. Many NSArray and NSMutableArray operations are executed in constant time (accessing an element, adding/removing on ends, replacing an element), whereas inserting an element in the middle of an NSMutableArray takes linear time. The following statement uses the NSArray arrayWithObjects: convenience constructor to create an NSArray object assigned to the variable myArray initialized with NSNumber literals.

NSArray *myArray = [NSArray arrayWithObjects:@1, @2, nil];

Notice that the arrayWithObjects: method requires parameters with a comma-separated list of objects ending with nil. The next statement retrieves the first element of this NSArray object using the NSArray indexOfObject: method.

id num0 = [myArray objectAtIndex:0];

The following statement returns the index of the NSNumber object (with a value of 2) in the preceding NSArray object.

NSUInteger index = [myArray indexOfObject:@2];

NSArray also includes the following methods to persist the contents of an array to a property list and initialize an NSArray object from a property list:

- writeToFile:atomically:
- writeToURL:atomically:
- initWithContentsOfFile:
- initWithContentsOfURL:

When persisting an array (via the writeTo... methods), its contents must all be property list objects (i.e., NSString, NSData, NSDate, NSNumber, NSArray, NSDictionary objects).

NSArray *myArray = [NSArray arrayWithObjects:@1, @2, nil];
NSArray *myArray = @[@1, @2];

NSPointerArray

NSPointerArray is a mutable collection similar to NSMutableArray that can hold arbitrary pointers and NULL values. It also allows you to manage the collection by setting the count for the array, such that if the number of elements in the collection is less than the count, then the collection is padded with NULL values; or if the number of elements in the collection is greater than the count, then the elements in the collection above the count value are removed.

NSDictionary

The NSDictionary and NSMutableDictionary classes manage collections of key/value (object) pairs. Within a collection, the value of a key is unique (i.e., it must be an object that adopts the NSCopying protocol and implements the hash and isEqual: methods). The operations supported by these classes include object creation and initialization, query, finding objects in the collection, filtering, comparing, and sorting the collection. The sorting options include sorting with selectors (using the keySortedByValueUsingSelector: method), and sorting with blocks (using the keySortedByValueUsingComparator: method). For keys with good hash functions (for example, NSString), NSDictionary operations take constant time (accessing, setting, removing an element from an NSDictionary or NSMutableDictionary). The code fragment shown in Listing 10-5 creates and initializes an NSDictionary object with two elements.

Listing 10-5.  Creating and Initializing an NSDictionary Object

NSArray *objects = @[@1, @2];
NSArray *keys = @[@"one", @"two"];
NSDictionary *myDi = [NSDictionary dictionaryWithObjects:objects];
                       withKeys:keys];

The next statement retrieves the value from the preceding NSDictionary object that has the key "one".

id value = [myDi objectForKey:@"one"];

As with NSArray, NSDictionary includes methods to persist the contents of a dictionary to a property list and initialize an NSDictionary object from a property list:

- writeToFile:atomically:
- writeToURL:atomically:
- initWithContentsOfFile:
- initWithContentsOfURL:

When persisting a dictionary (via the writeTo... methods), its contents must all be property list objects (NSString, NSData, NSDate, NSNumber, NSArray, and NSDictionary objects).

NSArray *objects = @[@1, @2];
NSArray *keys = @[@"one", @"two"];
NSDictionary *myDi = [NSDictionary dictionaryWithObjects:objects];

NSDictionary *myDi = @{@"one":@1, @"two":@2};

NSMapTable

NSPointerArray is a mutable collection similar to NSDictionary that provides additional storage options. Specifically, it can store arbitrary pointers. It can also store weakly referenced keys and/or values.

NSSet

NSSet and NSMutableSet manage unordered collections of objects that do not have to be of the same type. The objects stored in an NSSet are unique. The operations supported by NSSet include creation and initialization, finding an object in a set, comparing, and sorting (using the NSSet sortedArrayUsingDescriptors: method). If the objects in the set have a good hash function, accessing an element, setting an element, and removing an element all take constant time. With a poor hash function (one that causes frequent hash collisions), these operations take up linear time.

Sets, excluding NSCountedSets, ensure that no object is represented more than once, and there is no net effect for adding an object more than once. The following statement uses the NSSet setWithObjects: convenience constructor to create an NSSet object assigned to the variable mySet initialized with NSNumber literals.

NSSet *mySet = [NSSet setWithObjects:@1, @2, nil];

NSCountedSet

NSCountedSet is a mutable set that allows an object to be added multiple times (i.e., its elements aren’t required to be distinct). Each distinct object has an associated counter. An NSSet object keeps track of the number of times each distinct object is inserted and requires a corresponding object(s) to be removed the same number of times.

NSHashTable

NSHashTable is a mutable collection similar to NSSet that provides different options. Specifically, it can store arbitrary pointers. It can also store weakly referenced keys and/or values.

NSPointerFunctions

The NSPointerFunctions class defines functions for managing pointer functions. An NSHashTable , NSMapTable , or NSPointerArray object typically uses an NSPointerFunctions instance to define behavior for the pointers it manages.

XML DTD Processing

The NSXMLDTD classes (NSXMLDTD and NSXMLDTDNode) represent a Document Type Definition (DTD). They are used for creating and modifying DTDs. The XML DTD processing classes (NSXMLDTD, NSXMLDTDNode) are available for use on the Apple OS X platform only (i.e., these classes are not available for the iOS platform).

Tree-Based XML Processing

The Foundation NSXML classes enable you to create, manipulate, modify, and query XML documents. These classes employ a Document Object Model (DOM) styled, tree-based data model that represents an XML document as a tree of nodes. Each node of the tree corresponds to an XML construct—an Element, an Attribute, Text, a Comment, a Processing Instruction, or a Namespace. An NSXMLDocument object represents an entire XML document as a logical tree structure. The code fragment shown in Listing 10-6 creates an NSXMLDocument for the URL http://www.apress.com/proobjectivec.xml .

Listing 10-6.  Creating an NSXMLDocument Object

NSURL *url = [NSURL URLWithString:@"http://www.apress.com/proobjectivec.xml"];
NSError *err;
NSXMLDocument *xmlDoc = [[NSXMLDocument alloc]
                          initWithContentsOfURL:url
                                        options:NSXMLDocumentValidate
                                          error:&err];

NSXMLNode, the superclass of NSXMLDocument, includes methods for navigating a tree of nodes from an XML document. The following code fragment uses an NSXMLNode method, nextNode, to retrieve the next node in an XML document.

NSXMLNode *node = [xmlDoc nextNode];

NSXMLElement, a subclass of NSXMLNode, represents element nodes in an XML tree structure. It includes methods for managing child elements and attributes of an XML document. The following code fragment gets the NSXMLElement object with the given tag name of "test" and then uses this object to retrieve the child element nodes (an NSArray object) that have the specified name.

NSXMLElement *testElem = [NSXMLNode elementWithName:@"test"];
NSArray *children = [noteElem elementsForName:@"item"];

The XML processing classes (NSXMLDocument, NSXMLNode, NSXMLElement) are available for use on the Apple OS X platform only (i.e., these classes are not available for the iOS platform).

Event-Driven XML Processing

The NSXMLParser class is used to parse XML documents, including DTD documents, in an event-driven manner. An NSXMLParser instance is configured with a delegate, an object that implements certain methods that are invoked on it while the NSXMLParser instance is processing an XML document. The delegate must conform to the NSXMLParserDelegate protocol, thereby enabling it to respond to events (i.e., method invocations) when the parser begins/ends processing the document, processes XML elements and attributes, and so forth. The method shown in Listing 10-7 demonstrates the creation, initialization, and use of an NSXMLParser instance to parse an XML document.

Listing 10-7.  Parsing an XML Document

- (void) parseXMLInfoset:(NSString *)file
{
  NSURL *infoset = [NSURL fileURLWithPath:file];
  NSXMLParser *parser = [[NSXMLParser alloc]
    initWithContentsOfURL:infoset];
  [parser setDelegate:self];
  [parser setShouldResolveExternalEntities:YES];
  [parser parse];
}

As mentioned earlier, a delegate object must conform to the NSXMLParserDelegate protocol to be able to process document parsing events (e.g., begin parsing a document, end parsing a document, start parsing an element, start mapping a namespace prefix, end mapping a namespace prefix) from an NSXMLParser instance. Unlike the NSXML (tree-based XML processing classes), the event-driven XML parser classes enable you to read XML documents but not create or update them.

The NSXMLParser class is available for use on both the Apple OS X and iOS platform. The other XML processing classes mentioned here are only available for use on the OS X platform.