iPhone OS Reference Library Apple Developer Connection spyglass button

Foundation Functions Reference

Framework
Foundation/Foundation.h
Declared in
NSBundle.h
NSByteOrder.h
NSDecimal.h
NSException.h
NSObjCRuntime.h
NSObject.h
NSPathUtilities.h
NSRange.h
NSZone.h

Overview

This chapter describes the functions and function-like macros defined in the Foundation Framework.

Functions by Task

Assertions

For additional information about Assertions, see Assertions and Logging.

Bundles

For additional information on generating strings files see Strings Files in Internationalization Programming Topics.

Byte Ordering

Decimals

You can also use the class NSDecimalNumber for decimal arithmetic.

Exception Handling

You can find the following macros implemented in NSException.h. Exception Programming Topics for Cocoa discusses these macros and gives examples of their usage. These macros are useful for code that needs to run on versions of the system prior to Mac OS X v10.3 For later versions of the operating system, you should use the Objective-C compiler directives @try, @catch, @throw, and @finally; for information about these directives, see Exception Handling in The Objective-C Programming Language.

Managing Object Allocation and Deallocation

Interacting with the Objective-C Runtime

Logging Output

Managing File Paths

Managing Ranges

Uncaught Exception Handlers

Whether there’s an uncaught exception handler function, any uncaught exceptions cause the program to terminate, unless the exception is raised during the posting of a notification.

Managing Memory

Managing Zones

Functions

NSAllocateMemoryPages

Allocates a new block of memory.

void * NSAllocateMemoryPages (
   NSUInteger bytes
);
Discussion

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. If the allocation fails, raises NSInvalidArgumentException.

Availability
See Also
Declared In
NSZone.h

NSAllocateObject

Creates and returns a new instance of a given class.

id NSAllocateObject (
   Class aClass,
   NSUInteger extraBytes,
   NSZone *zone
);
Parameters
aClass

The class of which to create an instance.

extraBytes

The number of extra bytes required for indexed instance variables (this value is typically 0).

zone

The zone in which to create the new instance (pass NULL to specify the default zone).

Return Value

A new instance of aClass or nil if an instance could not be created.

Availability
See Also
Declared In
NSObject.h

NSAssert

Generates an assertion if a given condition is false.

#define NSAssert(condition, desc)
Parameters
condition

An expression that evaluates to YES or NO.

desc

An NSString object that contains an error message describing the failure condition.

Discussion

The NSAssert macro evaluates the condition and serves as a front end to the assertion handler.

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 NSInternalInconsistencyException exception. If condition evaluates to NO, the macro invokes handleFailureInMethod:object:file:lineNumber:description: on the assertion handler for the current thread, passing desc as the description string.

This macro should be used only within Objective-C methods.

Assertions are disabled if the preprocessor macro NS_BLOCK_ASSERTIONS is defined.

Availability
See Also
Related Sample Code
Declared In
NSException.h

NSAssert1

Generates an assertion if a given condition is false.

#define NSAssert1(condition, desc, arg1)
Parameters
condition

An expression that evaluates to YES or NO.

desc

An NSString object that contains a printf-style string containing an error message describing the failure condition and a placeholder for a single argument.

arg1

An argument to be inserted, in place, into desc.

Discussion

The NSAssert1 macro evaluates the condition and serves as a front end to the assertion handler.

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 NSInternalInconsistencyException exception. If condition evaluates to NO, the macro invokes handleFailureInMethod:object:file:lineNumber:description: on the assertion handler for the current thread, passing desc as the description string and arg1 as a substitution variable.

This macro should be used only within Objective-C methods.

Assertions are disabled if the preprocessor macro NS_BLOCK_ASSERTIONS is defined.

Availability
See Also
Related Sample Code
Declared In
NSException.h

NSAssert2

Generates an assertion if a given condition is false.

#define NSAssert2(condition, desc, arg1, arg2)
Parameters
condition

An expression that evaluates to YES or NO.

desc

An NSString object that contains a printf-style string containing an error message describing the failure condition and placeholders for two arguments.

arg1

An argument to be inserted, in place, into desc.

arg2

An argument to be inserted, in place, into desc.

Discussion

The NSAssert2 macro evaluates the condition and serves as a front end to the assertion handler.

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 NSInternalInconsistencyException exception. If condition evaluates to NO, the macro invokes handleFailureInMethod:object:file:lineNumber:description: on the assertion handler for the current thread, passing desc as the description string and arg1 and arg2 as substitution variables.

This macro should be used only within Objective-C methods.

Assertions are disabled if the preprocessor macro NS_BLOCK_ASSERTIONS is defined.

Availability
See Also
Related Sample Code
Declared In
NSException.h

NSAssert3

Generates an assertion if a given condition is false.

#define NSAssert3(condition, desc, arg1, arg2, arg3)
Parameters
condition

An expression that evaluates to YES or NO.

desc

An NSString object that contains a printf-style string containing an error message describing the failure condition and placeholders for three arguments.

arg1

An argument to be inserted, in place, into desc.

arg2

An argument to be inserted, in place, into desc.

arg3

An argument to be inserted, in place, into desc.

Discussion

The NSAssert3 macro evaluates the condition and serves as a front end to the assertion handler.

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 NSInternalInconsistencyException exception. If condition evaluates to NO, the macro invokes handleFailureInMethod:object:file:lineNumber:description: on the assertion handler for the current thread, passing desc as the description string and arg1, arg2, and arg3 as substitution variables.

This macro should be used only within Objective-C methods.

Assertions are disabled if the preprocessor macro NS_BLOCK_ASSERTIONS is defined.

Availability
See Also
Related Sample Code
Declared In
NSException.h

NSAssert4

Generates an assertion if a given condition is false.

