Version: $Revision$
Date: $Date$
Declared in: Foundation/NSThread.h
Prototype: NSThread* GSCurrentThread()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.
Returns the current thread. Could perhaps return nil
if executing a thread that was started outside the GNUstep
environment and not registered (this should not happen in a
well-coded application).
Declared in: Foundation/NSThread.h
Prototype: BOOL GSRegisterCurrentThread()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.
Returns YES if the thread can be registered,
NO if it is already registered.
Sends out a NSWillBecomeMultiThreadedNotification
if the process was not already multithreaded.
Declared in: Foundation/NSThread.h
Prototype: void GSUnregisterCurrentThread()This function is provided to let threads started by some other software library unregister themselves from the GNUstep threading system.
Calling this function causes a
NSThreadWillExitNotification
to be sent out, and destroys the GNUstep NSThread object
associated with the thread.
Declared in: Foundation/NSDebug.h
Prototype: BOOL GSDebugAllocationActive(BOOL active)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.
Declared in: Foundation/NSDebug.h
Prototype: int GSDebugAllocationCount(Class c)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 ...
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.
Declared in: Foundation/NSDebug.h
Prototype: int GSDebugAllocationPeak(Class c)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.
Declared in: Foundation/NSDebug.h
Prototype: int GSDebugAllocationTotal(Class c)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.
Declared in: Foundation/NSDebug.h
Prototype: Class* GSDebugAllocationClassList()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.
Declared in: Foundation/NSDebug.h
Prototype: const char* GSDebugAllocationList()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.
Declared in: Foundation/NSDebug.h
Prototype: const char* GSDebugAllocationListAll()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.
Declared in: Foundation/NSDebug.h
Prototype: void GSDebugAllocationActiveRecordingObjects()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.
Declared in: Foundation/NSDebug.h
Prototype: NSArray * GSDebugAllocationListRecordedObjects(Class c)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.
Declared in: Foundation/NSBundle.h
Prototype: NSString * NSLocalizedString(NSString * key, NSString * comment)
This function (macro) is used to get the localized
translation of the string key.
key is looked up in the
Localizable.strings file for the current
language. The current language is determined by the
available languages in which the application is
translated, and by using the NSLanguages user
defaults (which should contain an array of the languages
preferred by the user, in order of preference).
Technically, the function works by calling
localizedStringForKey:value:table: on the
main bundle, using @"" as value, and
nil as the table. The comment
is ignored when the macro is expanded; but when we have
tools which can generate the
Localizable.strings files automatically from
source code, the comment will be used by the
tools and added as a comment before the string to
translate. Upon finding something like
NSLocalizedString (@"My useful string",
@"My useful comment about the string");
in the source code, the tools will generate the lines
/* My useful comment about the string */
" My useful string" = "My useful string";
in the Localizable.strings file (the
translator then can use this as a skeleton for the
Localizable.strings 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.
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 @"" 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).
Declared in: Foundation/NSBundle.h
Prototype: NSString * NSLocalizedStringFromTable(NSString * key, NSString * table, NSString * comment)
This function (macro) does the same as
NSLocalizedString, but uses the table
table rather than the default table. This
means that the string to translate will be looked up in a
different file than Localizable.strings. For
example, if you pass DatabaseErrors as the
table, the string will be looked up for
translation in the file
DatabaseErrors.strings. 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.
Declared in: Foundation/NSBundle.h
Prototype: NSString * NSLocalizedStringFromTableInBundle(NSString * key, NSString * table, NSString * bundle, NSString * comment)
This function is the full-blown localization function (it
is actually a macro). It looks up the string
key for translation in the table
table of the bundle bundle
(please refer to the NSBundle documentation for more
information on how this lookup is done).
comment 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.
Declared in: Foundation/NSBundle.h
Prototype: NSString * NSLocalizedStaticString(NSString * key, NSString * comment)This function (macro) is a GNUstep extensions, and it is used to localize static strings. Here is an example of a static string:
NSString *message = @"Hi there";
/* ... some code ... */
NSLog (message);
This string can not be localized using the standard openstep functions/macros. By using this gnustep extension, you can localize it as follows:
NSString *message = NSLocalizedStaticString (@"Hi there",
@"Greeting");
/* ... some code ... */
NSLog (NSLocalizedString (message, @""));
When the tools generate the
Localizable.strings file from the source
code, they will ignore the NSLocalizedString
call while they will extract the string (and the comment)
to localize from the NSLocalizedStaticString
call.
When the code is compiled, instead, the
NSLocalizedStaticString call is ignored (discarded,
it is a macro which simply expands to key), while
the NSLocalizedString will actually look up the
string for translation in the Localizable.strings
file.
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.
Declared in: Foundation/NSBundle.h
Prototype: NSString * _(NSString * key)This function (macro) is a GNUstep extension.
_(@"My string to translate")
is exactly the same as
NSLocalizedString (@"My string to translate", @"")
It is useful when you need to translate an application
very quickly, as you just need to enclose all strings
inside _(). But please note that when you
use this macro, you are not taking advantage of comments
for the translator, so consider using
NSLocalizedString instead when you need a
comment.
Declared in: Foundation/NSBundle.h
Prototype: NSString * __(NSString * key)This function (macro) is a GNUstep extension.
__(@"My string to translate")
is exactly the same as
NSLocalizedStaticString (@"My string to translate",
@"")
It is useful when you need to translate an application very quickly. You would use it as follows for static strings:
NSString *message = __(@"Hello there");
/* ... more code ... */
NSLog (_(messages));
But please note that when you use this macro, you are not
taking advantage of comments for the translator, so
consider using NSLocalizedStaticString
instead when you need a comment.
Declared in: Foundation/NSRange.h
typedef struct { unsigned long location; unsigned long length; } NSRangeThe NSRange type is used to specify ranges of locations, typically items in an array, characters in a string, and bytes in a data object.
As 'boundary' or 'fencepost' errors are a particularly common problem in programming, it is important that you understand how an NSRange works.
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.
However, if you consider these points like the marks on a
ruler, you can only store information between
points. So the number of items that can be stored in a range
is the length of the range.