Up
Authors
- Richard Frith-Macdonald
-
Copyright: (C) 2005 Free Software Foundation, Inc.
GSLocalizedString(key, comment)
Warning - do not use this.
GSLocalizedStringFromTable(key, tbl, comment)
Warning - do not use this.
NSLocalizedStaticString(key, 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.
NSLocalizedString(key, 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 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).
NSLocalizedStringFromTable(key, tbl, 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.
NSLocalizedStringFromTableInBundle(key, tbl, bundle, 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.
_(X)
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.
__(X)
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.
GSOnceFLog(format, args,...)
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");
GSOnceMLog(format, args,...)
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");
NSDebugFLLog(level, format, args,...)
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.
NSDebugFLog(format, args,...)
This macro is a shorthand for
NSDebugFLLog()
using then default debug level... 'dflt'
NSDebugFRLog(object, msg)
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(level, format, args,...)
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.
NSDebugLog(format, args,...)
This macro is a shorthand for
NSDebugLLog()
using then default debug level... 'dflt'
NSDebugMLLog(level, format, args,...)
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.
NSDebugMLog(format, args,...)
This macro is a shorthand for
NSDebugMLLog()
using then default debug level... 'dflt'
NSDebugMRLog(object, msg)
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.
NSWarnFLog(format, args,...)
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(format, args,...)
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.
NSWarnMLog(format, args,...)
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.
NSDecimalMaxSize
Give a precision of at least 38 decimal digits requires 128 bits.
NSAssert(condition, desc)
Used in an ObjC method body.
See
NSAssertionHandler
for details.
When
condition is false, raise an exception using
desc
NSAssert1(condition, desc, arg1)
Used in an ObjC method body.
See
NSAssertionHandler
for details.
When
condition is false, raise an exception using
desc and
arg1
NSAssert2(condition, desc, arg1, arg2)
Used in an ObjC method body.
See
NSAssertionHandler
for details.
When
condition is false, raise an exception using
desc and
arg1,
arg2
NSAssert3(condition, desc, 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
NSAssert4(condition, desc, 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
NSAssert5(condition, desc, arg1, arg2, arg3, arg4, arg5)
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
NSCAssert(condition, 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
NSCAssert1(condition, desc, 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
NSCAssert2(condition, desc, 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
NSCAssert3(condition, desc, 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
NSCAssert4(condition, desc, 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
NSCAssert5(condition, desc, 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 and
arg1,
arg2,
arg3,
arg4,
arg5
NSCParameterAssert(condition)
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.
NSGetUncaughtExceptionHandler
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()
.
NSParameterAssert(condition)
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.
NSSetUncaughtExceptionHandler(proc)
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 *
.
NB. If the exception handler set by this function does not terminate the process, the process will be terminateed anyway. This is a safety precaution to ensure that, in the event of an exception ebing raised and not handled, the program does not try to continue running in a confused state (possibly doing horrible things like billing customers who shouldn't be billed etc), but shuts down as cleanly as possible.
Process termination is normally accomplished by calling the standard exit function of theC runtime library, but if the environment variable CRASH_ON_ABORT is set to YES
or TRUE or 1 the termination will be accomplished by calling the abort function instead, which should cause a core dump to be made for debugging.
NS_INVOCATION(aClass, message,...)
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.
NS_MESSAGE(target, message,...)
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.
GS_INITIALIZED_LOCK(IDENT, CLASSNAME)
Returns
IDENT which will be initialized to an instance of a
CLASSNAME in a thread safe manner. If
IDENT has been previously initialized this macro merely returns
IDENT.
IDENT is considered uninitialized, if it contains
nil
.
CLASSNAME must be either NSLock, NSRecursiveLock or one of their 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)
ASSIGN(object,value) assigns the value to the object with appropriate retain and release operations.
ASSIGNCOPY(object, value)
ASSIGNCOPY(object,value) assigns a copy of the value to the object with release of the original.
AUTORELEASE(object)
CREATE_AUTORELEASE_POOL(X)
Declares an autorelease pool variable and creates and initialises an autorelease pool object.
DESTROY(object)
DESTROY()
is a release operation which also sets the variable to be a
nil
pointer for tidiness - 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.
GS_API_LATEST
A constant to represent a feature which is still present in the latest version. This is the highest possible version number.
eg.
#if
OS_API_VERSION
(GS_API_MACOSX, GS_API_LATEST)
denotes code present from the initial MacOS-X version onwards.
GS_API_MACOSX
The version number of the first MacOS-X implementation.
eg.
#if
OS_API_VERSION
(GS_API_MACOSX, GS_API_LATEST)
denotes code present from the initial MacOS-X version onwards.
GS_API_NONE
A constant to represent a feature which is not present in any version. Use this to say a feature is not present in an API.
eg.
#if
OS_API_VERSION
(GS_API_NONE, GS_API_NONE)
denotes code not present in OpenStep/OPENSTEP/MacOS-X
GS_API_OPENSTEP
The version number of the first OPENSTEP implementation.
eg.
#if
OS_API_VERSION
(GS_API_OPENSTEP, GS_API_LATEST)
denotes code present from the initial OPENSTEP version onwards.
GS_API_OSSPEC
The version number of the initial OpenStep specification.
eg.
#if
OS_API_VERSION
(GS_API_OSSPEC, GS_API_LATEST)
denotes code present from the OpenStep specification onwards.
GS_API_VERSION(ADD, REM)
Macro to check a defined GNUstep version number (GS_GNUSTEP_V) against the supplied arguments. Returns true if no GNUstep version is specified, or if ADD <= version < REM, where ADD is the version number at which a feature guarded by the macro was introduced and REM is the version number at which it was removed.
The version number arguments are six digit integers where the first two digits are the major version number, the second two are the minor version number and the last two are the subminor number (all left padded with a zero where necessary). However, for convenience you can also use any of several predefined constants... GS_API_NONE
, GS_API_LATEST
, GS_API_OSSPEC
, GS_API_OPENSTEP
, GS_API_MACOSX
Also see OS_API_VERSION
NB. If you are changing the API (eg adding a new feature) you need to control the visibility io the new header file code using
#if GS_API_VERSION(ADD,GS_API_LATEST)
where ADD
is the version number of the next minor release after the most recent one.
As a general principle you should not change the API with changing subminor version numbers... as that tends to confuse people (though Apple has sometimes done it).
OS_API_VERSION(ADD, REM)
Macro to check a defined OpenStep/OPENSTEP/MacOS-X version against the supplied arguments. Returns true if no version is specified, or if ADD <= version < REM, where ADD is the version number at which a feature guarded by the macro was introduced and REM is the version number at which it was removed.
The version number arguments are six digit integers where the first two digits are the major version number, the second two are the minor version number and the last two are the subminor number (all left padded with a zero where necessary). However, for convenience you can also use any of several predefined constants... GS_API_NONE
, GS_API_LATEST
, GS_API_OSSPEC
, GS_API_OPENSTEP
, GS_API_MACOSX
Also see GS_API_VERSION
RECREATE_AUTORELEASE_POOL(X)
Similar, but allows reuse of variables. Be sure to use
DESTROY()
so the object variable stays
nil
.
RELEASE(object)
RETAIN(object)
TEST_AUTORELEASE(object)
Tested autorelease - only invoke the objective-c method if the receiver is not nil
.
TEST_RELEASE(object)
Tested release - only invoke the objective-c method if the receiver is not nil
.
TEST_RETAIN(object)
Tested retain - only invoke the objective-c method if the receiver is not nil
.
CHECK_INDEX_RANGE_ERROR(INDEX, OVER)
Checks whether INDEX is strictly less than OVER (within C array space).
GS_RANGE_CHECK(RANGE, SIZE)
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).
BOOL GSDebugAllocationActive(BOOL active);
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.
void GSDebugAllocationActiveRecordingObjects(Class c);
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.
void GSDebugAllocationAdd(Class c, id o);
Class* GSDebugAllocationClassList();
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()
.
int GSDebugAllocationCount(Class c);
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.
const char* GSDebugAllocationList(BOOL changeFlag);
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.
const char* GSDebugAllocationListAll();
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.
NSArray* GSDebugAllocationListRecordedObjects(Class c);
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.
int GSDebugAllocationPeak(Class c);
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.
void GSDebugAllocationRemove(Class c, id o);
id GSDebugAllocationTagRecordedObject(id object, id tag);
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.
int GSDebugAllocationTotal(Class c);
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.
NSString* GSDebugFunctionMsg(const char* func, const char* file, int line, NSString* fmt);
Used to produce a format string for logging a message with function location details.
NSString* GSDebugMethodMsg(id obj, SEL sel, const char* file, int line, NSString* fmt);
Used to produce a format string for logging a message with method location details.
void GSSetDebugAllocationFunctions(void(*) newAddObjectFunc, void(*) newRemoveObjectFunc);
This functions allows to set own function callbacks for debugging allocation of objects. Useful if you intend to write your own object allocation code.
unsigned int NSCountFrames();
Retrieve stack information. Use caution: uses built-in gcc functions and currently only works up to 100 frames.
void* NSFrameAddress(int offset);
Retrieve stack information. Use caution: uses built-in gcc functions and currently only works up to 100 frames.
void* NSReturnAddress(int offset);
Retrieve stack information. Use caution: uses built-in gcc functions and currently only works up to 100 frames.
NSCalculationError NSDecimalAdd(NSDecimal* result, const NSDecimal* left, const NSDecimal* right, NSRoundingMode mode);
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.
void NSDecimalCompact(NSDecimal* number);
Tries to reduce memory used to store number internally.
NSComparisonResult NSDecimalCompare(const NSDecimal* leftOperand, const NSDecimal* rightOperand);
Returns NSOrderedDescending
, NSOrderedSame
, or NSOrderedAscending
depending on whether leftOperand is greater than, equal to, or less than rightOperand.
void NSDecimalCopy(NSDecimal* destination, const NSDecimal* source);
Copies value of decimal number to preallocated destination.
NSCalculationError NSDecimalDivide(NSDecimal* result, const NSDecimal* l, const NSDecimal* rr, NSRoundingMode mode);
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.
double NSDecimalDouble(NSDecimal* number);
Give back the value of a NSDecimal as a double in (preallocated) result.
void NSDecimalFromComponents(NSDecimal* result, unsigned long long int mantissa, short int exponent, BOOL negative);
Create a NSDecimal with a mantissa, exponent and a negative flag in (preallocated) result.
void NSDecimalFromString(NSDecimal* result, NSString* numberValue, NSDictionary* locale);
Create a NSDecimal from a string using the locale, in (preallocated) result.
BOOL NSDecimalIsNotANumber(const NSDecimal* decimal);
Returns whether decimal represents an invalid number (i.e., an "NaN" as might result from an overflow or a division by zero).
void NSDecimalMax(NSDecimal* result);
Give back the biggest NSDecimal in (preallocated) result.
void NSDecimalMin(NSDecimal* result);
Give back the smallest NSDecimal in (preallocated) result.
NSCalculationError NSDecimalMultiply(NSDecimal* result, const NSDecimal* l, const NSDecimal* r, NSRoundingMode mode);
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.
NSCalculationError NSDecimalMultiplyByPowerOf10(NSDecimal* result, const NSDecimal* n, short int power, NSRoundingMode mode);
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.
NSCalculationError NSDecimalNormalize(NSDecimal* n1, NSDecimal* n2, NSRoundingMode mode);
Sets the exponents of n1 and n2 equal to one another, adjusting mantissas as necessary to preserve values. This makes certain operations quicker.
NSCalculationError NSDecimalPower(NSDecimal* result, const NSDecimal* n, unsigned int power, NSRoundingMode mode);
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.
void NSDecimalRound(NSDecimal* result, const NSDecimal* number, int scale, NSRoundingMode mode);
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.
NSString* NSDecimalString(const NSDecimal* decimal, NSDictionary* locale);
Returns a string representing the full decimal value, formatted according to locale (send nil
here for default locale).
NSCalculationError NSDecimalSubtract(NSDecimal* result, const NSDecimal* left, const NSDecimal* right, NSRoundingMode mode);
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.
void NSUncaughtExceptionHandler(NSException* exception);
void _NSAddHandler(NSHandler* handler);
Private support routine. Do not call directly.
void _NSRemoveHandler(NSHandler* handler);
Private support routine. Do not call directly.
BOOL NSContainsRect(NSRect aRect, NSRect bRect);
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.
void NSDivideRect(NSRect aRect, NSRect* slice, NSRect* remainder, float amount, NSRectEdge edge);
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.
BOOL NSEqualPoints(NSPoint aPoint, NSPoint bPoint);
Returns 'YES' iff aPoint's and bPoint's x- and y-coordinates are the same.
BOOL NSEqualRects(NSRect aRect, NSRect bRect);
Returns 'YES' iff aRect's and bRect's origin and size are the same.
BOOL NSEqualSizes(NSSize aSize, NSSize bSize);
Returns 'YES' iff aSize's and bSize's width and height are the same.
float NSHeight(NSRect aRect);
Returns aRect's height.
NSRect NSInsetRect(NSRect aRect, float dX, float dY);
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.
NSRect NSIntegralRect(NSRect aRect);
Returns a rectangle obtained by expanding aRect minimally so that all four of its defining components are integers.
NSRect NSIntersectionRect(NSRect aRect, NSRect bRect);
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.
BOOL NSIntersectsRect(NSRect aRect, NSRect bRect);
Returns YES
if aRect and bRect have non-zero intersection area (intersecting at a line or a point doesn't count).
BOOL NSIsEmptyRect(NSRect aRect);
Returns 'YES' iff the area of aRect is zero (i.e., iff either of aRect's width or height is negative or zero).
NSPoint NSMakePoint(float x, float y);
Returns an NSPoint having x-coordinate X and y-coordinate Y.
NSRect NSMakeRect(float x, float y, float w, float h);
Returns an NSRect having point of origin ( x, y) and size {w, h}.
NSSize NSMakeSize(float w, float h);
Returns an NSSize having width w and height h.
float NSMaxX(NSRect aRect);
Returns the greatest x-coordinate value still inside aRect.
float NSMaxY(NSRect aRect);
Returns the greatest y-coordinate value still inside aRect.
float NSMidX(NSRect aRect);
Returns the x-coordinate of aRect's middle point.
float NSMidY(NSRect aRect);
Returns the y-coordinate of aRect's middle point.
float NSMinX(NSRect aRect);
Returns the least x-coordinate value still inside aRect.
float NSMinY(NSRect aRect);
Returns the least y-coordinate value still inside aRect.
BOOL NSMouseInRect(NSPoint aPoint, NSRect aRect, BOOL flipped);
Returns 'YES' iff aPoint is inside aRect.
NSRect NSOffsetRect(NSRect aRect, float dx, float dy);
Returns the rectangle obtained by translating aRect horizontally by dx and vertically by dy.
NSPoint NSPointFromString(NSString* string);
Parses point from string of form " {x=a; y=b}
". (0,0) returned if parsing fails.
BOOL NSPointInRect(NSPoint aPoint, NSRect aRect);
Just like 'NSMouseInRect(aPoint, aRect, YES
)'.
NSRect NSRectFromString(NSString* string);
Parses point from string of form " {x=a; y=b; width=c; height=d}
". Rectangle of 0 size at origin returned if parsing fails.
NSSize NSSizeFromString(NSString* string);
Parses size from string of form " {width=a; height=b}
". Size of 0,0 returned if parsing fails.
NSString* NSStringFromPoint(NSPoint aPoint);
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...
NSString* NSStringFromRect(NSRect aRect);
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.
NSString* NSStringFromSize(NSSize aSize);
Returns an NSString of the form "{width=W; height=H}", where W and H are the width and height of aSize, respectively.
NSRect NSUnionRect(NSRect aRect, NSRect bRect);
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.
float NSWidth(NSRect aRect);
Returns aRect's width.
NSArray* NSAllHashTableObjects(NSHashTable* table);
Returns an array of all the objects in the table. NB. The table must contain objects, not pointers or integers.
BOOL NSCompareHashTables(NSHashTable* table1, NSHashTable* table2);
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.
NSHashTable* NSCopyHashTableWithZone(NSHashTable* table, NSZone* zone);
Copy the supplied map table creating the new table in the specified zone.
unsigned int NSCountHashTable(NSHashTable* table);
Returns the number of objects in the table .
NSHashTable* NSCreateHashTable(NSHashTableCallBacks callBacks, unsigned int capacity);
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.
NSHashTable* NSCreateHashTableWithZone(NSHashTableCallBacks callBacks, unsigned int capacity, NSZone* zone);
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.
void NSEndHashTableEnumeration(NSHashEnumerator* enumerator);
Function to be called when finished with the enumerator. This permits memory used by the enumerator to be released.
NSHashEnumerator NSEnumerateHashTable(NSHashTable* table);
void NSFreeHashTable(NSHashTable* table);
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.
void* NSHashGet(NSHashTable* table, const void* element);
Returns the value for the specified element, or a null pointer if the element is not found in the table .
void NSHashInsert(NSHashTable* table, const void* element);
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.
void* NSHashInsertIfAbsent(NSHashTable* table, const void* element);
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.
void NSHashInsertKnownAbsent(NSHashTable* table, const void* element);
Adds the element to table and returns nul.
If an equal element is already present, raises NSInvalidArgumentException.
If element is null raises an NSInvalidArgumentException.
void NSHashRemove(NSHashTable* table, const void* element);
Remove the specified element from the table.
void* NSNextHashEnumeratorItem(NSHashEnumerator* enumerator);
Step through the hash table... return the next item or return nul if we hit the of the table.
void NSResetHashTable(NSHashTable* table);
Empty the hash table (releasing all elements), but preserve its capacity.
NSString* NSStringFromHashTable(NSHashTable* table);
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.
NSArray* NSAllMapTableKeys(NSMapTable* table);
Returns an array of all the keys in the table. NB. The table must contain objects for its keys.
NSArray* NSAllMapTableValues(NSMapTable* table);
Returns an array of all the values in the table. NB. The table must contain objects for its values.
BOOL NSCompareMapTables(NSMapTable* table1, NSMapTable* table2);
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.
NSMapTable* NSCopyMapTableWithZone(NSMapTable* table, NSZone* zone);
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.
unsigned int NSCountMapTable(NSMapTable* table);
Returns the number of key/value pairs in the table.
NSMapTable* NSCreateMapTable(NSMapTableKeyCallBacks keyCallBacks, NSMapTableValueCallBacks valueCallBacks, unsigned int capacity);
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.
NSMapTable* NSCreateMapTableWithZone(NSMapTableKeyCallBacks keyCallBacks, NSMapTableValueCallBacks valueCallBacks, unsigned int capacity, NSZone* zone);
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.
void NSEndMapTableEnumeration(NSMapEnumerator* enumerator);
Function to be called when finished with the enumerator. This permits memory used by the enumerator to be released!
NSMapEnumerator NSEnumerateMapTable(NSMapTable* table);
void NSFreeMapTable(NSMapTable* table);
Destroy the map table and release 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.
void* NSMapGet(NSMapTable* table, const void* key);
Returns the value for the specified key, or a null pointer if the key is not found in the table.
void NSMapInsert(NSMapTable* table, const void* key, const void* value);
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.
void* NSMapInsertIfAbsent(NSMapTable* table, const void* key, const void* value);
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.
void NSMapInsertKnownAbsent(NSMapTable* table, const void* key, const void* value);
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.
BOOL NSMapMember(NSMapTable* table, const void* key, void** originalKey, void** value);
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.
void NSMapRemove(NSMapTable* table, const void* key);
Remove the specified key from the table (if present).
Causes the key and its associated value to be released.
BOOL NSNextMapEnumeratorPair(NSMapEnumerator* enumerator, void** key, void** value);
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.
void NSResetMapTable(NSMapTable* table);
Empty the map table (releasing every key and value), but preserve its capacity.
NSString* NSStringFromMapTable(NSMapTable* table);
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.
NSRecursiveLock* GSLogLock();
Class NSClassFromString(NSString* aClassName);
Returns the class whose name is supplied in the aClassName argument, or 0 if a nil
string is supplied.
const char* NSGetSizeAndAlignment(const char* typePtr, unsigned int* sizep, unsigned int* alignp);
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.
void NSLog(NSString* format,...);
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.
void NSLog_printf_handler(NSString* message);
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 and assign a pointer to it to _NSLog_printf_handler.
void NSLogv(NSString* format, va_list args);
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 current 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
SEL NSSelectorFromString(NSString* aSelectorName);
Returns a selector for the method whose name is supplied in the aSelectorName argument, or 0 if a nil
string is supplied.
NSString* NSStringFromClass(Class aClass);
Returns an
NSString
object containing the class name for
aClass. If
aClass is 0, returns
nil
.
NSString* NSStringFromSelector(SEL aSelector);
Returns a string object containing the method name for aSelector. If aSelector is 0, returns nil
.
NSObject* NSAllocateObject(Class aClass, unsigned int extraBytes, NSZone* zone);
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:]
method.
NSObject* NSCopyObject(NSObject* anObject, unsigned int extraBytes, NSZone* zone);
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.
void NSDeallocateObject(NSObject* anObject);
Used to release the memory used by an object.
This function is used by the
[NSObject -dealloc]
method.
BOOL NSDecrementExtraRefCountWasZero(id anObject);
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 reference count was decremented).
This function is used by the
[NSObject -release]
method.
unsigned int NSExtraRefCount(id anObject);
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.
void NSIncrementExtraRefCount(id anObject);
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.
BOOL NSShouldRetainWithZone(NSObject* anObject, NSZone* requestedZone);
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.
NSMutableDictionary* GNUstepConfig(NSDictionary* newConfig);
Returns a mutable copy of the system-wide configuration used to determine paths to locate files etc.
If the newConfig argument is non-nil it is used to set the config overriding any other version. You should not change the config after the user defaults system has been initialised as the new config will not be picked up by the defaults system.
A typical sequence of operation might be to
Call the function with a nil
argument to obtain the configuration information currently in use (usually obtained from the main GNUstep configuration file).
Modify the dictionary contents.
Call the function again passing back in the modified config.
If you call this function with a non-nil argument before the system configuration file has been read, you will prevent the file from being read. However, you must take care doing this that creation of the config dictionary you are going to pass in to the function does not have any side-effects which would cause the config file to be read earlier.
If you want to prevent the user specific config file from being read, you must set the GNUSTEP_USER_CONFIG_FILE value in the dictionary to be an empty string.
void GNUstepUserConfig(NSMutableDictionary* config, NSString* userName);
The
config dictionary passed to this function should be a system-wide
config as provided by
GNUstepConfig()
... and this function merges in user specific configuration file information if such a file exists and is owned by the user.
NB. If the GNUSTEP_USER_CONFIG_FILE value in the system-wide
config is an empty string, no user-specifc
config will be read.
NSString* GSDefaultsRootForUser(NSString* userName);
Returns the location of the defaults database for the specified user. This uses the same information you get from
GNUstepConfig()
and
GNUstepUserConfig()
and builds the path to the defaults database fromm it.
Return the path of the defaults directory for
userName.
This examines the.GNUsteprc file in the home directory of the user for the GNUSTEP_DEFAULTS_ROOT or the GNUSTEP_USER_ROOT directory definitions, over-riding those in GNUstep.conf.
void GSSetUserName(NSString* aName);
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 posses the file access privileges of the new name. This is provided primarily for use by processes that run as system-manager and need to act as particular users. It uses the [NSUserDefaults +resetUserDefaults] extension to reset the defaults system to use the defaults belonging to the new user.
NSString* NSFullUserName();
Returns the full username of the current user. If unable to determine this, returns the standard user name.
NSString* NSHomeDirectory();
NSString* NSHomeDirectoryForUser(NSString* loginName);
Returns loginName's home directory as an NSString object.
NSString* NSOpenStepRootDirectory();
Returns the location of the
root directory of the file hierarchy. This lets you build paths in a system independent manner (for instance the root on unix is '/' but on windows it is 'C:\') by appending path components to the root.
Don't assume that /System, /Network etc exist in this path (generally they don't)! Use other path utility functions such as
NSSearchPathForDirectoriesInDomains()
to find standard locations for libraries, applications etc.
Refer to the GNUstep File System Hierarchy documentation for more info.
NSArray* NSSearchPathForDirectoriesInDomains(NSSearchPathDirectory directoryKey, NSSearchPathDomainMask domainMask, BOOL expandTilde);
Returns an array of search paths to look at for resources.
The paths are returned in domain order: USER, LOCAL, NETWORK then SYSTEM.
NSArray* NSStandardApplicationPaths();
Returns the standard paths in which applications are stored and should be searched for. Calls
NSSearchPathForDirectoriesInDomains()
Refer to the GNUstep File System Hierarchy documentation for more info.
NSArray* NSStandardLibraryPaths();
Returns the standard paths in which resources are stored and should be searched for. Calls
NSSearchPathForDirectoriesInDomains()
Refer to the GNUstep File System Hierarchy documentation for more info.
NSString* NSTemporaryDirectory();
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.
NSString* NSUserName();
Return the caller's login name as an NSString object.
Under unix-like systems, the name associated with the current effective user ID is used.
Under ms-windows, the 'LOGNAME' environment is used, or if that fails, the GetUserName()
call is used to find the user name.
BOOL GSDebugSet(NSString* level);
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.
BOOL NSEqualRanges(NSRange range1, NSRange range2);
Returns whether range1 and range2 have same location and length.
NSRange NSIntersectionRange(NSRange aRange, NSRange bRange);
Returns range containing indices existing in both aRange and bRange. If the returned length is 0, the location is undefined and should be ignored.
BOOL NSLocationInRange(unsigned int location, NSRange range);
Returns whether location is greater than or equal to range's location and less than its max.
NSRange NSMakeRange(unsigned int location, unsigned int length);
Creates new range starting at location and of given length.
unsigned int NSMaxRange(NSRange range);
Returns top end of range (location + length).
NSRange NSRangeFromString(NSString* aString);
Parses range from string of form {location=a, length=b}; returns range with 0 location and length if this fails.
NSString* NSStringFromRange(NSRange range);
Returns string of form {location=a, length=b}.
NSRange NSUnionRange(NSRange aRange, NSRange bRange);
Returns range going from minimum of aRange's and bRange's locations to maximum of their two max's.
void _NSRangeExceptionRaise();
Convenience method for raising an NSRangeException.
void GSUPurge(unsigned int count);
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.
id GSUSet(id anObject, unsigned int count);
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.
id GSUnique(id anObject);
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.
void GSUniquing(BOOL flag);
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.
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).
NSMutableDictionary* GSCurrentThreadDictionary();
Fast access function for thread dictionary of current thread.
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.
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.
GSNumberInfo* GSNumberInfoFromObject(NSNumber* o);
Internal method for caching. DO NOT USE.
unsigned int GSSmallHash(int n);
Internal method: get cached values for integers in the range - GS_SMALL to + GS_SMALL
DO NOT USE
NSZone* GSAtomicMallocZone();
Returns the default zone used for atomic memory allocation (see NSMallocAtomic()), if no zone is specified.
void* GSOutOfMemory(size_t size, BOOL retry);
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.
void* NSAllocateMemoryPages(unsigned int bytes);
Allocate memory for this process and return a pointer to it (or a null pointer on failure).
void NSCopyMemoryPages(const void* src, void* dest, unsigned int bytes);
Perform an efficient large scale copy of data from src to dest. The value bytes specifies the length of the data copied.
NSZone* NSCreateZone(size_t start, size_t gran, BOOL canFree);
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.
void NSDeallocateMemoryPages(void* ptr, unsigned int bytes);
NSZone* NSDefaultMallocZone();
Returns the default zone used for memory allocation, created at startup. This zone cannot be recycled.
unsigned int NSLogPageSize();
Return log base 2 of the number of bytes in a memory page.
unsigned int NSPageSize();
Return the number of bytes in a memory page.
unsigned int NSRealMemoryAvailable();
Return the number of bytes of real (physical) memory available.
void NSRecycleZone(NSZone* zone);
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 NSZoneFree()). 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.
unsigned int NSRoundDownToMultipleOfPageSize(unsigned int bytes);
Round bytes down to the nearest multiple of the memory page size, and return it.
unsigned int NSRoundUpToMultipleOfPageSize(unsigned int bytes);
Round bytes up to the nearest multiple of the memory page size, and return it.
void NSSetZoneName(NSZone* zone, NSString* name);
Sets name of the given zone (useful for debugging and logging).
void* NSZoneCalloc(NSZone* zone, size_t elems, size_t bytes);
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.
BOOL NSZoneCheck(NSZone* zone);
Checks integrity of a zone. Not defined by OpenStep or OS X.
void NSZoneFree(NSZone* zone, void* ptr);
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.
NSZone* NSZoneFromPointer(void* ptr);
Searches and finds the zone ptr was allocated from. The speed depends upon the number of zones and their size.
void* NSZoneMalloc(NSZone* zone, size_t 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.
void* NSZoneMallocAtomic(NSZone* zone, size_t size);
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.
NSString* NSZoneName(NSZone* zone);
Returns the name assigned to the zone, if one has been given (see NSSetZoneName()), otherwise nil
. Useful for debugging/logging.
void* NSZoneRealloc(NSZone* zone, void* ptr, size_t size);
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.
struct NSZoneStats NSZoneStats(NSZone* zone);
Obtain statistics about the zone. Implementation emphasis is on correctness, not speed. Not defined by OpenStep or OS X.
Up