Functions and Macros

This section describes the functions and macros found in the Foundation Kit.

NSAllHashTableObjects

Summary: This function returns all of the elements in the specified hash table.

Declared in: Foundation/NSHashTable.h

Synopsis: NSArray *NSAllHashTableObjects(NSHashTable *table)

Description: Returns an array object containing all the elements of table. This function should be called only when the table elements are objects, not when they're any other data type.

See also: NSCreateHashTable, NSFreeHashTable

NSAllMapTableKeys

Summary: This function returns all of the keys in the specified map table.

Declared in: Foundation/NSMapTable.h

Synopsis: NSArray *NSAllMapTableKeys(NSMapTable *table)

Description: NSAllMapTableKeys Returns an array object containing all the keys in table. This function should be called only when the table keys are objects, not when they're any other type of pointer.

NSAllMapTableValues

Summary: This function returns all of the values in the specified table.

Declared in: Foundation/NSMapTable.h

Synopsis: NSArray *NSAllMapTableValues(NSMapTable *table)

Description: NSAllMapTableValues Returns an array object containing all the values in table. This function should be called only when the table values are objects, not when they're any other type of pointer.

NSAllocateObject

Summary: This function creates new objects.

Declared in: Foundation/NSObject.h

Synopsis: id *NSAllocateObject(Class class, unsigned extraBytes, NSZone *zone)

Description: NSAllocateObject allocates and returns a pointer to an instance of class, created in the specified zone (or in the default zone, if zone is NULL). The extraBytes argument (usually zero) states the number of extra bytes required for indexed instance variables. Returns nil on failure.

See also: NSCopyObject, NSDeallocateObject

NSAllocateMemoryPages

Summary: This function allocates a new block of memory.

Declared in: Foundation/NSZone.h

Synopsis: void *NSAllocateMemoryPages(unsigned byteCount)

Description: NSAllocateMemoryPages allocates the integral number of pages whose total size is closest to, but not less than, byteCount. The allocated pages are guaranteed to be filled with zeros.

NSAssert, NSAssertn

Summary: These macros generate assertions if the given condition is false.

Declared in: Foundation/NSExceptions.h

Synopsis: NSAssert(condition, NSString *description)

NSAssert1(condition, NSString *description, arg1)
NSAssert2(condition, NSString *description, arg1, arg2)
NSAssert3(condition, NSString *description, arg1, arg2, arg3)
NSAssert4(condition, NSString *description, arg1, arg2, arg3, arg4)
NSAssert5(condition, NSString *description, arg1, arg2, arg3, arg4, arg5)

Description: Assertions evaluate a condition and, if the condition evaluates to false, call the assertion handler for the current thread, passing it a format string and a variable number of arguments. Each thread has its own assertion handler, which is an object of class NSAssertionHandler. When invoked, an assertion handler prints an error message that includes the method and class names (or the function name). It then raises an exception of type NSInternalInconsistencyException.

The NSAssert and NSAssertn macros evaluate the condition and serve as a front end to the assertion handler. These macros should be used only within Objective-C methods. NSAssert takes no arguments other than the condition and format string. The other macros take the number of format-string arguments as indicated by n.

condition must be an expression that evaluates to true or false. description is a printf-style format string that contains the error message describing the failure condition. Each arg parameter is an argument to be inserted, in place, into the description.

Assertions are disabled if the preprocessor macro NS_BLOCK_ASSERTIONS is defined. All macros return void.

See also: NSLog,NSLogv, NSCAssert, NSCParameterAssert, NSParameterAssert

NSCAssert

Summary: These macros generate assertions if the given condition is false.

Declared in: Foundation/NSExceptions.h

Synopsis: NSCAssert(condition, NSString *description)

NSCAssert1(condition, NSString *description, arg1)
NSCAssert2(condition, NSString *description, arg1, arg2)
NSCAssert3(condition, NSString *description, arg1, arg2, arg3)
NSCAssert4(condition, NSString *description, arg1, arg2, arg3, arg4)
NSCAssert5(condition, NSString *description, arg1, arg2, arg3, arg4, arg5)

Description: Assertions evaluate a condition and, if the condition evaluates to false, call the assertion handler for the current thread, passing it a format string and a variable number of arguments. Each thread has its own assertion handler, which is an object of class NSAssertionHandler. When invoked, an assertion handler prints an error message that includes method and class names (or the function name). It then raises an exception of type NSInternalInconsistencyException.

The NSAssert and NSAssertn macros evaluate the condition and serve as a front end to the assertion handler. These macros should be used only within C functions. NSCAssert takes no arguments other than the condition and format string. The other macros take the number of format-string arguments as indicated by n.

condition must be an expression that evaluates to true or false. description is a printf-style format string that describes the failure condition. Each arg is an argument to be inserted, in place, into the description.

Assertions are disabled if the preprocessor macro NS_BLOCK_ASSERTIONS is defined. All macros return void.

See also: NSLog,NSLogv, NSAssert, NSCParameterAssert, NSParameterAssert

NSClassFromString

Summary: This function obtains a class by name.

Declared in: Foundation/NSObjCRuntime.h

Synopsis: Class NSClassFromString(NSString *aClassName)

Description: NSClassFromString returns the class object named by aClassName, or nil if no class by that name is currently loaded.

See also: NSStringFromClass

NSCompareHashTables

Summary: This function compares the elements of two hash tables for equality.

Declared in: Foundation/NSHashTable.h

Synopsis: BOOL NSCompareHashTables(NSHashTable *table1, NSHashTable *table2)

Description: Returns YES if the two hash tables are equal-that is, if each element of table1 is in table2, and the two tables are the same size.

NSCompareMapTables

Summary: This function compares the elements of two map tables for equality.

Declared in: Foundation/NSMapTable.h

Synopsis: BOOL NSCompareMapTables(NSMapTable *table1, NSMapTable *table2)

Description: Returns YES if each key of table1 is in table2, and the two tables are the same size. Note that this function does not compare values, only keys.

NSContainsRect

Summary: This function determines whether one rectangle completely encloses another.

Declared in: Foundation/NSGeometry.h

Synopsis: BOOL NSContainsRect(NSRect aRect, NSRect bRect)

Description: Returns YES if aRect completely encloses bRect. For this condition to be true, bRect cannot be empty and its sides must not touch the sides of aRect.

NSConvertHostDoubleToSwapped

Summary: This function performs a type conversion.

Declared in: Foundation/NSByteOrder.h

Synopsis: NSSwappedDouble NSConvertHostDoubleToSwapped(double x)

Description: Converts the double value in x to a value whose bytes can be swapped. This function does not actually swap the bytes of x. You should not need to call this method directly.

NSConvertHostFloatToSwapped

Summary: This function performs a type conversion.

Declared in: Foundation/NSByteOrder.h

Synopsis: NSSwappedFloat NSConvertHostFloatToSwapped(float x)

Description: Converts the float value in x to a value whose bytes can be swapped. This function does not actually swap the bytes of x. You should not need to call this method directly.

NSConvertSwappedDoubleToHost

Summary: This function performs a type conversion.

Declared in: Foundation/NSByteOrder.h

Synopsis: double NSConvertSwappedDoubleToHost(NSSwappedDouble x)

Description: Converts the value in x to a double value. This function does not actually swap the bytes of x. You should not need to call this method directly.

NSConvertSwappedFloatToHost

Summary: This function performs a type conversion.

Declared in: Foundation/NSByteOrder.h

Synopsis: float NSConvertSwappedFloatToHost(NSSwappedFloat x)

Description: Converts the value in x to a float value. This function does not actually swap the bytes of x. You should not need to call this method directly.

NSCopyHashTableWithZone

Summary: This function performs a shallow copy of the specified hash table.

Declared in: Foundation/NSHashTable.h

Synopsis: NSHashTable *NSCopyHashTableWithZone(NSHashTable *table, NSZone *zone)

Description: Returns a pointer to a new copy of table, created in zone and containing pointers to the data elements of table. If zone is NULL, the new table is created in the default zone.

The new table adopts the callback functions of table and calls the hash and retain callback functions as appropriate when inserting elements into the new table.

