Up

Functions

Authors

Richard Frith-Macdonald

Copyright: (C) 2005 Free Software Foundation, Inc.


Contents -

  1. Function index
  2. Macro index
  3. GNUstep macros
  4. GSObjCRuntime macros
  5. GSVersionMacros macros
  6. GSCategories functions
  7. GSIArray functions
  8. GSIMap functions
  9. GSObjCRuntime functions
  10. behavior functions
  11. Unicode functions

Function index

Function

Macro index

Macro

GNUstep macros

ASSIGN

ASSIGN(object, value)
Availability: OpenStep

ASSIGN(object,value) assigns the value to the object with appropriate retain and release operations.

ASSIGNCOPY

ASSIGNCOPY(object, value)
Availability: OpenStep

ASSIGNCOPY(object,value) assigns a copy of the value to the object with release of the original.

AUTORELEASE

AUTORELEASE(object)
Availability: OpenStep

Basic autorelease operation... calls [NSObject -autorelease]

CREATE_AUTORELEASE_POOL

CREATE_AUTORELEASE_POOL(X)
Availability: OpenStep

Declares an autorelease pool variable and creates and initialises an autorelease pool object.

DESTROY

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

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

RECREATE_AUTORELEASE_POOL(X)
Availability: OpenStep

Similar, but allows reuse of variables. This destroys the old pool before creating the new one.

RELEASE

RELEASE(object)
Availability: OpenStep

Basic release operation... calls [NSObject -release]

RETAIN

RETAIN(object)
Availability: OpenStep

Basic retain operation... calls [NSObject -retain]

TEST_AUTORELEASE

TEST_AUTORELEASE(object)
Availability: OpenStep

Tested autorelease - only invoke the objective-c method if the receiver is not nil.

TEST_RELEASE

TEST_RELEASE(object)
Availability: OpenStep

Tested release - only invoke the objective-c method if the receiver is not nil.

TEST_RETAIN

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.


GSObjCRuntime macros

GS_MAX_OBJECTS_FROM_STACK

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

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

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.


GSVersionMacros macros

GS_API_LATEST

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

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

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

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

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

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

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


GSCategories functions

GSCurrentThread

NSThread* GSCurrentThread();
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSCurrentThreadDictionary

NSMutableDictionary* GSCurrentThreadDictionary();
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSDebugFunctionMsg

NSString* GSDebugFunctionMsg(const char* func, const char* file, int line, NSString* fmt);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSDebugMethodMsg

NSString* GSDebugMethodMsg(id obj, SEL sel, const char* file, int line, NSString* fmt);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSDebugSet

BOOL GSDebugSet(NSString* level);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

NSDecimalFromComponents

void NSDecimalFromComponents(NSDecimal* result, unsigned long long int mantissa, short int exponent, BOOL negative);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

NSStandardLibraryPaths

NSArray* NSStandardLibraryPaths();
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArray functions

GSIArrayAddItem

void GSIArrayAddItem(GSIArray array, GSIArrayItem item);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayAddItemNoRetain

void GSIArrayAddItemNoRetain(GSIArray array, GSIArrayItem item);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayCapacity

unsigned int GSIArrayCapacity(GSIArray array);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayCheckSort

void GSIArrayCheckSort(GSIArray array, NSComparisonResult(*) sorter);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayClear

void GSIArrayClear(GSIArray array);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayCopyWithZone

GSIArray GSIArrayCopyWithZone(GSIArray array, NSZone* zone);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayCount

unsigned int GSIArrayCount(GSIArray array);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayEmpty

void GSIArrayEmpty(GSIArray array);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayGrow

void GSIArrayGrow(GSIArray array);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayGrowTo

void GSIArrayGrowTo(GSIArray array, unsigned int next);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayInitWithZoneAndCapacity

GSIArray GSIArrayInitWithZoneAndCapacity(GSIArray array, NSZone* zone, size_t capacity);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayInitWithZoneAndStaticCapacity

GSIArray GSIArrayInitWithZoneAndStaticCapacity(GSIArray array, NSZone* zone, size_t capacity, GSIArrayItem* buffer);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayInsertItem

void GSIArrayInsertItem(GSIArray array, GSIArrayItem item, unsigned int index);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayInsertItemNoRetain

void GSIArrayInsertItemNoRetain(GSIArray array, GSIArrayItem item, unsigned int index);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayInsertSorted

void GSIArrayInsertSorted(GSIArray array, GSIArrayItem item, NSComparisonResult(*) sorter);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayInsertSortedNoRetain

void GSIArrayInsertSortedNoRetain(GSIArray array, GSIArrayItem item, NSComparisonResult(*) sorter);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayInsertionPosition

unsigned int GSIArrayInsertionPosition(GSIArray array, GSIArrayItem item, NSComparisonResult(*) sorter);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayItemAtIndex

GSIArrayItem GSIArrayItemAtIndex(GSIArray array, unsigned int index);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayItems

GSIArrayItem* GSIArrayItems(GSIArray array);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayLastItem

GSIArrayItem GSIArrayLastItem(GSIArray array);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayRemoveAllItems

void GSIArrayRemoveAllItems(GSIArray array);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayRemoveItemAtIndex

void GSIArrayRemoveItemAtIndex(GSIArray array, unsigned int index);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayRemoveItemAtIndexNoRelease

void GSIArrayRemoveItemAtIndexNoRelease(GSIArray array, unsigned int index);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayRemoveItemsFromIndex

void GSIArrayRemoveItemsFromIndex(GSIArray array, unsigned int index);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArrayRemoveLastItem

void GSIArrayRemoveLastItem(GSIArray array);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArraySearch

unsigned int GSIArraySearch(GSIArray array, GSIArrayItem item, NSComparisonResult(*) sorter);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIArraySetItemAtIndex

void GSIArraySetItemAtIndex(GSIArray array, GSIArrayItem item, unsigned int index);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMap functions

GSIMapAddKey

GSIMapNode GSIMapAddKey(GSIMapTable map, GSIMapKey key);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapAddKeyNoRetain

GSIMapNode GSIMapAddKeyNoRetain(GSIMapTable map, GSIMapKey key);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapAddNodeToBucket

void GSIMapAddNodeToBucket(GSIMapBucket bucket, GSIMapNode node);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapAddNodeToMap

void GSIMapAddNodeToMap(GSIMapTable map, GSIMapNode node);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapAddPair

GSIMapNode GSIMapAddPair(GSIMapTable map, GSIMapKey key, GSIMapVal value);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapAddPairNoRetain

GSIMapNode GSIMapAddPairNoRetain(GSIMapTable map, GSIMapKey key, GSIMapVal value);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapBucketForKey

GSIMapBucket GSIMapBucketForKey(GSIMapTable map, GSIMapKey key);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapCleanMap

void GSIMapCleanMap(GSIMapTable map);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapEmptyMap

void GSIMapEmptyMap(GSIMapTable map);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapEndEnumerator

void GSIMapEndEnumerator(GSIMapEnumerator enumerator);
Availability: Not in OpenStep/MacOS-X

Tidies up after map enumeration... effectively destroys the enumerator.

GSIMapEnumeratorBucket

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.

GSIMapEnumeratorForMap

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.

GSIMapEnumeratorNextNode

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.

GSIMapFirstNode

GSIMapNode GSIMapFirstNode(GSIMapTable map);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapFreeNode

void GSIMapFreeNode(GSIMapTable map, GSIMapNode node);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapInitWithZoneAndCapacity

void GSIMapInitWithZoneAndCapacity(GSIMapTable map, NSZone* zone, uintptr_t capacity);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapLinkNodeIntoBucket

void GSIMapLinkNodeIntoBucket(GSIMapBucket bucket, GSIMapNode node);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapMoreNodes

void GSIMapMoreNodes(GSIMapTable map, unsigned int required);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapNodeForKey

GSIMapNode GSIMapNodeForKey(GSIMapTable map, GSIMapKey key);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapNodeForKeyInBucket

GSIMapNode GSIMapNodeForKeyInBucket(GSIMapTable map, GSIMapBucket bucket, GSIMapKey key);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapNodeForSimpleKey

GSIMapNode GSIMapNodeForSimpleKey(GSIMapTable map, GSIMapKey key);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapPickBucket

GSIMapBucket GSIMapPickBucket(unsigned int hash, GSIMapBucket buckets, uintptr_t bucketCount);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapRemangleBuckets

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.

GSIMapRemoveAndFreeNode

GSIMapNode GSIMapRemoveAndFreeNode(GSIMapTable map, uintptr_t bkt, GSIMapNode node);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapRemoveKey

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.

GSIMapRemoveNodeFromBucket

void GSIMapRemoveNodeFromBucket(GSIMapBucket bucket, GSIMapNode node);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapRemoveNodeFromMap

void GSIMapRemoveNodeFromMap(GSIMapTable map, GSIMapBucket bkt, GSIMapNode node);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapResize

void GSIMapResize(GSIMapTable map, uintptr_t new_capacity);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapRightSizeMap

void GSIMapRightSizeMap(GSIMapTable map, uintptr_t capacity);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSIMapUnlinkNodeFromBucket

void GSIMapUnlinkNodeFromBucket(GSIMapBucket bucket, GSIMapNode node);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

GSObjCRuntime functions

GSAddMethodList

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.


GSAllocMethodList

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.


GSAllocateMutexAt

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);
 }
 

GSAppendMethodToList

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.


GSAutoreleasedBuffer

void* GSAutoreleasedBuffer(unsigned int size);
Availability: BaseAdditions

Quickly return autoreleased data storage area.

GSCGetInstanceVariableDefinition

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.

GSClassFromName

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.

GSClassList

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.

GSClassNameFromObject

const char* GSClassNameFromObject(id obj);
Availability: BaseAdditions

Return the name of the object's class, or a nul pointer if no object was supplied.

GSFlushMethodCacheForClass

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.

GSGetMethod

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.

GSLastErrorStr

const char* GSLastErrorStr(long int error_id);
Availability: BaseAdditions
Likely to be changed/moved/removed at 1.15.0

Description forthcoming.

GSMethodFromList

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.


GSMethodListForSelector

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.


GSNameFromClass

const char* GSNameFromClass(Class cls);
Availability: BaseAdditions

Return the name of the supplied class, or a nul pointer if no class was supplied.

GSNameFromSelector

const char* GSNameFromSelector(SEL sel);
Availability: BaseAdditions

Return the name of the supplied selector, or a nul pointer if no selector was supplied.

GSObjCAddClassBehavior

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.


GSObjCAddClasses

void GSObjCAddClasses(NSArray* classes);
Availability: BaseAdditions

Description forthcoming.

GSObjCAllSubclassesOfClass

NSArray* GSObjCAllSubclassesOfClass(Class cls);
Availability: BaseAdditions

Returns an autoreleased array of subclasses of Class cls, including subclasses of subclasses.

GSObjCClass

Class GSObjCClass(id obj);
Availability: BaseAdditions

GSObjCClass() return the class of an instance. Returns a nul pointer if the argument is nil.

GSObjCDirectSubclassesOfClass

NSArray* GSObjCDirectSubclassesOfClass(Class cls);
Availability: BaseAdditions

Returns an autoreleased array containing subclasses directly descendent of Class cls.

GSObjCFindVariable

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).

GSObjCGetInstanceVariableDefinition

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.

GSObjCGetVal

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.

GSObjCGetVariable

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.

GSObjCIsClass

BOOL GSObjCIsClass(Class cls);
Availability: BaseAdditions

GSObjCIsClass() tests to see if an id is a class. Returns NO if the argument is nil.

GSObjCIsInstance

BOOL GSObjCIsInstance(id obj);
Availability: BaseAdditions

GSObjCIsInstance() tests to see if an id is an instance. Returns NO if the argument is nil.

GSObjCIsKindOf

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.

GSObjCMakeClass

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.


GSObjCMethodNames

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 .

GSObjCSetVal

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.

GSObjCSetVariable

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.

GSObjCSuper

Class GSObjCSuper(Class cls);
Availability: BaseAdditions

Returns the superclass of this.

GSObjCVariableNames

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.

GSObjCVersion

int GSObjCVersion(Class cls);
Availability: BaseAdditions

Returns the version number of this.

GSObjCZone

NSZone* GSObjCZone(NSObject* obj);
Availability: BaseAdditions

Return the zone in which an object belongs, without using the zone method

GSPrintf

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() .


GSProtocolFromName

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.

GSRegisterProtocol

void GSRegisterProtocol(Protocol* proto);
Availability: BaseAdditions

Registers proto in the cache used by GSProtocolFromName() .

GSRemoveMethodFromList

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.


GSRemoveMethodList

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.


GSSelectorFromName

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.

GSSelectorFromNameAndTypes

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.

GSSelectorTypesMatch

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.

GSTypesFromSelector

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.

behavior functions

behavior_class_add_category

void behavior_class_add_category(Class class, struct objc_category* category);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

behavior_class_add_class

void behavior_class_add_class(Class class, Class behavior);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

behavior_class_add_methods

void behavior_class_add_methods(Class class, struct objc_method_list* methods);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

behavior_set_debug

void behavior_set_debug(int i);
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

Unicode functions

GSEncodingForRegistry

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.

GSEncodingFromLocale

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.

GSFromUnicode

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.

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.


GSToUnicode

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.

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.


GSUnicode

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.

uni_cop

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.

uni_is_decomp

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.

uni_isnonsp

BOOL uni_isnonsp(unichar u);
Availability: Not in OpenStep/MacOS-X, BaseAdditions Likely to be changed/moved/removed at 1.15.0

Description forthcoming.

uni_tolower

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.

uni_toupper

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