#define NSAssert4(condition, desc, arg1, arg2, arg3, arg4)
Parameters
condition

An expression that evaluates to YES or NO.

desc

An NSString object that contains a printf-style string containing an error message describing the failure condition and placeholders for four arguments.

arg1

An argument to be inserted, in place, into desc.

arg2

An argument to be inserted, in place, into desc.

arg3

An argument to be inserted, in place, into desc.

arg4

An argument to be inserted, in place, into desc.

Discussion

The NSAssert4 macro evaluates the condition and serves as a front end to the assertion handler.

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 NSInternalInconsistencyException exception. If condition evaluates to NO, the macro invokes handleFailureInMethod:object:file:lineNumber:description: on the assertion handler for the current thread, passing desc as the description string and arg1, arg2, arg3, and arg4 as substitution variables.

This macro should be used only within Objective-C methods.

Assertions are disabled if the preprocessor macro NS_BLOCK_ASSERTIONS is defined.

Availability
See Also
Declared In
NSException.h

NSAssert5

Generates an assertion if a given condition is false.

#define NSAssert5(condition, desc, arg1, arg2, arg3, arg4, arg5)
Parameters
condition

An expression that evaluates to YES or NO.

desc

An NSString object that contains a printf-style string containing an error message describing the failure condition and placeholders for five arguments.

arg1

An argument to be inserted, in place, into desc.

arg2

An argument to be inserted, in place, into desc.

arg3

An argument to be inserted, in place, into desc.

arg4

An argument to be inserted, in place, into desc.

arg5

An argument to be inserted, in place, into desc.

Discussion

The NSAssert5 macro evaluates the condition and serves as a front end to the assertion handler.

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 NSInternalInconsistencyException exception. If condition evaluates to NO, the macro invokes handleFailureInMethod:object:file:lineNumber:description: on the assertion handler for the current thread, passing desc as the description string and arg1, arg2, arg3, arg4, and arg5 as substitution variables.

This macro should be used only within Objective-C methods.

Assertions are disabled if the preprocessor macro NS_BLOCK_ASSERTIONS is defined.

Availability
See Also
Declared In
NSException.h

NSCAssert

Generates an assertion if the given condition is false.

NSCAssert(condition, NSString *description)
Discussion

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 NSInternalInconsistencyException exception.

The NSCAssert macro evaluates the condition and serves as a front end to the assertion handler. This macro should be used only within C functions. NSCAssert takes no arguments other than the condition and format string.

The condition must be an expression that evaluates to true or false. description is a printf-style format string that describes the failure condition.

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

Availability
See Also
Related Sample Code
Declared In
NSException.h

NSCAssert1

NSCAssert1 is one of a series of macros that generate assertions if the given condition is false.

NSCAssert1(condition, NSString *description, arg1)
Discussion

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 NSInternalInconsistencyException exception.

The NSCAssert1 macro evaluates the condition and serves as a front end to the assertion handler. This macro should be used only within C functions.

The condition expression must evaluate to true or false. description is a printf-style format string that describes the failure condition. arg1 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.

Availability
See Also
Related Sample Code
Declared In
NSException.h

NSCAssert2

NSCAssert2 is one of a series of macros that generate assertions if the given condition is false.

NSCAssert2(condition, NSString *description, arg1, arg2)
Discussion

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 NSInternalInconsistencyException exception.

The NSCAssert2 macro evaluates the condition and serves as a front end to the assertion handler. This macro should be used only within C functions.

The condition expression must evaluate to true or false. description is a printf-style format string that describes the failure condition. Each argn 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.

Availability
See Also
Related Sample Code
Declared In
NSException.h

NSCAssert3

NSCAssert3 is one of a series of macros that generate assertions if the given condition is false.

NSCAssert3(condition, NSString *description, arg1, arg2, arg3)
Discussion

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 NSInternalInconsistencyException exception.

The NSCAssert3 macro evaluates the condition and serves as a front end to the assertion handler. This macro should be used only within C functions.

The condition expression must evaluate to true or false. description is a printf-style format string that describes the failure condition. Each argn 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.

Availability
See Also
Declared In
NSException.h

NSCAssert4

NSCAssert4 is one of a series of macros that generate assertions if the given condition is false.

NSCAssert4(condition, NSString *description, arg1, arg2, arg3, arg4)
Discussion

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 NSInternalInconsistencyException exception.

The NSCAssert4 macro evaluates the condition and serves as a front end to the assertion handler. This macro should be used only within C functions.

The condition expression must evaluate to true or false. description is a printf-style format string that describes the failure condition. Each argn 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.

Availability
See Also
Declared In
NSException.h

NSCAssert5

NSCAssert5 is one of a series of macros that generate assertions if the given condition is false.

NSCAssert5(condition, NSString *description, arg1, arg2, arg3, arg4, arg5)
Discussion

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 NSInternalInconsistencyException exception.

The NSCAssert5 macro evaluates the condition and serves as a front end to the assertion handler. This macro should be used only within C functions.

The condition expression must evaluate to true or false. description is a printf-style format string that describes the failure condition. Each argn 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.

Availability
See Also
Declared In
NSException.h

NSClassFromString

Obtains a class by name.

Class NSClassFromString (
   NSString *aClassName
);
Parameters
aClassName

The name of a class.

Return Value

The class object named by aClassName, or nil if no class by that name is currently loaded. If aClassName is nil, returns nil.

Availability
See Also
Related Sample Code
Declared In
NSObjCRuntime.h

NSConvertHostDoubleToSwapped

Performs a type conversion.

NSSwappedDouble NSConvertHostDoubleToSwapped (
   double x
);
Discussion

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 function directly.

Availability
See Also
Declared In
NSByteOrder.h

NSConvertHostFloatToSwapped

