1.4 Compiler and Preprocessor Directives

Compiler and preprocessor directives are special terms in your program that tell the compiler to perform some Objective-C-specific action. All compiler directives start with the character @, and preprocessor directives start with #.

1.4.1 Class Declarations and Definitions

The following compiler directives are used to begin or conclude the declaration and definition of Objective-C classes, categories, and protocols:

@interface

Begins the declaration of a class's or category's fields and methods.

@protocol

Begins the declaration of a protocol's methods.

@implementation

Begins the definition of a class's methods.

@end

Ends the declaration or definition of a class's, category's, or protocol's methods.

The use of these compiler directives is described in detail under Section 1.3, and especially in the subsections Section 1.3.2, Section 1.3.6, and Section 1.3.7.

1.4.2 Forward Declarations

The following compiler directives generate forward declarations, informing the compiler that a type exists:

@class ClassName

Forward declaration of a class.

@protocol ProtocolName

Forward declaration of a protocol.

Use forward declarations when an interface uses variables (fields or method parameters or return types) of a given type. Rather than import the header file for that type, you can simply forward reference it. For example:

@class  Point ;
@interface  Circle  : Graphic  {
  Point * center ;
  // etc.
}
@end 

This is sufficient because the declaration of Circle does not use any details of Point. You could import the header for Point, but this makes any other class that imports Circle.h appear dependent also on Point.h, and can cause unnecessary (and slow) recompiling in large projects.

1.4.3 Expanding Directives

Expanding complier directives look like functions, but they are really instructions to the compiler, which expands them as described in the following list:

@encode ( typeName)

Takes a type specification and evaluates to the C string used by the runtime to succinctly describe that type.

@defs ( className)

Takes the name of an Objective-C class and evaluates to a sequence of type declarations that duplicate the field declarations of the class. This directive can appear only in a C structure declaration.

@protocol ( ProtocolName)

Evaluates to a pointer to an instance of the Protocol class. You need this because you can't get a protocol class instance by using the protocol name directly, as you can with a class object.

@selector ( MethodName)

Evaluates to a SEL representing the specified method.

@ "string"

A shorthand for creating a string literal that's an instance of a user-defined string class. Use this when you need a string object constant.

The directives @encode, @defs, and @"string" deserve some additional explanation.

1.4.3.1 Using @encode

The following example shows how @encode can be used to get the string that the Objective-C runtime uses to describe a type:

char * itype  = @encode (int );

The result of this statement will be to define itype as the one-character string "i", which is the runtime representation of an int type.

The @encode directive can take any C or Objective-C type. The runtime uses the mapping between types and strings to encode the signatures of methods and associate them with selectors. You can use @encode to implement your own object storage and retrieval, or other tasks that need to describe the types of values.

Table 1-1 shows the results of applying @encode to C and Objective-C types.

Table 1-1. Types and their encodings

Type	@encode(type)
char	c
int	i
short	s
long	l
long long	q
unsigned char	C
unsigned int	I
unsigned short	S
unsigned long	L
unsigned long long	Q
float	f
double	d
void	v
char*	*
An object pointer	@
Class	#
SEL	:
An array of N elements of type	[Ntype]
A structure called name with elements t1, t2, etc.	{name=t1t2...}
A union	(type,...)
A bit field of size N	bN
A pointer to type	^type
Unknown type	?

The runtime system also uses encodings for type qualifiers, shown in Table 1-2, and you may encounter them in its representation of method signatures. However, you can't get those encodings with the @encode directive.

Table 1-2. Type qualifiers and their encodings

Qualifier	@encode(qualifier)
const	r
in	n
inout	N
out	o
bycopy	O
byref	R
oneway	V

1.4.3.2 Using @defs

The following example shows how @defs can be used to create a C structure with fields that match the fields in a class. In this example, both the order and type of the fields of MyStruct will match those in MyClass:

@interface  MyClass  : Object {
  int  i ;
}
@end 
    
typedef  struct  {
  @defs (MyClass )
} MyStruct ;

The typedef in this example is seen by the compiler as:

typedef  struct  {
  id  isa;
  int  i ;
} MyStruct ;

Having a structure that corresponds to a class lets you bypass the normal access restrictions on an Objective-C instance. In the following example, an instance of MyClass is cast to an instance of MyStruct. Once that's done, the protected field i can be accessed with impunity:

MyClass* c = [MyClass new];
MyStruct* s = (MyStruct*)c;
s->i = 42;

Obviously this is a facility you should use with restraint.

1.4.3.3 Using @"string"

The @"string" directive creates the Objective-C version of a string literal: one that you can pass to a method expecting a string object, or use to initialize or compare with another string object.

When you create a string with @"string", you get an instance of a class defined by the compiler option -fconstant-string-class. The instance is static: its contents are stored in your program's file, and the instance is created at runtime and kept around for the duration of program execution. You can't change its value, because it appears as an expression in your program, not as a variable

In the GNU runtime, the default string class is NXConstantString; for Darwin it is the Cocoa class NSConstantString.

1.4.4 Preprocessor Symbols

Objective-C adds one preprocessor directive and defines one symbol to the preprocessor before compiling:

#import fileName

Using #import has the same effect as the C directive #include, but will only include the file once.

_ _OBJC_ _

When gcc is compiling an Objective-C file, it defines this symbol for the preprocessor. If your code must compile as plain C as well as Objective-C, you can test to see if this symbol is defined:

#ifdef _ _OBJC_ _
  // Objective-C code here
#endif