NSCopyMapTableWithZone

Summary: This function performs a shallow copy of the specified map table.

Declared in: Foundation/NSMapTable.h

Synopsis: NSMapTable *NSCopyMapTableWithZone(NSMapTable *table, NSZone *zone)

Description: Returns a pointer to a new copy of table, created in zone and containing pointers to the keys and values of table. If zone is NULL, the new table is created in the default zone.

The new table adopts the callback functions of table and calls the hash and retain callback functions as appropriate when inserting elements into the new table.

NSCopyMemoryPages

Summary: This function copies a block of memory.

Declared in: Foundation/NSZone.h

Synopsis: void NSCopyMemoryPages(const void *source, void *destination,unsigned byteCount)

Description: Copies (or copies-on-write) byteCount bytes from source to destination.

NSCopyObject

Summary: This function performs

Declared in: Foundation/NSObject.h

Synopsis: NSObject *NSCopyObject(NSObject *anObject, unsigned extraBytes, NSZone *zone)

Description: Creates and returns a new object that's an exact copy of anObject, created in the specified zone (or in the default zone, if zone is NULL). The extraBytes argument (usually zero) states the number of extra bytes required for indexed instance variables. Returns nil if anObject is nil or if anObject could not be copied.

Return: Returns a pointer to a new NSObject that is an exact copy of anObject.

See also: NSAllocateObject, NSDeallocateObject

NSCountHashTable

Summary: This function returns the number of elements in a hash table.

Declared in: Foundation/NSHashTable.h

Synopsis: unsigned NSCountHashTable(NSHashTable *table)

Description: Returns the number of elements currently in table.

NSCountMapTable

Summary: This function returns the number of elements in a map table.

Declared in: Foundation/NSMapTable.h

Synopsis: unsigned NSCountMapTable(NSMapTable *table)

Description: Returns the number of key/value pairs currently in table.

NSCParameterAssert

Summary: This macro evaluates the specified parameter.

Declared in: Foundation/NSExceptions.h

Synopsis: NSCParameterAssert(condition)

Description: Assertions evaluate a condition and, if the condition evaluates to false, call the assertion handler for the current thread, passing it a format string and a variable number of arguments. Each thread has its own assertion handler, which is an object of class NSAssertionHandler. When invoked, an assertion handler prints an error message that includes method and class names (or the function name). It then raises an exception of type NSInternalInconsistencyException.

This macro validates a parameter for a C-function. Simply provide the parameter as the condition argument. The macro evaluates the parameter and, if the parameter evaluates to false, logs an error message which includes the parameter and then raises an exception.

Assertions are disabled if the preprocessor macro NS_BLOCK_ASSERTIONS is defined. All macros return void.

See also: NSLog,NSLogv, NSAssert, NSCAssert, NSParameterAssert

NSCreateHashTable

Summary: This function creates a new hash table in the default zone.

Declared in: Foundation/NSHashTable.h

Synopsis: NSHashTable *NSCreateHashTable(NSHashTableCallBacks callBacks, unsigned capacity)

Description: NSCreateHashTable creates and returns a pointer to an NSHashTable in the default zone.

The table's size is dependent on (but generally not equal to) capacity. If capacity is 0, a small hash table is created. The NSHashTableCallBacks structure callBacks has five pointers to functions (documented under "Types and Constants"), with the following defaults: pointer hashing, if hash is NULL; pointer equality, if isEqual is NULL; no call-back upon adding an element, if retain is NULL; no call-back upon removing an element, if release is NULL; and a function returning a pointer's hexadecimal value as a string, if describe is NULL. The hashing function must be defined such that if two data elements are equal, as defined by the comparison function, the values produced by hashing on these elements must also be equal. Also, data elements must remain invariant if the value of the hashing function depends on them; for example, if the hashing function operates directly on the characters of a string, that string can't change.

NSCreateHashTableWithZone

Summary: This function creates a new hash table in the specified zone.

Declared in: Foundation/NSHashTable.h

Synopsis: NSHashTable *NSCreateHashTableWithZone(NSHashTableCallBacks callBacks, unsigned capacity, NSZone *zone)

Description: This function creates a new hash table in the specified zone. If zone is NULL, the hash table is created in the default zone.

See also: NSCreateHashTable

NSCreateMapTable

Summary: This function creates a new map table in the default zone.

Declared in: Foundation/NSMapTable.h

Synopsis: NSMapTable *NSCreateMapTable(NSMapTableKeyCallBacks keyCallBacks, NSMapTableValueCallBacks valueCallBacks, unsigned capacity)

Description: NSCreateMapTable creates, and returns a pointer to, an NSMapTable in the default zone; the table's size is dependent on (but generally not equal to) capacity. If capacity is 0, a small map table is created. The NSMapTableKeyCallBacks arguments are structures (documented under "Types and Constants") that are very similar to the call-back structure used by NSCreateHashTable; in fact, they have the same defaults as documented for that function.

NSCreateMapTableWithZone

Summary: This function creates a new map table in the specified zone.

Declared in: Foundation/NSMapTable.h

Synopsis: NSMapTable *NSCreateMapTableWithZone(NSMapTableKeyCallBacks keyCallBacks, NSMapTableValueCallBacks valueCallBacks, unsigned capacity, NSZone *zone)

Description: This function creates a new map table in the specified zone. If zone is NULL, the hash table is created in the default zone.

The table's size is dependent on (but generally not equal to) capacity. If capacity is 0, a small map table is created. The NSMapTableKeyCallBacks arguments are structures (documented under "Types and Constants") that are very similar to the call-back structure used by NSCreateHashTable; in fact, they have the same defaults as documented for that function.

See also: NSCopyMapTableWithZone, NSCreateMapTable

NSCreateZone

Summary: Creates a new zone

Declared in: Foundation/NSZone.h

Synopsis: NSZone *NSCreateZone(unsigned startSize, unsigned granularity, BOOL canFree)

Description: Creates and returns a pointer to a new zone of startSize bytes, which will grow and shrink by granularity bytes. If canFree is zero, the allocator will never free memory, and malloc will be fast.

NSDeallocateMemoryPages

Summary: This function deallocates the specified block of memory.

Declared in: Foundation/NSZone.h

Synopsis: void NSDeallocateMemoryPages(void *pointer, unsigned byteCount)

Description: This function deallocates memory that was allocated with NSAllocateMemoryPages.

See also: NSCopyMemoryPages, NSAllocateMemoryPages

NSDeallocateObject

Summary: This function destroys an existing object.

Declared in: Foundation/NSObject.h

Synopsis: void NSDeallocateObject(id <NSObject> anObject)

Description: This function deallocates anObject, which must have been allocated using NSAllocateObject.

See also: NSCopyObject, NSAllocateObject

NSDecimalAdd

Summary: This function adds two decimal values.

Declared in: Foundation/NSDecimal.h

Synopsis: NSCalculationError NSDecimalAdd(NSDecimal *result, const NSDecimal *leftOperand, const NSDecimal *rightOperand, NSRoundingMode roundingMode)

Description: Adds leftOperand to rightOperand, and stores the sum in result.

An NSDecimal can represent a number with up to 38 significant digits. If a number is more precise than that, it must be rounded off. roundingMode determines how to round it off. There are four possible rounding modes:

NSRoundDown. The number rounds down.
NSRoundUp. The number rounds up.
NSRoundPlain. The number rounds to the closest 38-digit approximation. If the number is halfway between two positive numbers, it round up; if it's halfway between two negative numbers, it rounds down.
NSRoundBankers. The number rounds to the closest 38-digit approximation. If it is caught halfway between two possibilities, it rounds to the one whose last digit is even. In practice, this means that, over the long run, numbers will be rounded up as often as they are rounded down; there will be no systematic bias.

The return value indicates whether any machine limitations were encountered in the addition. If none were encountered, the function returns NSCalculationNoError. Otherwise it may return one of the following values: NSCalculationLossOfPrecision, NSCalculationOverflow or NSCalculationUnderflow. For descriptions of all these error conditions, see exceptionDuringOperation:error:leftOperand:rightOperand: in the protocol specification for NSDecimalNumberBehaviors.

