2
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.6//EN" "http://www.gnustep.org/gsdoc-0_6_6.xml">
3
<gsdoc base="NSFunctions" up="Base">
5
<title>NSFunctions</title>
6
<author name="Richard Frith-Macdonald">
7
<email address="rfm@gnu.org"/>
8
<url url="http://www.gnustep.org/developers/whoiswho.html"/>
10
<author name="Nicola Pero">
11
<email address="n.pero@mi.flashnet.it"/>
12
<url url="http://www.gnustep.org/developers/whoiswho.html"/>
14
<version>$Revision: 1.6 $</version>
15
<date>$Date: 2001/08/31 11:00:47 $</date>
19
<heading>Functions</heading>
21
<heading>Thread Function</heading>
22
<function name="GSCurrentThread" type="NSThread*">
23
<declared>Foundation/NSThread.h</declared>
26
This function is a GNUstep extension. It pretty much
27
duplicates the functionality of [NSThread +currentThread]
28
but is more efficient and is used internally throughout
32
Returns the current thread. Could perhaps return <code>nil</code>
33
if executing a thread that was started outside the GNUstep
34
environment and not registered (this should not happen in a
35
well-coded application).
38
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
41
<function name="GSRegisterCurrentThread" type="BOOL">
42
<declared>Foundation/NSThread.h</declared>
45
This function is provided to let threads started by some other
46
software library register themselves to be used with the
47
GNUstep system. All such threads should call this function
48
before attempting to use any GNUstep objects.
51
Returns <code>YES</code> if the thread can be registered,
52
<code>NO</code> if it is already registered.
55
Sends out a <code>NSWillBecomeMultiThreadedNotification</code>
56
if the process was not already multithreaded.
59
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
62
<function name="GSUnregisterCurrentThread" type="void">
63
<declared>Foundation/NSThread.h</declared>
66
This function is provided to let threads started by some other
67
software library unregister themselves from the GNUstep threading
71
Calling this function causes a
72
<code>NSThreadWillExitNotification</code>
73
to be sent out, and destroys the GNUstep NSThread object
74
associated with the thread.
77
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
82
<heading>Debugging Functions - Counting Instances of Classes</heading>
83
<function name="GSDebugAllocationActive" type="BOOL">
84
<arg type="BOOL">active</arg>
85
<declared>Foundation/NSDebug.h</declared>
88
This function is a GNUstep extension. It activates or
89
deactivates object allocation debugging. Returns the
90
previous state. You should call this function to activate
91
allocation debugging before using any of the functions
92
described in this section. Object allocation debugging
93
should not affect performance too much, and is very useful
94
as it allows you to monitor how many objects of each class
95
your application has allocated. See below for a detailed
96
description of the info you can get, and why it is useful.
99
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
102
<function name="GSDebugAllocationCount" type="int">
103
<arg type="Class">c</arg>
104
<declared>Foundation/NSDebug.h</declared>
107
This function is a GNUstep extension. Returns the number
108
of instances of the specified class which are currently
109
allocated. This number is very important to detect memory
110
leaks. If you notice that this number is constantly
111
increasing without apparent reason, it is very likely a
112
memory leak - you need to check that you are correctly
113
releasing objects of this class, otherwise when your
114
application runs for a long time, it will eventually
115
allocate so many objects as to eat up all your system's
120
This function, like the ones below, returns the number of
121
objects allocated/released from the time when
122
GSDebugAllocationActive was first called. A negative
123
number means that in total, there are less objects of this
124
class allocated now than there were when you called
125
GSDebugAllocationActive; a positive one means there are
129
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
132
<function name="GSDebugAllocationPeak" type="int">
133
<arg type="Class">c</arg>
134
<declared>Foundation/NSDebug.h</declared>
137
This function is a GNUstep extension. Returns the peak
138
number of instances of the specified class which have been
139
concurrently allocated. If this number is very high, it
140
means at some point in time you had a situation with a
141
huge number of objects of this class allocated - this is
142
an indicator that probably at some point in time your
143
application was using a lot of memory - so you might want
144
to investigate whether you can prevent this problem by
145
inserting autorelease pools in your application's
149
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
152
<function name="GSDebugAllocationTotal" type="int">
153
<arg type="Class">c</arg>
154
<declared>Foundation/NSDebug.h</declared>
157
This function is a GNUstep extension. Returns the total
158
number of instances of the specified class which have been
159
allocated - basically the number of times you have
160
allocated an object of this class. If this number is very
161
high, it means you are creating a lot of objects of this
162
class; even if you are releasing them correctly, you must
163
not forget that allocating and deallocating objects is
164
usually one of the slowest things you can do, so you might
165
want to consider whether you can reduce the number of
166
allocations and deallocations that you are doing - for
167
example, by recycling objects of this class, uniquing
168
them, and/or using some sort of flyweight pattern. It
169
might also be possible that you are unnecessarily creating
170
too many objects of this class. Well - of course some times
171
there is nothing you can do about it.
174
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
177
<function name="GSDebugAllocationClassList" type="Class*">
178
<declared>Foundation/NSDebug.h</declared>
181
This function is a GNUstep extension. Returns a NULL
182
terminated array listing all the classes for which
183
statistical information has been collected. Usually, you
184
call this function, and then loop on all the classes returned,
185
and for each one you get current, peak and total count by
186
using GSDebugAllocationCount, GSDebugAllocationPeak and
187
GSDebugAllocationTotal.
190
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
193
<function name="GSDebugAllocationList" type="const char*">
194
<declared>Foundation/NSDebug.h</declared>
197
This function is a GNUstep extension. Returns a newline
198
separated list of the classes which have instances
199
allocated, and the instance counts. If the 'changeFlag'
200
argument is YES then the list gives the number of
201
instances allocated/deallocated since the function was
202
last called. This function only returns the current count
203
of instances (not the peak or total count), but its output
204
is ready to be displayed or logged.
207
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
210
<function name="GSDebugAllocationListAll" type="const char*">
211
<declared>Foundation/NSDebug.h</declared>
214
This function is a GNUstep extension. Returns a newline
215
separated list of the classes which have had instances
216
allocated at any point, and the total count of the number
217
of instances allocated for each class. The difference with
218
GSDebugAllocationList is that this function returns also
219
classes which have no objects allocated at the moment, but
220
which had in the past.
223
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
228
<heading>Debugging Functions - Tracking Instances of Classes</heading>
229
<function name="GSDebugAllocationActiveRecordingObjects" type="void">
230
<declared>Foundation/NSDebug.h</declared>
233
This function is a GNUstep extension. It activates
234
tracking all allocated instances of the specified class
235
(passed as argument). This tracking can slow your
236
application down, so you should use it only when you are
237
into serious debugging. Usually, you will monitor your
238
application by using the functions GSDebugAllocationList
239
and similia (see above), which do not slow things down
240
much and return the number of allocated instances; when
241
(if) by studying the reports generated by these functions
242
you have found a leak of objects of a certain class, and
243
if you can't figure out how to fix it by looking at the
244
code, you can use this function to start tracking
245
allocated instances of that class, and the following one
246
can sometime allow you to list the leaked objects directly.
249
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
252
<function name="GSDebugAllocationListRecordedObjects" type="NSArray *">
253
<arg type="Class">c</arg>
254
<declared>Foundation/NSDebug.h</declared>
257
This function is a GNUstep extension. Returns an array
258
containing all the allocated objects of a certain class
259
which have been recorded (to start the recording, you need
260
to invoke GSDebugAllocationActiveRecordedObjects).
261
Presumably, you will immediately call -description on them
262
to find out the objects you are leaking. The objects are
263
returned in an array, so until the array is autoreleased,
264
the objects are not released.
267
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
272
<heading>Localization Functions and Macros</heading>
273
<function name="NSLocalizedString" type="NSString *">
274
<arg type="NSString *">key</arg>
275
<arg type="NSString *">comment</arg>
276
<declared>Foundation/NSBundle.h</declared>
279
This function (macro) is used to get the localized
280
translation of the string <code>key</code>.
281
<code>key</code> is looked up in the
282
<code>Localizable.strings</code> file for the current
283
language. The current language is determined by the
284
available languages in which the application is
285
translated, and by using the <code>NSLanguages</code> user
286
defaults (which should contain an array of the languages
287
preferred by the user, in order of preference).
290
Technically, the function works by calling
291
<code>localizedStringForKey:value:table:</code> on the
292
main bundle, using <code>@""</code> as value, and
293
<code>nil</code> as the table. The <code>comment</code>
294
is ignored when the macro is expanded; but when we have
295
tools which can generate the
296
<code>Localizable.strings</code> files automatically from
297
source code, the <code>comment</code> will be used by the
298
tools and added as a comment before the string to
299
translate. Upon finding something like
303
NSLocalizedString (@"My useful string",
304
@"My useful comment about the string");
308
in the source code, the tools will generate the lines
312
/* My useful comment about the string */
313
" My useful string" = "My useful string";
317
in the <code>Localizable.strings</code> file (the
318
translator then can use this as a skeleton for the
319
<code>Localizable.strings</code> for his/her own language,
320
where she/he can replace the right hand side with the
321
translation in her/his own language). The comment can
322
help the translator to decide how to translate when it is
323
not clear how to translate (because the original string is
324
now out of context, and out of context might not be so
325
clear what the string means). The comment is totally
326
ignored by the library code.
329
If you don't have a comment (because the string is so
330
self-explanatory that it doesn't need it), you can leave
331
it blank, by using <code>@""</code> as a comment. If the
332
string might be unclear out of context, it is recommended
333
that you add a comment (even if it is unused for now).
337
<function name="NSLocalizedStringFromTable" type="NSString *">
338
<arg type="NSString *">key</arg>
339
<arg type="NSString *">table</arg>
340
<arg type="NSString *">comment</arg>
341
<declared>Foundation/NSBundle.h</declared>
344
This function (macro) does the same as
345
<code>NSLocalizedString</code>, but uses the table
346
<code>table</code> rather than the default table. This
347
means that the string to translate will be looked up in a
348
different file than <code>Localizable.strings</code>. For
349
example, if you pass <code>DatabaseErrors</code> as the
350
<code>table</code>, the string will be looked up for
351
translation in the file
352
<code>DatabaseErrors.strings</code>. This allows you to
353
have the same string translated in different ways, by
354
having a different translation in different tables, and
355
choosing between the different translation by choosing a
360
<function name="NSLocalizedStringFromTableInBundle" type="NSString *">
361
<arg type="NSString *">key</arg>
362
<arg type="NSString *">table</arg>
363
<arg type="NSString *">bundle</arg>
364
<arg type="NSString *">comment</arg>
365
<declared>Foundation/NSBundle.h</declared>
368
This function is the full-blown localization function (it
369
is actually a macro). It looks up the string
370
<code>key</code> for translation in the table
371
<code>table</code> of the bundle <code>bundle</code>
372
(please refer to the NSBundle documentation for more
373
information on how this lookup is done).
374
<code>comment</code> is a comment, which is ignored by the
375
library (it is discarded when the macro is expanded) but which
376
can be used by tools which parse the source code and generate
377
strings table to provide a comment which the translator can
378
use when translating the string.
384
<heading>GNUstep Localization Functions and Macros</heading>
385
<function name="NSLocalizedStaticString" type="NSString *">
386
<arg type="NSString *">key</arg>
387
<arg type="NSString *">comment</arg>
388
<declared>Foundation/NSBundle.h</declared>
391
This function (macro) is a GNUstep extensions, and it is used
392
to localize static strings. Here is an example of a static
397
NSString *message = @"Hi there";
399
/* ... some code ... */
405
This string can not be localized using the standard
406
openstep functions/macros. By using this gnustep extension,
407
you can localize it as follows:
411
NSString *message = NSLocalizedStaticString (@"Hi there",
414
/* ... some code ... */
416
NSLog (NSLocalizedString (message, @""));
420
When the tools generate the
421
<code>Localizable.strings</code> file from the source
422
code, they will ignore the <code>NSLocalizedString</code>
423
call while they will extract the string (and the comment)
424
to localize from the <code>NSLocalizedStaticString</code>
428
When the code is compiled, instead, the
429
<code>NSLocalizedStaticString</code> call is ignored (discarded,
430
it is a macro which simply expands to <code>key</code>), while
431
the <code>NSLocalizedString</code> will actually look up the
432
string for translation in the <code>Localizable.strings</code>
436
Please note that there is currently no macro/function to
437
localize static strings using different tables. If you
438
need that functionality, you have either to prepare the
439
localization tables by hand, or to rewrite your code in
440
such a way as not to use static strings.
443
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
445
<function name="_" type="NSString *">
446
<arg type="NSString *">key</arg>
447
<declared>Foundation/NSBundle.h</declared>
450
This function (macro) is a GNUstep extension.
453
<code>_(@"My string to translate")</code>
456
is exactly the same as
459
<code>NSLocalizedString (@"My string to translate", @"")</code>
462
It is useful when you need to translate an application
463
very quickly, as you just need to enclose all strings
464
inside <code>_()</code>. But please note that when you
465
use this macro, you are not taking advantage of comments
466
for the translator, so consider using
467
<code>NSLocalizedString</code> instead when you need a
471
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
474
<function name="__" type="NSString *">
475
<arg type="NSString *">key</arg>
476
<declared>Foundation/NSBundle.h</declared>
479
This function (macro) is a GNUstep extension.
482
<code>__(@"My string to translate")</code>
485
is exactly the same as
488
<code>NSLocalizedStaticString (@"My string to translate",
492
It is useful when you need to translate an application very
493
quickly. You would use it as follows for static strings:
497
NSString *message = __(@"Hello there");
499
/* ... more code ... */
505
But please note that when you use this macro, you are not
506
taking advantage of comments for the translator, so
507
consider using <code>NSLocalizedStaticString</code>
508
instead when you need a comment.
511
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
518
<heading>Types</heading>
519
<type name="NSRange">
521
struct { unsigned long location; unsigned long length; }
523
<declared>Foundation/NSRange.h</declared>
526
The NSRange type is used to specify ranges of locations,
527
typically items in an array, characters in a string, and bytes
531
As 'boundary' or 'fencepost' errors are a particularly common
532
problem in programming, it is important that you understand
533
how an NSRange works.
536
An NSRange consists of a location and a length. The points
537
that are considered to lie in a range are the integers from
538
the location to the location plus the length, so the number
539
of points in a range is the length of the range plus one.<br />
540
However, if you consider these points like the marks on a
541
ruler, you can only store information <strong>between</strong>
542
points. So the number of items that can be stored in a range
543
is the length of the range.
546
<standards><OpenStep/><MacOS-X/><GNUstep/></standards>
added
removed
Documentation/gsdoc/NSFunctions.gsdoc
