Up
Authors
- Richard Frith-Macdonald
-
Copyright: (C) 2005 Free Software Foundation, Inc.
ASSIGN(object, value)
Availability: OpenStep
ASSIGN(object,value) assigns the
value to the object with
appropriate retain and release operations.
ASSIGNCOPY(object, value)
Availability: OpenStep
ASSIGNCOPY(object,value) assigns a
copy of the value to the object
with release of the original.
AUTORELEASE(object)
Availability: OpenStep
Basic autorelease operation... calls
[NSObject -autorelease]
CREATE_AUTORELEASE_POOL(X)
Availability: OpenStep
Declares an autorelease pool variable and creates
and initialises an autorelease pool object.
DESTROY(object)
Availability: OpenStep
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.
GSLocalizedStaticString(key, comment)
Availability: OpenStep
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 = GSLocalizedStaticString
(@"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
GSLocalizedStaticString
call.
When the code is compiled, instead, the
GSLocalizedStaticString
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.
RECREATE_AUTORELEASE_POOL(X)
Availability: OpenStep
Similar, but allows reuse of variables. This
destroys the old pool before creating the new one.
RELEASE(object)
Availability: OpenStep
Basic release operation... calls
[NSObject -release]
RETAIN(object)
Availability: OpenStep
Basic retain operation... calls
[NSObject -retain]
TEST_AUTORELEASE(object)
Availability: OpenStep
Tested autorelease - only invoke the objective-c
method if the receiver is not nil
.
TEST_RELEASE(object)
Availability: OpenStep
Tested release - only invoke the objective-c method if
the receiver is not nil
.
TEST_RETAIN(object)
Availability: OpenStep
Tested retain - only invoke the objective-c method if
the receiver is not nil
.
_(X)
Availability: OpenStep
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)
Availability: OpenStep
This function (macro) is a GNUstep extension.
__(@"My string to translate")
is exactly the same as
GSLocalizedStaticString (@"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
GSLocalizedStaticString
instead when
you need a comment.
GS_MAX_OBJECTS_FROM_STACK
Availability: BaseAdditions
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
GS_USEIDLIST(firstObject, code,...)
Availability: BaseAdditions
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.
The objects
are unpacked from the vararg list into a 'C' array and
then a code fragment you specify is able to
make use of them before that 'C' array is destroyed.
The firstObject argument is the name of the
formal parameter in your method or function which
precedes the ',...' denoting variable args.
The code argument is a piece of objective-c
code to be executed to make use of the
objects stored in the 'C' array.
When this
code is called the
unsigned integer '__count' will
contain the number of objects unpacked, and the
pointer '__objects' will point to the unpacked
objects, ie. firstObject followed by
the vararg arguments up to (but not including) the
first nil
.
GS_USEIDPAIRLIST(firstObject, code,...)
Availability: BaseAdditions
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.
The objects
are unpacked from the vararg list into two 'C' arrays
and then a code fragment you specify is able
to make use of them before that 'C' array is destroyed.
The firstObject argument is the name of the
formal parameter in your method or function which
precedes the ',...' denoting variable args.
The code argument is a piece of objective-c
code to be executed to make use of the
objects stored in the 'C' arrays.
When this
code is called the
unsigned 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'.
This lets you pack a list of the form 'key,
value, key, value,...' into an array of keys and an
array of values.
GS_API_LATEST
Availability: OpenStep
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
Availability: OpenStep
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
Availability: OpenStep
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.
eg.
#if
OS_API_VERSION
(GS_API_NONE, GS_API_NONE)
denotes code
not present in OpenStep/OPENSTEP/MacOS-X
GS_API_OPENSTEP
Availability: 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
Availability: OpenStep
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)
Availability: OpenStep
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)
Availability: OpenStep
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
NSThread* GSCurrentThread();
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
NSMutableDictionary* GSCurrentThreadDictionary();
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
NSString* GSDebugFunctionMsg(const char* func, const char* file, int line, NSString* fmt);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
NSString* GSDebugMethodMsg(id obj, SEL sel, const char* file, int line, NSString* fmt);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
BOOL GSDebugSet(NSString* level);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void NSDecimalFromComponents(NSDecimal* result, unsigned long long int mantissa, short int exponent, BOOL negative);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
NSArray* NSStandardLibraryPaths();
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIArrayAddItem(GSIArray array, GSIArrayItem item);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIArrayAddItemNoRetain(GSIArray array, GSIArrayItem item);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
unsigned int GSIArrayCapacity(GSIArray array);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIArrayCheckSort(GSIArray array, NSComparisonResult(*) sorter);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIArrayClear(GSIArray array);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
GSIArray GSIArrayCopyWithZone(GSIArray array, NSZone* zone);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
unsigned int GSIArrayCount(GSIArray array);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIArrayEmpty(GSIArray array);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIArrayGrow(GSIArray array);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIArrayGrowTo(GSIArray array, unsigned int next);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
GSIArray GSIArrayInitWithZoneAndCapacity(GSIArray array, NSZone* zone, size_t capacity);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
GSIArray GSIArrayInitWithZoneAndStaticCapacity(GSIArray array, NSZone* zone, size_t capacity, GSIArrayItem* buffer);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIArrayInsertItem(GSIArray array, GSIArrayItem item, unsigned int index);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIArrayInsertItemNoRetain(GSIArray array, GSIArrayItem item, unsigned int index);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIArrayInsertSorted(GSIArray array, GSIArrayItem item, NSComparisonResult(*) sorter);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIArrayInsertSortedNoRetain(GSIArray array, GSIArrayItem item, NSComparisonResult(*) sorter);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
unsigned int GSIArrayInsertionPosition(GSIArray array, GSIArrayItem item, NSComparisonResult(*) sorter);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
GSIArrayItem GSIArrayItemAtIndex(GSIArray array, unsigned int index);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
GSIArrayItem* GSIArrayItems(GSIArray array);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
GSIArrayItem GSIArrayLastItem(GSIArray array);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIArrayRemoveAllItems(GSIArray array);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIArrayRemoveItemAtIndex(GSIArray array, unsigned int index);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIArrayRemoveItemAtIndexNoRelease(GSIArray array, unsigned int index);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIArrayRemoveItemsFromIndex(GSIArray array, unsigned int index);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIArrayRemoveLastItem(GSIArray array);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
unsigned int GSIArraySearch(GSIArray array, GSIArrayItem item, NSComparisonResult(*) sorter);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIArraySetItemAtIndex(GSIArray array, GSIArrayItem item, unsigned int index);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
GSIMapNode GSIMapAddKey(GSIMapTable map, GSIMapKey key);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
GSIMapNode GSIMapAddKeyNoRetain(GSIMapTable map, GSIMapKey key);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIMapAddNodeToBucket(GSIMapBucket bucket, GSIMapNode node);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIMapAddNodeToMap(GSIMapTable map, GSIMapNode node);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
GSIMapNode GSIMapAddPair(GSIMapTable map, GSIMapKey key, GSIMapVal value);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
GSIMapNode GSIMapAddPairNoRetain(GSIMapTable map, GSIMapKey key, GSIMapVal value);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
GSIMapBucket GSIMapBucketForKey(GSIMapTable map, GSIMapKey key);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIMapCleanMap(GSIMapTable map);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIMapEmptyMap(GSIMapTable map);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIMapEndEnumerator(GSIMapEnumerator enumerator);
Availability: Not in OpenStep/MacOS-X
Tidies up after map enumeration... effectively
destroys the enumerator.
GSIMapBucket GSIMapEnumeratorBucket(GSIMapEnumerator enumerator);
Availability: Not in OpenStep/MacOS-X
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
GSIMapRemoveNodeFromMap()
function.
GSIMapEnumerator_t GSIMapEnumeratorForMap(GSIMapTable map);
Availability: Not in OpenStep/MacOS-X
Enumerating
Create an return an enumerator
for the specified
map.
You must call
GSIMapEndEnumerator()
when you have finished with the enumerator.
WARNING You should not alter a
map while an enumeration is in progress. The
results of doing so are reasonably unpredictable.
Remember, DON'T MESS WITH A MAP WHILE YOU'RE
ENUMERATING IT.
GSIMapNode GSIMapEnumeratorNextNode(GSIMapEnumerator enumerator);
Availability: Not in OpenStep/MacOS-X
Returns the next node in the map, or a nul pointer if
at the end.
GSIMapNode GSIMapFirstNode(GSIMapTable map);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIMapFreeNode(GSIMapTable map, GSIMapNode node);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIMapInitWithZoneAndCapacity(GSIMapTable map, NSZone* zone, uintptr_t capacity);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIMapLinkNodeIntoBucket(GSIMapBucket bucket, GSIMapNode node);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIMapMoreNodes(GSIMapTable map, unsigned int required);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
GSIMapNode GSIMapNodeForKey(GSIMapTable map, GSIMapKey key);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
GSIMapNode GSIMapNodeForKeyInBucket(GSIMapTable map, GSIMapBucket bucket, GSIMapKey key);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
GSIMapNode GSIMapNodeForSimpleKey(GSIMapTable map, GSIMapKey key);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
GSIMapBucket GSIMapPickBucket(unsigned int hash, GSIMapBucket buckets, uintptr_t bucketCount);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIMapRemangleBuckets(GSIMapTable map, GSIMapBucket old_buckets, uintptr_t old_bucketCount, GSIMapBucket new_buckets, uintptr_t new_bucketCount);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
GSIMapNode GSIMapRemoveAndFreeNode(GSIMapTable map, uintptr_t bkt, GSIMapNode node);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
BOOL GSIMapRemoveKey(GSIMapTable map, GSIMapKey key);
Availability: Not in OpenStep/MacOS-X
Removes the item for the specified key
from the map. If the key was
present, returns YES
, otherwise returns
NO
.
void GSIMapRemoveNodeFromBucket(GSIMapBucket bucket, GSIMapNode node);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIMapRemoveNodeFromMap(GSIMapTable map, GSIMapBucket bkt, GSIMapNode node);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIMapResize(GSIMapTable map, uintptr_t new_capacity);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIMapRightSizeMap(GSIMapTable map, uintptr_t capacity);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSIMapUnlinkNodeFromBucket(GSIMapBucket bucket, GSIMapNode node);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void GSAddMethodList(Class cls, GSMethodList list, BOOL toInstanceMethods);
Availability: BaseAdditions
Add the method list to the class as the
first list to be searched during method
invocation for the given class. Depending on
toInstanceMethods, this list
will be added as an instance or a class method
list. If the list is in use by
another class, behavior is undefined. Create a new
list with
GSAllocMethodList()
or use
GSRemoveMethodList()
to remove a list before inserting it in a
class.
After method list manipulation you should
call
GSFlushMethodCacheForClass()
for the changes to take effect.
This function should currently (June 2004) be
considered WIP. Please follow potential changes
(Name, parameters,...) closely until it stabilizes.
GSMethodList GSAllocMethodList(unsigned int count);
Availability: BaseAdditions
Returns a pointer to objc_malloc'ed memory large
enough to hold a struct objc_method_list with
'count' number of struct objc_method entries. The
memory returned is initialized with 0, including the
method count and next method list fields.
This function is intended for use in conjunction with
GSAppendMethodToList()
to fill the memory and
GSAddMethodList()
to activate the method list.
After method list manipulation you should call
GSFlushMethodCacheForClass()
for the changes to take effect.
WARNING: Manipulating the runtime structures
can be hazardous!
This function should currently (June 2004) be
considered WIP. Please follow potential changes
(Name, parameters,...) closely until it stabilizes.
void GSAllocateMutexAt(objc_mutex_t* request);
Availability: BaseAdditions
Allocate a new objc_mutex_t and store it in the
location pointed to by
request. A mutex
is only created if the value pointed to by
request is NULL. This function is thread
safe in the sense that multiple threads my call this
function with the same value of
request
and only one will actually set the mutex. It is the users
responsibility that no one else attempts to
set the mutex pointed to. This function should be used
with objc_mutex_t variables which were statically
initialized to NULL like:
void function (void)
{
static objc_mutex_t my_lock = NULL;
if (my_lock == NULL)
GSAllocateMutexAt(&my_lock);
objc_mutex_lock(my_lock);
do_work ();
objc_mutex_unlock(my_lock);
}
void GSAppendMethodToList(GSMethodList list, SEL sel, const char* types, IMP imp, BOOL isFree);
Availability: BaseAdditions
Inserts the method described by sel,
types and imp into the slot of
the list's method_count incremented by 1. This function
does not and cannot check whether the list
provided has the necessary capacity.
The GNU runtime makes a difference between method lists
that are "free standing" and those that "attached" to
classes. For "free standing" method lists (e.g.
created with
GSAllocMethodList()
that have not been added to a class or those which
have been removed via GSRemoveMethodList())
isFree must be passed YES
.
When manipulating "attached" method lists, specify
NO
.
This function is intended for use in conjunction with
GSAllocMethodList()
to allocate the list and
GSAddMethodList()
to activate the method list.
After method list manipulation you should
call
GSFlushMethodCacheForClass()
for the changes to take effect.
WARNING: Manipulating the runtime structures
can be hazardous!
This function should currently (June 2004) be
considered WIP. Please follow potential changes
(Name, parameters,...) closely until it stabilizes.
void* GSAutoreleasedBuffer(unsigned int size);
Availability: BaseAdditions
Quickly return autoreleased data storage area.
GSIVar GSCGetInstanceVariableDefinition(Class cls, const char* name);
Availability: BaseAdditions
Returns the pointer to the instance variable
structure for the instance variable name
in the specified class. This function searches the
specified class and its superclasses.
It
should be safe to use this function in
+load
implementations.
This function should
currently (June 2003) be considered WIP. Please
follow potential changes (Name, parameters,...)
closely until it stabilizes.
Class GSClassFromName(const char* name);
Availability: BaseAdditions
Given a class name, return the corresponding
class or a nul pointer if the class cannot be found.
If the argument is nil
, return a
nul pointer.
unsigned int GSClassList(Class* buffer, unsigned int max, BOOL clearCache);
Availability: BaseAdditions
Fills a nil
terminated array of
Class objects referenced by
buffer with max number of classes
registered with the objc runtime. The provided
buffer must be large enough to hold
max + 1 Class objects. If
buffer is nil
, the function
returns the number of Class objects
that would be inserted if the buffer is large
enough. Otherwise returns the number of
Class objects that did not fit into
the provided buffer. This function keeps a
cache of the class list for future invocations when
used with the GNU runtime. If clearCache is
YES
, this cache will be invalidated and
rebuild. The flag has no effect for the NeXT
runtime. This function is provided as consistent API
to both runtimes. In the case of the GNU runtime it is
likely more efficient to use
objc_next_class()
to iterate over the classes.
const char* GSClassNameFromObject(id obj);
Availability: BaseAdditions
Return the name of the object's class, or a nul
pointer if no object was supplied.
void GSFlushMethodCacheForClass(Class cls);
Availability: BaseAdditions
Flushes the cached method dispatch table for the
class. Call this function after any manipulations in
the method structures.
It should be safe to use
this function in
+load
implementations.
This function should
currently (June 2003) be considered WIP. Please
follow potential changes (Name, parameters,...)
closely until it stabilizes.
GSMethod GSGetMethod(Class cls, SEL sel, BOOL searchInstanceMethods, BOOL searchSuperClasses);
Availability: BaseAdditions
Returns the pointer to the method structure for the
selector in the specified class. Depending on
searchInstanceMethods, this function
searches either instance or class methods. Depending
on searchSuperClassesm this function searches either the
specified class only or also its superclasses.
To obtain the implementation pointer IMP use
returnValue->method_imp which should
be safe across all runtimes.
It should be safe to
use this function in
+load
implementations.
This function should
currently (June 2004) be considered WIP. Please
follow potential changes (Name, parameters,...)
closely until it stabilizes.
const char* GSLastErrorStr(long int error_id);
Availability: BaseAdditions
Likely to be changed/moved/removed at 1.15.0
Description forthcoming.
GSMethod GSMethodFromList(GSMethodList list, SEL sel, BOOL isFree);
Availability: BaseAdditions
Returns the (first) GSMethod contained in the
supplied list that corresponds to
sel. Returns NULL if none is found.
The GNU runtime makes a difference between method lists
that are "free standing" and those that "attached" to
classes. For "free standing" method lists (e.g.
created with
GSAllocMethodList()
that have not been added to a class or those which
have been removed via GSRemoveMethodList())
isFree must be passed YES
.
When manipulating "attached" method lists, specify
NO
.
GSMethodList GSMethodListForSelector(Class cls, SEL selector, void** iterator, BOOL searchInstanceMethods);
Availability: BaseAdditions
Returns a method list of the class that contains
the selector. Depending on
searchInstanceMethods either instance or
class methods are searched. Returns NULL if none are
found. This function does not search the
superclasses method lists. Call this method
with the address of a
void *
pointing to
NULL to obtain the first (active) method list
containing the selector. Subsequent
calls will return further method lists which contain
the selector. If none are found, it returns
NULL. You may instead pass NULL as the
iterator in which case the first method
list containing the selector will be
returned. Do not call it with an uninitialized
iterator. If either class or
selector are NULL the function returns
NULL. If subsequent calls to this function with the
same non-NULL iterator yet different
searchInstanceMethods value are called,
the behavior is undefined.
This function should currently (June 2004) be
considered WIP. Please follow potential changes
(Name, parameters,...) closely until it stabilizes.
const char* GSNameFromClass(Class cls);
Availability: BaseAdditions
Return the name of the supplied class, or a nul
pointer if no class was supplied.
const char* GSNameFromSelector(SEL sel);
Availability: BaseAdditions
Return the name of the supplied selector, or a nul
pointer if no selector was supplied.
void GSObjCAddClassBehavior(Class receiver, Class behavior);
Availability: BaseAdditions
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.
Behavior methods, when added to a class, override
the class's superclass methods, but not the class's
methods.
It's not the case that a class adding behaviors from
another class must have "no instance vars". The
receiver class just has to have the same
layout as the behavior class (optionally
with some additional ivars after those of the
behavior class).
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
behavior argument.
This function should be called in the
+initialize
method of the receiver.
If you add several behaviors to a class, be aware that
the order of the additions is significant.
void GSObjCAddClasses(NSArray* classes);
Availability: BaseAdditions
Description forthcoming.
NSArray* GSObjCAllSubclassesOfClass(Class cls);
Availability: BaseAdditions
Returns an autoreleased array of subclasses of
Class cls, including
subclasses of subclasses.
Class GSObjCClass(id obj);
Availability: BaseAdditions
GSObjCClass()
return the class of an instance. Returns a nul pointer
if the argument is
nil
.
NSArray* GSObjCDirectSubclassesOfClass(Class cls);
Availability: BaseAdditions
Returns an autoreleased array containing subclasses
directly descendent of Class
cls.
BOOL GSObjCFindVariable(id obj, const char* name, const char** type, unsigned int* size, int* offset);
Availability: BaseAdditions
This function is used to locate information about the
instance variable of obj called
name. It returns YES
if the
variable was found, NO
otherwise. If it
returns YES
, then the values pointed to
by type, size, and offset
will be set (except where they are null pointers).
GSIVar GSObjCGetInstanceVariableDefinition(Class cls, NSString* name);
Availability: BaseAdditions
Returns the pointer to the instance variable
structure for the instance variable name
in the specified class. This function searches the
specified class and its superclasses.
It is
not necessarily safe to use this function in
+load
implementations.
This function should
currently (June 2003) be considered WIP. Please
follow potential changes (Name, parameters,...)
closely until it stabilizes.
id GSObjCGetVal(NSObject* self, const char* key, SEL sel, const char* type, unsigned int size, int offset);
Availability: BaseAdditions
This is used internally by the key-value coding methods,
to get a value from an object either via an accessor
method (if sel is supplied), or via direct
access (if type, size, and
offset are supplied).
Automatic
conversion between NSNumber and C scalar types is
performed.
If type is null and
can't be determined from the selector, the
[NSObject -handleQueryWithUnboundKey:]
method is called to try to get a value.
void GSObjCGetVariable(id obj, int offset, unsigned int size, void* data);
Availability: BaseAdditions
Gets the value from an instance variable in
obj This function performs no
checking... you should use it only where you are
providing information from a call to
GSObjCFindVariable()
and you know that the
data area provided is
the correct
size.
BOOL GSObjCIsClass(Class cls);
Availability: BaseAdditions
GSObjCIsClass()
tests to see if an
id is a class.
Returns
NO
if the argument is
nil
.
BOOL GSObjCIsInstance(id obj);
Availability: BaseAdditions
GSObjCIsInstance()
tests to see if an
id is an instance.
Returns
NO
if the argument is
nil
.
BOOL GSObjCIsKindOf(Class cls, Class other);
Availability: BaseAdditions
GSObjCIsKindOf()
tests to see if a class inherits from another class The
argument to this function must NOT be
nil
.
NSValue* GSObjCMakeClass(NSString* name, NSString* superName, NSDictionary* iVars);
Availability: BaseAdditions
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
Create a Class 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 GSObjCAddClasses()
function).
The iVars dictionary lists the instance variable names and their types.
NSArray* GSObjCMethodNames(id obj);
Availability: BaseAdditions
This method returns an array listing the names of all
the instance methods available to obj, whether
they belong to the class of obj or one of its
superclasses.
If obj is a
class, this returns the class methods.
Returns
nil
if obj is nil
.
void GSObjCSetVal(NSObject* self, const char* key, id val, SEL sel, const char* type, unsigned int size, int offset);
Availability: BaseAdditions
This is used internally by the key-value coding methods,
to set a value in an object either via an accessor method
(if sel is supplied), or via direct access (if
type, size, and offset
are supplied).
Automatic conversion between
NSNumber and C scalar types is performed.
If
type is null and can't be determined from
the selector, the
[NSObject -handleTakeValue:forUnboundKey:]
method is called to try to set a value.
void GSObjCSetVariable(id obj, int offset, unsigned int size, const void* data);
Availability: BaseAdditions
Sets the value in an instance variable in
obj
This function performs no checking... you
should use it only where you are providing information
from a call to
GSObjCFindVariable()
and you know that the
data area provided is
the correct
size.
Class GSObjCSuper(Class cls);
Availability: BaseAdditions
Returns the superclass of this.
NSArray* GSObjCVariableNames(id obj);
Availability: BaseAdditions
This method returns an array listing the names of all
the instance variables present in the instance
obj, whether they belong to the class of
obj or one of its superclasses.
Returns nil
if obj is
nil
.
int GSObjCVersion(Class cls);
Availability: BaseAdditions
Returns the version number of this.
NSZone* GSObjCZone(NSObject* obj);
Availability: BaseAdditions
Return the zone in which an object belongs, without
using the zone method
BOOL GSPrintf(FILE* fptr, NSString* format,...);
Availability: BaseAdditions
Prints a message to fptr using the
format string provided and any additional
arguments. The format string is
interpreted as by the NSString formatted
initialisers, and understands the '%@' syntax
for printing an object.
The data is written to the file pointer in the default
CString encoding if possible, as a UTF8 string
otherwise.
This function is recommended for printing general log
messages. For debug messages use
NSDebugLog()
and friends. For error logging use
NSLog()
, and for warnings you might consider
NSWarnLog()
.
Protocol* GSProtocolFromName(const char* name);
Availability: BaseAdditions
Returns a protocol object with the corresponding
name. This function searches the registered
classes for any protocol with the supplied
name. If one is found, it is cached in for
future requests. If efficiency is a factor then use
GSRegisterProtocol()
to insert a protocol explicitly into the cache used by
this function. If no protocol is found this function
returns
nil
.
void GSRegisterProtocol(Protocol* proto);
Availability: BaseAdditions
BOOL GSRemoveMethodFromList(GSMethodList list, SEL sel, BOOL isFree);
Availability: BaseAdditions
Removes the method identified by sel
from the method list moving the following
methods up in the list, leaving the last
entry blank. After this call, all references of
previous
GSMethodFromList()
calls with this list should be considered
invalid. If the values they referenced are needed,
they must be copied to external buffers before this
function is called.
Returns YES
if the a matching method
was found a removed, NO
otherwise.
The GNU runtime makes a difference between method lists
that are "free standing" and those that "attached" to
classes. For "free standing" method lists (e.g.
created with
GSAllocMethodList()
that have not been added to a class or those which
have been removed via GSRemoveMethodList())
isFree must be passed YES
.
When manipulating "attached" method lists, specify
NO
.
After method list manipulation you should
call
GSFlushMethodCacheForClass()
for the changes to take effect.
WARNING: Manipulating the runtime structures
can be hazardous!
This function should currently (June 2004) be
considered WIP. Please follow potential changes
(Name, parameters,...) closely until it stabilizes.
void GSRemoveMethodList(Class cls, GSMethodList list, BOOL fromInstanceMethods);
Availability: BaseAdditions
Removes the method list from the classes
instance or class method lists depending on
fromInstanceMethods. If the
list is not part of the class, behavior is
undefined.
After method list manipulation you should
call
GSFlushMethodCacheForClass()
for the changes to take effect.
This function should currently (June 2004) be
considered WIP. Please follow potential changes
(Name, parameters,...) closely until it stabilizes.
SEL GSSelectorFromName(const char* name);
Availability: BaseAdditions
Return a selector matching the specified
name, or nil
if no
name is supplied. The returned selector
could be any one with the name.
If no
selector exists, returns nil
.
SEL GSSelectorFromNameAndTypes(const char* name, const char* types);
Availability: BaseAdditions
Return the selector for the specified name
and types. Returns a nul pointer if the
name is nul. Uses any available selector if
the types argument is nul.
Creates a
new selector if necessary.
BOOL GSSelectorTypesMatch(const char* types1, const char* types2);
Availability: BaseAdditions
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.
const char* GSTypesFromSelector(SEL sel);
Availability: BaseAdditions
Return the type information from the specified
selector. May return a nul pointer if the selector
was a nul pointer or if it was not typed.
void behavior_class_add_category(Class class, struct objc_category* category);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void behavior_class_add_class(Class class, Class behavior);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void behavior_class_add_methods(Class class, struct objc_method_list* methods);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
void behavior_set_debug(int i);
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
NSStringEncoding GSEncodingForRegistry(NSString* registry, NSString* encoding);
Availability: Not in OpenStep/MacOS-X, BaseAdditions Likely to be changed/moved/removed at 1.15.0
Returns the NSStringEncoding that matches the
specified character set registry and
encoding information. For instance, for the
iso8859-5 character set, the registry is
iso8859 and the encoding is 5, and the
returned NSStringEncoding is
NSISOCyrillicStringEncoding. If
there is no specific encoding, use @"0".
Returns GSUndefinedEncoding if there is no match.
NSStringEncoding GSEncodingFromLocale(const char* clocale);
Availability: Not in OpenStep/MacOS-X, BaseAdditions Likely to be changed/moved/removed at 1.15.0
Try to deduce the string encoding from the locale string
clocale. This function looks in the
Locale.encodings file installed as part of
GNUstep Base if the encoding cannot be deduced from
the clocale string itself. If
clocale isn't set or no match can be found,
returns GSUndefinedEncoding.
BOOL GSFromUnicode(unsigned char** dst, unsigned int* size, const unichar* src, unsigned int slen, NSStringEncoding enc, NSZone* zone, unsigned int options);
Availability: Not in OpenStep/MacOS-X
Function to convert from 16-bit unicode to 8-bit
data.
The dst 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 zone
argument is non-nul, the function is free to
allocate a larger buffer if necessary, and store
this new buffer in the dst argument. It
will *NOT* deallocate the original buffer!
The size argument is a pointer to the
initial size of the destination buffer.
If the function changes the buffer size, this
value will be altered to the new size.
This is measured in bytes.
The src argument is a pointer to the 16-bit
unicode string which is to be converted to 8-bit
data.
The slen 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.
The enc argument specifies the encoding type
of the 8-bit byte sequence which is to be produced from
the 16-bit unicode.
The zone argument specifies a memory
zone 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 dst is a
null pointer... indicating that converted data is to
be discarded).
If the library is built for
garbage collecting, the zone argument is
used only as a marker to say whether the function may
allocate memory (zone is non-null) or
not (zone is null).
The options argument controls some special
behavior.
-
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.
-
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 size. Also, if the
function grows the buffer, it will allow for an
extra termination byte.
-
If GSUniTemporary is set, the function will return the
results in an autoreleased buffer rather than in
a buffer that the caller must release.
-
If GSUniBOM is set, the function will read the first
unicode character as a byte order marker.
-
If GSUniShortOk is set, the function will return a
buffer containing any decoded characters even if
the whole conversion fails.
On return, the function result is a flag indicating
success (YES
) or failure (
NO
), and on success, the value stored
in size is the number of bytes in the
converted data. The converted data itself is
stored in the location given by dst.
NB. If the value stored in dst has
been changed, it is a pointer to allocated memory
which the caller is responsible for freeing, and the
caller is still responsible for freeing the
original buffer.
BOOL GSToUnicode(unichar** dst, unsigned int* size, const unsigned char* src, unsigned int slen, NSStringEncoding enc, NSZone* zone, unsigned int options);
Availability: Not in OpenStep/MacOS-X
Function to convert from 8-bit data to 16-bit
unicode characters.
The dst 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 zone argument is non-nul, the function
is free to allocate a larger buffer if necessary, and
store this new buffer in the dst argument.
It will *NOT* deallocate the original buffer!
The size argument is a pointer to the
initial size of the destination buffer.
If the function changes the buffer size, this
value will be altered to the new size.
This is measured in 16-bit unicode characters, not
bytes.
The src argument is a pointer to the byte
sequence which is to be converted to 16-bit
unicode.
The slen argument is the length of the byte
sequence which is to be converted to 16-bit
unicode. This is measured in bytes.
The enc argument specifies the encoding type
of the 8-bit byte sequence which is to be converted to
16-bit unicode.
The zone argument specifies a memory
zone 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 dst is a
null pointer... indicating that converted data is to
be discarded).
If the library is built for
garbage collecting, the zone argument is
used only as a marker to say whether the function may
allocate memory (zone is non-null) or
not (zone is null).
The options argument controls some special
behavior.
-
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 size. Also, if the
function grows the buffer, it will allow for an
extra termination character.
-
If GSUniTemporary is set, the function will return the
results in an autoreleased buffer rather than in
a buffer that the caller must release.
-
If GSUniBOM is set, the function will write the first
unicode character as a byte order marker.
-
If GSUniShortOk is set, the function will return a
buffer containing any decoded characters even if
the whole conversion fails.
On return, the function result is a flag indicating
success (YES
) or failure (
NO
), and on success, the value stored
in size is the number of characters in the
converted string. The converted string itself is
stored in the location given by dst.
NB. If the value stored in dst has
been changed, it is a pointer to allocated memory
which the caller is responsible for freeing, and the
caller is still responsible for freeing the
original buffer.
unsigned int GSUnicode(const unichar* chars, unsigned int length, BOOL* isASCII, BOOL* isLatin1);
Availability: Not in OpenStep/MacOS-X, BaseAdditions Likely to be changed/moved/removed at 1.15.0
Function to check a block of data for validity as a
unicode string and say whether it contains solely
ASCII or solely Latin1 data.
Any leading BOM
must already have been removed and the data must already
be in native byte order.
Returns the number of
characters which were found valid.
unsigned char uni_cop(unichar u);
Availability: Not in OpenStep/MacOS-X, BaseAdditions Likely to be changed/moved/removed at 1.15.0
Description forthcoming.
unichar* uni_is_decomp(unichar u);
Availability: Not in OpenStep/MacOS-X, BaseAdditions Likely to be changed/moved/removed at 1.15.0
Description forthcoming.
BOOL uni_isnonsp(unichar u);
Availability: Not in OpenStep/MacOS-X, BaseAdditions Likely to be changed/moved/removed at 1.15.0
Description forthcoming.
unichar uni_tolower(unichar ch);
Availability: Not in OpenStep/MacOS-X, BaseAdditions Likely to be changed/moved/removed at 1.15.0
Uses direct access into a two-level table to map cases.
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.
unichar uni_toupper(unichar ch);
Availability: Not in OpenStep/MacOS-X, BaseAdditions Likely to be changed/moved/removed at 1.15.0
Uses direct access into a two-level table to map cases.
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.
Up