Performs a type conversion.

NSSwappedFloat NSConvertHostFloatToSwapped (
   float x
);
Discussion

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 function directly.

Availability
See Also
Declared In
NSByteOrder.h

NSConvertSwappedDoubleToHost

Performs a type conversion.

double NSConvertSwappedDoubleToHost (
   NSSwappedDouble x
);
Discussion

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 function directly.

Availability
See Also
Declared In
NSByteOrder.h

NSConvertSwappedFloatToHost

Performs a type conversion.

float NSConvertSwappedFloatToHost (
   NSSwappedFloat x
);
Discussion

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 function directly.

Availability
See Also
Declared In
NSByteOrder.h

NSCopyMemoryPages

Copies a block of memory.

void NSCopyMemoryPages (
   const void *source,
   void *dest,
   NSUInteger bytes
);
Discussion

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

Availability
See Also
Declared In
NSZone.h

NSCopyObject

Creates an exact copy of an object.

id NSCopyObject (
   id object,
   NSUInteger extraBytes,
   NSZone *zone
);
Parameters
object

The object to copy.

extraBytes

The number of extra bytes required for indexed instance variables (this value is typically 0).

zone

The zone in which to create the new instance (pass NULL to specify the default zone).

Return Value

A new object that’s an exact copy of anObject, or nil if object is nil or if object could not be copied.

Special Considerations

This function is dangerous and very difficult to use correctly. It's use as part of copyWithZone: by any class that can be subclassed, is highly error prone. Under GC or when using Objective-C 2.0, the zone is completely ignored.

This function is likely to be deprecated after Mac OS X 10.6.

Availability
See Also
Related Sample Code
Declared In
NSObject.h

NSCParameterAssert

Evaluates the specified parameter.

NSCParameterAssert(condition)
Discussion

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 NSInternalInconsistencyException exception.

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 that includes the parameter and then raises an exception.

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

Availability
See Also
Declared In
NSException.h

NSCreateZone

Creates a new zone.

NSZone * NSCreateZone (
   NSUInteger startSize,
   NSUInteger granularity,
   BOOL canFree
);
Return Value

A pointer to a new zone of startSize bytes, which will grow and shrink by granularity bytes. If canFree is 0, the allocator will never free memory, and malloc will be fast. Returns NULL if a new zone could not be created.

Availability
See Also
Declared In
NSZone.h

NSDeallocateMemoryPages

Deallocates the specified block of memory.

void NSDeallocateMemoryPages (
   void *ptr,
   NSUInteger bytes
);
Discussion

This function deallocates memory that was allocated with NSAllocateMemoryPages.

Availability
See Also
Declared In
NSZone.h

NSDeallocateObject

Destroys an existing object.

void NSDeallocateObject (
   id object
);
Parameters
object

An object.

Discussion

This function deallocates object, which must have been allocated using NSAllocateObject.

Availability
See Also
Declared In
NSObject.h

NSDecimalAdd

Adds two decimal values.

NSCalculationError NSDecimalAdd (
   NSDecimal *result,
   const NSDecimal *leftOperand,
   const NSDecimal *rightOperand,
   NSRoundingMode roundingMode
);
Discussion

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:

NSRoundDownRound return values down.
NSRoundUpRound return values up.
NSRoundPlainRound to the closest possible return value; when caught halfway between two positive numbers, round up; when caught between two negative numbers, round down.
NSRoundBankersRound to the closest possible return value; when halfway between two possibilities, return the possibility whose last digit is even.

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

For more information, see Number and Value Programming Topics for Cocoa.

Availability
Declared In
NSDecimal.h

NSDecimalCompact

Compacts the decimal structure for efficiency.

void NSDecimalCompact (
   NSDecimal *number
);
Discussion

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

For more information, see Number and Value Programming Topics for Cocoa.

Availability
Declared In
NSDecimal.h

NSDecimalCompare

Compares two decimal values.

NSComparisonResult NSDecimalCompare (
   const NSDecimal *leftOperand,
   const NSDecimal *rightOperand
);
Return Value

NSOrderedDescending if leftOperand is bigger than rightOperand; NSOrderedAscending if rightOperand is bigger than leftOperand; or NSOrderedSame if the two operands are equal.

Discussion

For more information, see Number and Value Programming Topics for Cocoa.

Availability
Declared In
NSDecimal.h

NSDecimalCopy

Copies the value of a decimal number.

void NSDecimalCopy (
   NSDecimal *destination,
   const NSDecimal *source
);
Discussion

Copies the value in source to destination.

For more information, see Number and Value Programming Topics for Cocoa.

Availability
Declared In
NSDecimal.h

NSDecimalDivide

Divides one decimal value by another.

NSCalculationError NSDecimalDivide (
   NSDecimal *result,
   const NSDecimal *leftOperand,
   const NSDecimal *rightOperand,
   NSRoundingMode roundingMode
);
Discussion

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 possible return values and rounding modes, see NSDecimalAdd.

Note that repeating decimals or numbers with a mantissa larger than 38 digits cannot be represented precisely.

For more information, see Number and Value Programming Topics for Cocoa.

Availability
Declared In
NSDecimal.h

NSDecimalIsNotANumber

Returns a Boolean that indicates whether a given decimal contains a valid number.

BOOL NSDecimalIsNotANumber (
   const NSDecimal *dcm
);
Return Value

YES if the value in decimal represents a valid number, otherwise NO.

For more information, see Number and Value Programming Topics for Cocoa.

Availability
Declared In
NSDecimal.h

NSDecimalMultiply

Multiplies two decimal numbers together.

NSCalculationError NSDecimalMultiply (
   NSDecimal *result,
   const NSDecimal *leftOperand,
   const NSDecimal *rightOperand,
   NSRoundingMode roundingMode
);
Discussion

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

