Categories Add Methods to Existing Classes

If you need to add a method to an existing class, perhaps to add functionality to make it easier to do something in your own application, the easiest way is to use a category.

The syntax to declare a category uses the @interface keyword, just like a standard Objective-C class description, but does not indicate any inheritance from a subclass. Instead, it specifies the name of the category in parentheses, like this:

@interface ClassName (CategoryName)

@end

A category can be declared for any class, even if you don’t have the original implementation source code (such as for standard Cocoa or Cocoa Touch classes). Any methods that you declare in a category will be available to all instances of the original class, as well as any subclasses of the original class. At runtime, there’s no difference between a method added by a category and one that is implemented by the original class.

Consider the XYZPerson class from the previous chapters, which has properties for a person’s first and last name. If you’re writing a record-keeping application, you may find that you frequently need to display a list of people by last name, like this:

Appleseed, John

Doe, Jane

Smith, Bob

Warwick, Kate

Rather than having to write code to generate a suitable lastName, firstName string each time you wanted to display it, you could add a category to the XYZPerson class, like this:

#import "XYZPerson.h"

@interface XYZPerson (XYZPersonNameDisplayAdditions)

- (NSString *)lastNameFirstNameString;

@end

In this example, the XYZPersonNameDisplayAdditions category declares one additional method to return the necessary string.

A category is usually declared in a separate header file and implemented in a separate source code file. In the case of XYZPerson, you might declare the category in a header file called XYZPerson+XYZPersonNameDisplayAdditions.h.

Even though any methods added by a category are available to all instances of the class and its subclasses, you’ll need to import the category header file in any source code file where you wish to use the additional methods, otherwise you’ll run into compiler warnings and errors.

The category implementation might look like this:

#import "XYZPerson+XYZPersonNameDisplayAdditions.h"

@implementation XYZPerson (XYZPersonNameDisplayAdditions)

- (NSString *)lastNameFirstNameString {

    return [NSString stringWithFormat:@"%@, %@", self.lastName, self.firstName];

}

@end

Once you’ve declared a category and implemented the methods, you can use those methods from any instance of the class, as if they were part of the original class interface:

#import "XYZPerson+XYZPersonNameDisplayAdditions.h"

@implementation SomeObject

- (void)someMethod {

    XYZPerson *person = [[XYZPerson alloc] initWithFirstName:@"John"

                                                    lastName:@"Doe"];

    XYZShoutingPerson *shoutingPerson =

                        [[XYZShoutingPerson alloc] initWithFirstName:@"Monica"

                                                            lastName:@"Robinson"];

    NSLog(@"The two people are %@ and %@",

         [person lastNameFirstNameString], [shoutingPerson lastNameFirstNameString]);

}

@end

As well as just adding methods to existing classes, you can also use categories to split the implementation of a complex class across multiple source code files. You might, for example, put the drawing code for a custom user interface element in a separate file to the rest of the implementation if the geometrical calculations, colors, and gradients, etc, are particularly complicated. Alternatively, you could provide different implementations for the category methods, depending on whether you were writing an app for OS X or iOS.

Categories can be used to declare either instance methods or class methods but are not usually suitable for declaring additional properties. It’s valid syntax to include a property declaration in a category interface, but it’s not possible to declare an additional instance variable in a category. This means the compiler won’t synthesize any instance variable, nor will it synthesize any property accessor methods. You can write your own accessor methods in the category implementation, but you won’t be able to keep track of a value for that property unless it’s already stored by the original class.

The only way to add a traditional property—backed by a new instance variable—to an existing class is to use a class extension, as described in Class Extensions Extend the Internal Implementation.

@interface NSSortDescriptor (XYZAdditions)

+ (id)xyz_sortDescriptorWithKey:(NSString *)key ascending:(BOOL)ascending;

@end

    NSSortDescriptor *descriptor =

               [NSSortDescriptor xyz_sortDescriptorWithKey:@"name" ascending:YES];

Class Extensions Extend the Internal Implementation

A class extension bears some similarity to a category, but it can only be added to a class for which you have the source code at compile time (the class is compiled at the same time as the class extension). The methods declared by a class extension are implemented in the @implementation block for the original class so you can’t, for example, declare a class extension on a framework class, such as a Cocoa or Cocoa Touch class like NSString.

The syntax to declare a class extension is similar to the syntax for a category, and looks like this:

@interface ClassName ()

@end

Because no name is given in the parentheses, class extensions are often referred to as anonymous categories.

Unlike regular categories, a class extension can add its own properties and instance variables to a class. If you declare a property in a class extension, like this:

@interface XYZPerson ()

@property NSObject *extraProperty;

@end

the compiler will automatically synthesize the relevant accessor methods, as well as an instance variable, inside the primary class implementation.

If you add any methods in a class extension, these must be implemented in the primary implementation for the class.

It’s also possible to use a class extension to add custom instance variables. These are declared inside braces in the class extension interface:

@interface XYZPerson () {

    id _someCustomInstanceVariable;

}

...

@end

@interface XYZPerson : NSObject

...

@property (readonly) NSString *uniqueIdentifier;

- (void)assignUniqueIdentifier;

@end

@interface XYZPerson ()

@property (readwrite) NSString *uniqueIdentifier;

@end

@implementation XYZPerson

...

@end

Consider Other Alternatives for Class Customization

Categories and class extensions make it easy to add behavior directly to an existing class, but sometimes this isn’t the best option.

One of the primary goals of object-oriented programming is to write reusable code, which means that classes should be reusable in a variety of situations, wherever possible. If you’re creating a view class to describe an object that displays information on screen, for example, it’s a good idea to think whether the class could be usable in multiple situations.

Rather than hard-coding decisions about layout or content, one alternative is to leverage inheritance and leave those decisions in methods specifically designed to be overridden by subclasses. Although this does make it relatively easy to reuse the class, you still need to create a new subclass every time you want to make use of that original class.

Another alternative is for a class to use a delegate object. Any decisions that might limit reusability can be delegated to another object, which is left to make those decisions at runtime. One common example is a standard table view class (NSTableView for OS X and UITableView for iOS). In order for a generic table view (an object that displays information using one or more columns and rows) to be useful, it leaves decisions about its content to be decided by another object at runtime. Delegation is covered in detail in the next chapter, Working with Protocols.

Exercises

1. Add a category to the XYZPerson class to declare and implement additional behavior, such as displaying a person’s name in different ways.

2. Add a category to NSString in order to add a method to draw the uppercase version of a string at a given point, calling through to one of the existing NSStringDrawing category methods to perform the actual drawing. These methods are documented in NSString UIKit Additions Reference for iOS and NSString Application Kit Additions Reference for OS X.

3. Add two readonly properties to the original XYZPerson class implementation to represent a person’s height and weight, along with methods to measureWeight and measureHeight.

   Use a class extension to redeclare the properties as readwrite, and implement the methods to set the properties to suitable values.