Keywords: manual

Next: About this document ... Up: 3. Additional portability facilities Previous: 3. Additional portability facilities

Subsections

- 3.1.1 GNUstep memory management macros
- 3.1.2 GNUstep localization macros

# 3.1 GNUstep macros

There is a small set of macros in widespread use between the GNUstep programmers which is not available under Apple Mac OS X. Renaissance provides facilities to support those macros on all platforms. Renaissance ships the header

    Renaissance/GNUstep.h

which can be included whenever these macros are used. The header does nothing if Renaissance is running under GNUstep; it defines the macros if not running under GNUstep. This header is automatically included whenever you include

    Renaissance/Renaissance.h

The header defines a small set of macros (and the number is not expected to grow); which can be classified in two main groups: macros used for memory management, and macros used for localization. We now examine the two sets.

Please note that any GNUstep specific macro which is not explicitly listed in this reference is not supported and should be considered non-portable.

## 3.1.1 GNUstep memory management macros

GNUstep can be used with a garbage collector - instead of manual memory management of objects.

Many of the GNUstep core libraries are supposed to be compilable and usable both with and without the garbage collector; to support this double usage of the source code, a set of macros for memory management are commonly used inside GNUstep source code. Depending if garbage collecting is used or not, those macros expand to different expressions.

Most GNUstep programmers do use routinely these macros in all of their code, because that allows them to integrate the software more easily with garbage collector (if they wish to do so), and also because some of the macros are actually very handy: in particular the `ASSIGN` macro.

Renaissance defines those macros when running under Apple Mac OS X (the native definition is used under GNUstep), so that you can use them freely in your programs without fear of them not being portable.

Here is a list of the memory management macros defined by Renaissance:

- `AUTORELEASE (object)`: Send an autorelease message to object.
- `RELEASE (object)`: Send a release message to object.
- `RETAIN (object)`: Send a retain message to object.
- `DESTROY (variable)`: Send a release message to the object stored in the variable (often an instance variable), then set the variable to nil.
- `ASSIGN (variable, value)`: This macro is used to assign a value to a variable (often an instance variable). The macro retains the new value, puts the new value in the variable, then releases the old value. If the variable had already the new value, the macro does nothing. Using this macro is an excellent programming practice, because the code is simpler and more readable, and it reduces the probability of bugs due to incorrect retain/release of objects when setting variables.
- `ASSIGN_COPY (variable, value)`: The same as ASSIGN, but copies value before assigning it to variable.
- `TEST_AUTORELEASE (object)`: Send an autorelease message to object, but only if it's not nil. This is only useful when you have a strong suspicion that object might be nil, and extreme performance is required, so that skipping sending the autorelease message might make a difference (normally, it doesn't).
- `TEST_RELEASE (object)`: Send a release message to object if it's not nil.
- `TEST_RETAIN (object)`: Send a retain message to object if it's not nil.
- `CREATE_AUTORELEASE_POOL (pool)`: Expands to

      NSAutoreleasePool *pool = [NSAutoreleasePool new];

The following short example should make clear how to write the standard Objective-C accessor methods using these macros. Please note the usage of `ASSIGN(,)`.

    @interface TitledItem : NSObject
    {
      NSString *title;
    }
    - (id) initWithTitle: (NSString *)aTitle;
    - (NSString *) title;
    - (void) setTitle: (NSString *)aTitle;
    @end

    @implementation TitledItem

    - (id) initWithTitle: (NSString *)aTitle
    {
      ASSIGN (title, aTitle);
      return [super init];
    }

    - (NSString *) title
    {
      return title;
    }

    - (void) setTitle: (NSString *)aTitle
    {
      ASSIGN (title, aTitle);
    }

    - (void) dealloc
    {
      RELEASE (title);
      [super dealloc];
    }
    @end

## 3.1.2 GNUstep localization macros

GNUstep source code typically uses a few custom and very short macros for localized strings. The GNUstep `make_strings` program can recognize these macros in addition to the standard `NSBundle` methods and generate/manage `.strings` files from them.

The main reason why these macros are useful is that if you are really localizing all the strings in your program, your program could get quite horrible if you use a very long method invocation with three arguments for each localized string (as required by standards). The GNUstep macros are very short, so you can localize all your strings and still keep your code very readable.

- `NSLocalizedString (key, comment)`: Retrieves the localized string for key from the main bundle.

- `_(key)`: Retrieves the localized string for key from the main bundle, without a comment.

- `__(key)`: Does nothing and expands to `key`; used for localizing static strings.

- `NSLocalizedStaticString (key, comment)`: Does nothing and expands to `key`; used for localizing static strings.

Here is a very short example:

    - (void) logWelcomeMessage
    {
      NSString *message = _(@"Welcome to GNUstep");

      NSLog (message);
    }

the string `Welcome to GNUstep` is localized. If you have static strings, the way to localize them is as follows:

    static NSString *message = __(@"Welcome to GNUstep");

    @implementation XXX
    - (void) logWelcomeMessage
    {
      NSLog (_(message));
    }
    @end

The `__()` macro expands to nothing and is ignored at run time (but it is recognized by the GNUstep `make_strings` program, which records the string as a string to translate in the strings files), while the `_()` macro is the one actually translating the message at run time (but this macro is useless for the GNUstep `make_strings` program because its argument is a variable whose value will only be known at run time, which is why you need the other macro as well).

Next: About this document ... Up: 3. Additional portability facilities Previous: 3. Additional portability facilities