Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Foundation Functions Reference

Framework
Foundation/Foundation.h
Declared in
NSByteOrder.h
NSDecimal.h
NSException.h
NSGeometry.h
NSHFSFileTypes.h
NSHashTable.h
NSJavaSetup.h
NSMapTable.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 “Generating Strings Files”.

Byte Ordering

Decimals

The class "NSDecimalNumber" may also be used 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 and Thread Synchronization” in The Objective-C 2.0 Programming Language.

Java Setup

Hash Tables

HFS File Types

Managing Map Tables

Managing Object Allocation and Deallocation

Interacting with the Objective-C Runtime

Logging Output

Managing File Paths

Managing Points

Manipulating Ranges

Manipulating Rectangles

Sizes

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

NSAllHashTableObjects

Returns all of the elements in the specified hash table.

NSArray * NSAllHashTableObjects (
   NSHashTable *table
);

Return Value

An array object containing all the elements of table.

Discussion

This function should be called only when the table elements are objects, not when they’re any other data type.

Availability
See Also
Declared In
NSHashTable.h

NSAllMapTableKeys

Returns all of the keys in the specified map table.

NSArray * NSAllMapTableKeys (
   NSMapTable *table
);

Return Value

An array object containing all the keys in table. This function should be called only when table keys are objects, not when they’re any other type of pointer.

Availability
See Also
Declared In
NSMapTable.h

NSAllMapTableValues

Returns all of the values in the specified table.

NSArray * NSAllMapTableValues (
   NSMapTable *table
);

Return Value

An array object containing all the values in table. This function should be called only when table values are objects, not when they’re any other type of pointer.

Availability
See Also
Declared In
NSMapTable.h

NSAllocateCollectable

Allocates collectable memory.

void *__strong NSAllocateCollectable (
   NSUInteger size,
   NSUInteger options
);

Parameters
size

The number of bytes of memory to allocate.

options

0 or NSScannedOption: A value of 0 allocates nonscanned memory; a value of NSScannedOption allocates scanned memory.

Return Value

A pointer to the allocated memory, or NULL if the function is unable to allocate the requested memory.

Availability
Declared In
NSZone.h

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.

See Also

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.

See Also

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.

See Also

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 cl