For explanations of the possible return values and rounding modes, see NSDecimalAdd.

For more information, see Number and Value Programming Topics for Cocoa.

Availability
Declared In
NSDecimal.h

NSDecimalMultiplyByPowerOf10

Multiplies a decimal by the specified power of 10.

NSCalculationError NSDecimalMultiplyByPowerOf10 (
   NSDecimal *result,
   const NSDecimal *number,
   short power,
   NSRoundingMode roundingMode
);
Discussion

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

For explanations of the possible return values and rounding modes, see NSDecimalAdd.

For more information, see Number and Value Programming Topics for Cocoa.

Availability
Declared In
NSDecimal.h

NSDecimalNormalize

Normalizes the internal format of two decimal numbers to simplify later operations.

NSCalculationError NSDecimalNormalize (
   NSDecimal *number1,
   NSDecimal *number2,
   NSRoundingMode roundingMode
);
Discussion

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

Format 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 possible return values, see NSDecimalAdd.

For more information, see Number and Value Programming Topics for Cocoa.

Availability
Declared In
NSDecimal.h

NSDecimalPower

Raises the decimal value to the specified power.

NSCalculationError NSDecimalPower (
   NSDecimal *result,
   const NSDecimal *number,
   NSUInteger power,
   NSRoundingMode roundingMode
);
Discussion

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 rounding modes, see NSDecimalAdd.

For more information, see Number and Value Programming Topics for Cocoa.

Availability
Declared In
NSDecimal.h

NSDecimalRound

Rounds off the decimal value.

void NSDecimalRound (
   NSDecimal *result,
   const NSDecimal *number,
   NSInteger scale,
   NSRoundingMode roundingMode
);
Discussion

Rounds number off according to the parameters scale and roundingMode and stores the result in result.

The scale value 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 NSDecimalNumberBehaviors.

For more information, see Number and Value Programming Topics for Cocoa.

Availability
Declared In
NSDecimal.h

NSDecimalString

Returns a string representation of the decimal value.

NSString * NSDecimalString (
   const NSDecimal *dcm,
   id locale
);
Discussion

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

For more information, see Number and Value Programming Topics for Cocoa.

Availability
Declared In
NSDecimal.h

NSDecimalSubtract

Subtracts one decimal value from another.

NSCalculationError NSDecimalSubtract (
   NSDecimal *result,
   const NSDecimal *leftOperand,
   const NSDecimal *rightOperand,
   NSRoundingMode roundingMode
);
Discussion

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

For explanations of the possible return values and rounding modes, see NSDecimalAdd.

For more information, see Number and Value Programming Topics for Cocoa.

Availability
Declared In
NSDecimal.h

NSDecrementExtraRefCountWasZero

Decrements the specified object’s reference count.

BOOL NSDecrementExtraRefCountWasZero (
   id object
);
Parameters
object

An object.

Return Value

NO if anObject had an extra reference count, or YES if anObject didn’t have an extra reference count—indicating that the object should be deallocated (with dealloc).

Discussion

Decrements the “extra reference” count of anObject. 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.

Availability
See Also
Declared In
NSObject.h

NSDefaultMallocZone

Returns the default zone.

NSZone * NSDefaultMallocZone (void);
Return Value

The default zone, which is created automatically at startup.

Discussion

This zone is used by the standard C function malloc.

Availability
See Also
Declared In
NSZone.h

NSEqualRanges

Returns a Boolean value that indicates whether two given ranges are equal.

BOOL NSEqualRanges (
   NSRange range1,
   NSRange range2
);
Return Value

YES if range1 and range2 have the same locations and lengths.

Availability
Declared In
NSRange.h

NSExtraRefCount

Returns the specified object’s reference count.

NSUInteger NSExtraRefCount (
   id object
);
Parameters
object

An object.

Return Value

The current reference count of object.

Discussion

This function is used in conjunction with NSIncrementExtraRefCount and NSDecrementExtraRefCountWasZero in situations where you need to override an object’s retain and release methods.

Availability
Declared In
NSObject.h

NSFullUserName

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

NSString * NSFullUserName (void);
Return Value

A string containing the full name of the current user.

Availability
See Also
Declared In
NSPathUtilities.h

NSGetSizeAndAlignment

Obtains the actual size and the aligned size of an encoded type.

const char * NSGetSizeAndAlignment (
   const char *typePtr,
   NSUInteger *sizep,
   NSUInteger *alignp
);
Discussion

Obtains the actual size and the aligned size of the first data type represented by typePtr and returns a pointer to the position of the next data type in typePtr. You can specify NULL for either sizep or alignp to ignore the corresponding information.

The value returned in alignp is the aligned size of the data type; for example, on some platforms, the aligned size of a char might be 2 bytes while the actual physical size is 1 byte.

Availability
Declared In
NSObjCRuntime.h

NSGetUncaughtExceptionHandler

Returns the top-level error handler.

NSUncaughtExceptionHandler * NSGetUncaughtExceptionHandler (void);
Return Value

A pointer to the top-level error-handling function where you can perform last-minute logging before the program terminates.

Availability
See Also
Declared In
NSException.h

NSHomeDirectory

Returns the path to the current user’s home directory.

NSString * NSHomeDirectory (void);
Return Value

The path to the current user’s home directory.

Discussion

For more information on file-system utilities, see Low-Level File Management Programming Topics.

Availability
See Also
Declared In
NSPathUtilities.h

NSHomeDirectoryForUser

Returns the path to a given user’s home directory.

NSString * NSHomeDirectoryForUser (
   NSString *userName
);
Parameters
userName

The name of a user.

Return Value

The path to the home directory for the user specified by userName.

Discussion

For more information on file system utilities, see Low-Level File Management Programming Topics.

