/usr/share/doc/renaissance-doc/html/manual/node25.html is in renaissance-doc 0.9.0-4build3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 | <!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>
|