mirror of
https://github.com/gnustep/libs-base.git
synced 2025-04-26 18:21:04 +00:00
a2be53c7d0
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@10821 72102866-910b-0410-8b05-ffd578937521
601 lines
20 KiB
HTML
601 lines
20 KiB
HTML
<html><head>
|
|
<title>NSFunctions</title>
|
|
</head>
|
|
<body>
|
|
<a href ="Base.html">[Up] </a>
|
|
<h1>NSFunctions</h1>
|
|
<h3>Authors </h3>
|
|
<dl>
|
|
<dt><a href ="http://www.gnustep.org/developers/whoiswho.html">Richard Frith-Macdonald</a>
|
|
<dd>
|
|
<dt><a href ="http://www.gnustep.org/developers/whoiswho.html">Nicola Pero</a>
|
|
<dd>
|
|
</dl>
|
|
<p>Version: $Revision$</p>
|
|
<p>Date: $Date$</p>
|
|
<h2><a name ="cont-0">Functions</a></h2>
|
|
<h3><a name ="cont-1">Thread Function</a></h3>
|
|
<h2><a name ="function-0">GSCurrentThread</a></h2>
|
|
<p><b>Declared in: </b> Foundation/NSThread.h</p>
|
|
<b>Prototype: </b> NSThread* GSCurrentThread()<br>
|
|
|
|
<p>
|
|
|
|
This function is a GNUstep extension. It pretty much
|
|
duplicates the functionality of [NSThread +currentThread]
|
|
but is more efficient and is used internally throughout
|
|
GNUstep.
|
|
</p>
|
|
|
|
<p>
|
|
|
|
Returns the current thread. Could perhaps return <code>nil</code>
|
|
if executing a thread that was started outside the GNUstep
|
|
environment and not registered (this should not happen in a
|
|
well-coded application).
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h2><a name ="function-1">GSRegisterCurrentThread</a></h2>
|
|
<p><b>Declared in: </b> Foundation/NSThread.h</p>
|
|
<b>Prototype: </b> BOOL GSRegisterCurrentThread()<br>
|
|
|
|
<p>
|
|
|
|
This function is provided to let threads started by some other
|
|
software library register themselves to be used with the
|
|
GNUstep system. All such threads should call this function
|
|
before attempting to use any GNUstep objects.
|
|
</p>
|
|
|
|
<p>
|
|
|
|
Returns <code>YES</code> if the thread can be registered,
|
|
<code>NO</code> if it is already registered.
|
|
</p>
|
|
|
|
<p>
|
|
|
|
Sends out a <code>NSWillBecomeMultiThreadedNotification</code>
|
|
if the process was not already multithreaded.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h2><a name ="function-2">GSUnregisterCurrentThread</a></h2>
|
|
<p><b>Declared in: </b> Foundation/NSThread.h</p>
|
|
<b>Prototype: </b> void GSUnregisterCurrentThread()<br>
|
|
|
|
<p>
|
|
|
|
This function is provided to let threads started by some other
|
|
software library unregister themselves from the GNUstep threading
|
|
system.
|
|
</p>
|
|
|
|
<p>
|
|
|
|
Calling this function causes a
|
|
<code>NSThreadWillExitNotification</code>
|
|
to be sent out, and destroys the GNUstep NSThread object
|
|
associated with the thread.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="cont-2">Debugging Functions - Counting Instances of Classes</a></h3>
|
|
<h2><a name ="function-3">GSDebugAllocationActive</a></h2>
|
|
<p><b>Declared in: </b> Foundation/NSDebug.h</p>
|
|
<b>Prototype: </b> BOOL GSDebugAllocationActive(BOOL active)<br>
|
|
|
|
<p>
|
|
|
|
This function is a GNUstep extension. It activates or
|
|
deactivates object allocation debugging. Returns the
|
|
previous state. You should call this function to activate
|
|
allocation debugging before using any of the functions
|
|
described in this section. Object allocation debugging
|
|
should not affect performance too much, and is very useful
|
|
as it allows you to monitor how many objects of each class
|
|
your application has allocated. See below for a detailed
|
|
description of the info you can get, and why it is useful.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h2><a name ="function-4">GSDebugAllocationCount</a></h2>
|
|
<p><b>Declared in: </b> Foundation/NSDebug.h</p>
|
|
<b>Prototype: </b> int GSDebugAllocationCount(Class c)<br>
|
|
|
|
<p>
|
|
|
|
This function is a GNUstep extension. Returns the number
|
|
of instances of the specified class which are currently
|
|
allocated. This number is very important to detect memory
|
|
leaks. If you notice that this number is constantly
|
|
increasing without apparent reason, it is very likely a
|
|
memory leak - you need to check that you are correctly
|
|
releasing objects of this class, otherwise when your
|
|
application runs for a long time, it will eventually
|
|
allocate so many objects as to eat up all your system's
|
|
memory ...
|
|
</p>
|
|
|
|
|
|
<p>
|
|
|
|
This function, like the ones below, returns the number of
|
|
objects allocated/released from the time when
|
|
GSDebugAllocationActive was first called. A negative
|
|
number means that in total, there are less objects of this
|
|
class allocated now than there were when you called
|
|
GSDebugAllocationActive; a positive one means there are
|
|
more.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h2><a name ="function-5">GSDebugAllocationPeak</a></h2>
|
|
<p><b>Declared in: </b> Foundation/NSDebug.h</p>
|
|
<b>Prototype: </b> int GSDebugAllocationPeak(Class c)<br>
|
|
|
|
<p>
|
|
|
|
This function is a GNUstep extension. Returns the peak
|
|
number of instances of the specified class which have been
|
|
concurrently allocated. If this number is very high, it
|
|
means at some point in time you had a situation with a
|
|
huge number of objects of this class allocated - this is
|
|
an indicator that probably at some point in time your
|
|
application was using a lot of memory - so you might want
|
|
to investigate whether you can prevent this problem by
|
|
inserting autorelease pools in your application's
|
|
processing loops.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h2><a name ="function-6">GSDebugAllocationTotal</a></h2>
|
|
<p><b>Declared in: </b> Foundation/NSDebug.h</p>
|
|
<b>Prototype: </b> int GSDebugAllocationTotal(Class c)<br>
|
|
|
|
<p>
|
|
|
|
This function is a GNUstep extension. Returns the total
|
|
number of instances of the specified class which have been
|
|
allocated - basically the number of times you have
|
|
allocated an object of this class. If this number is very
|
|
high, it means you are creating a lot of objects of this
|
|
class; even if you are releasing them correctly, you must
|
|
not forget that allocating and deallocating objects is
|
|
usually one of the slowest things you can do, so you might
|
|
want to consider whether you can reduce the number of
|
|
allocations and deallocations that you are doing - for
|
|
example, by recycling objects of this class, uniquing
|
|
them, and/or using some sort of flyweight pattern. It
|
|
might also be possible that you are unnecessarily creating
|
|
too many objects of this class. Well - of course some times
|
|
there is nothing you can do about it.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h2><a name ="function-7">GSDebugAllocationClassList</a></h2>
|
|
<p><b>Declared in: </b> Foundation/NSDebug.h</p>
|
|
<b>Prototype: </b> Class* GSDebugAllocationClassList()<br>
|
|
|
|
<p>
|
|
|
|
This function is a GNUstep extension. Returns a NULL
|
|
terminated array listing all the classes for which
|
|
statistical information has been collected. Usually, you
|
|
call this function, and then loop on all the classes returned,
|
|
and for each one you get current, peak and total count by
|
|
using GSDebugAllocationCount, GSDebugAllocationPeak and
|
|
GSDebugAllocationTotal.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h2><a name ="function-8">GSDebugAllocationList</a></h2>
|
|
<p><b>Declared in: </b> Foundation/NSDebug.h</p>
|
|
<b>Prototype: </b> const char* GSDebugAllocationList()<br>
|
|
|
|
<p>
|
|
|
|
This function is a GNUstep extension. Returns a newline
|
|
separated list of the classes which have instances
|
|
allocated, and the instance counts. If the 'changeFlag'
|
|
argument is YES then the list gives the number of
|
|
instances allocated/deallocated since the function was
|
|
last called. This function only returns the current count
|
|
of instances (not the peak or total count), but its output
|
|
is ready to be displayed or logged.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h2><a name ="function-9">GSDebugAllocationListAll</a></h2>
|
|
<p><b>Declared in: </b> Foundation/NSDebug.h</p>
|
|
<b>Prototype: </b> const char* GSDebugAllocationListAll()<br>
|
|
|
|
<p>
|
|
|
|
This function is a GNUstep extension. Returns a newline
|
|
separated list of the classes which have had instances
|
|
allocated at any point, and the total count of the number
|
|
of instances allocated for each class. The difference with
|
|
GSDebugAllocationList is that this function returns also
|
|
classes which have no objects allocated at the moment, but
|
|
which had in the past.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="cont-3">Debugging Functions - Tracking Instances of Classes</a></h3>
|
|
<h2><a name ="function-10">GSDebugAllocationActiveRecordingObjects</a></h2>
|
|
<p><b>Declared in: </b> Foundation/NSDebug.h</p>
|
|
<b>Prototype: </b> void GSDebugAllocationActiveRecordingObjects()<br>
|
|
|
|
<p>
|
|
|
|
This function is a GNUstep extension. It activates
|
|
tracking all allocated instances of the specified class
|
|
(passed as argument). This tracking can slow your
|
|
application down, so you should use it only when you are
|
|
into serious debugging. Usually, you will monitor your
|
|
application by using the functions GSDebugAllocationList
|
|
and similia (see above), which do not slow things down
|
|
much and return the number of allocated instances; when
|
|
(if) by studying the reports generated by these functions
|
|
you have found a leak of objects of a certain class, and
|
|
if you can't figure out how to fix it by looking at the
|
|
code, you can use this function to start tracking
|
|
allocated instances of that class, and the following one
|
|
can sometime allow you to list the leaked objects directly.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h2><a name ="function-11">GSDebugAllocationListRecordedObjects</a></h2>
|
|
<p><b>Declared in: </b> Foundation/NSDebug.h</p>
|
|
<b>Prototype: </b> NSArray * GSDebugAllocationListRecordedObjects(Class c)<br>
|
|
|
|
<p>
|
|
|
|
This function is a GNUstep extension. Returns an array
|
|
containing all the allocated objects of a certain class
|
|
which have been recorded (to start the recording, you need
|
|
to invoke GSDebugAllocationActiveRecordedObjects).
|
|
Presumably, you will immediately call -description on them
|
|
to find out the objects you are leaking. The objects are
|
|
returned in an array, so until the array is autoreleased,
|
|
the objects are not released.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="cont-4">Localization Functions and Macros</a></h3>
|
|
<h2><a name ="function-12">NSLocalizedString</a></h2>
|
|
<p><b>Declared in: </b> Foundation/NSBundle.h</p>
|
|
<b>Prototype: </b> NSString * NSLocalizedString(NSString * key, NSString * comment)<br>
|
|
|
|
<p>
|
|
|
|
This function (macro) is used to get the localized
|
|
translation of the string <code>key</code>.
|
|
<code>key</code> is looked up in the
|
|
<code>Localizable.strings</code> file for the current
|
|
language. The current language is determined by the
|
|
available languages in which the application is
|
|
translated, and by using the <code>NSLanguages</code> user
|
|
defaults (which should contain an array of the languages
|
|
preferred by the user, in order of preference).
|
|
</p>
|
|
|
|
<p>
|
|
|
|
Technically, the function works by calling
|
|
<code>localizedStringForKey:value:table:</code> on the
|
|
main bundle, using <code>@""</code> as value, and
|
|
<code>nil</code> as the table. The <code>comment</code>
|
|
is ignored when the macro is expanded; but when we have
|
|
tools which can generate the
|
|
<code>Localizable.strings</code> files automatically from
|
|
source code, the <code>comment</code> will be used by the
|
|
tools and added as a comment before the string to
|
|
translate. Upon finding something like
|
|
</p>
|
|
|
|
<p>
|
|
|
|
<code>
|
|
NSLocalizedString (@"My useful string",
|
|
@"My useful comment about the string");
|
|
</code>
|
|
</p>
|
|
|
|
<p>
|
|
|
|
in the source code, the tools will generate the lines
|
|
</p>
|
|
|
|
<p>
|
|
|
|
<code>
|
|
/* My useful comment about the string */
|
|
" My useful string" = "My useful string";
|
|
</code>
|
|
</p>
|
|
|
|
<p>
|
|
|
|
in the <code>Localizable.strings</code> file (the
|
|
translator then can use this as a skeleton for the
|
|
<code>Localizable.strings</code> for his/her own language,
|
|
where she/he can replace the right hand side with the
|
|
translation in her/his own language). The comment can
|
|
help the translator to decide how to translate when it is
|
|
not clear how to translate (because the original string is
|
|
now out of context, and out of context might not be so
|
|
clear what the string means). The comment is totally
|
|
ignored by the library code.
|
|
</p>
|
|
|
|
<p>
|
|
|
|
If you don't have a comment (because the string is so
|
|
self-explanatory that it doesn't need it), you can leave
|
|
it blank, by using <code>@""</code> as a comment. If the
|
|
string might be unclear out of context, it is recommended
|
|
that you add a comment (even if it is unused for now).
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h2><a name ="function-13">NSLocalizedStringFromTable</a></h2>
|
|
<p><b>Declared in: </b> Foundation/NSBundle.h</p>
|
|
<b>Prototype: </b> NSString * NSLocalizedStringFromTable(NSString * key, NSString * table, NSString * comment)<br>
|
|
|
|
<p>
|
|
|
|
This function (macro) does the same as
|
|
<code>NSLocalizedString</code>, but uses the table
|
|
<code>table</code> rather than the default table. This
|
|
means that the string to translate will be looked up in a
|
|
different file than <code>Localizable.strings</code>. For
|
|
example, if you pass <code>DatabaseErrors</code> as the
|
|
<code>table</code>, the string will be looked up for
|
|
translation in the file
|
|
<code>DatabaseErrors.strings</code>. This allows you to
|
|
have the same string translated in different ways, by
|
|
having a different translation in different tables, and
|
|
choosing between the different translation by choosing a
|
|
different table.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h2><a name ="function-14">NSLocalizedStringFromTableInBundle</a></h2>
|
|
<p><b>Declared in: </b> Foundation/NSBundle.h</p>
|
|
<b>Prototype: </b> NSString * NSLocalizedStringFromTableInBundle(NSString * key, NSString * table, NSString * bundle, NSString * comment)<br>
|
|
|
|
<p>
|
|
|
|
This function is the full-blown localization function (it
|
|
is actually a macro). It looks up the string
|
|
<code>key</code> for translation in the table
|
|
<code>table</code> of the bundle <code>bundle</code>
|
|
(please refer to the NSBundle documentation for more
|
|
information on how this lookup is done).
|
|
<code>comment</code> is a comment, which is ignored by the
|
|
library (it is discarded when the macro is expanded) but which
|
|
can be used by tools which parse the source code and generate
|
|
strings table to provide a comment which the translator can
|
|
use when translating the string.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="cont-5">GNUstep Localization Functions and Macros</a></h3>
|
|
<h2><a name ="function-15">NSLocalizedStaticString</a></h2>
|
|
<p><b>Declared in: </b> Foundation/NSBundle.h</p>
|
|
<b>Prototype: </b> NSString * NSLocalizedStaticString(NSString * key, NSString * comment)<br>
|
|
|
|
<p>
|
|
|
|
This function (macro) is a GNUstep extensions, and it is used
|
|
to localize static strings. Here is an example of a static
|
|
string:
|
|
</p>
|
|
|
|
<p>
|
|
|
|
<code>
|
|
NSString *message = @"Hi there";
|
|
|
|
/* ... some code ... */
|
|
|
|
NSLog (message);
|
|
</code>
|
|
</p>
|
|
|
|
<p>
|
|
|
|
This string can not be localized using the standard
|
|
openstep functions/macros. By using this gnustep extension,
|
|
you can localize it as follows:
|
|
</p>
|
|
|
|
<p>
|
|
|
|
<code>
|
|
NSString *message = NSLocalizedStaticString (@"Hi there",
|
|
@"Greeting");
|
|
|
|
/* ... some code ... */
|
|
|
|
NSLog (NSLocalizedString (message, @""));
|
|
</code>
|
|
</p>
|
|
|
|
<p>
|
|
|
|
When the tools generate the
|
|
<code>Localizable.strings</code> file from the source
|
|
code, they will ignore the <code>NSLocalizedString</code>
|
|
call while they will extract the string (and the comment)
|
|
to localize from the <code>NSLocalizedStaticString</code>
|
|
call.
|
|
</p>
|
|
|
|
<p>
|
|
|
|
When the code is compiled, instead, the
|
|
<code>NSLocalizedStaticString</code> call is ignored (discarded,
|
|
it is a macro which simply expands to <code>key</code>), while
|
|
the <code>NSLocalizedString</code> will actually look up the
|
|
string for translation in the <code>Localizable.strings</code>
|
|
file.
|
|
</p>
|
|
|
|
<p>
|
|
|
|
Please note that there is currently no macro/function to
|
|
localize static strings using different tables. If you
|
|
need that functionality, you have either to prepare the
|
|
localization tables by hand, or to rewrite your code in
|
|
such a way as not to use static strings.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h2><a name ="function-16">_</a></h2>
|
|
<p><b>Declared in: </b> Foundation/NSBundle.h</p>
|
|
<b>Prototype: </b> NSString * _(NSString * key)<br>
|
|
|
|
<p>
|
|
|
|
This function (macro) is a GNUstep extension.
|
|
</p>
|
|
|
|
<p>
|
|
|
|
<code>_(@"My string to translate")</code>
|
|
</p>
|
|
|
|
<p>
|
|
|
|
is exactly the same as
|
|
</p>
|
|
|
|
<p>
|
|
|
|
<code>NSLocalizedString (@"My string to translate", @"")</code>
|
|
</p>
|
|
|
|
<p>
|
|
|
|
It is useful when you need to translate an application
|
|
very quickly, as you just need to enclose all strings
|
|
inside <code>_()</code>. But please note that when you
|
|
use this macro, you are not taking advantage of comments
|
|
for the translator, so consider using
|
|
<code>NSLocalizedString</code> instead when you need a
|
|
comment.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h2><a name ="function-17">__</a></h2>
|
|
<p><b>Declared in: </b> Foundation/NSBundle.h</p>
|
|
<b>Prototype: </b> NSString * __(NSString * key)<br>
|
|
|
|
<p>
|
|
|
|
This function (macro) is a GNUstep extension.
|
|
</p>
|
|
|
|
<p>
|
|
|
|
<code>__(@"My string to translate")</code>
|
|
</p>
|
|
|
|
<p>
|
|
|
|
is exactly the same as
|
|
</p>
|
|
|
|
<p>
|
|
|
|
<code>NSLocalizedStaticString (@"My string to translate",
|
|
@"")</code>
|
|
</p>
|
|
|
|
<p>
|
|
|
|
It is useful when you need to translate an application very
|
|
quickly. You would use it as follows for static strings:
|
|
</p>
|
|
|
|
<p>
|
|
|
|
<code>
|
|
NSString *message = __(@"Hello there");
|
|
|
|
/* ... more code ... */
|
|
|
|
NSLog (_(messages));
|
|
</code>
|
|
</p>
|
|
|
|
<p>
|
|
|
|
But please note that when you use this macro, you are not
|
|
taking advantage of comments for the translator, so
|
|
consider using <code>NSLocalizedStaticString</code>
|
|
instead when you need a comment.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h2><a name ="cont-6">Types</a></h2>
|
|
<h3><a name ="NSRange">NSRange</a></h3>
|
|
<p><b>Declared in: </b> Foundation/NSRange.h</p>
|
|
<b>typedef </b>
|
|
struct { unsigned long location; unsigned long length; }
|
|
NSRange<br>
|
|
|
|
|
|
<p>
|
|
|
|
The NSRange type is used to specify ranges of locations,
|
|
typically items in an array, characters in a string, and bytes
|
|
in a data object.
|
|
</p>
|
|
|
|
<p>
|
|
|
|
As 'boundary' or 'fencepost' errors are a particularly common
|
|
problem in programming, it is important that you understand
|
|
how an NSRange works.
|
|
</p>
|
|
|
|
<p>
|
|
|
|
An NSRange consists of a location and a length. The points
|
|
that are considered to lie in a range are the integers from
|
|
the location to the location plus the length, so the number
|
|
of points in a range is the length of the range plus one.<br>
|
|
However, if you consider these points like the marks on a
|
|
ruler, you can only store information <strong>between</strong>
|
|
points. So the number of items that can be stored in a range
|
|
is the length of the range.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
</body>
|
|
|
|
</html>
|