Availability
See Also
Declared In
NSPathUtilities.h

NSHostByteOrder

Returns the endian format.

long NSHostByteOrder (void);
Return Value

The endian format, either NS_LittleEndian or NS_BigEndian.

Availability
Declared In
NSByteOrder.h

NSIncrementExtraRefCount

Increments the specified object’s reference count.

void NSIncrementExtraRefCount (
   id object
);
Parameters
object

An object.

Discussion

This function increments the “extra reference” count of 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.

Availability
See Also
Declared In
NSObject.h

NSIntersectionRange

Returns the intersection of the specified ranges.

NSRange NSIntersectionRange (
   NSRange range1,
   NSRange range2
);
Return Value

A range describing the intersection of range1 and range2—that is, a range containing the indices that exist in both ranges.

Discussion

If the returned range’s length field is 0, then the two ranges don’t intersect, and the value of the location field is undefined.

Availability
See Also
Declared In
NSRange.h

NSLocalizedString

Returns a localized version of a string.

NSString *NSLocalizedString(NSString *key, NSString *comment)
Return Value

The result of invoking localizedStringForKey:value:table: on the main bundle and a nil table.

Discussion

You can specify Unicode characters in key using \\Uxxxx—see the -u option for for the genstrings utility.

For more information, see NSBundle.

Special Considerations

In Mac OS X v10.4 and earlier, to ensure correct parsing by the genstrings utility, the key parameter must not contain any high-ASCII characters.

Availability
Related Sample Code
Declared In
NSBundle.h

NSLocalizedStringFromTable

Returns a localized version of a string.

NSString *NSLocalizedStringFromTable(NSString *key, NSString *tableName, NSString *comment)
Return Value

The result of invoking localizedStringForKey:value:table: on the main bundle, passing it the specified key and tableName.

Discussion

You can specify Unicode characters in key using \\Uxxxx—see the -u option for for the genstrings utility.

For more information, see NSBundle.

Special Considerations

In Mac OS X v10.4 and earlier, to ensure correct parsing by the genstrings utility, the key parameter must not contain any high-ASCII characters.

Availability
Declared In
NSBundle.h

NSLocalizedStringFromTableInBundle

Returns a localized version of a string.

NSString *NSLocalizedStringFromTableInBundle(NSString *key, NSString *tableName, NSBundle *bundle, NSString *comment)
Return Value

The result of invoking localizedStringForKey:value:table: on bundle, passing it the specified key and tableName.

Discussion

You can specify Unicode characters in key using \\Uxxxx—see the -u option for for the genstrings utility.

For more information, see NSBundle.

Special Considerations

In Mac OS X v10.4 and earlier, to ensure correct parsing by the genstrings utility, the key parameter must not contain any high-ASCII characters.

Availability
Declared In
NSBundle.h

NSLocalizedStringWithDefaultValue

Returns a localized version of a string.

NSString *NSLocalizedStringWithDefaultValue(NSString *key, NSString *tableName, NSBundle *bundle, NSString *value, NSString *comment)
Return Value

The result of invoking localizedStringForKey:value:table: on bundle, passing it the specified key, value, and tableName.

Discussion

You can specify Unicode characters in key using \\Uxxxx—see the -u option for for the genstrings utility.

If you use genstrings to parse your code for localizable strings, you can use this method to specify an initial value that is different from key.

For more information, see NSBundle.

Special Considerations

In Mac OS X v10.4 and earlier, to ensure correct parsing by the genstrings utility, the key parameter must not contain any high-ASCII characters.

Availability
Declared In
NSBundle.h

NSLocationInRange

Returns a Boolean value that indicates whether a specified position is in a given range.

BOOL NSLocationInRange (
   NSUInteger loc,
   NSRange range
);
Return Value

YES if loc lies within range—that is, if it’s greater than or equal to range.location and less than range.location plus range.length.

Availability
Declared In
NSRange.h

NSLog

Logs an error message to the Apple System Log facility.

void NSLog (
   NSString *format,
   ...
);
Discussion

Simply calls NSLogv, passing it a variable number of arguments.

Availability
See Also
Related Sample Code
Declared In
NSObjCRuntime.h

NSLogPageSize

Returns the binary log of the page size.

NSUInteger NSLogPageSize (void);
Return Value

The binary log of the page size.

Availability
See Also
Declared In
NSZone.h

NSLogv

Logs an error message to the Apple System Log facility.

void NSLogv (
   NSString *format,
   va_list args
);
Discussion

Logs an error message to the Apple System Log facility (see man 3 asl). If the STDERR_FILENO file descriptor has been redirected away from the default or is going to a tty, it will also be written there. If you want to direct output elsewhere, you need to use a custom logging facility.

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). The supported format specifiers are described in String Format Specifiers. A final hard return is added to the error message if one is not present in the format.

In general, you should use the NSLog function instead of calling this function directly. If you do use this function directly, you must have prepared the variable argument list in the args argument by calling the standard C macro va_start. Upon completion, you must similarly call the standard C macro va_end for this list.

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

Availability
See Also
Declared In
NSObjCRuntime.h

NSMakeCollectable

Makes a newly allocated Core Foundation object eligible for collection.

NS_INLINE id NSMakeCollectable(CFTypeRef cf) {
   return cf ? (id)CFMakeCollectable(cf) : nil;
}
Discussion

This function is a wrapper for CFMakeCollectable, but its return type is id—avoiding the need for casting when using Cocoa objects.

This function may be useful when returning Core Foundation objects in code that must support both garbage-collected and non-garbage-collected environments, as illustrated in the following example.

- (CFDateRef)foo {
    CFDateRef aCFDate;
    // ...
    return [NSMakeCollectable(aCFDate) autorelease];
}

