iOS Developer Library — Prerelease

Developer

Foundation Framework Reference Foundation Functions Reference

Options
Deployment Target:

On This Page
Language:

Foundation Functions Reference

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

Functions

For additional information about Assertions, see Assertions and Logging Programming Guide.

  • Generates an assertion if a given condition is false.

    Declaration

    Objective-C

    #define NSAssert(condition, desc, ...)

    Parameters

    condition

    An expression that evaluates to YEStrue or NOfalse.

    desc

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

    ...

    The arguments displayed in the desc string.

    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 NOfalse, 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

    Available in iOS 2.0 and later.

  • Generates an assertion if a given condition is false.

    Declaration

    Objective-C

    #define NSAssert1(condition, desc, arg1)

    Parameters

    condition

    An expression that evaluates to YEStrue or NOfalse.

    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 NOfalse, 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

    Available in iOS 2.0 and later.

  • Generates an assertion if a given condition is false.

    Declaration

    Objective-C

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

    Parameters

    condition

    An expression that evaluates to YEStrue or NOfalse.

    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 NOfalse, 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

    Available in iOS 2.0 and later.

  • Generates an assertion if a given condition is false.

    Declaration

    Objective-C

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

    Parameters

    condition

    An expression that evaluates to YEStrue or NOfalse.

    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 NOfalse, 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

    Available in iOS 2.0 and later.

  • Generates an assertion if a given condition is false.

    Declaration

    Objective-C

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

    Parameters

    condition

    An expression that evaluates to YEStrue or NOfalse.

    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 NOfalse, 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

    Available in iOS 2.0 and later.

  • Generates an assertion if a given condition is false.

    Declaration

    Objective-C

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

    Parameters

    condition

    An expression that evaluates to YEStrue or NOfalse.

    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 NOfalse, 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

    Available in iOS 2.0 and later.

  • Generates an assertion if the given condition is false.

    Declaration

    Objective-C

    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

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

    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

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

    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

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

    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

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

    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

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

    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

    Available in iOS 2.0 and later.

  • Evaluates the specified parameter.

    Declaration

    Objective-C

    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

    Available in iOS 2.0 and later.

  • Validates the specified parameter.

    Declaration

    Objective-C

    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

    Available in iOS 2.0 and later.

For additional information on generating strings files see Using Strings Files for User-Facing Text.

  • Returns a localized version of a string.

    Declaration

    Objective-C

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

    Parameters

    key

    The key for a string in the default table.

    comment

    The comment to place above the key-value pair in the strings file.

    Return Value

    The result of invoking localizedStringForKey:value:table: on the main bundle passing nil as the table.

    Discussion

    Use this macro to generate the default Localizable.strings file from your code using the genstrings utility. You can specify Unicode characters in key using \\Uxxxx—see the -u option for the genstrings utility. The initial value for key in the strings file will be key. Use the NSLocalizedStringWithDefaultValue macro to specify another value for key.

    For more information, see NSBundle.

    Special Considerations

    In 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

    Available in iOS 2.0 and later.

  • Returns a localized version of a string from the specified table.

    Declaration

    Objective-C

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

    Parameters

    key

    The key for a string in the specified table.

    tableName

    The name of the table containing the key-value pairs. Also, the suffix for the strings file (a file with the .strings extension) to store the localized string.

    comment

    The comment to place above the key-value pair in the strings file.

    Return Value

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

    Discussion

    Use this macro to generate a specific strings files named [tableName].strings from your code using the genstrings utility. You can specify Unicode characters in key using \\Uxxxx—see the -u option for for the genstrings utility. The initial value for key in the strings file will be key. Use the NSLocalizedStringWithDefaultValue macro to specify another value for key.

    For more information, see NSBundle.

    Special Considerations

    In 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

    Available in iOS 2.0 and later.

  • Returns a localized version of a string.

    Declaration

    Objective-C

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

    Parameters

    key

    The key for a string in the specified table.

    tableName

    The name of the table containing the key-value pairs. Also, the suffix for the strings file (a file with the .strings extension) to store the localized string.

    bundle

    The bundle containing the strings file.

    comment

    The comment to place above the key-value pair in the strings file.

    Return Value

    The result of sending localizedStringForKey:value:table: to bundle, passing the specified key and tableName where the value parameter is nil.

    Discussion

    Use this macro to generate a strings files named [tableName].strings located in bundle from your code using the genstrings utility. You can specify Unicode characters in key using \\Uxxxx—see the -u option for for the genstrings utility. The initial value for key in the strings file will be key. Use the NSLocalizedStringWithDefaultValue macro to specify another value for key.

    For more information, see NSBundle.

    Special Considerations

    In 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

    Available in iOS 2.0 and later.

  • Returns a localized version of a string.

    Declaration

    Objective-C

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

    Parameters

    key

    The key for a string in the specified table.

    tableName

    The name of the table containing the key-value pairs. Also, the suffix for the strings file (a file with the .strings extension) to store the localized string.

    bundle

    The bundle containing the strings file.

    value

    The value to return if key is nil or if a localized string for key can’t be found in the table.

    comment

    The comment to place above the key-value pair in the strings file.

    Return Value

    The result of sending localizedStringForKey:value:table: to bundle, passing the specified key, value, and tableName.

    Discussion

    Use this macro to generate a strings files named [tableName].strings located in bundle from your code using the genstrings utility. The initial value for key in the strings file will be value. 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 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

    Available in iOS 2.0 and later.