NSDecimalCompact

Summary: This function compacts the decimal structure for efficiency.

Declared in: Foundation/NSDecimal.h

Synopsis: void NSDecimalCompact(NSDecimal *number)

Description: Formats number so that calculations using it will take up as little memory as possible. All the NSDecimal... arithmetic functions expect compact NSDecimal arguments.

NSDecimalCompare

Summary: This function compares two decimal values.

Declared in: Foundation/NSDecimal.h

Synopsis: NSComparisonResult NSDecimalCompare(const NSDecimal *leftOperand, const NSDecimal *rightOperand)

Description: Compares leftOperand to rightOperand, with three possible return values.

If leftOperand is bigger, the function returns NSOrderedDescending.
If rightOperand is bigger, the the function returns NSOrdered Ascending.
If the two operands are equal, the function returns NSOrderedSame.

NSDecimalCopy

Summary: This function copies the value of a decimal number.

Declared in: Foundation/NSDecimal.h

Synopsis: void NSDecimalCopy(NSDecimal *destination, const NSDecimal *source)

Description: Copies the value in source to destination.

NSDecimalDivide

Summary: This function divides one decimal value by another.

Declared in: Foundation/NSDecimal.h

Synopsis: NSCalculationError NSDecimalDivide(NSDecimal *result, const NSDecimal *leftOperand, const NSDecimal *rightOperand, NSRoundingMode roundingMode)

Description: Divides leftOperand by rightOperand, and stores the quotient, possibly rounded off according to roundingMode, in result. If rightOperand is 0, returns NSDivideByZero.

For explanations of the other possible return values, and of all the possible roundingMode's, see NSDecimalAdd, above.

Note that this function can't precisely represent a non-decimal fraction like 1/3.

NSDecimalIsNotANumber

Summary: This function determines if the specified decimal contains a valid number.

Declared in: Foundation/NSDecimal.h

Synopsis: BOOL NSDecimalIsNotANumber(const NSDecimal *decimal)

Description: Returns YES if the value in decimal represents a valid number, otherwise returns NO.

NSDecimalMultiply

Summary: This function multiplies two decimal numbers together.

Declared in: Foundation/NSDecimal.h

Synopsis: NSCalculationError NSDecimalMultiply(NSDecimal *result, const NSDecimal *leftOperand, const NSDecimal *rightOperand, NSRoundingMode roundingMode)

Description: Multiplies rightOperand by leftOperand, and stores the product, possibly rounded off according to roundingMode, in result.

For explanations of the possible return values and roundingMode's, see NSDecimalAdd, above.

NSDecimalMultiplyByPowerOf10

Summary: This function multiplies a decimal by the specified power of 10.

Declared in: Foundation/NSDecimal.h

Synopsis: NSCalculationError NSDecimalMultiplyByPowerOf10(NSDecimal *result, const NSDecimal *number, short power, NSRoundingMode roundingMode)

Description: Multiplies number by 10power, and stores the product, possibly rounded off according to roundingMode, in result.

For explanations of the possible return values and roundingMode's, see NSDecimalAdd, above.

NSDecimalNormalize

Summary: This function normalizes the internal format of two decimal numbers to simplify later operations.

Declared in: Foundation/NSDecimal.h

Synopsis: NSCalculationError NSDecimalNormalize(NSDecimal *number1, NSDecimal *number2, NSRoundingMode roundingMode)

Description: An NSDecimal is represented in memory as a mantissa and an exponent, expressing the value mantissa x 10exponent. A number can have many NSDecimal representations; for example, the following table lists several valid NSDecimal representations for the number 100:

Mantissa Exponent

100 0

10 1

1 2

`Mantissa`	Exponent
100	0
10	1
1	2

NSDecimalNormalize formats number1 and number2 so that they have equal exponents. This format makes addition and subtraction very convenient. Both NSDecimalAdd and NSDecimalSubtract call NSDecimalNormalize. You may want to use it if you write more complicated addition or subtraction routines.

For explanations of the function's possible return values, see NSDecimalAdd, above.

NSDecimalPower

Summary: This function raises the decimal value to the specified power.

Declared in: Foundation/NSDecimal.h

Synopsis: NSCalculationError NSDecimalPower(NSDecimal *result, const NSDecimal *number, unsigned power, NSRoundingMode roundingMode)

Description: Raises number to power, possibly rounding off according to roundingMode, and stores the resulting value in result.

For explanations of the possible return values and roundingMode's, see NSDecimalAdd, above.

NSDecimalRound

Summary: This function rounds off the decimal value.

Declared in: Foundation/NSDecimal.h

Synopsis: void NSDecimalRound(NSDecimal *result, const NSDecimal *number, int scale, NSRoundingMode roundingMode)

Description: Rounds number off according to the parameters scale and rounding mode, and stores the result in result.

scale specifies the number of digits result can have after its decimal point. roundingMode specifies the way that number is rounded off. There are four possible values for roundingMode: NSRoundDown, NSRoundUp, NSRoundPlain, and NSRoundBankers. For thorough discussions of scale and roundingMode, see the scale and roundingMode in the protocol specification for NSDecimalNumberBehaviors.

NSDecimalString

Summary: This function returns a string representation of the decimal value.

Declared in: Foundation/NSDecimal.h

Synopsis: NSString *NSDecimalString(const NSDecimal *decimal, NSDictionary *locale)

Description: Returns a string representation of decimal. locale determines the format of the decimal separator.

NSDecimalSubtract

Summary: This function subtracts one decimal value from another.

Declared in: Foundation/NSDecimal.h

Synopsis: NSCalculationError NSDecimalSubtract(NSDecimal *result, const NSDecimal *leftOperand, const NSDecimal *rightOperand, NSRoundingMode roundingMode)

Description: Subtracts rightOperand from leftOperand, and stores the difference, possibly rounded off according to roundingMode, in result.

For explanations of the possible return values and roundingMode's, see NSDecimalAdd, above.

NSDecrementExtraRefCountWasZero

Summary: This function decrements the specified object's reference count.

Declared in: Foundation/NSObject.h

Synopsis: BOOL NSDecrementExtraRefCountWasZero(id anObject)

Description: This function decrements the "extra reference" count of an object. Newly created objects have only one actual reference, so that a single release message results in the object being deallocated. Extra references are those beyond the single original reference, and are usually created by sending the object a retain message. Your code should generally not use these functions unless it is overriding the retain or release methods.

This function returns NO if anObject had an extra reference count. If anObject didn't have an extra referenct count, it returns YES, indicating that the object should be deallocated (with dealloc).

See also: NSExtraRefCount, NSIncrementExtraRefCount

NSDefaultMallocZone

Summary: Returns the default zone

Declared in: Foundation/NSZone.h

Synopsis: NSZone *NSDefaultMallocZone(void)

Description: Returns the default zone, which is created automatically at startup. This is the zone used by the standard C function malloc.

See also: NSCreateZone

NSDivideRect

Summary: This function divides a rectangle into two new rectangles.

Declared in: Foundation/NSGeometry.h

Synopsis: void NSDivideRect(NSRect inRect, NSRect *slice, NSRect *remainder, float amount, NSRectEdge edge)

Description: Creates two rectangles, slice and remainder, from inRect, by dividing inRect with a line that's parallel to one of inRect's sides (namely, the side specified by edge-either NSMinXEdge, NSMinYEdge, NSMaxXEdge, or NSMaxYEdge). The size of slice is determined by amount, which measures the distance from edge.

See also: NSInsetRect, NSIntegralRect, NSOffsetRect

NSEnumerateHashTable

Summary: This function creates an enumerator for the specified hash table.

Declared in: Foundation/NSHashTable.h

Synopsis: NSHashEnumerator NSEnumerateHashTable(NSHashTable *table)

Description: Returns an NSHashEnumerator structure that will cause successive elements of table to be returned each time this enumerator is passed to NSNextHashEnumeratorItem.

See also: NSNextHashEnumeratorItem

NSEnumerateMapTable

Summary: This function creates an enumerator for the specified map table.

Declared in: Foundation/NSMapTable.h