CFTypeRef style objects are garbage collected, yet only sometime after the last CFRelease is performed. Particularly for fully-bridged CFTypeRef objects such as CFStrings and collections (such as CFDictionary), you must call either CFMakeCollectable or the more type safe NSMakeCollectable, preferably right upon allocation.

Availability
Declared In
NSZone.h

NSMakeRange

Creates a new NSRange from the specified values.

NSRange NSMakeRange (
   NSUInteger loc,
   NSUInteger len
);
Return Value

An NSRange with location location and length length.

Availability
Declared In
NSRange.h

NSMaxRange

Returns the sum of the location and length of the range.

NSUInteger NSMaxRange (
   NSRange range
);
Return Value

The sum of the location and length of the range—that is, range.location + range.length.

Availability
Related Sample Code
Declared In
NSRange.h

NSOpenStepRootDirectory

Returns the root directory of the user’s system.

NSString * NSOpenStepRootDirectory (void);
Return Value

A string identifying the root directory of the user’s system.

Discussion

For more information on file system utilities, see Low-Level File Management Programming Topics.

Availability
See Also
Declared In
NSPathUtilities.h

NSPageSize

Returns the number of bytes in a page.

NSUInteger NSPageSize (void);
Return Value

The number of bytes in a page.

Availability
See Also
Declared In
NSZone.h

NSParameterAssert

Validates the specified parameter.

NSParameterAssert(condition)
Discussion

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 NSInternalInconsistencyException exception.

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

Availability
See Also
Related Sample Code
Declared In
NSException.h

NSProtocolFromString

Returns a the protocol with a given name.

Protocol *NSProtocolFromString (
   NSString *namestr
);
Parameters
namestr

The name of a protocol.

Return Value

The protocol object named by namestr, or nil if no protocol by that name is currently loaded. If namestr is nil, returns nil.

Availability
See Also
Declared In
NSObjCRuntime.h

NSRangeFromString

Returns a range from a textual representation.

NSRange NSRangeFromString (
   NSString *aString
);
Discussion

Scans aString for two integers which are used as the location and length values, in that order, to create an NSRange struct. If aString only contains a single integer, it is used as the location value. If aString does not contain any integers, this function returns an NSRange struct whose location and length values are both 0.

Availability
See Also
Declared In
NSRange.h

NSRealMemoryAvailable

Returns information about the user’s system.

NSUInteger NSRealMemoryAvailable (void);
Return Value

The number of bytes available in RAM.

Availability
Declared In
NSZone.h

NSRecycleZone

Frees memory in a zone.

void NSRecycleZone (
   NSZone *zone
);
Discussion

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

Availability
See Also
Declared In
NSZone.h

NSRoundDownToMultipleOfPageSize

Returns the specified number of bytes rounded down to a multiple of the page size.

NSUInteger NSRoundDownToMultipleOfPageSize (
   NSUInteger bytes
);
Return Value

In bytes, the multiple of the page size that is closest to, but not greater than, byteCount (that is, the number of bytes rounded down to a multiple of the page size).

Availability
See Also
Declared In
NSZone.h

NSRoundUpToMultipleOfPageSize

Returns the specified number of bytes rounded up to a multiple of the page size.

NSUInteger NSRoundUpToMultipleOfPageSize (
   NSUInteger bytes
);
Return Value

In bytes, the multiple of the page size that is closest to, but not less than, byteCount (that is, the number of bytes rounded up to a multiple of the page size).

Availability
See Also
Declared In
NSZone.h

NSSearchPathForDirectoriesInDomains

Creates a list of directory search paths.

NSArray * NSSearchPathForDirectoriesInDomains (
   NSSearchPathDirectory directory,
   NSSearchPathDomainMask domainMask,
   BOOL expandTilde
);
Discussion

Creates a list of path strings for the specified directories in the specified domains. The list is in the order in which you should search the directories. If expandTilde is YES, tildes are expanded as described in stringByExpandingTildeInPath.

For more information on file system utilities, see Locating Directories on the System.

Note: The directory returned by this method may not exist. This method simply gives you the appropriate location for the requested directory. Depending on the application’s needs, it may be up to the developer to create the appropriate directory and any in between.

Availability
Related Sample Code
Declared In
NSPathUtilities.h

NSSelectorFromString

Returns the selector with a given name.

SEL NSSelectorFromString (
   NSString *aSelectorName
);
Parameters
aSelectorName

A string of any length, with any characters, that represents the name of a selector.

Return Value

The selector named by aSelectorName. If aSelectorName is nil, or cannot be converted to UTF-8 (this should be only due to insufficient memory), returns (SEL)0.

Discussion

To make a selector, NSSelectorFromString passes a UTF-8 encoded character representation of aSelectorName to sel_registerName and returns the value returned by that function. Note, therefore, that if the selector does not exist it is registered and the newly-registered selector is returned.

Recall that a colon (“:”) is part of a method name; setHeight is not the same as setHeight:. For more about methods names, see Objects, Classes, and Messaging in The Objective-C Programming Language.

Availability
See Also
Declared In
NSObjCRuntime.h

NSSetUncaughtExceptionHandler

Changes the top-level error handler.

void NSSetUncaughtExceptionHandler (
   NSUncaughtExceptionHandler *
);
Discussion

Sets the top-level error-handling function where you can perform last-minute logging before the program terminates.

Availability
See Also
Declared In
NSException.h

NSSetZoneName

Sets the name of the specified zone.

void NSSetZoneName (
   NSZone *zone,
   NSString *name
);
Discussion

Sets the name of zone to name, which can aid in debugging.

Availability
See Also
Declared In
NSZone.h

NSShouldRetainWithZone

Indicates whether an object should be retained.

