Server : Apache/2.4.41 (Ubuntu) System : Linux absol.cf 5.4.0-198-generic #218-Ubuntu SMP Fri Sep 27 20:18:53 UTC 2024 x86_64 User : www-data ( 33) PHP Version : 7.4.33 Disable Function : pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wifcontinued,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_get_handler,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,pcntl_async_signals,pcntl_unshare, Directory : /usr/share/GNUstep/Documentation/Developer/BaseAdditions/Reference/
Upload File :
Current File : //usr/share/GNUstep/Documentation/Developer/BaseAdditions/Reference/Functions.gsdoc
<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.3//EN" "http://www.gnustep.org/gsdoc-1_0_3.dtd">
<!--
Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.
-->
<gsdoc base="Functions" up="Base">
<head>
<title>Functions</title>
<author name="Richard Frith-Macdonald"></author>
<copy>2005 Free Software Foundation, Inc.</copy>
</head>
<body>
<front>
<contents />
<chapter>
<heading>Function index</heading>
<index type="function" scope="file" />
</chapter>
<chapter>
<heading>Macro index</heading>
<index type="macro" scope="file" />
</chapter>
</front>
<!--StartMacros-->
<!--StartGNUstepMacros-->
<chapter>
<heading>GNUstep macros</heading>
<p></p>
<macro name="ASSIGN" ovadd="1.0.0">
<arg>object</arg>
<arg>value</arg>
<desc>
ASSIGN(<var>object</var>,value) assigns the
<var>value</var> to the <var>object</var> with
appropriate retain and release operations. <br />
Use this to avoid retain/release errors.
</desc>
</macro>
<macro name="ASSIGNCOPY" ovadd="1.0.0">
<arg>object</arg>
<arg>value</arg>
<desc>
ASSIGNCOPY(<var>object</var>,value) assigns a
copy of the <var>value</var> to the <var>object</var>
with release of the original. <br /> Use this to avoid
retain/release errors.
</desc>
</macro>
<macro name="AUTORELEASE" ovadd="1.0.0">
<arg>object</arg>
<desc>
Basic autorelease operation... calls
<ref type="method" id="-autorelease" class="NSObject">
[NSObject -autorelease]
</ref>
<br /> Deprecated... pointless on modern processors.
Simply call the
<ref type="method" id="-autorelease">
-autorelease
</ref>
method.
</desc>
</macro>
<macro name="CHECK_INDEX_RANGE_ERROR" ovadd="1.0.0">
<arg>INDEX</arg>
<arg>OVER</arg>
<desc>
Checks whether <var>INDEX</var> is strictly less than
<var>OVER</var> (within C array space).
<var>INDEX</var> and <var>OVER</var> must be
<strong>unsigned</strong> integers (NSUInteger).
</desc>
</macro>
<macro name="CREATE_AUTORELEASE_POOL" ovadd="1.0.0">
<arg>X</arg>
<desc>
DEPRECATED... use ENTER_POOL and LEAVE_POOL
</desc>
</macro>
<macro name="DEALLOC" ovadd="1.0.0">
<desc>
DEALLOC calls the superclass implementation of
dealloc, unless ARC is in use (in which case it does
nothing).
</desc>
</macro>
<macro name="DESTROY" ovadd="1.0.0">
<arg>object</arg>
<desc>
<ref type="function" id="DESTROY">
DESTROY()
</ref>
is a release operation which also sets the variable to be
a <code>nil</code> pointer for tidiness - we can't
accidentally use a DESTROYED <var>object</var>
later. It also makes sure to set the variable to
<code>nil</code> before releasing the
<var>object</var> - to avoid side-effects of the
release trying to reference the <var>object</var>
being released through the variable.
</desc>
</macro>
<macro name="ENTER_POOL" ovadd="1.0.0">
<desc>
ENTER_POOL creates an autorelease pool and places
subsequent code in a do/while loop (executed only
once) which can be broken out of to reach the point
when the pool is drained. <br /> The block must be
terminated with a corresponding LEAVE_POOL. <br />
You should not return from such a block of code (to do so
could leak an autorelease pool and give objects a
longer lifetime than they ought to have. If you wish
to leave the block of code early, you may do so using a
'break' statement.
</desc>
</macro>
<macro name="GSLocalizedStaticString" ovadd="1.0.0">
<arg>key</arg>
<arg>comment</arg>
<desc>
<p>
This function (macro) is a GNUstep extensions, and it
is used to localize static strings. Here is an example
of a static string:
</p>
<p>
<code>
NSString *message = @"Hi there";... some code...
NSLog (message);
</code>
</p>
<p>
This string can not be localized using the standard
openstep functions/macros. By using this gnustep
extension, you can localize it as follows:
</p>
<p>
<code>
NSString *message = GSLocalizedStaticString
(@"Hi there", @"Greeting");... some code... NSLog
(NSLocalizedString (message, @""));
</code>
</p>
<p>
When the tools generate the
<code>Localizable.strings</code> file from the
source code, they will ignore the
<code>NSLocalizedString</code> call while they will
extract the string (and the <var>comment</var>) to
localize from the
<code>GSLocalizedStaticString</code> call.
</p>
<p>
When the code is compiled, instead, the
<code>GSLocalizedStaticString</code> call is ignored
(discarded, it is a macro which simply expands
to <code><var>key</var></code>), while the
<code>NSLocalizedString</code> will actually look up
the string for translation in the
<code>Localizable.strings</code> file.
</p>
<p>
Please note that there is currently no
macro/function to localize static strings
using different tables. If you need that
functionality, you have either to prepare
the localization tables by hand, or to rewrite your
code in such a way as not to use static strings.
</p>
</desc>
</macro>
<macro name="GS_RANGE_CHECK" ovadd="1.0.0">
<arg>RANGE</arg>
<arg>SIZE</arg>
<desc>
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]. Size must be an
<strong>unsigned</strong> integer (NSUInteger).
</desc>
</macro>
<macro name="LEAVE_POOL" ovadd="1.0.0">
<desc>
LEAVE_POOL terminates a block of code started with
ENTER_POOL.
</desc>
</macro>
<macro name="RECREATE_AUTORELEASE_POOL" ovadd="1.0.0">
<arg>X</arg>
<desc>
DEPRECATED... use ENTER_POOL and LEAVE_POOL
</desc>
</macro>
<macro name="RELEASE" ovadd="1.0.0">
<arg>object</arg>
<desc>
Basic release operation... calls
<ref type="method" id="-release" class="NSObject">
[NSObject -release]
</ref>
<br /> Deprecated... pointless on modern processors.
Simply call the
<ref type="method" id="-release">
-release
</ref>
method.
</desc>
</macro>
<macro name="RETAIN" ovadd="1.0.0">
<arg>object</arg>
<desc>
Basic retain operation... calls
<ref type="method" id="-retain" class="NSObject">
[NSObject -retain]
</ref>
<br /> Deprecated... pointless on modern processors.
Simply call the
<ref type="method" id="-retain">
-retain
</ref>
method.
</desc>
</macro>
<macro name="TEST_AUTORELEASE" ovadd="1.0.0">
<arg>object</arg>
<desc>
Tested autorelease - only invoke the objective-c
method if the receiver is not <code>nil</code>. <br />
Deprecated... pointless on modern processors.
Simply call the
<ref type="method" id="-autorelease">
-autorelease
</ref>
method.
</desc>
</macro>
<macro name="TEST_RELEASE" ovadd="1.0.0">
<arg>object</arg>
<desc>
Tested release - only invoke the objective-c method if
the receiver is not <code>nil</code>. <br /> Deprecated
... pointless on modern processors. Simply call the
<ref type="method" id="-release">
-release
</ref>
method.
</desc>
</macro>
<macro name="TEST_RETAIN" ovadd="1.0.0">
<arg>object</arg>
<desc>
Tested retain - only invoke the objective-c method if
the receiver is not <code>nil</code>. <br /> Deprecated
... pointless on modern processors. Simply call the
<ref type="method" id="-retain">
-retain
</ref>
method.
</desc>
</macro>
<macro name="_" ovadd="1.0.0">
<arg>X</arg>
<desc>
<p>
This function (macro) is a GNUstep extension.
</p>
<p>
<code>_(@"My string to translate")</code>
</p>
<p>
is basically equivalent to
</p>
<p>
<code>
NSLocalizedString(@"My string to
translate", @"")
</code>
</p>
<p>
It is useful when you need to translate an application
very quickly, as you just need to enclose all strings
inside
<code><ref type="function" id="_">_()</ref></code>.
But please note that when you use this macro, you are
not taking advantage of comments for the translator, so
consider using <code>NSLocalizedString</code>
instead when you need a comment.
</p>
<p>
You may define GS_LOCALISATION_BUNDLE_ID to the bundle
identifier of the bundle which is to provide the
localisation information. <br /> This can be
used when compiling a single file by specifying
something like '-D
GS_LOCALISATION_BUNDLE_ID=$(FRAMEWORK_NAME)'
in your make file. <br /> If this is not defined, the
localisation is provided by your application's
main bundle exactly like the NSLocalizedString
function.
</p>
<p>
Alternatively you may define
GS_LOCALISATION_BUNDLE to be the
bundle to be used to prvide the localisation
information.
</p>
</desc>
</macro>
<macro name="__" ovadd="1.0.0">
<arg>X</arg>
<desc>
<p>
This function (macro) is a GNUstep extension.
</p>
<p>
<code>__(@"My string to translate")</code>
</p>
<p>
is exactly the same as
</p>
<p>
<code>
GSLocalizedStaticString(@"My
string to translate", @"")
</code>
</p>
<p>
It is useful when you need to translate an application
very quickly. You would use it as follows for static
strings:
</p>
<p>
<code>
NSString *message = __(@"Hello there");... more
code... NSLog (_(messages));
</code>
</p>
<p>
But please note that when you use this macro, you are
not taking advantage of comments for the translator, so
consider using
<code>GSLocalizedStaticString</code> instead when
you need a comment.
</p>
</desc>
</macro>
</chapter>
<!--EndGNUstepMacros-->
<!--StartGSBlocksMacros-->
<chapter>
<heading>GSBlocks macros</heading>
<p></p>
<macro name="CALL_BLOCK" ovadd="1.0.0">
<arg>block</arg>
<arg>args</arg>
<vararg />
<desc>
Calls a <var>block</var>. Works irrespective of whether
the compiler supports blocks.
</desc>
</macro>
<macro name="CALL_BLOCK_NO_ARGS" ovadd="1.0.0">
<arg>block</arg>
<desc>
Calls a <var>block</var> without arguments.
</desc>
</macro>
</chapter>
<!--EndGSBlocksMacros-->
<!--StartGSVersionMacrosMacros-->
<chapter>
<heading>GSVersionMacros macros</heading>
<p></p>
<macro name="GS_API_LATEST" ovadd="1.0.0">
<desc>
A constant to represent a feature which is still present in
the latest version. This is the highest possible version
number. <br /> eg. <br /> #if
<ref type="macro" id="OS_API_VERSION">
OS_API_VERSION
</ref>
(GS_API_MACOSX, GS_API_LATEST) <br /> denotes
code present from the initial MacOS-X version onwards.
</desc>
</macro>
<macro name="GS_API_MACOSX" ovadd="1.0.0">
<desc>
The version number of the first MacOS-X implementation.
<br /> eg. <br /> #if
<ref type="macro" id="OS_API_VERSION">
OS_API_VERSION
</ref>
(GS_API_MACOSX, GS_API_LATEST) <br /> denotes
code present from the initial MacOS-X version onwards.
</desc>
</macro>
<macro name="GS_API_NONE" ovadd="1.0.0">
<desc>
A constant which is the lowest possible version number (0)
so that when used as the removal version (second argument
of the GS_API_VERSION or OS_API_VERSION macro) represents
a feature which is not present in any version. <br /> eg.
<br /> #if
<ref type="macro" id="OS_API_VERSION">
OS_API_VERSION
</ref>
(GS_API_NONE, GS_API_NONE) <br /> denotes code
not present in OpenStep/OPENSTEP/MacOS-X
</desc>
</macro>
<macro name="GS_API_OPENSTEP" ovadd="1.0.0">
<desc>
The version number of the first OPENSTEP implementation.
<br /> eg. <br /> #if
<ref type="macro" id="OS_API_VERSION">
OS_API_VERSION
</ref>
(GS_API_OPENSTEP, GS_API_LATEST) <br />
denotes code present from the initial OPENSTEP
version onwards.
</desc>
</macro>
<macro name="GS_API_OSSPEC" ovadd="1.0.0">
<desc>
The version number of the initial OpenStep specification.
<br /> eg. <br /> #if
<ref type="macro" id="OS_API_VERSION">
OS_API_VERSION
</ref>
(GS_API_OSSPEC, GS_API_LATEST) <br /> denotes
code present from the OpenStep specification onwards.
</desc>
</macro>
<macro name="GS_API_VERSION" ovadd="1.0.0">
<arg>ADD</arg>
<arg>REM</arg>
<desc>
<p>
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 <var>ADD</var> <= version
< <var>REM</var>, where <var>ADD</var> is the
version number at which a feature guarded by the
macro was introduced and <var>REM</var> is the
version number at which it was removed.
</p>
<p>
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 the predefined
constants...
<ref type="macro" id="GS_API_NONE">
GS_API_NONE
</ref>
,
<ref type="macro" id="GS_API_LATEST">
GS_API_LATEST
</ref>
,
</p>
<p>
Also see
<ref type="macro" id="OS_API_VERSION">
OS_API_VERSION
</ref>
</p>
<p>
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 <br />
<code>
#if GS_API_VERSION(<var>ADD</var>,GS_API_LATEST)
</code>
<br /> where <code><var>ADD</var></code> is the
version number of the next minor release after the
most recent one. <br /> As a general principle you
should <em>not</em> change the API with changing
subminor version numbers... as that tends to
confuse people (though Apple has sometimes done
it).
</p>
</desc>
</macro>
<macro name="OS_API_VERSION" ovadd="1.0.0">
<arg>ADD</arg>
<arg>REM</arg>
<desc>
<p>
Macro to check a defined OpenStep/OPENSTEP/MacOS-X
version against the supplied arguments. Returns
true if no version is specified, or if <var>ADD</var>
<= version < <var>REM</var>, where
<var>ADD</var> is the version number at which a
feature guarded by the macro was introduced and
<var>REM</var> is the version number at which it was
removed.
</p>
<p>
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...
<ref type="macro" id="GS_API_NONE">
GS_API_NONE
</ref>
,
<ref type="macro" id="GS_API_LATEST">
GS_API_LATEST
</ref>
,
<ref type="macro" id="GS_API_OSSPEC">
GS_API_OSSPEC
</ref>
,
<ref type="macro" id="GS_API_OPENSTEP">
GS_API_OPENSTEP
</ref>
,
<ref type="macro" id="GS_API_MACOSX">
GS_API_MACOSX
</ref>
</p>
<p>
Also see
<ref type="macro" id="GS_API_VERSION">
GS_API_VERSION
</ref>
</p>
<p>
For OSX compatibility, this macro also supports the use
of Apple's symbolic constants for version numbering.
Their contants are currently four digit values (two
digits for the major version, one for the minor, and
one for the subminor).
</p>
<p>
The Apple compatibility version macros are currently:
<ref type="macro" id="MAC_OS_X_VERSION_10_0">
MAC_OS_X_VERSION_10_0
</ref>
,
<ref type="macro" id="MAC_OS_X_VERSION_10_1">
MAC_OS_X_VERSION_10_1
</ref>
,
<ref type="macro" id="MAC_OS_X_VERSION_10_2">
MAC_OS_X_VERSION_10_2
</ref>
,
<ref type="macro" id="MAC_OS_X_VERSION_10_3">
MAC_OS_X_VERSION_10_3
</ref>
,
<ref type="macro" id="MAC_OS_X_VERSION_10_4">
MAC_OS_X_VERSION_10_4
</ref>
,
<ref type="macro" id="MAC_OS_X_VERSION_10_5">
MAC_OS_X_VERSION_10_5
</ref>
,
<ref type="macro" id="MAC_OS_X_VERSION_10_6">
MAC_OS_X_VERSION_10_6
</ref>
,
<ref type="macro" id="MAC_OS_X_VERSION_10_7">
MAC_OS_X_VERSION_10_7
</ref>
,
<ref type="macro" id="MAC_OS_X_VERSION_10_8">
MAC_OS_X_VERSION_10_8
</ref>
<ref type="macro" id="MAC_OS_X_VERSION_10_9">
MAC_OS_X_VERSION_10_9
</ref>
</p>
</desc>
</macro>
</chapter>
<!--EndGSVersionMacrosMacros-->
<!--StartGSObjCRuntimeMacros-->
<chapter>
<heading>GSObjCRuntime macros</heading>
<p></p>
<macro name="GS_MAX_OBJECTS_FROM_STACK" ovadd="1.0.0">
<desc>
The number of objects to try to get from varargs into an
array on the stack... if there are more than this, use
the heap. NB. This MUST be a multiple of 2
</desc>
</macro>
<macro name="GS_USEIDLIST" ovadd="1.0.0">
<arg>firstObject</arg>
<arg>code</arg>
<vararg />
<desc>
<p>
This is a macro designed to minimise the use of memory
allocation and deallocation when you need to
work with a vararg list of objects. <br /> The objects
are unpacked from the vararg list into a 'C' array and
then a <var>code</var> fragment you specify is able to
make use of them before that 'C' array is destroyed.
</p>
<p>
The <var>firstObject</var> argument is the name of the
formal parameter in your method or function which
precedes the ',...' denoting variable args.
</p>
<p>
The <var>code</var> argument is a piece of objective-c
<var>code</var> to be executed to make use of the
objects stored in the 'C' array. <br /> When this
<var>code</var> is called the
<strong>unsigned</strong> integer '__count' will
contain the number of objects unpacked, and the
pointer '__objects' will point to the unpacked
objects, ie. <var>firstObject</var> followed by
the vararg arguments up to (but not including) the
first <code>nil</code>.
</p>
</desc>
</macro>
<macro name="GS_USEIDPAIRLIST" ovadd="1.0.0">
<arg>firstObject</arg>
<arg>code</arg>
<vararg />
<desc>
<p>
This is a macro designed to minimise the use of memory
allocation and deallocation when you need to
work with a vararg list of objects. <br /> The objects
are unpacked from the vararg list into two 'C' arrays
and then a <var>code</var> fragment you specify is able
to make use of them before that 'C' array is destroyed.
</p>
<p>
The <var>firstObject</var> argument is the name of the
formal parameter in your method or function which
precedes the ',...' denoting variable args.
</p>
<p>
The <var>code</var> argument is a piece of objective-c
<var>code</var> to be executed to make use of the
objects stored in the 'C' arrays. <br /> When this
<var>code</var> is called the
<strong>unsigned</strong> integer '__count' will
contain the number of objects unpacked, the pointer
'__objects' will point to the first object in
each pair, and the pointer '__pairs' will point to an
array containing the second halves of the pairs of
objects whose first halves are in '__objects'.
<br /> This lets you pack a list of the form 'key,
value, key, value,...' into an array of keys and an
array of values.
</p>
</desc>
</macro>
</chapter>
<!--EndGSObjCRuntimeMacros-->
<!--StartNSDebug+GNUstepBaseMacros-->
<chapter>
<heading>NSDebug+GNUstepBase macros</heading>
<p></p>
<macro name="GSOnceFLog" ovadd="0.0.0">
<arg>format</arg>
<arg>args</arg>
<vararg />
<desc>
Macro to log a message only the first time it is
encountered. <br /> 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. <br /> Use this from inside a
function. Pass an NSString as a <var>format</var>,
followed by zero or more arguments for the
<var>format</var> string. Example: GSOnceFLog(@"This
function is deprecated, use another");
</desc>
</macro>
<macro name="GSOnceMLog" ovadd="0.0.0">
<arg>format</arg>
<arg>args</arg>
<vararg />
<desc>
Macro to log a message only the first time it is
encountered. <br /> 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. <br /> Use this from inside a
method. Pass an NSString as a <var>format</var>
followed by zero or more arguments for the
<var>format</var> string. <br /> Example:
GSOnceMLog(@"This method is deprecated, use
another");
</desc>
</macro>
<macro name="NSDebugFLLog" ovadd="0.0.0">
<arg>level</arg>
<arg>format</arg>
<arg>args</arg>
<vararg />
<desc>
This macro is like
<ref type="function" id="NSDebugLLog">
NSDebugLLog()
</ref>
but includes the name and location of the function in
which the macro is used as part of the log output.
</desc>
</macro>
<macro name="NSDebugFLog" ovadd="0.0.0">
<arg>format</arg>
<arg>args</arg>
<vararg />
<desc>
This macro is a shorthand for
<ref type="function" id="NSDebugFLLog">
NSDebugFLLog()
</ref>
using then default debug level... 'dflt'
</desc>
</macro>
<macro name="NSDebugFRLog" ovadd="0.0.0">
<arg>object</arg>
<arg>msg</arg>
<desc>
This macro saves the name and location of the function
in which the macro is used, along with a
<strong>short</strong> string <var>msg</var> as the
tag associated with a recorded <var>object</var>.
</desc>
</macro>
<macro name="NSDebugLLog" ovadd="0.0.0">
<arg>level</arg>
<arg>format</arg>
<arg>args</arg>
<vararg />
<desc>
<p>
<ref type="function" id="NSDebugLLog">
NSDebugLLog()
</ref>
is the basic debug logging macro used to display log
messages using
<ref type="function" id="NSLog">
NSLog()
</ref>
, if debug logging was enabled at compile time and the
appropriate logging <var>level</var> was set at
runtime.
</p>
<p>
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.
</p>
<p>
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 <code>NSProcessInfo</code> '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.
</p>
<p>
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.
</p>
<p>
NSUserDefaults also adds debug levels from
the array given by the GNU-Debug key... but these
values will not take effect until the
<ref type="method" id="+standardUserDefaults">
+standardUserDefaults
</ref>
method is called... so they are useless for
debugging NSUserDefaults itself or for debugging
any code executed before the defaults system is used.
</p>
<p>
To embed debug logging in your code you use the
<ref type="function" id="NSDebugLLog">
NSDebugLLog()
</ref>
or
<ref type="function" id="NSDebugLog">
NSDebugLog()
</ref>
macro.
<ref type="function" id="NSDebugLog">
NSDebugLog()
</ref>
is just
<ref type="function" id="NSDebugLLog">
NSDebugLLog()
</ref>
with the debug <var>level</var> set to 'dflt'. So, to
activate debug statements that use
<ref type="function" id="NSDebugLog">
NSDebugLog()
</ref>
, you supply the '--GNU-Debug=dflt' argument to your
program.
</p>
<p>
You can also change the active debug levels under your
programs control - NSProcessInfo has a
<ref type="method" id="-debugSet">
[-debugSet]
</ref>
method that returns the mutable set that contains
the active debug levels - your program can modify this
set.
</p>
<p>
Two debug levels have a special effect - 'dflt' is the
<var>level</var> used for debug logs statements where
no debug <var>level</var> is specified, and 'NoWarn' is
used to *disable* warning messages.
</p>
<p>
As a convenience, there are four more logging macros you
can use -
<ref type="function" id="NSDebugFLog">
NSDebugFLog()
</ref>
,
<ref type="function" id="NSDebugFLLog">
NSDebugFLLog()
</ref>
,
<ref type="function" id="NSDebugMLog">
NSDebugMLog()
</ref>
and
<ref type="function" id="NSDebugMLLog">
NSDebugMLLog()
</ref>
. 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.
</p>
</desc>
</macro>
<macro name="NSDebugLog" ovadd="0.0.0">
<arg>format</arg>
<arg>args</arg>
<vararg />
<desc>
This macro is a shorthand for
<ref type="function" id="NSDebugLLog">
NSDebugLLog()
</ref>
using then default debug level... 'dflt'
</desc>
</macro>
<macro name="NSDebugMLLog" ovadd="0.0.0">
<arg>level</arg>
<arg>format</arg>
<arg>args</arg>
<vararg />
<desc>
This macro is like
<ref type="function" id="NSDebugLLog">
NSDebugLLog()
</ref>
but includes the name and location of the <em>method</em>
in which the macro is used as part of the log output.
</desc>
</macro>
<macro name="NSDebugMLog" ovadd="0.0.0">
<arg>format</arg>
<arg>args</arg>
<vararg />
<desc>
This macro is a shorthand for
<ref type="function" id="NSDebugMLLog">
NSDebugMLLog()
</ref>
using then default debug level... 'dflt'
</desc>
</macro>
<macro name="NSDebugMRLog" ovadd="0.0.0">
<arg>object</arg>
<arg>msg</arg>
<desc>
This macro saves the name and location of the method in
which the macro is used, along with a
<strong>short</strong> string <var>msg</var> as the
tag associated with a recorded <var>object</var>.
</desc>
</macro>
<macro name="NSWarnFLog" ovadd="0.0.0">
<arg>format</arg>
<arg>args</arg>
<vararg />
<desc>
This macro is like
<ref type="function" id="NSWarnLog">
NSWarnLog()
</ref>
but includes the name and location of the
<em>function</em> in which the macro is used as part of
the log output.
</desc>
</macro>
<macro name="NSWarnLog" ovadd="0.0.0">
<arg>format</arg>
<arg>args</arg>
<vararg />
<desc>
<p>
<ref type="function" id="NSWarnLog">
NSWarnLog()
</ref>
is the basic debug logging macro used to display warning
messages using
<ref type="function" id="NSLog">
NSLog()
</ref>
, if warn logging was not disabled at compile time and
the disabling logging level was not set at runtime.
</p>
<p>
Warning messages which can be enabled/disabled by
defining GSWARN when compiling.
</p>
<p>
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'.
</p>
<p>
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').
</p>
<p>
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.
</p>
<p>
To embed debug logging in your code you use the
<ref type="function" id="NSWarnLog">
NSWarnLog()
</ref>
macro.
</p>
<p>
As a convenience, there are two more logging macros you
can use -
<ref type="function" id="NSWarnFLog">
NSWarnFLog()
</ref>
, and
<ref type="function" id="NSWarnMLog">
NSWarnMLog()
</ref>
. 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.
</p>
</desc>
</macro>
<macro name="NSWarnMLog" ovadd="0.0.0">
<arg>format</arg>
<arg>args</arg>
<vararg />
<desc>
This macro is like
<ref type="function" id="NSWarnLog">
NSWarnLog()
</ref>
but includes the name and location of the <em>method</em>
in which the macro is used as part of the log output.
</desc>
</macro>
</chapter>
<!--EndNSDebug+GNUstepBaseMacros-->
<!--StartNSLock+GNUstepBaseMacros-->
<chapter>
<heading>NSLock+GNUstepBase macros</heading>
<p></p>
<macro name="GS_INITIALIZED_LOCK" ovadd="0.0.0">
<arg>IDENT</arg>
<arg>CLASSNAME</arg>
<desc>
Returns <var>IDENT</var> which will be initialized to
an instance of a <var>CLASSNAME</var> in a thread safe
manner. If <var>IDENT</var> has been previously
initialized this macro merely returns
<var>IDENT</var>. <var>IDENT</var> is considered
uninitialized, if it contains <code>nil</code>
. <var>CLASSNAME</var> must be either NSLock,
NSRecursiveLock or one of their subclasses.
See
<ref type="method" id="+newLockAt:" class="NSLock">
[NSLock +newLockAt:]
</ref>
for details. This macro is intended for code that cannot
insure that a lock can be initialized in thread safe
manner otherwise.
<example>
NSLock *my_lock = nil;
void function (void)
{
[GS_INITIALIZED_LOCK(my_lock, NSLock) lock];
do_work ();
[my_lock unlock];
}
</example>
</desc>
</macro>
</chapter>
<!--EndNSLock+GNUstepBaseMacros-->
<!--EndMacros-->
<!--StartFunctions-->
<!--StartGSBlocksFunctions-->
<chapter>
<heading>GSBlocks functions</heading>
<p></p>
<function type="void*" name="_Block_copy" ovadd="1.0.0">
<arg type="const void*"></arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="_Block_release" ovadd="1.0.0">
<arg type="const void*"></arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
</chapter>
<!--EndGSBlocksFunctions-->
<!--StartGSVersionMacrosFunctions-->
<chapter>
<heading>GSVersionMacros functions</heading>
<p></p>
<function type="void" name="gs_consumed" ovadd="1.0.0">
<arg type="id">o</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
</chapter>
<!--EndGSVersionMacrosFunctions-->
<!--StartGSObjCRuntimeFunctions-->
<chapter>
<heading>GSObjCRuntime functions</heading>
<p></p>
<function type="void*" name="GSAutoreleasedBuffer" ovadd="1.0.0">
<arg type="unsigned int">size</arg>
<desc>
Quickly return autoreleased data storage area.
</desc>
</function>
<function type="GSIVar" name="GSCGetInstanceVariableDefinition" ovadd="1.0.0">
<arg type="Class">cls</arg>
<arg type="const char*">name</arg>
<desc>
Deprecated.. use
<ref type="function" id="class_getInstanceVariable">
class_getInstanceVariable()
</ref>
</desc>
</function>
<function type="Class" name="GSClassFromName" ovadd="1.0.0">
<arg type="const char*">name</arg>
<desc>
<ref type="function" id="GSClassFromName">
GSClassFromName()
</ref>
is deprecated... use
<ref type="function" id="objc_lookUpClass">
objc_lookUpClass()
</ref>
</desc>
</function>
<function type="unsigned int" name="GSClassList" ovadd="1.0.0">
<arg type="Class*">buffer</arg>
<arg type="unsigned int">max</arg>
<arg type="BOOL">clearCache</arg>
<desc>
Deprecated... use
<ref type="function" id="objc_getClassList">
objc_getClassList()
</ref>
</desc>
</function>
<function type="const char*" name="GSClassNameFromObject" ovadd="1.0.0">
<arg type="id">obj</arg>
<desc>
<ref type="function" id="GSClassNameFromObject">
GSClassNameFromObject()
</ref>
is deprecated... use
<ref type="function" id="object_getClass">
object_getClass()
</ref>
in conjunction with
<ref type="function" id="class_getName">
class_getName()
</ref>
</desc>
</function>
<function type="void" name="GSClassSwizzle" ovadd="1.0.0">
<arg type="id">instance</arg>
<arg type="Class">newClass</arg>
<desc>
Function to change the class of the specified
<var>instance</var> to <var>newClass</var>. This
handles memory debugging issues in GNUstep-base and
also deals with class finalisation issues in a garbage
collecting environment, so you should use this
function rather than attempting to swizzle class
pointers directly.
</desc>
</function>
<function type="void" name="GSFlushMethodCacheForClass" ovadd="1.0.0">
<arg type="Class">cls</arg>
<desc>
Deprecated.. does nothing.
</desc>
</function>
<function type="GSMethod" name="GSGetMethod" ovadd="1.0.0">
<arg type="Class">cls</arg>
<arg type="SEL">sel</arg>
<arg type="BOOL">searchInstanceMethods</arg>
<arg type="BOOL">searchSuperClasses</arg>
<desc>
Returns the pointer to the method structure for the
selector in the specified class. Depending on
<var>searchInstanceMethods</var>, this function
searches either instance or class methods. Depending
on searchSuperClassesm this function searches either the
specified class only or also its superclasses.
<br /> To obtain the implementation pointer IMP use
returnValue->method_imp which should
be safe across all runtimes. <br /> It should be safe to
use this function in
<ref type="method" id="+load">
+load
</ref>
implementations. <br /> This function should
currently (June 2004) be considered WIP. Please
follow potential changes (Name, parameters,...)
closely until it stabilizes.
</desc>
</function>
<function type="const char*" name="GSLastErrorStr" gvadd="0.0.0" gvrem="1.15.0">
<arg type="long int">error_id</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="const char*" name="GSNameFromClass" ovadd="1.0.0">
<arg type="Class">cls</arg>
<desc>
<ref type="function" id="GSNameFromClass">
GSNameFromClass()
</ref>
is deprecated... use
<ref type="function" id="class_getName">
class_getName()
</ref>
</desc>
</function>
<function type="const char*" name="GSNameFromSelector" ovadd="1.0.0">
<arg type="SEL">sel</arg>
<desc>
<ref type="function" id="GSNameFromSelector">
GSNameFromSelector()
</ref>
is deprecated... use
<ref type="function" id="sel_getName">
sel_getName()
</ref>
</desc>
</function>
<function type="void" name="GSObjCAddClassBehavior" ovadd="1.0.0">
<arg type="Class">receiver</arg>
<arg type="Class">behavior</arg>
<desc>
<p>
A Behavior can be seen as a "Protocol with an
implementation" or a "Class without any
instance variables". A key feature of behaviors is
that they give a degree of multiple inheritance.
</p>
<p>
Behavior methods, when added to a class, override
the class's superclass methods, but not the class's
methods.
</p>
<p>
Whan a <var>behavior</var> class is added to a
<var>receiver</var> class, not only are the methods
defined in the <var>behavior</var> class added, but
the methods from the behavior's class hierarchy are
also added (unless already present).
</p>
<p>
It's not the case that a class adding behaviors from
another class must have "no instance vars". The
<var>receiver</var> class just has to have the same
layout as the <var>behavior</var> class (optionally
with some additional ivars after those of the
<var>behavior</var> class).
</p>
<p>
This function provides Behaviors without adding any
new syntax to the Objective C language. Simply define a
class with the methods you want to add, then call
this function with that class as the
<var>behavior</var> argument.
</p>
<p>
This function should be called in the
<ref type="method" id="+initialize">
+initialize
</ref>
method of the <var>receiver</var>.
</p>
<p>
If you add several behaviors to a class, be aware that
the order of the additions is significant.
</p>
</desc>
</function>
<function type="void" name="GSObjCAddClassOverride" ovadd="1.0.0">
<arg type="Class">receiver</arg>
<arg type="Class">override</arg>
<desc>
<p>
An Override can be seen as a "category implemented as a
separate class and manually added to the
<var>receiver</var> class under program control,
rather than automatically added by the
compiler/runtime.
</p>
<p>
Override methods, when added to a
<var>receiver</var> class, replace the class's
class's methods of the same name (or are added if
the class did not define methods with that name).
</p>
<p>
It's not the case that a class adding overrides from
another class must have "no instance vars". The
<var>receiver</var> class just has to have the same
layout as the <var>override</var> class (optionally
with some additional ivars after those of the
<var>override</var> class).
</p>
<p>
This function provides overrides without adding any
new syntax to the Objective C language. Simply define a
class with the methods you want to add, then call
this function with that class as the
<var>override</var> argument.
</p>
<p>
This function should usually be called in the
<ref type="method" id="+initialize">
+initialize
</ref>
method of the <var>receiver</var>.
</p>
<p>
If you add several overrides to a class, be aware that
the order of the additions is significant.
</p>
</desc>
</function>
<function type="void" name="GSObjCAddClasses" ovadd="1.0.0">
<arg type="NSArray*">classes</arg>
<desc>
The <var>classes</var> argument is an array of NSValue
objects containing pointers to <var>classes</var>
previously created by the
<ref type="function" id="GSObjCMakeClass">
GSObjCMakeClass()
</ref>
function.
</desc>
</function>
<function type="void" name="GSObjCAddMethods" ovadd="1.0.0">
<arg type="Class">cls</arg>
<arg type="Method*">list</arg>
<arg type="BOOL">replace</arg>
<desc>
Given a NULL terminated <var>list</var> of methods, add
them to the class. <br /> If the method already exists
in a superclass, the new version overrides that one, but
if the method already exists in the class itsself, the new
one is quietly ignored (replace==NO) or replaced with the
new version (if replace==YES). <br /> To add class
methods, <var>cls</var> should be the metaclass of
the class to which the methods are being added.
</desc>
</function>
<function type="NSArray*" name="GSObjCAllSubclassesOfClass" ovadd="1.0.0">
<arg type="Class">cls</arg>
<desc>
Returns an autoreleased array of subclasses of
<strong>Class</strong> <var>cls</var>, including
subclasses of subclasses.
</desc>
</function>
<function type="BOOL" name="GSObjCBehaviorDebug" ovadd="1.0.0">
<arg type="int">setget</arg>
<desc>
Turn on (<code>YES</code>), off (<code>NO</code>) or
test (-1) behavior debugging.
</desc>
</function>
<function type="Class" name="GSObjCClass" ovadd="1.0.0">
<arg type="id">obj</arg>
<desc>
<ref type="function" id="GSObjCClass">
GSObjCClass()
</ref>
is deprecated... use
<ref type="function" id="object_getClass">
object_getClass()
</ref>
</desc>
</function>
<function type="NSArray*" name="GSObjCDirectSubclassesOfClass" ovadd="1.0.0">
<arg type="Class">cls</arg>
<desc>
Returns an autoreleased array containing subclasses
directly descendent of <strong>Class</strong>
<var>cls</var>.
</desc>
</function>
<function type="BOOL" name="GSObjCFindVariable" ovadd="1.0.0">
<arg type="id">obj</arg>
<arg type="const char*">name</arg>
<arg type="const char**">type</arg>
<arg type="unsigned int*">size</arg>
<arg type="int*">offset</arg>
<desc>
This function is used to locate information about the
instance variable of <var>obj</var> called
<var>name</var>. It returns <code>YES</code> if the
variable was found, <code>NO</code> otherwise. If it
returns <code>YES</code>, then the values pointed to
by <var>type</var>, <var>size</var>, and <var>offset</var>
will be set (except where they are null pointers).
</desc>
</function>
<function type="GSIVar" name="GSObjCGetInstanceVariableDefinition" ovadd="1.0.0">
<arg type="Class">cls</arg>
<arg type="NSString*">name</arg>
<desc>
Deprecated.. use
<ref type="function" id="class_getInstanceVariable">
class_getInstanceVariable()
</ref>
</desc>
</function>
<function type="id" name="GSObjCGetVal" ovadd="1.0.0">
<arg type="NSObject*">self</arg>
<arg type="const char*">key</arg>
<arg type="SEL">sel</arg>
<arg type="const char*">type</arg>
<arg type="unsigned int">size</arg>
<arg type="int">offset</arg>
<desc>
This is used internally by the key-value coding methods,
to get a value from an object either via an accessor
method (if <var>sel</var> is supplied), or via direct
access (if <var>type</var>, <var>size</var>, and
<var>offset</var> are supplied). <br /> Automatic
conversion between NSNumber and C scalar types is
performed. <br /> If <var>type</var> is null and
can't be determined from the selector, the
<ref type="method" id="-handleQueryWithUnboundKey:" class="NSObject">[NSObject -handleQueryWithUnboundKey:]</ref> method is called to try to get a value.
</desc>
</function>
<function type="void" name="GSObjCGetVariable" ovadd="1.0.0">
<arg type="id">obj</arg>
<arg type="int">offset</arg>
<arg type="unsigned int">size</arg>
<arg type="void*">data</arg>
<desc>
Gets the value from an instance variable in
<var>obj</var> <br /> This function performs no
checking... you should use it only where you are
providing information from a call to
<ref type="function" id="GSObjCFindVariable">
GSObjCFindVariable()
</ref>
and you know that the <var>data</var> area provided is
the correct <var>size</var>.
</desc>
</function>
<function type="BOOL" name="GSObjCIsClass" ovadd="1.0.0">
<arg type="Class">cls</arg>
<desc>
<ref type="function" id="GSObjCIsClass">
GSObjCIsClass()
</ref>
is deprecated... use
<ref type="function" id="object_getClass">
object_getClass()
</ref>
in conjunction with
<ref type="function" id="class_isMetaClass">
class_isMetaClass()
</ref>
</desc>
</function>
<function type="BOOL" name="GSObjCIsInstance" ovadd="1.0.0">
<arg type="id">obj</arg>
<desc>
<ref type="function" id="GSObjCIsInstance">
GSObjCIsInstance()
</ref>
is deprecated... use
<ref type="function" id="object_getClass">
object_getClass()
</ref>
in conjunction with
<ref type="function" id="class_isMetaClass">
class_isMetaClass()
</ref>
</desc>
</function>
<function type="BOOL" name="GSObjCIsKindOf" ovadd="1.0.0">
<arg type="Class">cls</arg>
<arg type="Class">other</arg>
<desc>
Test to see if class inherits from another class The
argument to this function must NOT be
<code>nil</code>.
</desc>
</function>
<function type="NSValue*" name="GSObjCMakeClass" ovadd="1.0.0">
<arg type="NSString*">name</arg>
<arg type="NSString*">superName</arg>
<arg type="NSDictionary*">iVars</arg>
<desc>
references:
http://www.macdevcenter.com/pub/a/mac/2002/05/31/runtime_parttwo.html?page=1 http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/9objc_runtime_reference/chapter_5_section_1.html http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/9objc_runtime_reference/chapter_5_section_21.html ObjcRuntimeUtilities.m by Nicola Pero <br />
<p>
Create a <strong>Class</strong> structure for use by
the ObjectiveC runtime and return an NSValue object
pointing to it. The class will not be added to the
runtime (you must do that later using the
<ref type="function" id="GSObjCAddClasses">
GSObjCAddClasses()
</ref>
function).
</p>
<p>
The <var>iVars</var> dictionary lists the instance
variable names and their types.
</p>
</desc>
</function>
<function type="NSArray*" name="GSObjCMethodNames" ovadd="1.0.0">
<arg type="id">obj</arg>
<arg type="BOOL">recurse</arg>
<desc>
This method returns an array listing the names of all
the instance methods available to <var>obj</var>, whether
they belong to the class of <var>obj</var> or one of its
superclasses. <br /> If <var>obj</var> is a
class, this returns the class methods. <br /> Returns
<code>nil</code> if <var>obj</var> is <code>nil</code>
.
</desc>
</function>
<function type="void" name="GSObjCSetVal" ovadd="1.0.0">
<arg type="NSObject*">self</arg>
<arg type="const char*">key</arg>
<arg type="id">val</arg>
<arg type="SEL">sel</arg>
<arg type="const char*">type</arg>
<arg type="unsigned int">size</arg>
<arg type="int">offset</arg>
<desc>
This is used internally by the key-value coding methods,
to set a value in an object either via an accessor method
(if <var>sel</var> is supplied), or via direct access (if
<var>type</var>, <var>size</var>, and <var>offset</var>
are supplied). <br /> Automatic conversion between
NSNumber and C scalar types is performed. <br /> If
<var>type</var> is null and can't be determined from
the selector, the
<ref type="method" id="-handleTakeValue:forUnboundKey:" class="NSObject">[NSObject -handleTakeValue:forUnboundKey:]</ref> method is called to try to set a value.
</desc>
</function>
<function type="void" name="GSObjCSetVariable" ovadd="1.0.0">
<arg type="id">obj</arg>
<arg type="int">offset</arg>
<arg type="unsigned int">size</arg>
<arg type="const void*">data</arg>
<desc>
Sets the value in an instance variable in <var>obj</var>
<br /> This function performs no checking... you
should use it only where you are providing information
from a call to
<ref type="function" id="GSObjCFindVariable">
GSObjCFindVariable()
</ref>
and you know that the <var>data</var> area provided is
the correct <var>size</var>.
</desc>
</function>
<function type="Class" name="GSObjCSuper" ovadd="1.0.0">
<arg type="Class">cls</arg>
<desc>
<ref type="function" id="GSObjCSuper">
GSObjCSuper()
</ref>
is deprecated... use
<ref type="function" id="class_getSuperclass">
class_getSuperclass()
</ref>
</desc>
</function>
<function type="NSArray*" name="GSObjCVariableNames" ovadd="1.0.0">
<arg type="id">obj</arg>
<arg type="BOOL">recurse</arg>
<desc>
This method returns an array listing the names of all
the instance variables present in the instance
<var>obj</var>, whether they belong to the class of
<var>obj</var> or one of its superclasses. <br />
Returns <code>nil</code> if <var>obj</var> is
<code>nil</code>.
</desc>
</function>
<function type="int" name="GSObjCVersion" ovadd="1.0.0">
<arg type="Class">cls</arg>
<desc>
<ref type="function" id="GSObjCVersion">
GSObjCVersion()
</ref>
is deprecated... use
<ref type="function" id="class_getVersion">
class_getVersion()
</ref>
</desc>
</function>
<function type="BOOL" name="GSPrintf" ovadd="1.0.0">
<arg type="FILE*">fptr</arg>
<arg type="NSString*">format</arg>
<vararg />
<desc>
<p>
Prints a message to <var>fptr</var> using the
<var>format</var> string provided and any additional
arguments. The <var>format</var> string is
interpreted as by the NSString formatted
initialisers, and understands the '%@' syntax
for printing an object.
</p>
<p>
The data is written to the file pointer in the default
CString encoding if possible, as a UTF8 string
otherwise.
</p>
<p>
This function is recommended for printing general log
messages. For debug messages use
<ref type="function" id="NSDebugLog">
NSDebugLog()
</ref>
and friends. For error logging use
<ref type="function" id="NSLog">
NSLog()
</ref>
, and for warnings you might consider
<ref type="function" id="NSWarnLog">
NSWarnLog()
</ref>
.
</p>
</desc>
</function>
<function type="Protocol*" name="GSProtocolFromName" ovadd="1.0.0">
<arg type="const char*">name</arg>
<desc>
Returns a protocol object with the corresponding
<var>name</var>. This function searches the registered
classes for any protocol with the supplied
<var>name</var>. If one is found, it is cached in for
future requests. If efficiency is a factor then use
<ref type="function" id="GSRegisterProtocol">
GSRegisterProtocol()
</ref>
to insert a protocol explicitly into the cache used by
this function. If no protocol is found this function
returns <code>nil</code>.
</desc>
</function>
<function type="struct objc_method_description" name="GSProtocolGetMethodDescriptionRecursive" ovadd="1.0.0">
<arg type="Protocol*">aProtocol</arg>
<arg type="SEL">aSel</arg>
<arg type="BOOL">isRequired</arg>
<arg type="BOOL">isInstance</arg>
<desc>
A variant of protocol_getMethodDescription which
recursively searches parent protocols if the
requested selector isn't found in the given
protocol. Returns a {NULL, NULL} structure if the
requested selector couldn't be found.
</desc>
</function>
<function type="void" name="GSRegisterProtocol" ovadd="1.0.0">
<arg type="Protocol*">proto</arg>
<desc>
Registers <var>proto</var> in the cache used by
<ref type="function" id="GSProtocolFromName">
GSProtocolFromName()
</ref>
.
</desc>
</function>
<function type="SEL" name="GSSelectorFromName" ovadd="1.0.0">
<arg type="const char*">name</arg>
<desc>
<ref type="function" id="GSSelectorFromName">
GSSelectorFromName()
</ref>
is deprecated... use
<ref type="function" id="sel_getUid">
sel_getUid()
</ref>
</desc>
</function>
<function type="SEL" name="GSSelectorFromNameAndTypes" ovadd="1.0.0">
<arg type="const char*">name</arg>
<arg type="const char*">types</arg>
<desc>
Return the selector for the specified <var>name</var>
and <var>types</var>. <br /> Returns a nul pointer if the
<var>name</var> is nul. <br /> Creates a new selector
if necessary. <br /> Code must NOT rely on this providing
a selector with type information.
</desc>
</function>
<function type="BOOL" name="GSSelectorTypesMatch" ovadd="1.0.0">
<arg type="const char*">types1</arg>
<arg type="const char*">types2</arg>
<desc>
Compare only the type information ignoring
qualifiers, the frame layout and register
markers. Unlike sel_types_match, this function also
handles comparisons of types with and without any
layout information.
</desc>
</function>
<function type="const char*" name="GSSkipTypeQualifierAndLayoutInfo" ovadd="1.0.0">
<arg type="const char*">types</arg>
<desc>
Takes full type information and skips forward to the
actual type as specified in the _C_... constants.
</desc>
</function>
<function type="const char*" name="GSTypesFromSelector" ovadd="1.0.0">
<arg type="SEL">sel</arg>
<desc>
Return the type information from the specified
selector. <br /> May return a nul pointer if the
selector was a nul pointer or if it was not typed
(or if the runtime does not support typed selectors).
<br /> Code must NOT rely on this providing any type
information.
</desc>
</function>
</chapter>
<!--EndGSObjCRuntimeFunctions-->
<!--StartGSIArrayFunctions-->
<chapter>
<heading>GSIArray functions</heading>
<p></p>
<function type="void" name="GSIArrayAddItem" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<arg type="GSIArrayItem">item</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIArrayAddItemNoRetain" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<arg type="GSIArrayItem">item</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="unsigned int" name="GSIArrayCapacity" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIArrayCheckSort" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<arg type="NSComparisonResult(*)">sorter</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIArrayClear" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="GSIArray" name="GSIArrayCopyWithZone" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<arg type="NSZone*">zone</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="unsigned int" name="GSIArrayCount" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIArrayEmpty" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIArrayGrow" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIArrayGrowTo" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<arg type="unsigned int">next</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="GSIArray" name="GSIArrayInitWithZoneAndCapacity" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<arg type="NSZone*">zone</arg>
<arg type="size_t">capacity</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="GSIArray" name="GSIArrayInitWithZoneAndStaticCapacity" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<arg type="NSZone*">zone</arg>
<arg type="size_t">capacity</arg>
<arg type="GSIArrayItem*">buffer</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIArrayInsertItem" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<arg type="GSIArrayItem">item</arg>
<arg type="unsigned int">index</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIArrayInsertItemNoRetain" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<arg type="GSIArrayItem">item</arg>
<arg type="unsigned int">index</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIArrayInsertSorted" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<arg type="GSIArrayItem">item</arg>
<arg type="NSComparisonResult(*)">sorter</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIArrayInsertSortedNoRetain" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<arg type="GSIArrayItem">item</arg>
<arg type="NSComparisonResult(*)">sorter</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="unsigned int" name="GSIArrayInsertionPosition" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<arg type="GSIArrayItem">item</arg>
<arg type="NSComparisonResult(*)">sorter</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="GSIArrayItem" name="GSIArrayItemAtIndex" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<arg type="unsigned int">index</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="GSIArrayItem*" name="GSIArrayItems" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="GSIArrayItem" name="GSIArrayLastItem" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIArrayRemoveAllItems" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIArrayRemoveItemAtIndex" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<arg type="unsigned int">index</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIArrayRemoveItemAtIndexNoRelease" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<arg type="unsigned int">index</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIArrayRemoveItemsFromIndex" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<arg type="unsigned int">index</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIArrayRemoveLastItem" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="unsigned int" name="GSIArraySearch" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<arg type="GSIArrayItem">item</arg>
<arg type="NSComparisonResult(*)">sorter</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIArraySetItemAtIndex" ovadd="0.0.0">
<arg type="GSIArray">array</arg>
<arg type="GSIArrayItem">item</arg>
<arg type="unsigned int">index</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
</chapter>
<!--EndGSIArrayFunctions-->
<!--StartGSIMapFunctions-->
<chapter>
<heading>GSIMap functions</heading>
<p></p>
<function type="GSIMapNode" name="GSIMapAddKey" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<arg type="GSIMapKey">key</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="GSIMapNode" name="GSIMapAddKeyNoRetain" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<arg type="GSIMapKey">key</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIMapAddNodeToBucket" ovadd="0.0.0">
<arg type="GSIMapBucket">bucket</arg>
<arg type="GSIMapNode">node</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIMapAddNodeToMap" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<arg type="GSIMapNode">node</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="GSIMapNode" name="GSIMapAddPair" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<arg type="GSIMapKey">key</arg>
<arg type="GSIMapVal">value</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="GSIMapNode" name="GSIMapAddPairNoRetain" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<arg type="GSIMapKey">key</arg>
<arg type="GSIMapVal">value</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="GSIMapBucket" name="GSIMapBucketForKey" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<arg type="GSIMapKey">key</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIMapCleanMap" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="NSUInteger" name="GSIMapCountByEnumeratingWithStateObjectsCount" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<arg type="NSFastEnumerationState*">state</arg>
<arg type="id*">stackbuf</arg>
<arg type="NSUInteger">len</arg>
<desc>
Used to implement fast enumeration methods in classes
that use GSIMap for their data storage.
</desc>
</function>
<function type="void" name="GSIMapEmptyMap" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIMapEndEnumerator" ovadd="0.0.0">
<arg type="GSIMapEnumerator">enumerator</arg>
<desc>
Tidies up after map enumeration... effectively
destroys the <var>enumerator</var>.
</desc>
</function>
<function type="GSIMapBucket" name="GSIMapEnumeratorBucket" ovadd="0.0.0">
<arg type="GSIMapEnumerator">enumerator</arg>
<desc>
Returns the bucket from which the next node in the
enumeration will come. Once the next node has
been enumerated, you can use the bucket and node to
remove the node from the map using the
<ref type="function" id="GSIMapRemoveNodeFromMap">
GSIMapRemoveNodeFromMap()
</ref>
function.
</desc>
</function>
<function type="GSIMapEnumerator_t" name="GSIMapEnumeratorForMap" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<desc>
Enumerating <br /> Create an return an enumerator
for the specified <var>map</var>. <br /> You must call
<ref type="function" id="GSIMapEndEnumerator">
GSIMapEndEnumerator()
</ref>
when you have finished with the enumerator. <br />
<strong>WARNING</strong> You should not alter a
<var>map</var> while an enumeration is in progress. The
results of doing so are reasonably unpredictable.
<br /> Remember, DON'T MESS WITH A MAP WHILE YOU'RE
ENUMERATING IT.
</desc>
</function>
<function type="GSIMapNode" name="GSIMapEnumeratorNextNode" ovadd="0.0.0">
<arg type="GSIMapEnumerator">enumerator</arg>
<desc>
Returns the next node in the map, or a nul pointer if
at the end.
</desc>
</function>
<function type="GSIMapNode" name="GSIMapFirstNode" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIMapFreeNode" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<arg type="GSIMapNode">node</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIMapInitWithZoneAndCapacity" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<arg type="NSZone*">zone</arg>
<arg type="uintptr_t">capacity</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIMapLinkNodeIntoBucket" ovadd="0.0.0">
<arg type="GSIMapBucket">bucket</arg>
<arg type="GSIMapNode">node</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIMapMoreNodes" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<arg type="unsigned int">required</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="GSIMapNode" name="GSIMapNodeForKey" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<arg type="GSIMapKey">key</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="GSIMapNode" name="GSIMapNodeForKeyInBucket" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<arg type="GSIMapBucket">bucket</arg>
<arg type="GSIMapKey">key</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="GSIMapNode" name="GSIMapNodeForSimpleKey" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<arg type="GSIMapKey">key</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="GSIMapBucket" name="GSIMapPickBucket" ovadd="0.0.0">
<arg type="unsigned int">hash</arg>
<arg type="GSIMapBucket">buckets</arg>
<arg type="uintptr_t">bucketCount</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIMapRemangleBuckets" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<arg type="GSIMapBucket">old_buckets</arg>
<arg type="uintptr_t">old_bucketCount</arg>
<arg type="GSIMapBucket">new_buckets</arg>
<arg type="uintptr_t">new_bucketCount</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="GSIMapNode" name="GSIMapRemoveAndFreeNode" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<arg type="uintptr_t">bkt</arg>
<arg type="GSIMapNode">node</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="BOOL" name="GSIMapRemoveKey" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<arg type="GSIMapKey">key</arg>
<desc>
Removes the item for the specified <var>key</var>
from the <var>map</var>. If the <var>key</var> was
present, returns <code>YES</code>, otherwise returns
<code>NO</code>.
</desc>
</function>
<function type="void" name="GSIMapRemoveNodeFromBucket" ovadd="0.0.0">
<arg type="GSIMapBucket">bucket</arg>
<arg type="GSIMapNode">node</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIMapRemoveNodeFromMap" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<arg type="GSIMapBucket">bkt</arg>
<arg type="GSIMapNode">node</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIMapRemoveWeak" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIMapResize" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<arg type="uintptr_t">new_capacity</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIMapRightSizeMap" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<arg type="uintptr_t">capacity</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="NSUInteger" name="GSIMapSize" ovadd="0.0.0">
<arg type="GSIMapTable">map</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="void" name="GSIMapUnlinkNodeFromBucket" ovadd="0.0.0">
<arg type="GSIMapBucket">bucket</arg>
<arg type="GSIMapNode">node</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
</chapter>
<!--EndGSIMapFunctions-->
<!--StartGSFunctionsFunctions-->
<chapter>
<heading>GSFunctions functions</heading>
<p></p>
<function type="NSString*" name="GSFindNamedFile" gvadd="0.0.0" gvrem="1.15.0">
<arg type="NSArray*">paths</arg>
<arg type="NSString*">aName</arg>
<arg type="NSString*">anExtension</arg>
<desc>
Try to locate file/directory (aName).(
<var>anExtension</var> (<var>aName</var>).(anExtension)
in <var>paths</var>. Will return the first found or
<code>nil</code> if nothing is found. <br />
Deprecated... may be removed in later release.
</desc>
</function>
</chapter>
<!--EndGSFunctionsFunctions-->
<!--StartGSLocaleFunctions-->
<chapter>
<heading>GSLocale functions</heading>
<p></p>
<function type="NSString*" name="GSDefaultLanguageLocale" ovadd="1.0.0">
<desc>
Returns the locale string for LC_MESSAGES
</desc>
</function>
<function type="NSDictionary*" name="GSDomainFromDefaultLocale" ovadd="1.0.0">
<desc>
Set the current locale to the system default, and backup
what it was previously (should have been @"C"). <br />
Restore the current locale to what we backed up
(again, should be restored to @"C")
</desc>
</function>
<function type="NSString*" name="GSLanguageFromLocale" ovadd="1.0.0">
<arg type="NSString*">locale</arg>
<desc>
Returns a language name string for a given
<var>locale</var>. e.g. GSLanguageFromLocale(@"en_CA")
returns @"CanadaEnglish"
</desc>
</function>
<function type="NSArray*" name="GSLanguagesFromLocale" ovadd="1.0.0">
<arg type="NSString*">locale</arg>
<desc>
Convenience function which calls GSLocaleVariants
to expand the given <var>locale</var> to a list of
variants, and then calls GSLanguageFromLocale on
each. e.g. GSLanguagesFromLocale(@"en_CA") returns
(@"CanadaEnglish", @"English")
</desc>
</function>
<function type="NSArray*" name="GSLocaleVariants" ovadd="1.0.0">
<arg type="NSString*">locale</arg>
<desc>
Return an array of variants of a <var>locale</var>,
formed by stripping off parts of the identifier,
ordered from most similar to least similar. e.g.
GSLocaleVariants(@"en_CA") returns
(@"en_CA", @"en").
</desc>
</function>
<function type="NSString*" name="GSSetLocale" ovadd="1.0.0">
<arg type="int">category</arg>
<arg type="NSString*">locale</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="const char*" name="GSSetLocaleC" ovadd="1.0.0">
<arg type="int">category</arg>
<arg type="const char*">loc</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
</chapter>
<!--EndGSLocaleFunctions-->
<!--StartNSDebug+GNUstepBaseFunctions-->
<chapter>
<heading>NSDebug+GNUstepBase functions</heading>
<p></p>
<function type="NSString*" name="GSDebugFunctionMsg" ovadd="0.0.0">
<arg type="const char*">func</arg>
<arg type="const char*">file</arg>
<arg type="int">line</arg>
<arg type="NSString*">fmt</arg>
<desc>
Used to produce a format string for logging a message
with function location details.
</desc>
</function>
<function type="NSString*" name="GSDebugMethodMsg" ovadd="0.0.0">
<arg type="id">obj</arg>
<arg type="SEL">sel</arg>
<arg type="const char*">file</arg>
<arg type="int">line</arg>
<arg type="NSString*">fmt</arg>
<desc>
Used to produce a format string for logging a message
with method location details.
</desc>
</function>
<function type="BOOL" name="GSDebugSet" ovadd="0.0.0">
<arg type="NSString*">level</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
</chapter>
<!--EndNSDebug+GNUstepBaseFunctions-->
<!--StartNSThread+GNUstepBaseFunctions-->
<chapter>
<heading>NSThread+GNUstepBase functions</heading>
<p></p>
<function type="NSThread*" name="GSCurrentThread" ovadd="0.0.0">
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="NSMutableDictionary*" name="GSCurrentThreadDictionary" ovadd="0.0.0">
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
</chapter>
<!--EndNSThread+GNUstepBaseFunctions-->
<!--StartUnicodeFunctions-->
<chapter>
<heading>Unicode functions</heading>
<p></p>
<function type="NSStringEncoding" name="GSEncodingForRegistry" ovadd="0.0.0" gvadd="0.0.0" gvrem="1.15.0">
<arg type="NSString*">registry</arg>
<arg type="NSString*">encoding</arg>
<desc>
Returns the NSStringEncoding that matches the
specified character set <var>registry</var> and
<var>encoding</var> information. For instance, for the
iso8859-5 character set, the <var>registry</var> is
iso8859 and the <var>encoding</var> is 5, and the
returned NSStringEncoding is
NSISOCyrillicStringEncoding. If
there is no specific <var>encoding</var>, use @"0".
Returns GSUndefinedEncoding if there is no match.
</desc>
</function>
<function type="NSStringEncoding" name="GSEncodingFromLocale" ovadd="0.0.0" gvadd="0.0.0" gvrem="1.15.0">
<arg type="const char*">clocale</arg>
<desc>
Try to deduce the string encoding from the locale string
<var>clocale</var>. This function looks in the
Locale.encodings file installed as part of
GNUstep Base if the encoding cannot be deduced from
the <var>clocale</var> string itself. If
<var>clocale</var> isn't set or no match can be found,
returns GSUndefinedEncoding.
</desc>
</function>
<function type="BOOL" name="GSFromUnicode" ovadd="0.0.0">
<arg type="unsigned char**">dst</arg>
<arg type="unsigned int*">size</arg>
<arg type="const unichar*">src</arg>
<arg type="unsigned int">slen</arg>
<arg type="NSStringEncoding">enc</arg>
<arg type="NSZone*">zone</arg>
<arg type="unsigned int">options</arg>
<desc>
Function to convert from 16-bit unicode to 8-bit
data.
<p>
The <var>dst</var> argument is a pointer to a pointer
to a buffer in which the converted data is to be stored.
If it is a null pointer, this function discards
converted data, and is used only to determine the
length of the converted data. If the <var>zone</var>
argument is non-nul, the function is free to
allocate a larger buffer if necessary, and store
this new buffer in the <var>dst</var> argument. It
will *NOT* deallocate the original buffer!
</p>
<p>
The <var>size</var> argument is a pointer to the
initial <var>size</var> of the destination buffer.
If the function changes the buffer <var>size</var>, this
value will be altered to the new <var>size</var>.
This is measured in bytes.
</p>
<p>
The <var>src</var> argument is a pointer to the 16-bit
unicode string which is to be converted to 8-bit
data.
</p>
<p>
The <var>slen</var> argument is the length of the
16-bit unicode string which is to be converted to
8-bit data. This is measured in 16-bit characters,
not bytes.
</p>
<p>
The <var>enc</var> argument specifies the encoding type
of the 8-bit byte sequence which is to be produced from
the 16-bit unicode.
</p>
<p>
The <var>zone</var> argument specifies a memory
<var>zone</var> in which the function may allocate a
buffer to return data in. If this is nul, the
function will fail if the originally supplied
buffer is not big enough (unless <var>dst</var> is a
null pointer... indicating that converted data is to
be discarded). <br /> If the library is built for
garbage collecting, the <var>zone</var> argument is
used only as a marker to say whether the function may
allocate memory (<var>zone</var> is non-null) or
not (<var>zone</var> is null).
</p>
The <var>options</var> argument controls some special
behavior.
<list>
<item>
If GSUniStrict is set, the function will fail if a
character is encountered in the source which
can't be converted. Otherwise, some approximation
or marker will be placed in the destination.
</item>
<item>
If GSUniTerminate is set, the function is expected to
nul terminate the output data, and will assume that
it is safe to place the nul just beyond the end of the
stated buffer <var>size</var>. Also, if the
function grows the buffer, it will allow for an
extra termination byte.
</item>
<item>
If GSUniTemporary is set, the function will return the
results in an autoreleased buffer rather than in
a buffer that the caller must release.
</item>
<item>
If GSUniBOM is set, the function will read the first
unicode character as a byte order marker.
</item>
<item>
If GSUniShortOk is set, the function will return a
buffer containing any decoded characters even if
the whole conversion fails.
</item>
</list>
<p>
On return, the function result is a flag indicating
success (<code>YES</code>) or failure (
<code>NO</code>), and on success, the value stored
in <var>size</var> is the number of bytes in the
converted data. The converted data itself is
stored in the location given by <var>dst</var>.
<br /> NB. If the value stored in <var>dst</var> has
been changed, it is a pointer to allocated memory
which the caller is responsible for freeing, and the
caller is <em>still</em> responsible for freeing the
original buffer.
</p>
</desc>
</function>
<function type="BOOL" name="GSToUnicode" ovadd="0.0.0">
<arg type="unichar**">dst</arg>
<arg type="unsigned int*">size</arg>
<arg type="const unsigned char*">src</arg>
<arg type="unsigned int">slen</arg>
<arg type="NSStringEncoding">enc</arg>
<arg type="NSZone*">zone</arg>
<arg type="unsigned int">options</arg>
<desc>
Function to convert from 8-bit data to 16-bit
unicode characters.
<p>
The <var>dst</var> argument is a pointer to a pointer
to a buffer in which the converted string is to be
stored. If it is a null pointer, this function
discards converted data, and is used only to
determine the length of the converted string. If
the <var>zone</var> argument is non-nul, the function
is free to allocate a larger buffer if necessary, and
store this new buffer in the <var>dst</var> argument.
It will *NOT* deallocate the original buffer!
</p>
<p>
The <var>size</var> argument is a pointer to the
initial <var>size</var> of the destination buffer.
If the function changes the buffer <var>size</var>, this
value will be altered to the new <var>size</var>.
This is measured in 16-bit unicode characters, not
bytes.
</p>
<p>
The <var>src</var> argument is a pointer to the byte
sequence which is to be converted to 16-bit
unicode.
</p>
<p>
The <var>slen</var> argument is the length of the byte
sequence which is to be converted to 16-bit
unicode. This is measured in bytes.
</p>
<p>
The <var>enc</var> argument specifies the encoding type
of the 8-bit byte sequence which is to be converted to
16-bit unicode.
</p>
<p>
The <var>zone</var> argument specifies a memory
<var>zone</var> in which the function may allocate a
buffer to return data in. If this is nul, the
function will fail if the originally supplied
buffer is not big enough (unless <var>dst</var> is a
null pointer... indicating that converted data is to
be discarded). <br /> If the library is built for
garbage collecting, the <var>zone</var> argument is
used only as a marker to say whether the function may
allocate memory (<var>zone</var> is non-null) or
not (<var>zone</var> is null).
</p>
The <var>options</var> argument controls some special
behavior.
<list>
<item>
If GSUniTerminate is set, the function is expected to
null terminate the output string, and will assume
that it is safe to place the nul just beyond the end
of the stated buffer <var>size</var>. Also, if the
function grows the buffer, it will allow for an
extra termination character.
</item>
<item>
If GSUniTemporary is set, the function will return the
results in an autoreleased buffer rather than in
a buffer that the caller must release.
</item>
<item>
If GSUniBOM is set, the function will write the first
unicode character as a byte order marker.
</item>
<item>
If GSUniShortOk is set, the function will return a
buffer containing any decoded characters even if
the whole conversion fails.
</item>
</list>
<p>
On return, the function result is a flag indicating
success (<code>YES</code>) or failure (
<code>NO</code>), and on success, the value stored
in <var>size</var> is the number of characters in the
converted string. The converted string itself is
stored in the location given by <var>dst</var>.
<br /> NB. If the value stored in <var>dst</var> has
been changed, it is a pointer to allocated memory
which the caller is responsible for freeing, and the
caller is <em>still</em> responsible for freeing the
original buffer.
</p>
</desc>
</function>
<function type="unsigned int" name="GSUnicode" ovadd="0.0.0" gvadd="0.0.0" gvrem="1.15.0">
<arg type="const unichar*">chars</arg>
<arg type="unsigned int">length</arg>
<arg type="BOOL*">isASCII</arg>
<arg type="BOOL*">isLatin1</arg>
<desc>
Function to check a block of data for validity as a
unicode string and say whether it contains solely
ASCII or solely Latin1 data. <br /> Any leading BOM
must already have been removed and the data must already
be in native byte order. <br /> Returns the number of
characters which were found valid.
</desc>
</function>
<function type="unsigned char" name="uni_cop" ovadd="0.0.0" gvadd="0.0.0" gvrem="1.15.0">
<arg type="unichar">u</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="unichar*" name="uni_is_decomp" ovadd="0.0.0" gvadd="0.0.0" gvrem="1.15.0">
<arg type="unichar">u</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="BOOL" name="uni_isnonsp" ovadd="0.0.0" gvadd="0.0.0" gvrem="1.15.0">
<arg type="unichar">u</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</function>
<function type="unichar" name="uni_tolower" ovadd="0.0.0" gvadd="0.0.0" gvrem="1.15.0">
<arg type="unichar">ch</arg>
<desc>
Uses direct access into a two-level table to map cases.
<br /> The two-level table method is less space
efficient (but still not bad) than a single table
and a linear search, but it reduces the number of
conditional statements to just one.
</desc>
</function>
<function type="unichar" name="uni_toupper" ovadd="0.0.0" gvadd="0.0.0" gvrem="1.15.0">
<arg type="unichar">ch</arg>
<desc>
Uses direct access into a two-level table to map cases.
<br /> The two-level table method is less space
efficient (but still not bad) than a single table
and a linear search, but it reduces the number of
conditional statements to just one.
</desc>
</function>
</chapter>
<!--EndUnicodeFunctions-->
<!--EndFunctions-->
</body>
</gsdoc>
Server : Apache/2.4.41 (Ubuntu)