Synopsis: NSMapEnumerator NSEnumerateMapTable(NSMapTable *table)

Description: NSEnumerateMapTable returns an NSMapEnumerator structure that will cause successive key/value pairs of table to be visited each time this enumerator is passed to NSNextMapEnumeratorPair.

NSEqualPoints

Summary: This function tests the two points for equality.

Declared in: Foundation/NSGeometry.h

Synopsis: BOOL NSEqualPoints(NSPoint aPoint, NSPoint bPoint)

Description: Returns YES if the two points aPoint and bPoint are identical, and NO otherwise.

NSEqualRanges

Summary: This function tests the two range values for equality.

Declared in: Foundation/NSRange.h

Synopsis: BOOL NSEqualRanges(NSRange range1, NSRange range2)

Description: Returns YES if range1 and range2 have the same locations and lengths.

NSEqualRects

Summary: This function tests the two rectangles for equality.

Declared in: Foundation/NSGeometry.h

Synopsis: BOOL NSEqualRects(NSRect aRect, NSRect bRect)

Description: Returns YES if the two rectangles aRect and bRect are identical, and NOotherwise.

NSEqualSizes

Summary: This function tests the two size values for equality.

Declared in: Foundation/NSGeometry.h

Synopsis: BOOL NSEqualSizes(NSSize aSize, NSSize bSize)

Description: Returns YES if the two sizes aSize and bSize are identical, and NO otherwise.

NSExtraRefCount

Summary: This function returns the specified object's reference count.

Declared in: Foundation/NSObject.h

Synopsis: unsigned int NSExtraRefCount(id object)

Description: Returns the current reference count of object. This function is used in conjunction with NSIncrementExtraRefCount and NSDecrementExtraRefCountWasZero in situations where you need to override an object's retain and release methods.

NSFreeHashTable

Summary: This function deletes the specified hash table.

Declared in: Foundation/NSHashTable.h

Synopsis: void NSFreeHashTable(NSHashTable *table)

Description: NSFreeHashTable releases each element of the specified hash table and frees the table itself.

See also: NSResetHashTable

NSFreeMapTable

Summary: This function deletes the specified map table.

Declared in: Foundation/NSMapTable.h

Synopsis: void NSFreeMapTable(NSMapTable *table)

Description: NSFreeMapTable releases each key and value of the specified map table and frees the table itself.

See also: NSResetMapTable

NSFullUserName

Summary: This function returns the full name of the current user.

Declared in: Foundation/NSPathUtilities.h

Synopsis: NSString* NSFullUserName(void)

Description: Returns a string containing the full name of the current user.

See also: NSUserName

NSGetSizeAndAlignment

Summary: This function returns the type and size of the specified data type.

Declared in: Foundation/NSObjCRuntime.h

Synopsis: const char* NSGetSizeAndAlignment(const char *typePtr,
unsigned int *sizep,
unsigned int *alignp)

Description: Gets the next type code from typePtr and returns the size and alignment of that data type in sizep and alignp, respectively. You can specify 0 for either sizep or alignp to ignore the corresponding information. This function returns a new pointer to the string specified by typePtr; the new pointer points to the character just past the type code that was read.

NSGetUncaughtExceptionHandler

Summary: This function returns the top-level error handler.

Declared in: Foundation/NSException.h

Synopsis: NSUncaughtExceptionHandler *NSGetUncaughtExceptionHandler(void)

Description: NSGetUncaughtExceptionHandler returns a pointer to the function serving as the top-level error handler. This handler will process exceptions raised outside of any exception-handling domain.

See also: NSSetUncaughtExceptionHandler

NSHashGet

Summary: This function returns an element of the hash table.

Declared in: Foundation/NSHashTable.h

Synopsis: void *NSHashGet(NSHashTable *table, const void *pointer)

Description: Returns the pointer in the table that matches pointer (as defined by the isEqual call-back function). If there is no matching element, the function returns NULL

NSHashInsert

Summary: This function adds an element to the specified hash table.

Declared in: Foundation/NSHashTable.h

Synopsis: void NSHashInsert(NSHashTable *table, const void *pointer)

Description: NSHashInsert inserts pointer, which must not be NULL, into table. If pointer matches an item already in the table, the previous pointer is released using the release call-back function that was specified when the table was created.

NSHashInsertKnownAbsent

Summary: This function adds an element to the specified hash table.

Declared in: Foundation/NSHashTable.h

Synopsis: void NSHashInsertKnownAbsent(NSHashTable *table, const void *pointer)

Description: NSHashInsertKnownAbsent inserts pointer, which must not be NULL, into table. Unike NSHashInsert, this function raises NSInvalidArgumentException if table already includes an element that matches pointer.

NSHashInsertIfAbsent

Summary: This function adds an element to the specified hash table only if the table does not already contain the element.

Declared in: Foundation/NSHashTable.h

Synopsis: void *NSHashInsertIfAbsent(NSHashTable *table, const void *pointer)

Description: If pointer matches an item already in table, NSHashInsertIfAbsent returns the pre-existing pointer; otherwise, it adds pointer to the table and returns NULL. You must not specify NULL for pointer.

NSHashRemove

Summary: This function removes an element from the specified hash table.

Declared in: Foundation/NSHashTable.h

Synopsis: void NSHashRemove(NSHashTable *table, const void *pointer)

Description: If pointer matches an item already in table, this function releases the pre-existing item.

NSHeight

Summary: This function returns the height of the specified rectangle.

Declared in: Foundation/NSGeometry.h

Synopsis: float NSHeight(NSRect aRect)

Description: Returns the height of aRect.

See also: NSMaxX, NSMaxY, NSMidX, NSMidY, NSMinX, NSMinY, NSWidth

NSHomeDirectory

Summary: This function getsinformation about a user.

Declared in: Foundation/NSPathUtilities.h

Synopsis: NSString *NSHomeDirectory(void)

Description: NSHomeDirectory returns a path to the current user's home directory.

NSHomeDirectoryForUser

Summary: Get information about a user

Declared in: Foundation/NSPathUtilities.h

Synopsis: NSString *NSHomeDirectoryForUser(NSString * userName)

Description: NSHomeDirectoryForUser returns a path to the home directory for the user specified by userName.

See also: NSFullUserName, NSUserName, NSHomeDirectory

NSHostByteOrder

Declared in: Foundation/NSByteOrder.h

Synopsis: NSByteOrder NSHostByteOrder(void)

Description: Returns the endian format, either NSLittleEndian or NSBigEndian, supported by the current platform.

NSIncrementExtraRefCount

Summary: This function increments the specified object's reference count.

Declared in: Foundation/NSObject.h

Synopsis: void NSIncrementExtraRefCount(id anObject)

BOOL NSDecrementExtraRefCountWasZero(id anObject)

Description: This function increments the "extra reference" count of an object. Newly created objects have only one actual reference, so that a single release message results in the object being deallocated. Extra references are those beyond the single original reference, and are usually created by sending the object a retain message. Your code should generally not use these functions unless it is overriding the retain or release methods.

NSInsetRect

Summary: This function insets the rectangle by the specified amount.

Declared in: Foundation/NSGeometry.h

Synopsis: NSRect NSInsetRect(NSRect aRect, float dX, float dY)

Description: NSInsetRect returns a copy of the rectangle aRect, altered by moving the two sides that are parallel to the y-axis inwards by dX, and the two sides parallel to the x-axis inwards by dY.

See also: NSDivideRect, NSIntegralRect, NSOffsetRect

NSIntegralRect

Summary: This function adjusts the sides of the rectangle to integer values.

Declared in: Foundation/NSGeometry.h

Synopsis: NSRect NSIntegralRect(NSRect aRect)

Description: NSIntegralRect returns a copy of the rectangle aRect, expanded outwards just enough to ensure that none of its four defining values (x, y, width, and height) have fractional parts. If aRect's width or height is zero or negative, this function returns a rectangle with origin at (0.0, 0.0) and with zero width and height.

See also: NSDivideRect, NSInsetRect, NSOffsetRect

NSIntersectionRange

Summary: This function returns the intersection of the specified ranges.