BOOL NSShouldRetainWithZone (
   id anObject,
   NSZone *requestedZone
);
Parameters
anObject

An object.

requestedZone

A memory zone.

Return Value

Returns YES if requestedZone is NULL, the default zone, or the zone in which anObject was allocated; otherwise NO.

Discussion

This function is typically called from inside an NSObject’s copyWithZone:, when deciding whether to retain anObject as opposed to making a copy of it.

Availability
Declared In
NSObject.h

NSStringFromClass

Returns the name of a class as a string.

NSString * NSStringFromClass (
   Class aClass
);
Parameters
aClass

A class.

Return Value

A string containing the name of aClass. If aClass is nil, returns nil.

Availability
See Also
Declared In
NSObjCRuntime.h

NSStringFromProtocol

Returns the name of a protocol as a string.

NSString * NSStringFromProtocol (
   Protocol *proto
);
Parameters
proto

A protocol.

Return Value

A string containing the name of proto.

Availability
See Also
Declared In
NSObjCRuntime.h

NSStringFromRange

Returns a string representation of a range.

NSString * NSStringFromRange (
   NSRange range
);
Return Value

A string of the form “{a, b}”, where a and b are non-negative integers representing aRange.

Availability
Declared In
NSRange.h

NSStringFromSelector

Returns a string representation of a given selector.

NSString *NSStringFromSelector (
   SEL aSelector
);
Parameters
aSelector

A selector.

Return Value

A string representation of aSelector.

Availability
See Also
Declared In
NSObjCRuntime.h

NSSwapBigDoubleToHost

A utility for swapping the bytes of a number.