You can also use the class NSDecimalNumber for decimal arithmetic.

You can find the following macros implemented in NSException.h. They are obsolete and should not be used. See Exception Programming Topics for information on how to handle exceptions.

  • Marks the start of the exception-handling domain.

    Declaration

    Objective-C

    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

    Available in iOS 2.0 and later.

  • Marks the end of the local event handler.

    Declaration

    Objective-C

    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

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

    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

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

    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

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

    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

    Available in iOS 2.0 and later.

  • Creates and returns a new instance of a given class.

    Declaration

    Objective-C

    id __nonnull NSAllocateObject ( Class __nonnull aClass, NSUInteger extraBytes, NSZone * __nullable 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

    Available in iOS 2.0 and later.

  • NSCopyObject (iOS 6.0)

    Creates an exact copy of an object.

    Declaration

    Objective-C

    id __nonnull NSCopyObject ( id __nonnull object, NSUInteger extraBytes, NSZone * __nullable 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 OS X v10.6.

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 6.0.

  • Destroys an existing object.

    Declaration

    Objective-C

    void NSDeallocateObject ( id __nonnull object );

    Parameters

    object

    An object.

    Discussion

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

    Availability

    Available in iOS 2.0 and later.

    See Also

    NSAllocateObject

  • Decrements the specified object’s reference count.

    Declaration

    Objective-C

    BOOL NSDecrementExtraRefCountWasZero ( id __nonnull object );

    Parameters

    object

    An object.

    Return Value

    NOfalse if anObject had an extra reference count, or YEStrue 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

    Available in iOS 2.0 and later.

  • Returns the specified object’s reference count.

    Declaration

    Objective-C

    NSUInteger NSExtraRefCount ( id __nonnull 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

    Available in iOS 2.0 and later.

  • Increments the specified object’s reference count.

    Declaration

    Objective-C

    void NSIncrementExtraRefCount ( id __nonnull 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

    Available in iOS 2.0 and later.

  • Indicates whether an object should be retained.

    Declaration

    Objective-C

    BOOL NSShouldRetainWithZone ( id __nonnull anObject, NSZone * __nullable requestedZone );

    Parameters

    anObject

    An object.

    requestedZone

    A memory zone.

    Return Value

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

    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

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func NSGetSizeAndAlignment(_ typePtr: UnsafePointer<Int8>, _ sizep: UnsafeMutablePointer<Int>, _ alignp: UnsafeMutablePointer<Int>) -> UnsafePointer<Int8>

    Objective-C

    const char * __nonnull NSGetSizeAndAlignment ( const char * __nonnull typePtr, NSUInteger * __nullable sizep, NSUInteger * __nullable 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

    Available in iOS 2.0 and later.

  • Obtains a class by name.

    Declaration

    Swift

    func NSClassFromString(_ aClassName: String) -> AnyClass?

    Objective-C

    Class __nullable NSClassFromString ( NSString * __nonnull 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

    Available in iOS 2.0 and later.

  • Returns the name of a class as a string.

    Declaration

    Swift

    func NSStringFromClass(_ aClass: AnyClass) -> String

    Objective-C

    NSString * __nonnull NSStringFromClass ( Class __nonnull aClass );

    Parameters

    aClass

    A class.

    Return Value

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

    Availability

    Available in iOS 2.0 and later.

  • Returns the selector with a given name.

    Declaration

    Swift

    func NSSelectorFromString(_ aSelectorName: String) -> Selector

    Objective-C

    SEL __nonnull NSSelectorFromString ( NSString * __nonnull 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:.

    Availability

    Available in iOS 2.0 and later.

  • Returns a string representation of a given selector.

    Declaration

    Swift

    func NSStringFromSelector(_ aSelector: Selector) -> String

    Objective-C

    NSString * __nonnull NSStringFromSelector ( SEL __nonnull aSelector );

    Parameters

    aSelector

    A selector.

    Return Value

    A string representation of aSelector.

    Availability

    Available in iOS 2.0 and later.

  • Returns the name of a protocol as a string.

    Declaration

    Swift

    func NSStringFromProtocol(_ proto: Protocol) -> String

    Objective-C

    NSString * __nonnull NSStringFromProtocol ( Protocol * __nonnull proto );

    Parameters

    proto

    A protocol.

    Return Value

    A string containing the name of proto.

    Availability

    Available in iOS 2.0 and later.

  • Returns a the protocol with a given name.

    Declaration

    Swift

    func NSProtocolFromString(_ namestr: String) -> Protocol?

    Objective-C

    Protocol * __nullable NSProtocolFromString ( NSString * __nonnull 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

    Available in iOS 2.0 and later.

  • Logs an error message to the Apple System Log facility.

    Declaration

    Objective-C

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

    Discussion

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

    Availability

    Available in iOS 2.0 and later.

    See Also

    NSLogv

  • Logs an error message to the Apple System Log facility.

    Declaration

    Swift

    func NSLogv(_ format: String, _ args: CVaListPointer)

    Objective-C

    void NSLogv ( NSString * __nonnull format, va_list __nonnull 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

    Available in iOS 2.0 and later.

    See Also

    NSLog

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

    Declaration

    Swift

    func NSEqualRanges(_ range1: NSRange, _ range2: NSRange) -> Bool

    Objective-C

    BOOL NSEqualRanges ( NSRange range1, NSRange range2 );

    Return Value

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

    Availability

    Available in iOS 2.0 and later.

  • Returns the intersection of the specified ranges.

    Declaration

    Swift

    func NSIntersectionRange(_ range1: NSRange, _ range2: NSRange) -> NSRange

    Objective-C

    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

    Available in iOS 2.0 and later.

    See Also

    NSUnionRange

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

    Declaration

    Swift

    func NSLocationInRange(_ loc: Int, _ range: NSRange) -> Bool

    Objective-C

    BOOL NSLocationInRange ( NSUInteger loc, NSRange range );

    Return Value

    YEStrue 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

    Available in iOS 2.0 and later.

  • Creates a new NSRange from the specified values.

    Declaration

    Swift

    func NSMakeRange(_ loc: Int, _ len: Int) -> NSRange

    Objective-C

    NSRange NSMakeRange ( NSUInteger loc, NSUInteger len );

    Return Value

    An NSRange with location location and length length.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func NSMaxRange(_ range: NSRange) -> Int

    Objective-C

    NSUInteger NSMaxRange ( NSRange range );

    Return Value

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

    Availability

    Available in iOS 2.0 and later.

  • Returns a range from a textual representation.

    Declaration

    Swift

    func NSRangeFromString(_ aString: String) -> NSRange

    Objective-C

    NSRange NSRangeFromString ( NSString * __nonnull 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

    Available in iOS 2.0 and later.

  • Returns a string representation of a range.

    Declaration

    Swift

    func NSStringFromRange(_ range: NSRange) -> String

    Objective-C

    NSString * __nonnull NSStringFromRange ( NSRange range );

    Return Value

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

    Availability

    Available in iOS 2.0 and later.

  • Returns the union of the specified ranges.

    Declaration

    Swift

    func NSUnionRange(_ range1: NSRange, _ range2: NSRange) -> NSRange

    Objective-C

    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

    Available in iOS 2.0 and later.

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.

  • Casts an Objective-C pointer to a Core Foundation pointer and also transfers ownership to the caller.

    Declaration

    Swift

    func CFBridgingRetain(_ X: AnyObject?) -> AnyObject?

    Objective-C

    CFTypeRef __nullable CFBridgingRetain ( id __nullable X );

    Discussion

    You use this function to cast an Objective-C object as Core Foundation-style object and take ownership of the object so that you can manage its lifetime. You are responsible for subsequently releasing the object, as illustrated in this example:

    1. NSString *string = <#Get a string#>;
    2. CFStringRef cfString = (CFStringRef)CFBridgingRetain(string);
    3. // Use the CF string.
    4. CFRelease(cfString);

    Availability

    Available in iOS 5.0 and later.

  • Moves a non-Objective-C pointer to Objective-C and also transfers ownership to ARC.

    Declaration

    Objective-C

    id __nullable CFBridgingRelease ( CFTypeRef __nullable X );

    Discussion

    You use this function to cast a Core Foundation-style object as an Objective-C object and transfer ownership of the object to ARC such that you don’t have to release the object, as illustrated in this example:

    1. CFStringRef cfName = ABRecordCopyValue(person, kABPersonFirstNameProperty);
    2. NSString *name = (NSString *)CFBridgingRelease(cfName);

    Availability

    Available in iOS 5.0 and later.

    See Also

    CFBridgingRetain

Zones are ignored on iOS and 64-bit runtime on OS X. You should not use zones in current development.

  • Creates a new zone.

    Zones are ignored on iOS and 64-bit runtime on OS X. You should not use zones in current development.

    Declaration

    Objective-C

    NSZone * __nonnull 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

    Available in iOS 2.0 and later.

  • Frees memory in a zone.

    Zones are ignored on iOS and 64-bit runtime on OS X. You should not use zones in current development.

    Declaration

    Objective-C

    void NSRecycleZone ( NSZone * __nonnull 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

    Available in iOS 2.0 and later.

  • Sets the name of the specified zone.

    Zones are ignored on iOS and 64-bit runtime on OS X. You should not use zones in current development.

    Declaration

    Objective-C

    void NSSetZoneName ( NSZone * __nullable zone, NSString * __nonnull name );

    Discussion

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

    Availability

    Available in iOS 2.0 and later.

  • Allocates memory in a zone.

    Zones are ignored on iOS and 64-bit runtime on OS X. You should not use zones in current development.

    Declaration

    Objective-C

    void * __nonnull NSZoneCalloc ( NSZone * __nullable 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

    Available in iOS 2.0 and later.

  • Deallocates a block of memory in the specified zone.

    Zones are ignored on iOS and 64-bit runtime on OS X. You should not use zones in current development.

    Declaration

    Objective-C

    void NSZoneFree ( NSZone * __nullable zone, void * __nonnull 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

    Available in iOS 2.0 and later.

  • Gets the zone for a given block of memory.

    Zones are ignored on iOS and 64-bit runtime on OS X. You should not use zones in current development.

    Declaration

    Objective-C

    NSZone * __nullable NSZoneFromPointer ( void * __nonnull 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

    Available in iOS 2.0 and later.

  • Allocates memory in a zone.

    Zones are ignored on iOS and 64-bit runtime on OS X. You should not use zones in current development.

    Declaration

    Objective-C

    void * __nonnull NSZoneMalloc ( NSZone * __nullable 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

    Available in iOS 2.0 and later.

  • Returns the name of the specified zone.

    Zones are ignored on iOS and 64-bit runtime on OS X. You should not use zones in current development.

    Declaration

    Objective-C

    NSString * __nonnull NSZoneName ( NSZone * __nullable 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

    Available in iOS 2.0 and later.

  • Allocates memory in a zone.

    Zones are ignored on iOS and 64-bit runtime on OS X. You should not use zones in current development.

    Declaration

    Objective-C

    void * __nonnull NSZoneRealloc ( NSZone * __nullable zone, void * __nullable 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

    Available in iOS 2.0 and later.

  • Returns the default zone.

    Zones are ignored on iOS and 64-bit runtime on OS X. You should not use zones in current development.

    Declaration

    Objective-C

    NSZone * __nonnull 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

    Available in iOS 2.0 and later.