Declared in: Foundation/NSRange.h

Synopsis: NSRange NSIntersectionRange(NSRange range1, NSRange range2)

Description: NSIntersectionRange returns a range describing the intersection of range1 and range2-that is, a range containing the indices that exist in both ranges. If the returned range's length field is zero, then the two ranges don't intersect, and the value of the location field is undefined.

See also: NSUnionRange

NSIntersectionRect

Summary: This function calculates the intersection of two rectangles.

Declared in: Foundation/NSGeometry.h

Synopsis: NSRect NSIntersectionRect(NSRect aRect, NSRect bRect)

Description: NSIntersectionRect returns the graphic intersection of aRect and bRect. If the two rectangles don't overlap, the returned rectangle has its origin at (0.0, 0.0) and zero width and height. (This includes situations where the intersection is a point or a line segment.)

See also: NSUnionRect

NSIntersectsRect

Summary: This function tests whether two rectangles intersect.

Declared in: Foundation/NSGeometry.h

Synopsis: BOOL NSIntersectsRect(NSRect aRect, NSRect bRect)

Description: Returns YES if aRect intersects bRect, otherwise returns NO. This function returns NO if either aRect and bRect has a width or height that is 0.

See also: NSIntersectionRect

NSIsEmptyRect

Summary: This function tests whether the specified rectangle is empty.

Declared in: Foundation/NSGeometry.h

Synopsis: BOOL NSIsEmptyRect(NSRect aRect)

Description: Returns YES if the rectangle encloses no area at all-that is, if its width or height is zero or negative.

NSLocationInRange

Summary: This function verifies that the specified position is in the given range.

Declared in: Foundation/NSRange.h

Synopsis: BOOL NSLocationInRange(unsigned index, NSRange aRange)

Description: NSLocationInRange returns YES if the given index lies within aRange-that is, if it's greater than or equal to aRange.location and less than aRange.location plus aRange.length.

NSLog

Summary: This function logs error messages to stderr.

Declared in: Foundation/NSUtilities.h

Synopsis: void NSLog(NSString *format, ...)

Description: NSLog simply calls NSLogv, passing it a variable number of arguments.

See also: NSLogv

NSLogPageSize

Summary: This function returns the binary log of the page size.

Declared in: Foundation/NSZone.h

Synopsis: unsigned NSLogPageSize(void)

Description: NSLogPageSize returns the binary log of the current page size.

NSLogv

Summary: This function logs error messages to stderr.

Declared in: Foundation/NSUtilities.h

Synopsis: void NSLogv(NSString *format, va_list args)

Description: NSLogv logs an error message. The message consists of a timestamp and the process ID prefixed to the string you pass in. You compose this string with a format string , format, and one or more arguments to be inserted into the string. The format specification allowed by these functions is that which is understood by NSString's formatting capabilities (which is not necessarily the set of format escapes and flags understood by printf).