double NSSwapBigDoubleToHost (
   NSSwappedDouble x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapBigFloatToHost

A utility for swapping the bytes of a number.

float NSSwapBigFloatToHost (
   NSSwappedFloat x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapBigIntToHost

A utility for swapping the bytes of a number.

unsigned int NSSwapBigIntToHost (
   unsigned int x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapBigLongLongToHost

A utility for swapping the bytes of a number.

unsigned long long NSSwapBigLongLongToHost (
   unsigned long long x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapBigLongToHost

A utility for swapping the bytes of a number.

unsigned long NSSwapBigLongToHost (
   unsigned long x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapBigShortToHost

A utility for swapping the bytes of a number.

unsigned short NSSwapBigShortToHost (
   unsigned short x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapDouble

A utility for swapping the bytes of a number.

NSSwappedDouble NSSwapDouble (
   NSSwappedDouble x
);
Discussion

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.

Availability
See Also
Declared In
NSByteOrder.h

NSSwapFloat

A utility for swapping the bytes of a number.

NSSwappedFloat NSSwapFloat (
   NSSwappedFloat x
);
Discussion

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 bytes 2 and 3.

Availability
See Also
Declared In
NSByteOrder.h

NSSwapHostDoubleToBig

A utility for swapping the bytes of a number.

NSSwappedDouble NSSwapHostDoubleToBig (
   double x
);
Discussion

Converts the value in x, specified in the current endian format, 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.

Availability
See Also
Declared In
NSByteOrder.h

NSSwapHostDoubleToLittle

A utility for swapping the bytes of a number.

NSSwappedDouble NSSwapHostDoubleToLittle (
   double x
);
Discussion

Converts the value in x, specified in the current endian format, 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.

Availability
See Also
Declared In
NSByteOrder.h

NSSwapHostFloatToBig

A utility for swapping the bytes of a number.

NSSwappedFloat NSSwapHostFloatToBig (
   float x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapHostFloatToLittle

A utility for swapping the bytes of a number.

NSSwappedFloat NSSwapHostFloatToLittle (
   float x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapHostIntToBig

A utility for swapping the bytes of a number.

unsigned int NSSwapHostIntToBig (
   unsigned int x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapHostIntToLittle

A utility for swapping the bytes of a number.

unsigned int NSSwapHostIntToLittle (
   unsigned int x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapHostLongLongToBig

A utility for swapping the bytes of a number.

unsigned long long NSSwapHostLongLongToBig (
   unsigned long long x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapHostLongLongToLittle

A utility for swapping the bytes of a number.

unsigned long long NSSwapHostLongLongToLittle (
   unsigned long long x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapHostLongToBig

A utility for swapping the bytes of a number.

unsigned long NSSwapHostLongToBig (
   unsigned long x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapHostLongToLittle

A utility for swapping the bytes of a number.

unsigned long NSSwapHostLongToLittle (
   unsigned long x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapHostShortToBig

A utility for swapping the bytes of a number.

unsigned short NSSwapHostShortToBig (
   unsigned short x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapHostShortToLittle

A utility for swapping the bytes of a number.

unsigned short NSSwapHostShortToLittle (
   unsigned short x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapInt

A utility for swapping the bytes of a number.

unsigned int NSSwapInt (
   unsigned int inv
);
Discussion

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 bytes 2 and 3.

Availability
See Also
Declared In
NSByteOrder.h

NSSwapLittleDoubleToHost

A utility for swapping the bytes of a number.

double NSSwapLittleDoubleToHost (
   NSSwappedDouble x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapLittleFloatToHost

A utility for swapping the bytes of a number.

float NSSwapLittleFloatToHost (
   NSSwappedFloat x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapLittleIntToHost

A utility for swapping the bytes of a number.

unsigned int NSSwapLittleIntToHost (
   unsigned int x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapLittleLongLongToHost

A utility for swapping the bytes of a number.

unsigned long long NSSwapLittleLongLongToHost (
   unsigned long long x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapLittleLongToHost

A utility for swapping the bytes of a number.

unsigned long NSSwapLittleLongToHost (
   unsigned long x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapLittleShortToHost

A utility for swapping the bytes of a number.

unsigned short NSSwapLittleShortToHost (
   unsigned short x
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSSwapLong

A utility for swapping the bytes of a number.

unsigned long NSSwapLong (
   unsigned long inv
);
Discussion

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 bytes 2 and 3.

Availability
See Also
Declared In
NSByteOrder.h

NSSwapLongLong

A utility for swapping the bytes of a number.

unsigned long long NSSwapLongLong (
   unsigned long long inv
);
Discussion

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.

Availability
See Also
Declared In
NSByteOrder.h

NSSwapShort

A utility for swapping the bytes of a number.

unsigned short NSSwapShort (
   unsigned short inv
);
Discussion

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

Availability
See Also
Declared In
NSByteOrder.h

NSTemporaryDirectory

Returns the path of the temporary directory for the current user.

NSString * NSTemporaryDirectory (void);
Return Value

A string containing the path of the temporary directory for the current user. If no such directory is currently available, returns nil.

Discussion

For more information on file system utilities, see Low-Level File Management Programming Topics.

The temporary directory is determined by confstr(3) passing the _CS_DARWIN_USER_TEMP_DIR flag. The erase rules are whatever match that directory.

See the NSFileManager method URLForDirectory:inDomain:appropriateForURL:create:error: for an alternate (and more flexible) means of finding the correct temporary directory.

Availability
See Also
Related Sample Code
Declared In
NSPathUtilities.h

NSUnionRange

Returns the union of the specified ranges.

NSRange NSUnionRange (
   NSRange range1,
   NSRange range2
);
Return Value

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.

Availability
See Also
Declared In
NSRange.h

NSUserName

Returns the logon name of the current user.

NSString * NSUserName (void);
Return Value

The logon name of the current user.

Availability
See Also
Declared In
NSPathUtilities.h

NSZoneCalloc

Allocates memory in a zone.

void * NSZoneCalloc (
   NSZone *zone,
   NSUInteger numElems,
   NSUInteger byteSize
);
Discussion

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 NULL if it was unable to allocate the requested memory.

Availability
See Also
Declared In
NSZone.h

NSZoneFree

Deallocates a block of memory in the specified zone.

void NSZoneFree (
   NSZone *zone,
   void *ptr
);
Discussion

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.

Availability
See Also
Declared In
NSZone.h

NSZoneFromPointer

Gets the zone for a given block of memory.

NSZone * NSZoneFromPointer (
   void *ptr
);
Return Value

The zone for the block of memory indicated by pointer, or NULL if the block was not allocated from a zone.

Discussion

pointer must be one that was returned by a prior call to an allocation function.

Availability
See Also
Declared In
NSZone.h

NSZoneMalloc

Allocates memory in a zone.

void * NSZoneMalloc (
   NSZone *zone,
   NSUInteger size
);
Discussion

Allocates size bytes in zone and returns a pointer to the allocated memory. This function returns NULL if it was unable to allocate the requested memory.

Availability
See Also
Declared In
NSZone.h

NSZoneName

Returns the name of the specified zone.

NSString * NSZoneName (
   NSZone *zone
);
Return Value

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.

Availability
See Also
Declared In
NSZone.h

NSZoneRealloc

Allocates memory in a zone.

void * NSZoneRealloc (
   NSZone *zone,
   void *ptr,
   NSUInteger size
);
Discussion

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 NULL if it was unable to allocate the requested memory.

Availability
See Also
Declared In
NSZone.h

NS_DURING

Marks the start of the exception-handling domain.

NS_DURING
Discussion

The NS_DURING macro marks the start of the exception-handling domain for a section of code. (The NS_HANDLERmacro marks the end of the domain.) Within the exception-handling domain you can raise an exception, giving the local exception handler (or lower exception handlers) a chance to handle it.

Availability
Declared In
NSException.h

NS_ENDHANDLER

Marks the end of the local event handler.

NS_ENDHANDLER
Discussion

The NS_ENDHANDLER marks the end of a section of code that is a local exception handler. (The NS_HANDLERmacros marks the beginning of this section.) If an exception is raised in the exception handling domain marked off by the NS_DURING and NS_HANDLER, the local exception handler (if specified) is given a chance to handle the exception.

Availability
Declared In
NSException.h

NS_HANDLER

Marks the end of the exception-handling domain and the start of the local exception handler.

NS_HANDLER
Discussion

The NS_HANDLER macro marks end of a section of code that is an exception-handling domain while at the same time marking the beginning of a section of code that is a local exception handler for that domain. (The NS_DURING macro marks the beginning of the exception-handling domain; the NS_ENDHANDLER marks the end of the local exception handler.) If an exception is raised in the exception-handling domain, the local exception handler is first given the chance to handle the exception before lower-level handlers are given a chance.

Availability
Declared In
NSException.h

NS_VALUERETURN

Permits program control to exit from an exception-handling domain with a value of a specified type.

NS_VALUERETURN(val, type)
Parameters
val

A value to preserve beyond the exception-handling domain.

type

The type of the value specified in val.

Discussion

The NS_VALUERETURN macro returns program control to the caller out of the exception-handling domain—that is, a section of code between the NS_DURING and NS_HANDLER macros that might raise an exception. The specified value (of the specified type) is returned to the caller. The standard return statement does not work as expected in the exception-handling domain.

Availability
Declared In
NSException.h

NS_VOIDRETURN

Permits program control to exit from an exception-handling domain.

NS_VOIDRETURN
Discussion

The NS_VOIDRETURN macro returns program control to the caller out of the exception-handling domain—that is, a section of code between the NS_DURING and NS_HANDLER macros that might raise an exception. The standard return statement does not work as expected in the exception-handling domain.

Availability
Declared In
NSException.h

Last updated: 2009-10-11

Did this document help you? Yes It's good, but... Not helpful...