/usr/share/doc/renaissance-doc/html/manual/node25.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<!--Converted with LaTeX2HTML 2002-2-1 (1.71)
original version by:  Nikos Drakos, CBLU, University of Leeds
* revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>3.1 GNUstep macros</TITLE>
<META NAME="description" CONTENT="3.1 GNUstep macros">
<META NAME="keywords" CONTENT="manual">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">

<META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

<LINK REL="STYLESHEET" HREF="manual.css">

<LINK REL="previous" HREF="node24.html">
<LINK REL="up" HREF="node24.html">
<LINK REL="next" HREF="node26.html">
</HEAD>

<BODY BGCOLOR="#FFFFFF" text="#000000" link="#0000FF" vlink="#4444FF" alink="#3388FF">
<B> Next: <A NAME="tex2html917"
  HREF="node26.html">About this document ...</A> </B>
<B>Up: <A NAME="tex2html913"
  HREF="node24.html">3. Additional portability facilities</A>  </B>
<B> Previous: <A NAME="tex2html909"
  HREF="node24.html">3. Additional portability facilities</A> </B>
<BR> <P>

<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>

<UL>
<LI><A NAME="tex2html918"
  HREF="node25.html#SECTION00411000000000000000">3.1.1 GNUstep memory management macros</A>
<LI><A NAME="tex2html919"
  HREF="node25.html#SECTION00412000000000000000">3.1.2 GNUstep localization macros</A>
</UL>
<!--End of Table of Child-Links-->
<HR>

<H1><A NAME="SECTION00410000000000000000">
3.1 GNUstep macros</A>
</H1>
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
<PRE>
Renaissance/GNUstep.h
</PRE>
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
<PRE>
Renaissance/Renaissance.h
</PRE>
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.

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

<P>

<H2><A NAME="SECTION00411000000000000000">
3.1.1 GNUstep memory management macros</A>
</H2>
GNUstep can be used with a garbage collector - instead of manual
memory management of objects.

<P>
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.

<P>
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
<TT>ASSIGN</TT> macro.

<P>
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.

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

<UL>
<LI><TT>AUTORELEASE (object)</TT>: Send an autorelease message to object.
</LI>
<LI><TT>RELEASE (object)</TT>: Send a release message to object.
</LI>
<LI><TT>RETAIN (object)</TT>: Send a retain message to object.
</LI>
<LI><TT>DESTROY (variable)</TT>: Send a release message to the object
stored in the variable (often an instance variable), then set the
variable to nil.
</LI>
<LI><TT>ASSIGN (variable, value)</TT>: 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.
</LI>
<LI><TT>ASSIGN_COPY (variable, value)</TT>: The same as ASSIGN, but copies
value before assigning it to variable.
</LI>
<LI><TT>TEST_AUTORELEASE (object)</TT>: 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).
</LI>
<LI><TT>TEST_RELEASE (object)</TT>: Send a release message to
object if it's not nil.
</LI>
<LI><TT>TEST_RETAIN (object)</TT>: Send a retain message to
object if it's not nil.
</LI>
<LI><TT>CREATE_AUTORELEASE_POOL (pool)</TT>: Expands to
<PRE>
NSAutoreleasePool *pool = [NSAutoreleasePool new];
</PRE>
</LI>
</UL>

<P>
The following short example should make clear how to write the
standard Objective-C accessor methods using these macros.  Please note
the usage of <TT>ASSIGN(,)</TT>.
<PRE>
@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
</PRE>

<P>

<H2><A NAME="SECTION00412000000000000000">
3.1.2 GNUstep localization macros</A>
</H2>
GNUstep source code typically uses a few custom and very short macros
for localized strings.  The GNUstep <TT>make_strings</TT> program can
recognize these macros in addition to the standard <TT>NSBundle</TT>
methods and generate/manage <TT>.strings</TT> files from them.

<P>
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.

<P>

<UL>
<LI><TT>NSLocalizedString (key, comment)</TT>: Retrieves the 
localized string for key from the main bundle.

<P>
</LI>
<LI><TT>_(key)</TT>: Retrieves the localized string for key from the main
bundle, without a comment.

<P>
</LI>
<LI><TT>__(key)</TT>: Does nothing and expands to <TT>key</TT>;
used for localizing static strings.

<P>
</LI>
<LI><TT>NSLocalizedStaticString (key, comment)</TT>: Does nothing and
expands to <TT>key</TT>; used for localizing static strings.
</LI>
</UL>

<P>
Here is a very short example:
<PRE>
- (void) logWelcomeMessage
{
  NSString *message = _(@"Welcome to GNUstep");

  NSLog (message);
}
</PRE>
the string <TT>Welcome to GNUstep</TT> is localized.  If you have static
strings, the way to localize them is as follows:
<PRE>
static NSString *message = __(@"Welcome to GNUstep");

@implementation XXX
- (void) logWelcomeMessage
{
  NSLog (_(message));
}
@end
</PRE>
The <TT>__()</TT> macro expands to nothing and is ignored at run
time (but it is recognized by the GNUstep <TT>make_strings</TT>
program, which records the string as a string to translate in the
strings files), while the <TT>_()</TT> macro is the one actually
translating the message at run time (but this macro is useless for the
GNUstep <TT>make_strings</TT> 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).

<P>
<HR><B> Next: <A NAME="tex2html917"
  HREF="node26.html">About this document ...</A> </B>
<B>Up: <A NAME="tex2html913"
  HREF="node24.html">3. Additional portability facilities</A> </B>
<B> Previous: <A NAME="tex2html909"
  HREF="node24.html">3. Additional portability facilities</A> </B>

<!--End of Navigation Panel-->
<ADDRESS>

2008-03-19
</ADDRESS>
</BODY>
</HTML>
renaissance-doc 0.9.0-4build7 / usr / share / doc / renaissance-doc / html / manual / node25.html
