Core Location extensions for bearing and distance | Technology news, reviews of software, applications, devices, and IT stuff around the world

As part of a recent iPhone project, I needed to find a point at a certain distance from one location in the direction of a second location. I found the formulas I needed on Movable Type Ltd’s scripts page, and converted these into the appropriate Obj-C code to run on an iPhone using the iPhone SDK.

I’m posting the code with permission from Chris Veness of Movable Type Ltd., in case anyone else finds this useful. The three functions have been created as a category implementation for the CLLocation class.

Adding Methods to Classes

You can add methods to a class by declaring them in an interface file under a category name and defining them in an implementation file under the same name. The category name indicates that the methods are additions to a class declared elsewhere, not a new class. You cannot, however, use a category to add additional instance variables to a class.

The methods the category adds become part of the class type. For example, methods added to the NSArray class in a category are among the methods the compiler expects an NSArray instance to have in its repertoire. Methods added to the NSArray class in a subclass are not included in the NSArray type. (This matters only for statically typed objects, since static typing is the only way the compiler can know an object’s class.)

Category methods can do anything that methods defined in the class proper can do. At runtime, there’s no difference. The methods the category adds to the class are inherited by all the class’s subclasses, just like other methods.

The declaration of a category interface looks very much like a class interface declaration—except the category name is listed within parentheses after the class name and the superclass isn’t mentioned. Unless its methods don’t access any instance variables of the class, the category must import the interface file for the class it extends:

#import "ClassName.h"

@interface ClassName ( CategoryName )

// method declarations

@end

The implementation, as usual, imports its own interface. A common naming convention is that the base file name of the category is the name of the class the category extends followed by “+” followed by the name of the category. A category implementation (in a file named ClassName+CategoryName.m) might therefore look like this:

#import "ClassName+CategoryName.h"

@implementation ClassName ( CategoryName )

// method definitions

@end

Note that a category can’t declare additional instance variables for the class; it includes only methods. However, all instance variables within the scope of the class are also within the scope of the category. That includes all instance variables declared by the class, even ones declared @private.

There’s no limit to the number of categories that you can add to a class, but each category name must be different, and each should declare and define a different set of methods.

- (double)bearingInRadiansTowardsLocation:(CLLocation *)towardsLocation;

- (CLLocation *)newLocationAtDistance:(CLLocationDistance)atDistance alongBearingInRadians:(double)bearingInRadians;

- (CLLocation *)newLocationAtDistance:(CLLocationDistance)atDistance towardsLocation:(CLLocation *)towardsLocation;

You would use them as follows:

double theBearing = [theStartLocation bearingInRadiansTowardsLocation:theEndLocation];

CLLocation *theNewLocation = [theStartLocation newLocationAtDistance:150.0 alongBearingInRadians:4.0];

CLLocation *theNewLocation = [theStartLocation newLocationAtDistance:150.0 towardsLocation:theEndLocation];

…where theStartLocation and theEndLocation are existing CLLocation instances, and distances are in metres.

All you need to do to use these functions is to add both CLLocation+CLExtensions.h and CLLocation+CLExtensions.m to your XCode project, and then include CLLocation+CLExtensions.h at the top of any class in which you want to make use of the three extension functions mentioned above.

Note that the CLLocation instances returned by the second and third functions are owned by the calling code and will need to be released via [theNewLocation release] when you are done with them.