Warning - do not use this.
Warning - do not use this.
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.
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 a comment and the line
" 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).
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.
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.
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.
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.
Macro to log a message only the first time it is
encountered.
Not entirely thread safe...
but that's not really important, it just means that it's
possible for the message to be logged more than once
if two threads call it simultaneously when it has not
already been called.
Use this from inside a
function. Pass an NSString as a format,
followed by zero or more arguments for the
format string. Example: GSOnceMLog(@"This
function is deprecated, use another");
Macro to log a message only the first time it is
encountered.
Not entirely thread safe...
but that's not really important, it just means that it's
possible for the message to be logged more than once
if two threads call it simultaneously when it has not
already been called.
Use this from inside a
method. Pass an NSString as a format
followed by zero or more arguments for the
format string.
Example:
GSOnceMLog(@"This method is deprecated, use
another");
This macro is like NSDebugLLog() but includes the name and location of the function in which the macro is used as part of the log output.
This macro is a shorthand for NSDebugFLLog() using then default debug level... 'dflt'
This macro saves the name and location of the function in which the macro is used, along with a short string msg as the tag associated with a recorded object.
NSDebugLLog() is the basic debug logging macro used to display log messages using NSLog() , if debug logging was enabled at compile time and the appropriate logging level was set at runtime.
Debug logging which can be enabled/disabled by defining GSDIAGNOSE when compiling and also setting values in the mutable set which is set up by NSProcessInfo. GSDIAGNOSE is defined automatically unless diagnose=no is specified in the make arguments.
NSProcess initialises a set of strings that are
the names of active debug levels using the
'--GNU-Debug=...' command line argument.
Each command-line argument of that form is removed
from NSProcessInfo
's list of arguments
and the variable part (...) is added to the set. This
means that as far as the program proper is concerned,
it is running with the same arguments as if debugging
had not been enabled.
For instance, to debug the NSBundle class, run your program with '--GNU-Debug=NSBundle' You can of course supply multiple '--GNU-Debug=...' arguments to output debug information on more than one thing.
NSUserDefaults also adds debug levels from the array given by the GNU-Debug key... but these values will not take effect until the +standardUserDefaults method is called... so they are useless for debugging NSUserDefaults itself or for debugging any code executed before the defaults system is used.
To embed debug logging in your code you use the NSDebugLLog() or NSDebugLog() macro. NSDebugLog() is just NSDebugLLog() with the debug level set to 'dflt'. So, to activate debug statements that use NSDebugLog() , you supply the '--GNU-Debug=dflt' argument to your program.
You can also change the active debug levels under your programs control - NSProcessInfo has a [-debugSet] method that returns the mutable set that contains the active debug levels - your program can modify this set.
Two debug levels have a special effect - 'dflt' is the level used for debug logs statements where no debug level is specified, and 'NoWarn' is used to *disable* warning messages.
As a convenience, there are four more logging macros you can use - NSDebugFLog() , NSDebugFLLog() , NSDebugMLog() and NSDebugMLLog() . These are the same as the other macros, but are specifically for use in either functions or methods and prepend information about the file, line and either function or class/method in which the message was generated.
This macro is a shorthand for NSDebugLLog() using then default debug level... 'dflt'
This macro is like NSDebugLLog() but includes the name and location of the method in which the macro is used as part of the log output.
This macro is a shorthand for NSDebugMLLog() using then default debug level... 'dflt'
This macro saves the name and location of the method in which the macro is used, along with a short string msg as the tag associated with a recorded object.
This macro is like NSWarnLog() but includes the name and location of the function in which the macro is used as part of the log output.
NSWarnLog() is the basic debug logging macro used to display warning messages using NSLog() , if warn logging was not disabled at compile time and the disabling logging level was not set at runtime.
Warning messages which can be enabled/disabled by defining GSWARN when compiling.
You can also disable these messages at runtime by supplying a '--GNU-Debug=NoWarn' argument to the program, or by adding 'NoWarn' to the user default array named 'GNU-Debug'.
These logging macros are intended to be used when the software detects something that it not necessarily fatal or illegal, but looks like it might be a programming error. eg. attempting to remove 'nil' from an NSArray, which the Spec/documentation does not prohibit, but which a well written program should not be attempting (since an NSArray object cannot contain a 'nil').
NB. The 'warn=yes' option is understood by the GNUstep make package to mean that GSWARN should be defined, and the 'warn=no' means that GSWARN should be undefined. Default is to define it.
To embed debug logging in your code you use the NSWarnLog() macro.
As a convenience, there are two more logging macros you can use - NSWarnFLog() , and NSWarnMLog() . These are specifically for use in either functions or methods and prepend information about the file, line and either function or class/method in which the message was generated.
This macro is like NSWarnLog() but includes the name and location of the method in which the macro is used as part of the log output.
Give a precision of at least 38 decimal digits requires 128 bits.
Used in an ObjC method body.
See
NSAssertionHandler
for details.
When condition is false,
raise an exception using desc
Used in an ObjC method body.
See
NSAssertionHandler
for details.
When condition is false,
raise an exception using desc and
arg1
Used in an ObjC method body.
See
NSAssertionHandler
for details.
When condition is false,
raise an exception using desc and
arg1, arg2
Used in an ObjC method body.
See
NSAssertionHandler
for details.
When condition is false,
raise an exception using desc and
arg1, arg2, arg3
Used in an ObjC method body.
See
NSAssertionHandler
for details.
When condition is false,
raise an exception using desc and
arg1, arg2, arg3,
arg4
Used in an ObjC method body.
See
NSAssertionHandler
for details.
When condition is false,
raise an exception using desc and
arg1, arg2, arg3,
arg4, arg5
Used in plain C code (not in an ObjC method body).
See
NSAssertionHandler
for details.
When condition is false,
raise an exception using desc
Used in plain C code (not in an ObjC method body).
See
NSAssertionHandler
for details.
When condition is false,
raise an exception using desc and
arg1
Used in plain C code (not in an ObjC method body).
See
NSAssertionHandler
for details.
When condition is false,
raise an exception using desc and
arg1, arg2
Used in plain C code (not in an ObjC method body).
See
NSAssertionHandler
for details.
When condition is false,
raise an exception using desc and
arg1, arg2, arg3
Used in plain C code (not in an ObjC method body).
See
NSAssertionHandler
for details.
When condition is false,
raise an exception using desc and
arg1, arg2, arg3,
arg4
Used in plain C code (not in an ObjC method body).
See
NSAssertionHandler
for details.
When condition is false,
raise an exception using desc and
arg1, arg2, arg3,
arg4, arg5
Used in plain C code (not in an ObjC method body).
See
NSAssertionHandler
for details.
When condition is false,
raise an exception saying that an invalid parameter
was supplied to the method.
Returns the exception handler called when an
exception is generated and not caught by the
programmer (by enclosing in NS_DURING
and NS_HANDLER
... NS_ENDHANDLER
). The default prints an error message and exits the
program. You can change this behavior by calling
NSSetUncaughtExceptionHandler()
.
Used in an ObjC method body.
See
NSAssertionHandler
for details.
When condition is false,
raise an exception saying that an invalid parameter
was supplied to the method.
Sets the exception handler called when an exception is
generated and not caught by the programmer (by
enclosing in NS_DURING
and
NS_HANDLER
... NS_ENDHANDLER
). The default prints an error message and exits the
program. proc should take a single
argument of type NSException *
.
Creates and returns an autoreleased invocation
containing a message to an instance of
the class. The 'message' consists of selector
and arguments like a standard ObjectiveC method call.
Before using the returned invocation, you need
to set its target.
Creates and returns an autoreleased invocation containing a message to the target object. The 'message' consists of selector and arguments like a standard ObjectiveC method call.
Returns IDENT which will be initialized to
an instance of a CLASSNAME in a thread safe
manner. If IDENT has been previoulsy
initilized this macro merely returns
IDENT. IDENT is considered
uninitialzed, if it contains nil
.
CLASSNAME must be either NSLock,
NSRecursiveLock or one of thier subclasses.
See
[NSLock +newLockAt:]
for details. This macro is intended for code that cannot
insure that a lock can be initialized in thread safe
manner otherwise.
NSLock *my_lock = nil; void function (void) { [GS_INITIALIZED_LOCK(my_lock, NSLock) lock]; do_work (); [my_lock unlock]; }
ASSIGN(object,value) assigns the value to the object with appropriate retain and release operations.
ASSIGNCOPY(object,value) assigns a copy of the value to the object with release of the original.
Basic autorelease operation... calls [NSObject -autorelease]
Declares an autorelease pool variable and creates and initialises an autorelease pool object.
DESTROY()
is a release operation which also sets the variable to be
a nil
pointer for tidyness - we can't
accidentally use a DESTROYED object
later. It also makes sure to set the variable to
nil
before releasing the
object - to avoid side-effects of the
release trying to reference the object
being released through the variable.
Similar, but allows reuse of variables. Be sure to
use DESTROY()
so
the object variable stays nil
.
Basic release operation... calls [NSObject -release]
Basic retain operation... calls [NSObject -retain]
Tested autorelease - only invoke the objective-c
method if the receiver is not nil
.
Tested release - only invoke the objective-c method if
the receiver is not nil
.
Tested retain - only invoke the objective-c method if
the receiver is not nil
.
Checks whether INDEX is strictly less than OVER (within C array space).
To be used inside a method for making sure that a range does not specify anything outside the size of an array/string. Raises exception if range extends beyond [0,size).
Convert a time interval since the reference date into
broken out elements.
External - so NSDate and
others can use it.
Convert a broken out time specification into a time
interval since the reference date.
External -
so NSDate and others can use it.
Activates or deactivates object allocation
debugging. Returns previous state.
This
function activates or deactivates object allocation
debugging.
Returns the previous state.
You should call this function to activate
allocation debugging before using any of the other
allocation debugging functions such as
GSDebugAllocationList()
or
GSDebugAllocationTotal()
.
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.
Starts recording all allocated objects of a certain
class.
Use with extreme care... this could slow
down your application enormously.
This function
activates tracking all allocated instances of the
specified class c.
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 similar, 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.
Used internally by NSAllocateObject() ... you probably don't need this.
Returns a NULL terminated array listing all the
classes for which statistical information has been
collected.
This function 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()
.
Returns the number of instances of the specified
class which are currently allocated.
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.
Returns a newline separated list of the classes which
have instances allocated, and the instance counts. If
'changeFlag' is YES
then the list
gives the number of instances allocated/deallocated
since the function was last called.
This
function 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.
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.
This function 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.
Returns an array containing all the allocated objects
of a certain class which have been recorded. Presumably,
you will immediately call
[NSObject -description]
on them to find out the objects you are leaking. Warning -
the objects are put in an array, so until the array is
autoreleased, the objects are not released.
This function returns an array containing all
the allocated objects of a certain class which have been
recorded... to start the recording, you need to
invoke
GSDebugAllocationActiveRecordingObjects()
. Presumably, you will immediately call [NSObject -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.
Returns the peak number of instances of the specified
class which have been concurrently allocated.
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.
Used internally by NSDeallocateObject() ... you probably don't need this.
This function associates the supplied tag
with a recorded object and returns the
tag which was previously associated with it
(if any).
If the object was not
recorded, the method returns nil
The tag is retained while it is
associated with the object.
See
also the
NSDebugFRLog()
and
NSDebugMRLog()
macros.
This function associates the supplied
tag with a recorded object and
returns the tag which was previously
associated with it (if any).
If the
object was not recorded, the method returns
nil
The tag is retained
while it is associated with the object.
Returns the total number of instances of the
specified class which have been allocated.
Returns the total number of instances of the
specified class c 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.
Used to produce a format string for logging a message with function location details.
Used to produce a format string for logging a message with method location details.
This functions allows to set own function backcalls for debugging allocation of objects. Useful if you intend to write your own objectalloc.
Retrieve stack information. Use caution: uses built-in gcc functions and currently only works up to 100 frames.
Retrieve stack information. Use caution: uses built-in gcc functions and currently only works up to 100 frames.
Retrieve stack information. Use caution: uses built-in gcc functions and currently only works up to 100 frames.
Adds two decimals and returns result to 38-digit precision. See the <NSDecimalNumberBehaviors> protocol for a description of mode and the return value. The result should be preallocated but can be the same as left or right.
Tries to reduce memory used to store number internally.
Returns NSOrderedDescending
,
NSOrderedSame
, or
NSOrderedAscending
depending on whether
leftOperand is greater than, equal to, or
less than rightOperand.
Copies value of decimal number to preallocated destination.
Divides l by rr and returns result to 38-digit precision. See the <NSDecimalNumberBehaviors> protocol for a description of mode and the return value. The result should be preallocated but can be the same as l or rr.
Give back the value of a NSDecimal as a double in (preallocated) result.
Create a NSDecimal with a mantissa, exponent and a negative flag in (preallocated) result.
Create a NSDecimal from a string using the locale, in (preallocated) result.
Returns whether decimal represents an invalid number (i.e., an "NaN" as might result from an overflow or a division by zero).
Give back the biggest NSDecimal in (preallocated) result.
Give back the smallest NSDecimal in (preallocated) result.
Multiplies two decimals and returns result to 38-digit precision. See the <NSDecimalNumberBehaviors> protocol for a description of mode and the return value. The result should be preallocated but can be the same as l or r.
Multiplies n by 10^power and returns result to 38-digit precision. See the <NSDecimalNumberBehaviors> protocol for a description of mode and the return value. The result should be preallocated but can be the same as n.
Sets the exponents of n1 and n2 equal to one another, adjusting mantissas as necessary to preserve values. This makes certain operations quicker.
Raises n to power and returns result to 38-digit precision. See the <NSDecimalNumberBehaviors> protocol for a description of mode and the return value. The result should be preallocated but can be the same as n or power.
Rounds number to result such that it has at most scale digits to the right of its decimal point, according to mode (see the <NSDecimalNumberBehaviors> protocol). The result should be preallocated but can be the same as number.
Returns a string representing the full
decimal value, formatted according to
locale (send nil
here for
default locale).
Subtracts two decimals and returns result to 38-digit precision. See the <NSDecimalNumberBehaviors> protocol for a description of mode and the return value. The result should be preallocated but can be the same as left or right.
This is the type of the exception handler called when an exception is generated and not caught by the programmer. See NSGetUncaughtExceptionHandler() , NSSetUncaughtExceptionHandler() .
Private support routine. Do not call directly.
Private support routine. Do not call directly.
Returns 'YES' iff aRect totally encloses bRect. NOTE: For this to be the case, aRect cannot be empty, nor can any side of bRect go beyond any side of aRect . Note that this behavior is different than the original OpenStep behavior, where the sides of bRect could not touch aRect.
Divides aRect into two rectangles (namely slice and remainder) by "cutting" aRect---parallel to, and a distance amount from the given edge of aRect. You may pass 0 in as either of slice or remainder to avoid obtaining either of the created rectangles.
Returns 'YES' iff aPoint's and bPoint's x- and y-coordinates are the same.
Returns 'YES' iff aRect's and bRect's origin and size are the same.
Returns 'YES' iff aSize's and bSize's width and height are the same.
Returns aRect's height.
Returns the rectangle obtained by moving each of aRect's horizontal sides inward by dy and each of aRect's vertical sides inward by dx.
Returns a rectangle obtained by expanding aRect minimally so that all four of its defining components are integers.
Returns the largest rectangle which lies in both aRect and bRect. If aRect and bRect have empty intersection (or, rather, intersection of measure zero, since this includes having their intersection be only a point or a line), then the empty rectangle is returned.
Returns YES
if aRect and
bRect have non-zero intersection area
(intersecting at a line or a point doesn't
count).
Returns 'YES' iff the area of aRect is zero (i.e., iff either of aRect's width or height is negative or zero).
Returns an NSPoint having x-coordinate X and y-coordinate Y.
Returns an NSRect having point of origin ( x, y) and size {w, h}.
Returns an NSSize having width w and height h.
Returns the greatest x-coordinate value still inside aRect.
Returns the greatest y-coordinate value still inside aRect.
Returns the x-coordinate of aRect's middle point.
Returns the y-coordinate of aRect's middle point.
Returns the least x-coordinate value still inside aRect.
Returns the least y-coordinate value still inside aRect.
Returns 'YES' iff aPoint is inside aRect.
Returns the rectangle obtained by translating aRect horizontally by dx and vertically by dy.
Parses point from string of form "
{x=a; y=b}
". (0,0) returned if parsing
fails.
Just like 'NSMouseInRect(aPoint,
aRect, YES
)'.
Parses point from string of form "
{x=a; y=b; width=c; height=d}
".
Rectangle of 0 size at origin returned if parsing
fails.
Parses size from string of form "
{width=a; height=b}
". Size of 0,0
returned if parsing fails.
Returns an NSString of the form "{x=X; y=Y}", where X
and Y are the x- and y-coordinates of aPoint,
respectively.
Get a String
Representation...
Returns an NSString of the form "{x=X; y=Y; width=W; height=H}", where X, Y, W, and H are the x-coordinate, y-coordinate, width, and height of aRect, respectively.
Returns an NSString of the form "{width=W; height=H}", where W and H are the width and height of aSize, respectively.
Returns the smallest rectangle which contains both aRect and bRect (modulo a set of measure zero). If either of aRect or bRect is an empty rectangle, then the other rectangle is returned. If both are empty, then the empty rectangle is returned.
Returns aRect's width.
Returns an array of all the objects in the table. NB. The table must contain objects, not pointers or integers.
Compares the two hash tables for equality. If the
tables are different sizes, returns NO
.
Otherwise, compares the values in the two tables
and returns NO
if they differ.
The
GNUstep implementation enumerates the values in
table1 and uses the hash and isEqual
functions of table2 for comparison.
Copy the supplied map table creating the new table in the specified zone.
Returns the number of objects in the table .
Create a new hash table by calling
NSCreateHashTableWithZone()
using
NSDefaultMallocZone()
. callbacks provides five helper functions used by the main
implementation. See the NSHashTableCallbacks
documentation for more information.
If
capacity is small or 0, then the returned
table has a reasonable (but still small)
capacity.
Create a new hash table using the supplied callbacks structure. If any functions in the callback structure is null the default values are used... as for non-owned pointers. The table will be created with the specified capacity... ie ready to hold at lest that many items.
Function to be called when finished with the enumerator. This permits memory used by the enumerator to be released.
Return an enumerator for stepping through a map table using the NSNextHashEnumeratorItem() function.
Releases all the keys and values of table (using the callbacks specified at the time of table's creation), and then proceeds to deallocate the space allocated for table itself.
Returns the value for the specified element, or a null pointer if the element is not found in the table .
Adds the element to table.
If an equal element is already in
table, replaces it with the new one.
If element is null raises an
NSInvalidArgumentException.
Adds the element to table and
returns nul.
If an equal element is
already in table, returns the old
element instead of adding the new one.
If element is nul, raises an
NSInvalidArgumentException.
Adds the element to table and
returns nul.
If an equal element is
already present, raises NSInvalidArgumentException.
If element is null raises an
NSInvalidArgumentException.
Remove the specified element from the table.
Step through the hash table... return the next item or return nulif we hit the of the table.
Empty the hash table (releasing all elements), but preserve its capacity.
Returns a string describing the table
contents.
For each item, a string of the
form "value;\n" is appended. The appropriate describe
function is used to generate the strings for each
item.
Returns an array of all the keys in the table. NB. The table must contain objects for its keys.
Returns an array of all the values in the table. NB. The table must contain objects for its values.
Compares the two map tables for equality. If the
tables are different sizes, returns NO
.
Otherwise, compares the keys
(not the values) in the two map tables and
returns NO
if they differ.
The
GNUstep implementation enumerates the keys in
table1 and uses the hash and isEqual
functions of table2 for comparison.
Copy the supplied map table.
Returns a
map table, space for which is allocated in
zone, which has (newly retained) copies of
table's keys and values. As always, if
zone is 0, then
NSDefaultMallocZone()
is used.
Returns the number of key/value pairs in the table.
Create a new map table by calling
NSCreateMapTableWithZone()
using
NSDefaultMallocZone()
.
Returns a (pointer to) an NSMapTable space for
which is allocated in the default zone. If
capacity is small or 0, then the returned
table has a reasonable capacity.
Create a new map table using the supplied callbacks
structures. If any functions in the callback
structures are null the default values are used...
as for non-owned pointers.
Of course, if you send 0
for zone, then the map table will be created
in
NSDefaultMallocZone()
.
The table will be created with the specified
capacity... ie ready to hold at least that
many items.
Function to be called when finished with the enumerator. This permits memory used by the enumerator to be released!
Return an enumerator for stepping through a map table using the NSNextMapEnumeratorPair() function.
Destroy the map table and relase its
contents.
Releases all the keys and values
of table (using the key and value callbacks
specified at the time of table's creation), and
then proceeds to deallocate the space allocated for
table itself.
Returns the value for the specified key, or a null pointer if the key is not found in the table.
Adds the key and value to
table.
If an equal key is
already in table, replaces its mapped
value with the new one, without changing the
key itself.
If key is
equal to the notAKeyMarker field of the table's
NSMapTableKeyCallBacks, raises an
NSInvalidArgumentException.
Adds the key and value to
table and returns nul.
If an equal
key is already in table, returns
the old key instead of adding the new
key-value pair.
If key is equal
to the notAKeyMarker field of the table's
NSMapTableKeyCallBacks, raises an
NSInvalidArgumentException.
Adds the key and value to
table and returns nul.
If an equal
key is already in table, raises
an NSInvalidArgumentException.
If key is
equal to the notAKeyMarker field of the table's
NSMapTableKeyCallBacks, raises an
NSInvalidArgumentException.
Returns a flag to say whether the table
contains the specified key. Returns the
original key and the value it
maps to.
The GNUstep implementation checks
originalKey and value to see if
they are null pointers, and only updates them if
non-null.
Remove the specified key from the
table (if present).
Causes the
key and its associated value to be released.
Step through the map table... return the next key-value
pair and return YES
, or hit the end of the
table and return NO
.
The
enumerator parameter is a value
supplied by
NSEnumerateMapTable()
and must be destroyed using
NSEndMapTableEnumeration()
.
The GNUstep implementation permits either
key or value to be a null
pointer, and refrains from attempting to return the
appropriate result in that case.
Empty the map table (releasing every key and value), but preserve its capacity.
Returns a string describing the table
contents.
For each key-value pair, a string
of the form "key = value;\n" is appended. The appropriate
describe functions are used to generate the strings
for each key and value.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Returns the lock used to protect the GNUstep NSLogv() implementation. Use this to protect changes to _NSLogDescriptor and _NSLog_printf_handler
Returns the class whose name is supplied in the
aClassName argument, or 0 if a
nil
string is supplied.
When provided with a C string containing encoded type
information, this method extracts size and
alignment information for the specified type into
the buffers pointed to by sizep and
alignp.
If either sizep or
alignp is a nil
pointer, the
corresponding data is not extracted.
The
function returns a pointer to the type information C
string.
Provides the standard OpenStep logging facility. For details see the lower level NSLogv() function (which this function uses).
GNUstep provides powerful alternatives for logging ... see NSDebugLog() , NSWarnLog() and GSPrintf() for example. We recommend the use of NSDebugLog() and its relatives for debug purposes, and GSPrintf() for general log messages, with NSLog() being reserved for reporting possible/likely errors. GSPrintf() is declared in GSObjCRuntime.h.
OpenStep spec states that log messages go to stderr, but just in case someone wants them to go somewhere else, they can implement a function like this.
The core logging function...
The function generates a standard log entry by prepending process ID and date/time information to your message, and ensuring that a newline is present at the end of the message.
In GNUstep, the GSLogThread user default may be set to
YES
in order to instruct this function
to include the internal ID of the mcurrent thread after
the process ID. This can help you to track the behavior
of a multi-threaded program.
The resulting message is then passed to a handler function to perform actual output. Locking is performed around the call to the function actually writing the message out, to ensure that logging is thread-safe. However, the actual creation of the message written is only as safe as the [NSObject -description] methods of the arguments you supply.
The function to write the data is pointed to by _NSLog_printf_handler
Returns a selector for the method whose name is
supplied in the aSelectorName argument,
or 0 if a nil
string is supplied.
Returns an
NSString
object containing the class name for
aClass. If aClass is 0, returns
nil
.
Returns a string object containing the method name
for aSelector. If aSelector is 0,
returns nil
.
Used to allocate memory to hold an object, and
initialise the class of the object to be
aClass etc. The allocated memory will be
extraBytes larger than the space actually
needed to hold the instance variables of the object.
This function is used by the
[NSObject +allocWithZone:]
mnethod.
Used to copy anObject. This makes a bitwise
copy of anObject to memory allocated from
zone. The allocated memory will be
extraBytes longer than that necessary to
actually store the instance variables of the copied
object.
This is used by the NSObject
implementation of the
[<NSCopying>-copyWithZone:]
method.
Used to release the memory used by an object.
This function is used by the
[NSObject -dealloc]
mnethod.
Examines the extra reference count for the object
and, if non-zero decrements it, otherwise leaves it
unchanged.
Returns a flag to say whether
the count was zero (and hence whether the extra refrence
count was decremented).
This function is used by
the
[NSObject -release]
method.
Return the extra reference count of
anObject (a value in the range from 0 to the
maximum unsigned integer value minus one).
The
retain count for an object is this value plus one.
Increments the extra reference count for
anObject.
The GNUstep version raises
an exception if the reference count would be incremented
to too large a value.
This is used by the
[NSObject -retain]
method.
Returns a flag to indicate whether
anObject should be retained or copied in
order to make a copy in the specified zone.
Basically, this tests to see if
anObject was allocated from
requestedZone and returns YES
if it was.
Return the path of the defaults directory for name.
This examines the.GNUsteprc file in the home
directory of the user for the GNUSTEP_DEFAULTS_ROOT
or the GNUSTEP_USER_ROOT directory definitions.
This extension permits a change of username from that
specified in the LOGNAME environment variable.
Using it will almost certainly cause trouble if the
process does not posess the file access priviliges of
the new name. This is provided primarily for
use by processes that run as system-manager and need to
act as particular users. If uses the [NSUserDefaults
+resetUserDefaults] extension to reset
the defaults system to use the defaults belonging to the
new user.
Sets the user name for this
process. This method is supplied to enable setuid
programs to run properly as the user indicated by
their effective user Id.
This function calls
[NSUserDefaults +resetStandardUserDefaults]
as well as changing the value returned by NSUserName()
and modifying the user root directory for the process.
Returns an array of strings which contain paths that should be in the standard search order for resources, etc. If the environment variable GNUSTEP_PATHPREFIX_LIST is set. It returns the list of paths set in that variable. Otherwise, it returns the user, local, network, and system paths, in that order. This function is guarenteed to return a non-nil answer (unless something is seriously wrong, in which case the application will probably crash anyway)
Returns a string containing the path to the GNUstep system installation directory. This function is guarenteed to return a non-nil answer (unless something is seriously wrong, in which case the application will probably crash anyway)
Returns the full username of the current user. If unable to determine this, returns the standard user name.
Return the caller's home directory as an NSString object. Calls NSHomeDirectoryForUser() to do this.
Returns loginName's home directory as an NSString object.
Returns the root directory for the OpenStep (GNUstep) installation. This is determined by the GNUSTEP_ROOT environment variable if available.
Returns an array of search paths to look at for resources.
Returns the standard paths in which applications are stored and should be searched for. Calls NSSearchPathForDirectoriesInDomains()
Returns the standard paths in which libraries are stored and should be searched for. Calls NSSearchPathForDirectoriesInDomains()
Returns the name of a directory in which temporary
files can be stored. Under GNUstep this is a location
which is not readable by other users.
If a
suitable directory can't be found or created, this
function raises an NSGenericException.
Return the caller's login name as an NSString object.
Under ms-windows, the 'LOGNAME' environment
variable is used as the user name.
Under
unix-like systems, the name associated with the
current effective user ID is used.
Function for rapid testing to see if a debug
level is set.
This is used by the
debugging macros.
If debug logging has been
turned off, this returns NO
even if the
specified level exists in the set of
debug levels.
Returns whether range1 and range2 have same location and length.
Returns range containing indices existing in both aRange and bRange. If the returned length is 0, the location is undefined and should be ignored.
Returns whether location is greater than or equal to range's location and less than its max.
Creates new range starting at location and of given length.
Returns top end of range (location + length).
Parses range from string of form {location=a, length=b}; returns range with 0 location and length if this fails.
Returns string of form {location=a, length=b}.
Returns range going from minimum of aRange's and bRange's locations to maximum of their two max's.
Convenience method for raising an NSRangeException.
This function purges the global NSCountedSet object used for uniquing. It handles locking as necessary. It can be used to purge the set even when uniquing is turned off.
This function sets the count for the specified object. If the count for the object is set to zero then the object is removed from the global uniquing set. The object is added to the set if necessary. The object returned is the one stored in the set. The function handles locking as necessary. It can be used to alter the set even when uniquing is turned off.
This function uniques the supplied argument, returning the result. It works by using the [-unique:] method of a global NSCountedSet object. It handles locking as necessary. If uniquing is turned off, it simply returns its argument.
This function sets the state of a flag that determines the behavior of the GSUnique() function. If the flag is on, uniquing is performed, if it is off the function has no effect. The default is for uniquing to be turned off.
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).
Fast access function for thread dictionary of current thread.
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.
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.
Internal method for caching.
Internal method: get cached values for integers in the range - GS_SMALL to + GS_SMALL
Returns the default zone used for atomic memory allocation (see NSMallocAtomic()), if no zone is specified.
Try to get more memory - the normal process has failed. If we can't do anything, just return a null pointer. Try to do some logging if possible.
Allocate memory for this process and return a pointer to it (or a null pointer on failure).
Perform an efficient large scale copy of data from src to dest. The value bytes specifies the length of the data copied.
Creates a new zone of start bytes, which will grow and shrink by granularity bytes. If canFree is 0, memory in zone is allocated but never freed, meaning allocation will be very fast. The whole zone can still be freed with NSRecycleZone() , and you should still call NSZoneFree on memory in the zone that is no longer needed, since a count of allocated pointers is kept and must reach zero before freeing the zone.
Deallocate memory which was previously allocated using the NSAllocateMemoryPages() function.
Returns the default zone used for memory allocation, created at startup. This zone cannot be recycled.
Return log base 2 of the number of bytes in a memory page.
Return the number of bytes in a memory page.
Return the number of bytes of real (physical) memory available.
Return memory for an entire zone to system. In fact, this will not be done unless all memory in the zone has been explicitly freed (by calls to ZNSZoneFree()). For "non-freeable" zones, the number of NSZoneFree() calls must simply equal the number of allocation calls. The default zone, on the other hand, cannot be recycled.
Round bytes down to the nearest multiple of the memory page size, and return it.
Round bytes up to the nearest multiple of the memory page size, and return it.
Sets name of the given zone (useful for debugging and logging).
Allocates and returns cleared memory for
elems items of size bytes, in the
given zone. Returns NULL if allocation of
size 0 requested. Raises NSMallocException
if not enough free memory in zone to allocate
and no more can be obtained from system, unless using the
default zone, in which case NULL is
returned.
Allocates and returns cleared
memory for elems items of size
bytes, in the given zone. Returns
NULL if allocation of size 0 requested. Raises
NSMallocException
if not enough free
memory in zone to allocate and no more can
be obtained from system.
Checks integrity of a zone. Not defined by OpenStep or OS X.
Frees memory pointed to by ptr (which should have been allocated by a previous call to NSZoneMalloc() , NSZoneCalloc() , or NSZoneRealloc()) and returns it to zone. Note, if this is a nonfreeable zone, the memory is not actually freed, but the count of number of free()s is updated.
Searches and finds the zone ptr was allocated from. The speed depends upon the number of zones and their size.
Allocates and returns cleared memory for elems
items of size bytes, in the given
zone. Returns NULL if allocation of
size 0 requested. Raises
NSMallocException
if not enough free
memory in zone to allocate and no more can
be obtained from system, unless using the default
zone, in which case NULL is returned.
Allocates memory of size bytes from zone, with the assumption that the memory will never contain pointers. This is only relevant in situations where a form of garbage collection is enabled, and NSZoneMalloc() should always be used otherwise. Not defined by OpenStep or OS X.
Returns the name assigned to the zone, if
one has been given (see NSSetZoneName()), otherwise
nil
. Useful for debugging/logging.
Reallocates the chunk of memory in
zone pointed to by ptr to a new
one of size bytes. Existing contents in
ptr are copied over. Raises an
NSMallocException
if insufficient memory
is available in the zone and no more memory can
be obtained from the system, unless using the default
zone, in which case NULL is returned.
Obtain statistics about the zone. Implementation emphasis is on correctness, not speed. Not defined by OpenStep or OS X.