On HP-UX, Solaris, and Mach, NSLogv writes the log to STDERR_FILENO if the file descriptor is open. If that fails, the message is sent to the syslog subsystem, if it exists on a platform, with the LOG_USER facility (or default facility if LOG_USER doesn't exist on a platform), with priority LOG_ERR (or similar, depending on what the platform supports). If both of these attempts to write the message fail, the message is discarded.

On Windows platforms, the message is written to the STD_ERROR_HANDLE, if that handle is valid, on Windows platforms that support that standard handle. It is also written to the Windows Event Log on Windows platforms that support that, or to a file c:\fndation.log on Windows platforms that do not, if that file can be opened. If all of these attempts fail, the message is discarded. On some Windows platforms, the message to the Event Log may be truncated if there is a limit to the size of a message that the Event Log can accept. On Windows platforms that support an application discovering whether or not it's running under a debugger, NSLogv may only send the message to the debugger for its handling, via standard WIN32 mechanisms, and not also write the message to STD_ERROR_HANDLE and the Event Log. Note that a debugger may choose to not display message thus sent to it, or may choose not to display all of the message-that has nothing to do with NSLogv.

Output from NSLogv is serialized, in that only one thread in a process can be doing the writing/logging described above at a time. All attempts at writing/logging a message complete before the next thread can begin its attempts.

The effects of NSLogv are not serialized with subsystems other than those discussed above (such as the standard I/O package) and do not produce side effects on those subsystems (such as causing buffered output to be flushed, which may be undesirable).

See also: NSLog

NSMakePoint

Summary: This function creates a new NSPoint from the specified values.

Declared in: Foundation/NSGeometry.h

Synopsis: NSPoint NSMakePoint(float x, float y)

Description: Creates an NSPoint having the coordinates x and y.

NSMakeRect

Summary: This function creates a new NSRect from the specified values.

Declared in: Foundation/NSGeometry.h

Synopsis: NSRect NSMakeRect(float x, float y, float w, float h)

Description: Creates an NSRect having the specified origin and size.

NSMakeRange

Summary: This function creates a new NSRange from the specified values.

Declared in: Foundation/NSRange.h

Synopsis: NSRange NSMakeRange(unsigned int location, unsigned int length)

Description: Creates an NSRange having the specified location and length.

NSMakeSize

Summary: This function creates a new NSSize from the specified values.

Declared in: Foundation/NSGeometry.h

Synopsis: NSSize NSMakeSize(float w, float h)

Description: Creates an NSSize having the specified width and height.

NSMapGet

Summary: This function returns a map-table value for the specified key.

Declared in: Foundation/NSMapTable.h

Synopsis: void *NSMapGet(NSMapTable *table, const void *key)

Description: Returns the value that table maps to key, or NULL if the table doesn't contain key.

NSMapInsert

Summary: This function inserts a key/value pair into the specified table.

Declared in: Foundation/NSMapTable.h

Synopsis: void NSMapInsert(NSMapTable *table, const void *key, const void *value)

Description: NSMapInsert inserts key and value into table. If key matches a key already in the table, value is retained and the previous value is released, using the retain and release call-back functions that were specified when the table was created. Raises InvalidArgumentException if key is equal to the notAKeyMarker field of the table's NSMapTableKeyCallBacks structure.

NSMapInsertIfAbsent

Summary: This function inserts a key/value pair into the specified table.

Declared in: Foundation/NSMapTable.h

Synopsis: void *NSMapInsertIfAbsent(NSMapTable *table, const void *key,const void *value)

Description: If key matches a key already in table, NSMapInsertIfAbsent returns the pre-existing key; otherwise, it adds key and value to the table and returns NULL. Raises NSInvalidArgumentException if key is equal to the notAKeyMarker field of the table's NSMapTableKeyCallBacks structure.

NSMapInsertKnownAbsent

Summary: This function inserts a key/value pair into the specified table if the pair had not been previously added.

Declared in: Foundation/NSMapTable.h

Synopsis: void NSMapInsertKnownAbsent(NSMapTable *table, const void *key, const void *value)

Description: NSMapInsertKnownAbsent inserts key (which must not be notAKeyMarker) and value into table. Unlike NSMapInsert, this function raises NSInvalidArgumentException if table already includes a key that matches key.

See also: NSMapRemove, NSMapInsert, NSMapInsertIfAbsent

NSMapMember

Declared in: Foundation/NSMapTable.h

Synopsis: BOOL NSMapMember(NSMapTable *table, const void *key, void **originalKey, void **value)

Description: Returns YES if table contains a key equal to key. If so, originalKey is set to key, and value is set to the value that the table maps to key.

NSMapRemove

Declared in: Foundation/NSMapTable.h

Synopsis: void NSMapRemove(NSMapTable *table, const void *key)

Description: If key matches a key already in table, this function release the pre-existing key and its corresponding value.

NSMaxRange

Declared in: Foundation/NSRange.h

Synopsis: unsigned NSMaxRange(NSRange range)

Description: Returns range.location + range.length-in other words, the number one greater than the maximum value within the range.

NSMaxX

Summary: This function returns the largest x-coordinate of a rectangle.

Declared in: Foundation/NSGeometry.h

Synopsis: float NSMaxX(NSRect aRect)

Description: NSMaxX returns the largest x-coordinate value within aRect.

See also: NSWidth, NSHeight, NSMaxY

NSMaxY

Summary: This function returns the largest y-coordinate of a rectangle.

Declared in: Foundation/NSGeometry.h

Synopsis: float NSMaxY(NSRect aRect)

Description: NSMaxY returns the largest y-coordinate value within aRect.

See also: NSWidth, NSHeight, NSMaxX

NSMidX

Summary: This function returns the x-coordinate of a rectangle's midpoint.

Declared in: Foundation/NSGeometry.h

Synopsis: float NSMidX(NSRect aRect)

Description: NSMidX returns the x-coordinate of the center of the rectangle.

See also: NSWidth, NSHeight, NSMidY

NSMidY

Summary: This function returns the y-coordinate of a rectangle's midpoint.

Declared in: Foundation/NSGeometry.h

Synopsis: float NSMidY(NSRect aRect)

Description: NSMidY returns the y-coordinate of the rectangle's center point.

See also: NSWidth, NSHeight, NSMidX

NSMinX

Summary: This function returns the smallest x-coordinate of a rectangle.

Declared in: Foundation/NSGeometry.h

Synopsis: float NSMinX(NSRect aRect)

Description: NSMinX returns the smallest x-coordinate value within aRect.

See also: NSWidth, NSHeight, NSMinY

NSMinY

Summary: This function returns the smallest y-coordinate of a rectangle.

Declared in: Foundation/NSGeometry.h

Synopsis: float NSMinY(NSRect aRect)

Description: NSMinY returns the smallest y-coordinate value within aRect .

See also: NSWidth, NSHeight, NSMinX

NSMouseInRect

Summary: This function tests whether the point is in the specified rectangle.

Declared in: Foundation/NSGeometry.h

Synopsis: BOOL NSMouseInRect(NSPoint aPoint, NSRect aRect, BOOL flipped)

Description: Returns YES if the point represented by aPoint is located within the rectangle represented by aRect. It assumes an unscaled and unrotated coordinate system; the argument flipped should be YES if the coordinate system has been flipped so that the positive y-axis extends downward. This function is used to determine whether the hot spot of the cursor lies inside a given rectangle.

NSNextHashEnumeratorItem

Summary: This function returns the next hash-table element in the enumeration.

Declared in: Foundation/NSHashTable.h

Synopsis: void *NSNextHashEnumeratorItem(NSHashEnumerator *enumerator)

Description: NSNextHashEnumeratorItem returns the next element in the table that enumerator is associated with, or NULL if enumerator has already iterated over all the elements.

See also: NSEnumerateHashTable

NSNextMapEnumeratorPair

Summary: This function returns the next map-table pair in the enumeration

Declared in: Foundation/NSMapTable.h

Synopsis: BOOL NSNextMapEnumeratorPair(NSMapEnumerator *enumerator, void **key, void **value)

Description: NSNextMapEnumeratorPair returns NO if enumerator has already iterated over all the elements in the table that enumerator is associated with. Otherwise, this function sets key and value to match the next key/value pair in the table, and returns YES.

NSOffsetRect

Summary: This function insets the rectangle by the specified amount.

Declared in: Foundation/NSGeometry.h

Synopsis: NSRect NSOffsetRect(NSRect aRect, float dX, float dY)

Description: NSOffsetRect returns a copy of the rectangle aRect, with its location shifted by dX along the x-axis and by dY along the y-axis.

See also: NSDivideRect, NSInsetRect, NSIntegralRect

NSOpenStepRootDirectory

Summary: This function returns the root directory of the user's system.

Declared in: Foundation/NSPathUtilities.h

Synopsis: NSString* NSOpenStepRootDirectory(void)

Description: Returns a string identifying the root directory of the user's system.

See also: NSHomeDirectory, NSHomeDirectoryForUser

NSPageSize

Summary: This function returns the number of bytes in a page.

Declared in: Foundation/NSZone.h

Synopsis: unsigned NSPageSize(void)

See also: NSPageSize returns the number of bytes in a page. NSRoundDownToMultipleOfPageSize, NSRoundUpToMultipleOfPageSize, NSLogPageSize

NSParameterAssert

Summary: This macro validates the specified parameter.

Declared in: Foundation/NSExceptions.h

Synopsis: NSParameterAssert(condition)

Description: Assertions evaluate a condition and, if the condition evaluates to false, call the assertion handler for the current thread, passing it a format string and a variable number of arguments. Each thread has its own assertion handler, which is an object of class NSAssertionHandler. When invoked, an assertion handler prints an error message that includes method and class names (or the function name). It then raises an exception of type NSInternalInconsistencyException.

This macro validates a parameter for an Objective-C method. Simply provide the parameter as the condition argument. The macro evaluates the parameter and, if it is false, it logs an error message which includes the parameter and then raises an exception.

Assertions are disabled if the preprocessor macro NS_BLOCK_ASSERTIONS is defined.All assertion macros return void.

See also: NSLog,NSLogv, NSAssert, NSCAssert, NSCParameterAssert

NSPointFromString

Summary: This function returns a point from a text-based representation.

Declared in: Foundation/NSGeometry.h

Synopsis: NSPoint NSPointFromString(NSString *aString)

Description: Scans aString for text of the form "{x=a; y=b}" and returns the values for a and b in a new NSPoint object. If aString does not contain this text, this function returns an NSPoint object whose x- and y-coordinates are both 0.

See also: NSStringFromPoint

NSPointInRect

Summary: This function tests whether the specified point is in the rectangle.

Declared in: Foundation/NSGeometry.h

Synopsis: BOOL NSPointInRect(NSPoint aPoint, NSRect aRect)

Description: Performs the same test as NSMouseInRect, but assumes a flipped coordinate system.

NSRangeFromString

Summary: This function returns a range from a text-based representation.

Declared in: Foundation/NSRange.h

Synopsis: NSRange NSRangeFromString(NSString *aString)

Description: Returns aString for text of the form: "{location = a; length = b}" and returns the values for a and b in a new NSRange object. If aString does not contain this text, this function returns an NSRange object whose location and length values are both 0.

See also: NSStringFromRange

NSRealMemoryAvailable

Summary: This function returns information about the user's system.

Declared in: Foundation/NSZone.h

Synopsis: unsigned NSRealMemoryAvailable(void)

Description: NSRealMemoryAvailable returns the number of bytes available in RAM.

NSRectFromString

Summary: This function returns a rectangle from a text-based representation.

Declared in: Foundation/NSGeometry.h

Synopsis: NSRect NSRectFromString(NSString *aString)

Description: Scans aString for text of the form "{x=a; y=b; width=c; height=d}", and returns the values for a, b, c, and d in a new NSRect object. If aString does not contain the specified text, this function returns an NSRect object with a rectangle whose origin is (0, 0) and width and height are both 0.

See also: NSStringFromRect

NSRecycleZone

Summary: This function frees memory in a zone.

Declared in: Foundation/NSZone.h

Synopsis: void NSRecycleZone(NSZone *zone)

void NSZoneFree(NSZone *zone, void *pointer)

Description: NSRecycleZone frees zone after adding any of its pointers still in use to the default zone. (This strategy prevents retained objects from being inadvertently destroyed.)

NSZoneFree returns the memory indicated by pointer to zone. The standard C function free does the same, but spends time finding which zone the memory belongs to.

Return: Both functions return void.

See also: NSCreateZone, NSZoneMalloc

NSResetHashTable

Summary: This function deletes the elements of the specified hash table.

Declared in: Foundation/NSHashTable.h

Synopsis: void NSResetHashTable(NSHashTable *table)

Description: NSResetHashTable releases each element but doesn't deallocate the table. This is useful for preserving the table's capacity.

See also: NSFreeHashTable

NSResetMapTable

Summary: This function deletes the elements of the specified map table.

Declared in: Foundation/NSMapTable.h

Synopsis: void NSResetMapTable(NSMapTable *table)

Description: NSResetMapTable releases each key and value but doesn't deallocate the table. This is useful for preserving the table's capacity.

See also: NSFreeMapTable

NSRoundDownToMultipleOfPageSize

Summary: This function returns the number of pages that correspond to the specified number of bytes.

Declared in: Foundation/NSZone.h

Synopsis: unsigned NSRoundDownToMultipleOfPageSize(unsigned byteCount)

Description: NSRoundDownToMultipleOfPageSize returns the multiple of the page size that is closest to, but not greater than, byteCount.

NSRoundUpToMultipleOfPageSize

Summary: This function returns the number of pages that correspond to the specified number of bytes.

Declared in: Foundation/NSZone.h

Synopsis: unsigned NSRoundUpToMultipleOfPageSize(unsigned byteCount)

Description: NSRoundUpToMultipleOfPageSize returns the multiple of the page size that is closest to, but not less than, byteCount.

NSSelectorFromString,

Summary: This function obtains a selector by name.

Declared in: Foundation/NSObjCRuntime.h

Synopsis: SEL NSSelectorFromString(NSString *aSelectorName)

Description: NSSelectorFromString returns the selector named by aSelectorName, or zero if none by this name exists.

See also: NSStringFromSelector

NSSetUncaughtExceptionHandler

Summary: This function changes the top level error handler.

Declared in: Foundation/NSException.h

Synopsis: void NSSetUncaughtExceptionHandler(NSUncaughtExceptionHandler *handler)

Description: NSSetUncaughtExceptionHandler sets the top-level error-handling function to handler. If handler is NULL or this function is never invoked, the default top-level handler is used.

See also: NSGetUncaughtExceptionHandler

NSSetZoneName

Summary: This function sets the name of the specified zone.

Declared in: Foundation/NSZone.h

Synopsis: void NSSetZoneName(NSZone *zone, NSString *name)

Description: NSSetZoneName sets the specified zone's name to name, which can aid in debugging.

See also: NSZoneName

NSShouldRetainWithZone

Summary: This function indicates whether an object should be retained.

Declared in: Foundation/NSObject.h

Synopsis: BOOL NSShouldRetainWithZone(NSObject *anObject, NSZone *requestedZone)

Description: Returns YES if requestedZone is NULL, the default zone, or the zone in which anObject was allocated. This function is typically called from inside an NSObject's copyWithZone: method, when deciding whether to retain anObject as opposed to making a copy of it.

NSSizeFromString

Summary: This function returns an NSSize from a text-based representation.

Declared in: Foundation/NSGeometry.h

Synopsis: NSSize NSSizeFromString(NSString *aString)

Description: Scans aString for text of the form "{width=a; height=b}" and returns the values for a and b in an NSSize object. If aString does not contain the specified text, this function returns an NSSize object whose width and height are both 0.

See also: NSStringFromSize

NSStandardApplicationPaths

Summary: This function returns the application paths for the user's system.

Declared in: Foundation/NSPathUtilities.h

Synopsis: NSArray* NSStandardApplicationPaths(void)

Description: Returns an array of strings, each string specifying one of the standard paths to the OpenStep applications.

See also: NSStandardLibraryPaths

NSStandardLibraryPaths

Summary: This function returns the library paths for the user's system.

Declared in: Foundation/NSPathUtilities.h

Synopsis: NSArray* NSStandardLibraryPaths(void)

Description: Returns an array of strings, each string specifying one of the standard paths to the OpenStep libraries.

See also: NSStandardApplicationPaths

NSStringFromClass

Summary: This function obtains the name of a class

Declared in: Foundation/NSObjCRuntime.h

Synopsis: NSString *NSStringFromClass(Class aClass)

Description: This function returns an NSString containing the name of aClass.

See also: NSClassFromString

NSStringFromHashTable

Summary: This function returns a string describing the hash table's contents.

Declared in: Foundation/NSHashTable.h

Synopsis: NSString *NSStringFromHashTable(NSHashTable *table)

Description: Returns a string describing the hash table's contents. The function iterates over the table's elements, and for each one appends the string returned by the describe call-back function. If NULL was specified for the call-back function, the hexadecimal value of each pointer is added to the string.

NSStringFromMapTable

Summary: This function returns a string describing the map table's contents.

Declared in: Foundation/NSMapTable.h

Synopsis: NSString *NSStringFromMapTable(NSMapTable *table)

Description: Returns a string describing the map table's contents. The function iterates over the table's key/value pairs, and for each one appends the string "a = b;\n", where a and b are the key and value strings returned by the corresponding describe call-back functions. If NULL was specified for the call-back function, a and b are the key and value pointers, expressed as hexadecimal numbers.

NSStringFromPoint

Summary: This function returns a string representation of a point.

Declared in: Foundation/NSGeometry.h

Synopsis: NSString *NSStringFromPoint(NSPoint aPoint)

Description: Returns a string of the form "{x=a; y=b}", where a and b are the x- and y-coordinates of aPoint.

See also: NSPointFromString

NSStringFromRange

Summary: This function returns a string representation of a range.

Declared in: Foundation/NSRange.h

Synopsis: NSString *NSStringFromRange(NSRange aRange)

Description: Returns a string of the form: "{location = a; length = b}", where a and b are non-negative integers representing aRange.

NSStringFromRect

Summary: This function returns a string representation of a rect.

Declared in: Foundation/NSGeometry.h

Synopsis: NSString *NSStringFromRect(NSRect aRect)

Description: Returns a string of the form "{x=a; y=b; width=c; height=d}", where a, b, c, and d are the x- and y-coordinates and the width and height, respectively, of aRect.

See also: NSRectFromString

NSStringFromSelector

Summary: This function returns the name of a selector.

Declared in: Foundation/NSObjCRuntime.h

Synopsis: NSString *NSStringFromSelector(SEL aSelector)

Description: NSStringFromSelector returns an NSString containing the name of aSelector.

See also: NSSelectorFromString

NSStringFromSize

Summary: This function returns a string representation of a size.

Declared in: Foundation/NSGeometry.h

Synopsis: NSString *NSStringFromSize(NSSize aSize)

Description: Returns a string of the form "{width=a; height=b}", where a and b are the width and height of aSize.

See also: NSSizeFromString

NSSwapBigDoubleToHost

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: double NSSwapBigDoubleToHost(NSSwappedDouble x)

Description: Converts the big-endian value in x to the endian format of the current platform and returns the resulting value. If it is necessary to swap the bytes of x, this function calls NSSwapDouble to perform the swap.

NSSwapBigFloatToHost

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: float NSSwapBigFloatToHost(NSSwappedFloat x)

NSSwapBigIntToHost

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned int NSSwapBigIntToHost(unsigned int x)

See also: NSSwapHostIntToBig, NSSwapLittleIntToHost

NSSwapBigLongLongToHost

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned long long NSSwapBigLongLongToHost(unsigned long long x)

NSSwapBigLongToHost

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned long NSSwapBigLongToHost(unsigned long x)

NSSwapBigShortToHost

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned short NSSwapBigShortToHost(unsigned short x)

NSSwapDouble

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: NSSwappedDouble NSSwapDouble(NSSwappedDouble x)

Description: Swaps the bytes of x and returns the resulting value. Bytes are swapped from each low-order position to the corresponding high-order position and vice versa. For example, if the bytes of x are numbered from 1 to 8, this function swaps bytes 1 and 8, bytes 2 and 7, bytes 3 and 6, and bytes 4 and 5.

See also: NSSwapLongLong, NSSwapFloat

NSSwapFloat

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: NSSwappedFloat NSSwapFloat(NSSwappedFloat x)

Description: Swaps the bytes of x and returns the resulting value.Bytes are swapped from each low-order position to the corresponding high-order position and vice versa. For example, if the bytes of x are numbered from 1 to 4, this function swaps bytes 1 and 4, and swaps bytes 2 and 3.

See also: NSSwapLong, NSSwapDouble

NSSwapHostDoubleToBig

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: NSSwappedDouble NSSwapHostDoubleToBig(double x)

Description: Converts the value in x, specified in the endian format of the current platform, to big-endian format and returns the resulting value. If it is necessary to swap the bytes, this function calls NSSwapDouble to perform the swap.

NSSwapHostDoubleToLittle

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: NSSwappedDouble NSSwapHostDoubleToLittle(double x)

Description: Converts the value in x, specified in the endian format of the current platform, to little-endian format and returns the resulting value. If it is necessary to swap the bytes, this function calls NSSwapDouble to perform the swap.

NSSwapHostFloatToBig

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: NSSwappedFloat NSSwapHostFloatToBig(float x)

NSSwapHostFloatToLittle

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: NSSwappedFloat NSSwapHostFloatToLittle(float x)

NSSwapHostIntToBig

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned int NSSwapHostIntToBig(unsigned int x)

See also: NSSwapBigIntToHost, NSSwapHostIntToLittle

NSSwapHostIntToLittle

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned int NSSwapHostIntToLittle(unsigned int x)

See also: NSSwapLittleIntToHost, NSSwapHostIntToBig

NSSwapHostLongLongToBig

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned long long NSSwapHostLongLongToBig(unsigned long long x)

NSSwapHostLongLongToLittle

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned long long NSSwapHostLongLongToLittle(unsigned long long x)

NSSwapHostLongToBig

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned long NSSwapHostLongToBig(unsigned long x)

NSSwapHostLongToLittle

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned long NSSwapHostLongToLittle(unsigned long x)

NSSwapHostShortToBig

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned short NSSwapHostShortToBig(unsigned short x)

NSSwapHostShortToLittle

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned short NSSwapHostShortToLittle(unsigned short x)

NSSwapInt

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned int NSSwapInt (unsigned int inv)

Description: Swaps the bytes of inv and returns the resulting value. Bytes are swapped from each low-order position to the corresponding high-order position and vice versa. For example, if the bytes of inv are numbered from 1 to 4, this function swaps bytes 1 and 4, and swaps bytes 2 and 3.

See also: NSSwapShort, NSSwapLong, NSSwapLongLong

NSSwapLittleDoubleToHost

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: double NSSwapLittleDoubleToHost(NSSwappedDouble x)

Description: Converts the little-endian formatted value in x to the endian format of the current platform and returns the resulting value. If it is necessary to swap the bytes of x, this function calls NSSwapDouble to perform the swap.

NSSwapLittleFloatToHost

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: float NSSwapLittleFloatToHost(NSSwappedFloat x)

NSSwapLittleIntToHost

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned int NSSwapLittleIntToHost(unsigned int x)

Description: Converts the little-endian formatted value in x to the endian format of the current platform and returns the resulting value. If it is necessary to swap the bytes, this function calls NSSwapInt to perform the swap.

See also: NSSwapHostIntToLittle, NSSwapBigIntToHost

NSSwapLittleLongLongToHost

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned long long NSSwapLittleLongLongToHost(unsigned long long x)

Description: Converts the little-endian formatted value in x to the endian format of the current platform and returns the resulting value. If it is necessary to swap the bytes, this function calls NSSwapLongLong to perform the swap.

NSSwapLittleLongToHost

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned long NSSwapLittleLongToHost(unsigned long x)

NSSwapLittleShortToHost

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned short NSSwapLittleShortToHost(unsigned short x)

NSSwapLong

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned long NSSwapLong(unsigned long inv)

See also: NSSwapLongLong, NSSwapInt, NSSwapFloat

NSSwapLongLong

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned long long NSSwapLongLong(unsigned long long inv)

Description: Swaps the bytes of inv and returns the resulting value. Bytes are swapped from each low-order position to the corresponding high-order position and vice versa. For example, if the bytes of inv are numbered from 1 to 8, this function swaps bytes 1 and 8, bytes 2 and 7, bytes 3 and 6, and bytes 4 and 5.

See also: NSSwapLong, NSSwapDouble

NSSwapShort

Summary: This function is a utility for swapping the bytes of a number.

Declared in: Foundation/NSByteOrder.h

Synopsis: unsigned short NSSwapShort (unsigned short inv)

Description: Swaps the low-order and high-order bytes of inv and returns the resulting value.

See also: NSSwapInt, NSSwapLong

NSTemporaryDirectory

Summary: This function returns the temporary directory on the user's system.

Declared in: Foundation/NSPathUtilities.h

Synopsis: NSString* NSTemporaryDirectory(void)

Description: Returns a string containing the path of the current temporary directory. If no such directory is currently available, this function returns nil.

NSUnionRange

Summary: This function returns the intersection of the specified ranges.

Declared in: Foundation/NSRange.h

Synopsis: NSRange NSUnionRange(NSRange range1, NSRange range2)

Description: NSUnionRange returns a range covering all indices in and between range1 and range2. If one range is completely contained in the other, the returned range is equal to the larger range.

See also: NSIntersectionRange

NSUnionRect

Summary: This function calculates the union of two rectangles.

Declared in: Foundation/NSGeometry.h

Synopsis: NSRect NSUnionRect(NSRect aRect, NSRect bRect)

Description: NSUnionRect returns the smallest rectangle that completely encloses both aRect and bRect. If one of the rectangles has zero (or negative) width or height, a copy of the other rectangle is returned; but if both have zero (or negative) width or height, the returned rectangle has its origin at (0.0, 0.0) and has zero width and height.

See also: NSIntersectionRect

NSUserName

Summary: This function gets information about a user.

Declared in: Foundation/NSPathUtilities.h

Synopsis: NSString *NSUserName(void)

Description: NSUserName returns the logon name of the current user.

NSWidth

Summary: This function returns the width of the specified rectangle.

Declared in: Foundation/NSGeometry.h

Synopsis: float NSWidth(NSRect aRect)

Description: NSWidth returns the width of aRect.

See also: NSMaxX, NSMaxY, NSMidX, NSMidY, NSMinX, NSMinY, NSHeight

NSZoneCalloc

Summary: This function allocates memory in a zone.

Declared in: Foundation/NSZone.h

Synopsis: void *NSZoneCalloc(NSZone *zone, unsigned numElems, unsigned byteSize)

Description: NSZoneCalloc allocates enough memory from zone for numElems elements, each with a size numBytes bytes, and returns a pointer to the allocated memory. The memory is initialized with zeros. This function returns nil if it was unable to allocate the requested memory.

NSZoneFree

Summary: This function deallocates a block of memory in the specified zone.

Declared in: Foundation/NSZone.h

Synopsis: NSZoneFree(NSZone *zone, void *pointer)

Description: Returns memory to the zone from which it was allocated. The standard C function free does the same, but spends time finding which zone the memory belongs to.

NSZoneFromPointer

Summary: This function gets the zone for a given block of memory

Declared in: Foundation/NSZone.h

Synopsis: NSZone *NSZoneFromPointer(void *pointer)

Description: Returns the zone for the block of memory indicated by pointer, or NULL if the block was not allocated from a zone. The pointer must be one that was returned by a prior call to an allocation function.

Return: Returns the zone for the indicated block of memory, or NULL if the block was not allocated from a zone.

See also: NSZoneCalloc, NSZoneMalloc, NSZoneRealloc

NSZoneMalloc

Summary: This function allocates memory in a zone.

Declared in: Foundation/NSZone.h

Synopsis: void *NSZoneMalloc(NSZone *zone, unsigned size)

Description: NSZoneMalloc allocates size bytes in zone, and returns a pointer to the allocated memory. This function returns nil if it was unable to allocate the requested memory.

NSZoneName

Summary: This function returns the name of the specified zone.

Declared in: Foundation/NSZone.h

Synopsis: NSString *NSZoneName(NSZone *zone)

Description: Returns a string containing the name associated with zone, If zone is nil, the default zone is used. If no name is associated with zone, the returned string is empty.

See also: NSSetZoneName

NSZoneRealloc

Summary: This function allocates memory in a zone.

Declared in: Foundation/NSZone.h

Synopsis: void *NSZoneRealloc(NSZone *zone, void *ptr, unsigned size)

Description: NSZoneRealloc changes the size of the block of memory pointed to by ptr to size bytes. It may allocate new memory to replace the old, in which case it moves the contents of the old memory block to the new block, up to a maximum of size bytes. ptr may be NULL. This function returns nil if it was unable to allocate the requested memory.