Mac Developer Library

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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.2 and later.

  • Performs a type conversion.

    Declaration

    Swift

    func NSConvertHostDoubleToSwapped(_ x: Double) -> NSSwappedDouble

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Performs a type conversion.

    Declaration

    Swift

    func NSConvertHostFloatToSwapped(_ x: Float) -> NSSwappedFloat

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Performs a type conversion.

    Declaration

    Swift

    func NSConvertSwappedDoubleToHost(_ x: NSSwappedDouble) -> Double

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Performs a type conversion.

    Declaration

    Swift

    func NSConvertSwappedFloatToHost(_ x: NSSwappedFloat) -> Float

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the endian format.

    Declaration

    Swift

    func NSHostByteOrder() -> Int

    Objective-C

    long NSHostByteOrder ( void );

    Return Value

    The endian format, either NS_LittleEndian or NS_BigEndian.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapBigDoubleToHost(_ x: NSSwappedDouble) -> Double

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapBigFloatToHost(_ x: NSSwappedFloat) -> Float

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapBigIntToHost(_ x: UInt32) -> UInt32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapBigLongLongToHost(_ x: UInt64) -> UInt64

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapBigLongToHost(_ x: UInt) -> UInt

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapBigShortToHost(_ x: UInt16) -> UInt16

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapDouble(_ x: NSSwappedDouble) -> NSSwappedDouble

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapFloat(_ x: NSSwappedFloat) -> NSSwappedFloat

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapHostDoubleToBig(_ x: Double) -> NSSwappedDouble

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapHostDoubleToLittle(_ x: Double) -> NSSwappedDouble

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapHostFloatToBig(_ x: Float) -> NSSwappedFloat

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapHostFloatToLittle(_ x: Float) -> NSSwappedFloat

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapHostIntToBig(_ x: UInt32) -> UInt32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapHostIntToLittle(_ x: UInt32) -> UInt32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapHostLongLongToBig(_ x: UInt64) -> UInt64

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapHostLongLongToLittle(_ x: UInt64) -> UInt64

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapHostLongToBig(_ x: UInt) -> UInt

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapHostLongToLittle(_ x: UInt) -> UInt

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapHostShortToBig(_ x: UInt16) -> UInt16

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapHostShortToLittle(_ x: UInt16) -> UInt16

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapInt(_ inv: UInt32) -> UInt32

    Objective-C

    unsigned int NSSwapInt ( unsigned int inv );

    Discussion

    Swaps the bytes of iv 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapLittleDoubleToHost(_ x: NSSwappedDouble) -> Double

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapLittleFloatToHost(_ x: NSSwappedFloat) -> Float

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapLittleIntToHost(_ x: UInt32) -> UInt32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapLittleLongLongToHost(_ x: UInt64) -> UInt64

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapLittleLongToHost(_ x: UInt) -> UInt

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapLittleShortToHost(_ x: UInt16) -> UInt16

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapLong(_ inv: UInt) -> UInt

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapLongLong(_ inv: UInt64) -> UInt64

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A utility for swapping the bytes of a number.

    Declaration

    Swift

    func NSSwapShort(_ inv: UInt16) -> UInt16

    Objective-C

    unsigned short NSSwapShort ( unsigned short inv );

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

You can also use the class NSDecimalNumber for decimal arithmetic.

  • Adds two decimal values.

    Declaration

    Swift

    func NSDecimalAdd(_ result: COpaquePointer, _ leftOperand: COpaquePointer, _ rightOperand: COpaquePointer, _ roundingMode: NSRoundingMode) -> NSCalculationError

    Objective-C

    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:

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Compacts the decimal structure for efficiency.

    Declaration

    Swift

    func NSDecimalCompact(_ number: COpaquePointer)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Compares two decimal values.

    Declaration

    Swift

    func NSDecimalCompare(_ leftOperand: COpaquePointer, _ rightOperand: COpaquePointer) -> NSComparisonResult

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Copies the value of a decimal number.

    Declaration

    Swift

    func NSDecimalCopy(_ destination: COpaquePointer, _ source: COpaquePointer)

    Objective-C

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

    Discussion

    Copies the value in source to destination.

    For more information, see Number and Value Programming Topics.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Divides one decimal value by another.

    Declaration

    Swift

    func NSDecimalDivide(_ result: COpaquePointer, _ leftOperand: COpaquePointer, _ rightOperand: COpaquePointer, _ roundingMode: NSRoundingMode) -> NSCalculationError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func NSDecimalIsNotANumber(_ dcm: COpaquePointer) -> Bool

    Objective-C

    BOOL NSDecimalIsNotANumber ( const NSDecimal *dcm );

    Return Value

    YEStrue if the value in decimal represents a valid number, otherwise NOfalse.

    For more information, see Number and Value Programming Topics.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Multiplies two decimal numbers together.

    Declaration

    Swift

    func NSDecimalMultiply(_ result: COpaquePointer, _ leftOperand: COpaquePointer, _ rightOperand: COpaquePointer, _ roundingMode: NSRoundingMode) -> NSCalculationError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Multiplies a decimal by the specified power of 10.

    Declaration

    Swift

    func NSDecimalMultiplyByPowerOf10(_ result: COpaquePointer, _ number: COpaquePointer, _ power: Int16, _ roundingMode: NSRoundingMode) -> NSCalculationError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func NSDecimalNormalize(_ number1: COpaquePointer, _ number2: COpaquePointer, _ roundingMode: NSRoundingMode) -> NSCalculationError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Raises the decimal value to the specified power.

    Declaration

    Swift

    func NSDecimalPower(_ result: COpaquePointer, _ number: COpaquePointer, _ power: Int, _ roundingMode: NSRoundingMode) -> NSCalculationError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Rounds off the decimal value.

    Declaration

    Swift

    func NSDecimalRound(_ result: COpaquePointer, _ number: COpaquePointer, _ scale: Int, _ roundingMode: NSRoundingMode)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a string representation of the decimal value.

    Declaration

    Swift

    func NSDecimalString(_ dcm: COpaquePointer, _ locale: AnyObject!) -> String!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Subtracts one decimal value from another.

    Declaration

    Swift

    func NSDecimalSubtract(_ result: COpaquePointer, _ leftOperand: COpaquePointer, _ rightOperand: COpaquePointer, _ roundingMode: NSRoundingMode) -> NSCalculationError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.

  • NSJavaBundleCleanup NSJavaBundleCleanup Available in OS X v10.2 through OS X v10.5

    This function has been deprecated.

    Declaration

    Objective-C

    void NSJavaBundleCleanup ( NSBundle *bundle, NSDictionary *plist );

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.2 through OS X v10.5.

    Deprecated in OS X v10.5.

  • NSJavaBundleSetup NSJavaBundleSetup Available in OS X v10.2 through OS X v10.5

    This function has been deprecated.

    Declaration

    Objective-C

    id NSJavaBundleSetup ( NSBundle *bundle, NSDictionary *plist );

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.2 through OS X v10.5.

    Deprecated in OS X v10.5.

  • NSJavaClassesForBundle NSJavaClassesForBundle Available in OS X v10.2 through OS X v10.5

    Loads the Java classes located in the specified bundle.

    Declaration

    Objective-C

    NSArray * NSJavaClassesForBundle ( NSBundle *bundle, BOOL usesyscl, id *vm );

    Discussion

    Loads and returns the Java classes in the specified bundle. If the Java virtual machine is not loaded, load it first. A reference to the Java virtual machine is returned in the vm parameter. You can pass nil for the vm parameter if you do not want this information. Pass NOfalse for usesyscl if you want to use a new instance of the class loader to load the classes; otherwise, the system can reuse an existing instance of the class loader. If you pass NOfalse for usesyscl, the new class loader will be released when you are done with it; otherwise, the class loader will be cached for use next time.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.2 through OS X v10.5.

    Deprecated in OS X v10.5.

  • NSJavaClassesFromPath NSJavaClassesFromPath Available in OS X v10.2 through OS X v10.5

    Loads the Java classes located at the specified path.

    Declaration

    Objective-C

    NSArray * NSJavaClassesFromPath ( NSArray *path, NSArray *wanted, BOOL usesyscl, id *vm );

    Discussion

    Loads and returns the Java classes in the specified bundle. If the Java virtual machine is not loaded, load it first. A reference to the Java virtual machine is returned in the vm parameter. You can pass nil for the vm parameter if you do not want this information. Pass an array of names of classes to load in the wanted parameter. If you pass nil for the wanted parameter, all classes at the specified path will be loaded. Pass NOfalse for usesyscl if you want to use a new instance of the class loader to load the classes; otherwise, the system can reuse an existing instance of the class loader. If you pass NOfalse for usesyscl, the new class loader will be released when you are done with it; otherwise, the class loader will be cached for use next time.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.2 through OS X v10.5.

    Deprecated in OS X v10.5.

  • NSJavaNeedsToLoadClasses NSJavaNeedsToLoadClasses Available in OS X v10.0 through OS X v10.5

    Returns a Boolean value that indicates whether a virtual machine is needed or if Java classes are provided.

    Declaration

    Objective-C

    BOOL NSJavaNeedsToLoadClasses ( NSDictionary *plist );

    Discussion

    Returns YEStrue if a virtual machine is needed or if a virtual machine already exists and there’s an indication that Java classes are provided.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 through OS X v10.5.

    Deprecated in OS X v10.5.

  • NSJavaNeedsVirtualMachine NSJavaNeedsVirtualMachine Available in OS X v10.0 through OS X v10.5

    Returns a Boolean value that indicates whether a Java virtual machine is required.

    Declaration

    Objective-C

    BOOL NSJavaNeedsVirtualMachine ( NSDictionary *plist );

    Discussion

    Returns YEStrue if plist contains a key saying that it requires Java.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 through OS X v10.5.

    Deprecated in OS X v10.5.

  • NSJavaObjectNamedInPath NSJavaObjectNamedInPath Available in OS X v10.2 through OS X v10.5

    Creates an instance of the named class using the class loader previously specified at the given path.

    Declaration

    Objective-C

    id NSJavaObjectNamedInPath ( NSString *name, NSArray *path );

    Discussion

    Returns a new instance of the class name. The class loader must be already be set up for the specified path (you can do this using a function such as NSJavaClassesFromPath).

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.2 through OS X v10.5.

    Deprecated in OS X v10.5.

  • NSJavaProvidesClasses NSJavaProvidesClasses Available in OS X v10.0 through OS X v10.5

    Returns a Boolean value that indicates whether Java classes are provided.

    Declaration

    Objective-C

    BOOL NSJavaProvidesClasses ( NSDictionary *plist );

    Discussion

    Returns YEStrue if plist contains an NSJavaPath key.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 through OS X v10.5.

    Deprecated in OS X v10.5.

  • NSJavaSetup NSJavaSetup Available in OS X v10.2 through OS X v10.5

    Loads the Java virtual machine with specified parameters.

    Declaration

    Objective-C

    id NSJavaSetup ( NSDictionary *plist );

    Discussion

    Part of the Java-to-Objective-C bridge. You normally shouldn’t use it yourself.

    You can pass nil for the plist dictionary, in which case the Java virtual machine will not be loaded, so you should probably just use NSJavaSetupVirtualMachine instead. The plist dictionary may contain the following key-value pairs.

    • NSJavaRoot—An NSString indicating the root of the location where the application’s classes are.

    • NSJavaPath—An NSArray of NSStrings, each string containing one component of a class path whose components will be prepended by NSJavaRoot if they are not absolute locations.

    • NSJavaUserPath—An NSString indicating another segment of the class path so that the application developer can customize where the class loader should search for classes. When searching for classes, this path is searched after the application’s class path so that one cannot replace the classes used by the application.

    • NSJavaLibraryPath—An NSArray of NSStrings, each string containing one component of a path to search for dynamic shared libraries needed by Java wrappers.

    • NSJavaClasses—An NSArray of NSStrings, each string containing the name of one class that the VM should load so that their associated frameworks will be loaded.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.2 through OS X v10.5.

    Deprecated in OS X v10.5.

  • NSJavaSetupVirtualMachine NSJavaSetupVirtualMachine Available in OS X v10.2 through OS X v10.5

    Sets up the Java virtual machine.

    Declaration

    Objective-C

    id NSJavaSetupVirtualMachine ( void );

    Discussion

    Sets up and returns a reference to the Java virtual machine.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.2 through OS X v10.5.

    Deprecated in OS X v10.5.

  • Returns all of the elements in the specified hash table.

    Declaration

    Swift

    func NSAllHashTableObjects(_ table: NSHashTable!) -> [AnyObject]!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether the elements of two hash tables are equal.

    Declaration

    Swift

    func NSCompareHashTables(_ table1: NSHashTable!, _ table2: NSHashTable!) -> Bool

    Objective-C

    BOOL NSCompareHashTables ( NSHashTable *table1, NSHashTable *table2 );

    Return Value

    YEStrue if the two hash tables are equal—that is, if each element of table1 is in table2 and the two tables are the same size, otherwise NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Performs a shallow copy of the specified hash table.

    Declaration

    Swift

    func NSCopyHashTableWithZone(_ table: NSHashTable!, _ zone: NSZone) -> NSHashTable!

    Objective-C

    NSHashTable * NSCopyHashTableWithZone ( NSHashTable *table, NSZone *zone );

    Return Value

    A pointer to a new copy of table, created in zone and containing pointers to the data elements of table.

    Discussion

    If zone is NULL, the new table is created in the default zone.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the number of elements in a hash table.

    Declaration

    Swift

    func NSCountHashTable(_ table: NSHashTable!) -> Int

    Objective-C

    NSUInteger NSCountHashTable ( NSHashTable *table );

    Return Value

    The number of elements currently in table.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Creates and returns a new hash table.

    Declaration

    Swift

    func NSCreateHashTable(_ callBacks: NSHashTableCallBacks, _ capacity: Int) -> NSHashTable!

    Objective-C

    NSHashTable * NSCreateHashTable ( NSHashTableCallBacks callBacks, NSUInteger capacity );

    Return Value

    A pointer to an NSHashTable created in the default zone.

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Creates a new hash table in a given zone.

    Declaration

    Swift

    func NSCreateHashTableWithZone(_ callBacks: NSHashTableCallBacks, _ capacity: Int, _ zone: NSZone) -> NSHashTable!

    Objective-C

    NSHashTable * NSCreateHashTableWithZone ( NSHashTableCallBacks callBacks, NSUInteger capacity, NSZone *zone );

    Return Value

    A pointer to a new hash table created in the specified zone. If zone is NULL, the hash table is created in the default zone.

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Used when finished with an enumerator.

    Declaration

    Swift

    func NSEndHashTableEnumeration(_ enumerator: UnsafeMutablePointer<NSHashEnumerator>)

    Objective-C

    void NSEndHashTableEnumeration ( NSHashEnumerator *enumerator );

    Discussion

    This function should be called when you have finished using the enumeration struct enumerator.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Creates an enumerator for the specified hash table.

    Declaration

    Swift

    func NSEnumerateHashTable(_ table: NSHashTable!) -> NSHashEnumerator

    Objective-C

    NSHashEnumerator NSEnumerateHashTable ( NSHashTable *table );

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Deletes the specified hash table.

    Declaration

    Swift

    func NSFreeHashTable(_ table: NSHashTable!)

    Objective-C

    void NSFreeHashTable ( NSHashTable *table );

    Discussion

    Releases each element of the specified hash table and frees the table itself.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSResetHashTable

  • Returns an element of the hash table.

    Declaration

    Swift

    func NSHashGet(_ table: NSHashTable!, _ pointer: UnsafePointer<Void>) -> UnsafeMutablePointer<Void>

    Objective-C

    void * NSHashGet ( NSHashTable *table, const void *pointer );

    Return Value

    The pointer in the table that matches pointer (as defined by the isEqual callback function). If there is no matching element, returns NULL.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Adds an element to the specified hash table.

    Declaration

    Swift

    func NSHashInsert(_ table: NSHashTable!, _ pointer: UnsafePointer<Void>)

    Objective-C

    void NSHashInsert ( NSHashTable *table, const void *pointer );

    Discussion

    Inserts pointer, which must not be NULL, into table. If pointer matches an item already in the table, the previous pointer is released using the release callback function that was specified when the table was created.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Adds an element to the specified hash table only if the table does not already contain the element.

    Declaration

    Swift

    func NSHashInsertIfAbsent(_ table: NSHashTable!, _ pointer: UnsafePointer<Void>) -> UnsafeMutablePointer<Void>

    Objective-C

    void * NSHashInsertIfAbsent ( NSHashTable *table, const void *pointer );

    Return Value

    If pointer matches an item already in table, returns the preexisting pointer; otherwise, pointer is added to the table and returns NULL.

    Discussion

    You must not specify NULL for pointer.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Adds an element to the specified hash table.

    Declaration

    Swift

    func NSHashInsertKnownAbsent(_ table: NSHashTable!, _ pointer: UnsafePointer<Void>)

    Objective-C

    void NSHashInsertKnownAbsent ( NSHashTable *table, const void *pointer );

    Discussion

    Inserts pointer, which must not be NULL, into table. Unlike NSHashInsert, this function raises NSInvalidArgumentException if table already includes an element that matches pointer.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Removes an element from the specified hash table.

    Declaration

    Swift

    func NSHashRemove(_ table: NSHashTable!, _ pointer: UnsafePointer<Void>)

    Objective-C

    void NSHashRemove ( NSHashTable *table, const void *pointer );

    Discussion

    If pointer matches an item already in table, this function releases the preexisting item.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the next hash-table element in the enumeration.

    Declaration

    Swift

    func NSNextHashEnumeratorItem(_ enumerator: UnsafeMutablePointer<NSHashEnumerator>) -> UnsafeMutablePointer<Void>

    Objective-C

    void * NSNextHashEnumeratorItem ( NSHashEnumerator *enumerator );

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Deletes the elements of the specified hash table.

    Declaration

    Swift

    func NSResetHashTable(_ table: NSHashTable!)

    Objective-C

    void NSResetHashTable ( NSHashTable *table );

    Discussion

    Releases each element but doesn’t deallocate table. This function is useful for preserving the capacity of table.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSFreeHashTable

  • Returns a string describing the hash table’s contents.

    Declaration

    Swift

    func NSStringFromHashTable(_ table: NSHashTable!) -> String!

    Objective-C

    NSString * NSStringFromHashTable ( NSHashTable *table );

    Return Value

    A string describing table’s contents.

    Discussion

    The function iterates over the elements of table, and for each one appends the string returned by the describe callback function. If NULL was specified for the callback function, the hexadecimal value of each pointer is added to the string.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a string encoding a file type code.

    Declaration

    Swift

    func NSFileTypeForHFSTypeCode(_ hfsFileTypeCode: OSType) -> String!

    Objective-C

    NSString * NSFileTypeForHFSTypeCode ( OSType hfsFileTypeCode );

    Parameters

    hfsFileTypeCode

    An HFS file type code.

    Return Value

    A string that encodes hfsFileTypeCode.

    Discussion

    For more information, see HFS File Types.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a file type code.

    Declaration

    Swift

    func NSHFSTypeCodeFromFileType(_ fileTypeString: String!) -> OSType

    Objective-C

    OSType NSHFSTypeCodeFromFileType ( NSString *fileTypeString );

    Parameters

    fileTypeString

    A string of the sort encoded by NSFileTypeForHFSTypeCode().

    Return Value

    The HFS file type code corresponding to fileTypeString, or 0 if it cannot be found.

    Discussion

    For more information, see HFS File Types.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a string encoding a file type.

    Declaration

    Swift

    func NSHFSTypeOfFile(_ fullFilePath: String!) -> String!

    Objective-C

    NSString * NSHFSTypeOfFile ( NSString *fullFilePath );

    Parameters

    fullFilePath

    The full absolute path of a file.

    Return Value

    A string that encodes fullFilePath‘s HFS file type, or nil if the operation was not successful

    Discussion

    For more information, see HFS File Types.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns all of the keys in the specified map table.

    Declaration

    Swift

    func NSAllMapTableKeys(_ table: NSMapTable!) -> [AnyObject]!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns all of the values in the specified table.

    Declaration

    Swift

    func NSAllMapTableValues(_ table: NSMapTable!) -> [AnyObject]!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Compares the elements of two map tables for equality.

    Declaration

    Swift

    func NSCompareMapTables(_ table1: NSMapTable!, _ table2: NSMapTable!) -> Bool

    Objective-C

    BOOL NSCompareMapTables ( NSMapTable *table1, NSMapTable *table2 );

    Return Value

    YEStrue if the keys and corresponding values of table1 and table2 are the same, and the two tables are the same size, otherwise NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Performs a shallow copy of the specified map table.

    Declaration

    Swift

    func NSCopyMapTableWithZone(_ table: NSMapTable!, _ zone: NSZone) -> NSMapTable!

    Objective-C

    NSMapTable * NSCopyMapTableWithZone ( NSMapTable *table, NSZone *zone );

    Return Value

    A pointer to a new copy of table, created in zone and containing pointers to the keys and values of table.

    Discussion

    If zone is NULL, the new table is created in the default zone.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the number of elements in a map table.

    Declaration

    Swift

    func NSCountMapTable(_ table: NSMapTable!) -> Int

    Objective-C

    NSUInteger NSCountMapTable ( NSMapTable *table );

    Parameters

    table

    A reference to a map table structure.

    Return Value

    The number of key-value pairs currently in table.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Creates a new map table in the default zone.

    Declaration

    Swift

    func NSCreateMapTable(_ keyCallBacks: NSMapTableKeyCallBacks, _ valueCallBacks: NSMapTableValueCallBacks, _ capacity: Int) -> NSMapTable!

    Objective-C

    NSMapTable * NSCreateMapTable ( NSMapTableKeyCallBacks keyCallBacks, NSMapTableValueCallBacks valueCallBacks, NSUInteger capacity );

    Discussion

    Creates and returns a pointer to an NSMapTable structure in the default zone; the table’s size is dependent on (but generally not equal to) capacity. If capacity is 0, a small map table is created. The NSMapTableKeyCallBacks arguments are structures that are very similar to the callback structure used by NSCreateHashTable—they have the same defaults as documented for that function.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Creates a new map table in the specified zone.

    Declaration

    Swift

    func NSCreateMapTableWithZone(_ keyCallBacks: NSMapTableKeyCallBacks, _ valueCallBacks: NSMapTableValueCallBacks, _ capacity: Int, _ zone: NSZone) -> NSMapTable!

    Objective-C

    NSMapTable * NSCreateMapTableWithZone ( NSMapTableKeyCallBacks keyCallBacks, NSMapTableValueCallBacks valueCallBacks, NSUInteger capacity, NSZone *zone );

    Return Value

    A new map table in allocated in zone. If zone is NULL, the hash table is created in the default zone.

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Used when finished with an enumerator.

    Declaration

    Swift

    func NSEndMapTableEnumeration(_ enumerator: UnsafeMutablePointer<NSMapEnumerator>)

    Objective-C

    void NSEndMapTableEnumeration ( NSMapEnumerator *enumerator );

    Discussion

    This function should be called when you have finished using the enumeration struct enumerator.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Creates an enumerator for the specified map table.

    Declaration

    Swift

    func NSEnumerateMapTable(_ table: NSMapTable!) -> NSMapEnumerator

    Objective-C

    NSMapEnumerator NSEnumerateMapTable ( NSMapTable *table );

    Parameters

    table

    A reference to a map table structure.

    Return Value

    An NSMapEnumerator structure that will cause successive key-value pairs of table to be visited each time this enumerator is passed to NSNextMapEnumeratorPair.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Deletes the specified map table.

    Declaration

    Swift

    func NSFreeMapTable(_ table: NSMapTable!)

    Objective-C

    void NSFreeMapTable ( NSMapTable *table );

    Parameters

    table

    A reference to a map table structure.

    Discussion

    Releases each key and value of the specified map table and frees the table itself.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSResetMapTable

  • Returns a map table value for the specified key.

    Declaration

    Swift

    func NSMapGet(_ table: NSMapTable!, _ key: UnsafePointer<Void>) -> UnsafeMutablePointer<Void>

    Objective-C

    void * NSMapGet ( NSMapTable *table, const void *key );

    Return Value

    The value that table maps to key, or NULL if table doesn’t contain key.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Inserts a key-value pair into the specified table.

    Declaration

    Swift

    func NSMapInsert(_ table: NSMapTable!, _ key: UnsafePointer<Void>, _ value: UnsafePointer<Void>)

    Objective-C

    void NSMapInsert ( NSMapTable *table, const void *key, const void *value );

    Discussion

    Inserts key and value into table. If key matches a key already in table, value is retained and the previous value is released, using the retain and release callback functions that were specified when the table was created. Raises NSInvalidArgumentException if key is equal to the notAKeyMarker field of the table’s NSMapTableKeyCallBacks structure.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Inserts a key-value pair into the specified table.

    Declaration

    Swift

    func NSMapInsertIfAbsent(_ table: NSMapTable!, _ key: UnsafePointer<Void>, _ value: UnsafePointer<Void>) -> UnsafeMutablePointer<Void>

    Objective-C

    void * NSMapInsertIfAbsent ( NSMapTable *table, const void *key, const void *value );

    Return Value

    If key matches a key already in table, the preexisting value; otherwise, key and value are added to table and returns NULL.

    Discussion

    Raises NSInvalidArgumentException if key is equal to the notAKeyMarker field of the table’s NSMapTableKeyCallBacks structure.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Inserts a key-value pair into the specified table if the pair had not been previously added.

    Declaration

    Swift

    func NSMapInsertKnownAbsent(_ table: NSMapTable!, _ key: UnsafePointer<Void>, _ value: UnsafePointer<Void>)

    Objective-C

    void NSMapInsertKnownAbsent ( NSMapTable *table, const void *key, const void *value );

    Discussion

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

    key is compared with notAKeyMarker using pointer comparison; if key is identical to notAKeyMarker, raises NSInvalidArgumentException.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Indicates whether a given table contains a given key.

    Declaration

    Swift

    func NSMapMember(_ table: NSMapTable!, _ key: UnsafePointer<Void>, _ originalKey: UnsafeMutablePointer<UnsafeMutablePointer<Void>>, _ value: UnsafeMutablePointer<UnsafeMutablePointer<Void>>) -> Bool

    Objective-C

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

    Return Value

    YEStrue if table contains a key equal to key, otherwise NOfalse.

    Discussion

    If table contains a key equal to key, originalKey is set to key, and value is set to the value that table maps to key.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Removes a key and corresponding value from the specified table.

    Declaration

    Swift

    func NSMapRemove(_ table: NSMapTable!, _ key: UnsafePointer<Void>)

    Objective-C

    void NSMapRemove ( NSMapTable *table, const void *key );

    Discussion

    If key matches a key already in table, this function releases the preexisting key and its corresponding value.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether the next map-table pair in the enumeration are set.

    Declaration

    Swift

    func NSNextMapEnumeratorPair(_ enumerator: UnsafeMutablePointer<NSMapEnumerator>, _ key: UnsafeMutablePointer<UnsafeMutablePointer<Void>>, _ value: UnsafeMutablePointer<UnsafeMutablePointer<Void>>) -> Bool

    Objective-C

    BOOL NSNextMapEnumeratorPair ( NSMapEnumerator *enumerator, void **key, void **value );

    Return Value

    NOfalse if enumerator has already iterated over all the elements in the table that enumerator is associated with; otherwise, sets key and value to match the next key-value pair in the table and returns YEStrue.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Deletes the elements of the specified map table.

    Declaration

    Swift

    func NSResetMapTable(_ table: NSMapTable!)

    Objective-C

    void NSResetMapTable ( NSMapTable *table );

    Parameters

    table

    A reference to a map table structure.

    Discussion

    Releases each key and value but doesn’t deallocate table. This method is useful for preserving the capacity of table.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSFreeMapTable

  • Returns a string describing the map table’s contents.

    Declaration

    Swift

    func NSStringFromMapTable(_ table: NSMapTable!) -> String!

    Objective-C

    NSString * NSStringFromMapTable ( NSMapTable *table );

    Parameters

    table

    A reference to a map table structure.

    Return Value

    A string describing the map table’s contents.

    Discussion

    The function iterates over the key-value pairs of table and for each one appends the string “a = b;\n”, where a and b are the key and value strings returned by the corresponding describe callback functions. If NULL was specified for the callback function, a and b are the key and value pointers, expressed as hexadecimal numbers.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.

  • NSCopyObject NSCopyObject (OS X v10.8)

    Creates an exact copy of an object.

    Declaration

    Objective-C

    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 OS X v10.6.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Destroys an existing object.

    Declaration

    Objective-C

    void NSDeallocateObject ( id object );

    Parameters

    object

    An object.

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSAllocateObject

  • Decrements the specified object’s reference count.

    Declaration

    Objective-C

    BOOL NSDecrementExtraRefCountWasZero ( id 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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.

  • Returns the specified object’s reference count.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.

  • Increments the specified object’s reference count.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.

  • Indicates whether an object should be retained.

    Declaration

    Objective-C

    BOOL NSShouldRetainWithZone ( id anObject, NSZone *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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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 * 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Obtains a class by name.

    Declaration

    Swift

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

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the name of a class as a string.

    Declaration

    Swift

    func NSStringFromClass(_ aClass: AnyClass!) -> String!

    Objective-C

    NSString * NSStringFromClass ( Class aClass );

    Parameters

    aClass

    A class.

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the selector with a given name.

    Declaration

    Swift

    func NSSelectorFromString(_ aSelectorName: String!) -> Selector

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a string representation of a given selector.

    Declaration

    Swift

    func NSStringFromSelector(_ aSelector: Selector) -> String!

    Objective-C

    NSString * NSStringFromSelector ( SEL aSelector );

    Parameters

    aSelector

    A selector.

    Return Value

    A string representation of aSelector.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the name of a protocol as a string.

    Declaration

    Swift

    func NSStringFromProtocol(_ proto: Protocol!) -> String!

    Objective-C

    NSString * NSStringFromProtocol ( Protocol *proto );

    Parameters

    proto

    A protocol.

    Return Value

    A string containing the name of proto.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Returns a the protocol with a given name.

    Declaration

    Swift

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

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Objective-C

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

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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 *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).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSLog

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

    Declaration

    Swift

    func NSFullUserName() -> String!

    Objective-C

    NSString * NSFullUserName ( void );

    Return Value

    A string containing the full name of the current user.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSUserName

  • Returns the path to either the user’s or application’s home directory, depending on the platform.

    Declaration

    Swift

    func NSHomeDirectory() -> String!

    Objective-C

    NSString * NSHomeDirectory ( void );

    Return Value

    The path to the current home directory..

    Discussion

    In iOS, the home directory is the application’s sandbox directory. In OS X, it is the application’s sandbox directory or the current user’s home directory (if the application is not in a sandbox)

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func NSHomeDirectoryForUser(_ userName: String!) -> String!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the root directory of the user’s system.

    Declaration

    Swift

    func NSOpenStepRootDirectory() -> String!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Creates a list of directory search paths.

    Declaration

    Swift

    func NSSearchPathForDirectoriesInDomains(_ directory: NSSearchPathDirectory, _ domainMask: NSSearchPathDomainMask, _ expandTilde: Bool) -> [AnyObject]!

    Objective-C

    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 YEStrue, tildes are expanded as described in stringByExpandingTildeInPath.

    You should consider using the NSFileManager methods URLsForDirectory:inDomains: and URLForDirectory:inDomain:appropriateForURL:create:error:. which return URLs, which are the preferred format.

    For more information on file system utilities, see File System Programming Guide.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func NSTemporaryDirectory() -> String!

    Objective-C

    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

    See the NSFileManager method URLForDirectory:inDomain:appropriateForURL:create:error: for the preferred means of finding the correct temporary directory.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the logon name of the current user.

    Declaration

    Swift

    func NSUserName() -> String!

    Objective-C

    NSString * NSUserName ( void );

    Return Value

    The logon name of the current user.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func NSEqualPoints(_ aPoint: NSPoint, _ bPoint: NSPoint) -> Bool

    Objective-C

    BOOL NSEqualPoints ( NSPoint aPoint, NSPoint bPoint );

    Return Value

    YEStrue if the two points aPoint and bPoint are identical, otherwise NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Creates a new NSPoint from the specified values.

    Declaration

    Swift

    func NSMakePoint(_ x: CGFloat, _ y: CGFloat) -> NSPoint

    Objective-C

    NSPoint NSMakePoint ( CGFloat x, CGFloat y );

    Return Value

    An NSPoint having the coordinates x and y.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a point from a text-based representation.

    Declaration

    Swift

    func NSPointFromString(_ aString: String!) -> NSPoint

    Objective-C

    NSPoint NSPointFromString ( NSString *aString );

    Parameters

    aString

    A string of the form “{x, y}”.

    Return Value

    If aString is of the form “{x, y}” an NSPoint structure that uses x and y as the x and y coordinates, in that order.

    If aString only contains a single number, it is used as the x coordinate. If aString does not contain any numbers, returns an NSPoint object whose x and y coordinates are both 0.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a string representation of a point.

    Declaration

    Swift

    func NSStringFromPoint(_ aPoint: NSPoint) -> String!

    Objective-C

    NSString * NSStringFromPoint ( NSPoint aPoint );

    Parameters

    aPoint

    A point structure.

    Return Value

    A string of the form “{a, b}”, where a and b are the x and y coordinates of aPoint.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns an NSPoint typecast from a CGPoint.

    Declaration

    Swift

    func NSPointFromCGPoint(_ cgpoint: CGPoint) -> NSPoint

    Objective-C

    NSPoint NSPointFromCGPoint ( CGPoint cgpoint );

    Return Value

    An NSPoint typecast from a CGPoint.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Returns a CGPoint typecast from an NSPoint.

    Declaration

    Swift

    func NSPointToCGPoint(_ nspoint: NSPoint) -> CGPoint

    Objective-C

    CGPoint NSPointToCGPoint ( NSPoint nspoint );

    Return Value

    A CGPoint typecast from an NSPoint.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a range from a textual representation.

    Declaration

    Swift

    func NSRangeFromString(_ aString: String!) -> NSRange

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a string representation of a range.

    Declaration

    Swift

    func NSStringFromRange(_ range: NSRange) -> String!

    Objective-C

    NSString * NSStringFromRange ( NSRange range );

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether one rectangle completely encloses another.

    Declaration

    Swift

    func NSContainsRect(_ aRect: NSRect, _ bRect: NSRect) -> Bool

    Objective-C

    BOOL NSContainsRect ( NSRect aRect, NSRect bRect );

    Return Value

    YEStrue if aRect completely encloses bRect. For this condition to be true, bRect cannot be empty, and must not extend beyond aRect in any direction.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Divides a rectangle into two new rectangles.

    Declaration

    Swift

    func NSDivideRect(_ inRect: NSRect, _ slice: UnsafeMutablePointer<NSRect>, _ rem: UnsafeMutablePointer<NSRect>, _ amount: CGFloat, _ edge: NSRectEdge)

    Objective-C

    void NSDivideRect ( NSRect inRect, NSRect *slice, NSRect *rem, CGFloat amount, NSRectEdge edge );

    Discussion

    Creates two rectangles—slice and rem—from inRect, by dividing inRect with a line that’s parallel to the side of inRect specified by edge. The size of slice is determined by amount, which specifies the distance from edge.

    slice and rem must not be NULL.

    For more information, see NSRectEdge.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether the two rectangles are equal.

    Declaration

    Swift

    func NSEqualRects(_ aRect: NSRect, _ bRect: NSRect) -> Bool

    Objective-C

    BOOL NSEqualRects ( NSRect aRect, NSRect bRect );

    Return Value

    YEStrue if aRect and bRect are identical, otherwise NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether a given rectangle is empty.

    Declaration

    Swift

    func NSIsEmptyRect(_ aRect: NSRect) -> Bool

    Objective-C

    BOOL NSIsEmptyRect ( NSRect aRect );

    Return Value

    YEStrue if aRect encloses no area at all—that is, if its width or height is 0 or negative, otherwise NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the height of a given rectangle.

    Declaration

    Swift

    func NSHeight(_ aRect: NSRect) -> CGFloat

    Objective-C

    CGFloat NSHeight ( NSRect aRect );

    Return Value

    The height of aRect.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Insets a rectangle by a specified amount.

    Declaration

    Swift

    func NSInsetRect(_ aRect: NSRect, _ dX: CGFloat, _ dY: CGFloat) -> NSRect

    Objective-C

    NSRect NSInsetRect ( NSRect aRect, CGFloat dX, CGFloat dY );

    Return Value

    A copy of aRect, altered by moving the two sides that are parallel to the y axis inward by dX, and the two sides parallel to the x axis inwards by dY.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Adjusts the sides of a rectangle to integer values.

    Declaration

    Swift

    func NSIntegralRect(_ aRect: NSRect) -> NSRect

    Objective-C

    NSRect NSIntegralRect ( NSRect aRect );

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Adjusts the sides of a rectangle to integral values using the specified options.

    Declaration

    Swift

    func NSIntegralRectWithOptions(_ aRect: NSRect, _ opts: NSAlignmentOptions) -> NSRect

    Objective-C

    NSRect NSIntegralRectWithOptions ( NSRect aRect, NSAlignmentOptions opts );

    Return Value

    A copy of aRect, modified based on the options. The options are defined in NSAlignmentOptions.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.7 and later.

    See Also

    NSIntegralRect

  • Calculates the intersection of two rectangles.

    Declaration

    Swift

    func NSIntersectionRect(_ aRect: NSRect, _ bRect: NSRect) -> NSRect

    Objective-C

    NSRect NSIntersectionRect ( NSRect aRect, NSRect bRect );

    Return Value

    The graphic intersection of aRect and bRect. If the two rectangles don’t overlap, the returned rectangle has its origin at (0.0, 0.0) and zero width and height (including situations where the intersection is a point or a line segment).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSUnionRect

  • Returns a Boolean value that indicates whether two rectangles intersect.

    Declaration

    Swift

    func NSIntersectsRect(_ aRect: NSRect, _ bRect: NSRect) -> Bool

    Objective-C

    BOOL NSIntersectsRect ( NSRect aRect, NSRect bRect );

    Return Value

    YEStrue if aRect intersects bRect, otherwise NOfalse. Returns NOfalse if either aRect or bRect has a width or height that is 0.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Creates a new NSRect from the specified values.

    Declaration

    Swift

    func NSMakeRect(_ x: CGFloat, _ y: CGFloat, _ w: CGFloat, _ h: CGFloat) -> NSRect

    Objective-C

    NSRect NSMakeRect ( CGFloat x, CGFloat y, CGFloat w, CGFloat h );

    Return Value

    An NSRect having the specified origin of [x, y] and size of [w, h].

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the largest x coordinate of a given rectangle.

    Declaration

    Swift

    func NSMaxX(_ aRect: NSRect) -> CGFloat

    Objective-C

    CGFloat NSMaxX ( NSRect aRect );

    Return Value

    The largest x coordinate value within aRect.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the largest y coordinate of a given rectangle.

    Declaration

    Swift

    func NSMaxY(_ aRect: NSRect) -> CGFloat

    Objective-C

    CGFloat NSMaxY ( NSRect aRect );

    Return Value

    The largest y coordinate value within aRect.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the x coordinate of a given rectangle’s midpoint.

    Declaration

    Swift

    func NSMidX(_ aRect: NSRect) -> CGFloat

    Objective-C

    CGFloat NSMidX ( NSRect aRect );

    Return Value

    Returns the x coordinate of the center of aRect.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the y coordinate of a given rectangle’s midpoint.

    Declaration

    Swift

    func NSMidY(_ aRect: NSRect) -> CGFloat

    Objective-C

    CGFloat NSMidY ( NSRect aRect );

    Return Value

    The y coordinate of aRect’s center point.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the smallest x coordinate of a given rectangle.

    Declaration

    Swift

    func NSMinX(_ aRect: NSRect) -> CGFloat

    Objective-C

    CGFloat NSMinX ( NSRect aRect );

    Return Value

    The smallest x coordinate value within aRect.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the smallest y coordinate of a given rectangle.

    Declaration

    Swift

    func NSMinY(_ aRect: NSRect) -> CGFloat

    Objective-C

    CGFloat NSMinY ( NSRect aRect );

    Return Value

    The smallest y coordinate value within aRect.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether the point is in the specified rectangle.

    Declaration

    Swift

    func NSMouseInRect(_ aPoint: NSPoint, _ aRect: NSRect, _ flipped: Bool) -> Bool

    Objective-C

    BOOL NSMouseInRect ( NSPoint aPoint, NSRect aRect, BOOL flipped );

    Return Value

    YEStrue if the hot spot of the cursor lies inside a given rectangle, otherwise NOfalse.

    Discussion

    This method assumes an unscaled and unrotated coordinate system. Specify YEStrue for flipped if the underlying view uses a flipped coordinate system.

    Point-in-rectangle functions generally assume that the bottom edge of a rectangle is outside of the rectangle boundaries, while the upper edge is inside the boundaries. This method views aRect from the point of view of the user—that is, this method always treats the bottom edge of the rectangle as the one closest to the bottom edge of the user’s screen. By making this adjustment, this function ensures consistent mouse-detection behavior from the user’s perspective.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSPointInRect

  • Offsets the rectangle by the specified amount.

    Declaration

    Swift

    func NSOffsetRect(_ aRect: NSRect, _ dX: CGFloat, _ dY: CGFloat) -> NSRect

    Objective-C

    NSRect NSOffsetRect ( NSRect aRect, CGFloat dX, CGFloat dY );

    Return Value

    A copy of aRect, with its location shifted by dX along the x axis and by dY along the y axis.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether a given point is in a given rectangle.

    Declaration

    Swift

    func NSPointInRect(_ aPoint: NSPoint, _ aRect: NSRect) -> Bool

    Objective-C

    BOOL NSPointInRect ( NSPoint aPoint, NSRect aRect );

    Return Value

    YEStrue if aPoint is located within the rectangle represented by aRect, otherwise NOfalse.

    Discussion

    Point-in-rectangle functions generally assume that the “upper” and “left” edges of a rectangle are inside the rectangle boundaries, while the “lower” and “right” edges are outside the boundaries. This method treats the “upper” and “left” edges of the rectangle as the ones containing the origin of the rectangle.

    Special Considerations

    The meanings of “upper” and “lower” (and “left” and “right”) are relative to the current coordinate system and the location of the rectangle. For a rectangle of positive height located in positive x and y coordinates:

    • In the default OS X desktop coordinate system—where the origin is at the bottom left—the rectangle edge closest to the bottom of the screen is the “upper” edge (and is considered inside the rectangle).

    • On iOS and in a flipped coordinate system on OS X desktop—where the origin is at the top left—the rectangle edge closest to the bottom of the screen is the “lower” edge (and is considered outside the rectangle).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSMouseInRect

  • Returns a rectangle from a text-based representation.

    Declaration

    Swift

    func NSRectFromString(_ aString: String!) -> NSRect

    Objective-C

    NSRect NSRectFromString ( NSString *aString );

    Discussion

    Scans aString for four numbers which are used as the x and y coordinates and the width and height, in that order, to create an NSPoint object. If aString does not contain four numbers, those numbers that were scanned are used, and 0 is used for the remaining values. If aString does not contain any numbers, this function returns an NSRect object with a rectangle whose origin is (0, 0) and width and height are both 0.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSStringFromRect

  • Returns a string representation of a rectangle.

    Declaration

    Swift

    func NSStringFromRect(_ aRect: NSRect) -> String!

    Objective-C

    NSString * NSStringFromRect ( NSRect aRect );

    Discussion

    Returns a string of the form “{{a, b}, {c, d}}”, where a, b, c, and d are the x and y coordinates and the width and height, respectively, of aRect.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSRectFromString

  • Returns an NSRect typecast from a CGRect.

    Declaration

    Swift

    func NSRectFromCGRect(_ cgrect: CGRect) -> NSRect

    Objective-C

    NSRect NSRectFromCGRect ( CGRect cgrect );

    Return Value

    An NSRect typecast from a CGRect.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Returns a CGRect typecast from an NSRect.

    Declaration

    Swift

    func NSRectToCGRect(_ nsrect: NSRect) -> CGRect

    Objective-C

    CGRect NSRectToCGRect ( NSRect nsrect );

    Return Value

    A CGRect typecast from an NSRect.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Calculates the union of two rectangles.

    Declaration

    Swift

    func NSUnionRect(_ aRect: NSRect, _ bRect: NSRect) -> NSRect

    Objective-C

    NSRect NSUnionRect ( NSRect aRect, NSRect bRect );

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the width of the specified rectangle.

    Declaration

    Swift

    func NSWidth(_ aRect: NSRect) -> CGFloat

    Objective-C

    CGFloat NSWidth ( NSRect aRect );

    Return Value

    The width of aRect.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean that indicates whether two size values are equal.

    Declaration

    Swift

    func NSEqualSizes(_ aSize: NSSize, _ bSize: NSSize) -> Bool

    Objective-C

    BOOL NSEqualSizes ( NSSize aSize, NSSize bSize );

    Return Value

    YEStrue if aSize and bSize are identical, otherwise NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a new NSSize from the specified values.

    Declaration

    Swift

    func NSMakeSize(_ w: CGFloat, _ h: CGFloat) -> NSSize

    Objective-C

    NSSize NSMakeSize ( CGFloat w, CGFloat h );

    Return Value

    An NSSize having the specified width and height.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns an NSSize from a text-based representation.

    Declaration

    Swift

    func NSSizeFromString(_ aString: String!) -> NSSize

    Objective-C

    NSSize NSSizeFromString ( NSString *aString );

    Discussion

    Scans aString for two numbers which are used as the width and height, in that order, to create an NSSize struct. If aString only contains a single number, it is used as the width. The aString argument should be formatted like the output of NSStringFromSize, for example, @"{10,20}". If aString does not contain any numbers, this function returns an NSSize struct whose width and height are both 0.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSStringFromSize

  • Returns a string representation of a size.

    Declaration

    Swift

    func NSStringFromSize(_ aSize: NSSize) -> String!

    Objective-C

    NSString * NSStringFromSize ( NSSize aSize );

    Return Value

    A string of the form “{a, b}”, where a and b are the width and height, respectively, of aSize.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSSizeFromString

  • Returns an NSSize typecast from a CGSize.

    Declaration

    Swift

    func NSSizeFromCGSize(_ cgsize: CGSize) -> NSSize

    Objective-C

    NSSize NSSizeFromCGSize ( CGSize cgsize );

    Return Value

    An NSSize typecast from a CGSize.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Returns a CGSize typecast from an NSSize.

    Declaration

    Swift

    func NSSizeToCGSize(_ nssize: NSSize) -> CGSize

    Objective-C

    CGSize NSSizeToCGSize ( NSSize nssize );

    Return Value

    A CGSize typecast from an NSSize.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 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.

  • Returns the top-level error handler.

    Declaration

    Swift

    func NSGetUncaughtExceptionHandler() -> CFunctionPointer<NSUncaughtExceptionHandler>

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Changes the top-level error handler.

    Declaration

    Swift

    func NSSetUncaughtExceptionHandler(_ _: CFunctionPointer<NSUncaughtExceptionHandler>)

    Objective-C

    void NSSetUncaughtExceptionHandler ( NSUncaughtExceptionHandler * );

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • 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 CFBridgingRetain ( id 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:

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Objective-C

    id CFBridgingRelease ( CFTypeRef 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:

    • CFStringRef cfName = ABRecordCopyValue(person, kABPersonFirstNameProperty);
    • NSString *name = (NSString *)CFBridgingRelease(cfName);

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.7 and later.

    See Also

    CFBridgingRetain

  • Allocates a new block of memory.

    Declaration

    Swift

    func NSAllocateMemoryPages(_ bytes: Int) -> UnsafeMutablePointer<Void>

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Copies a block of memory.

    Declaration

    Swift

    func NSCopyMemoryPages(_ source: UnsafePointer<Void>, _ dest: UnsafeMutablePointer<Void>, _ bytes: Int)

    Objective-C

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

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Deallocates the specified block of memory.

    Declaration

    Swift

    func NSDeallocateMemoryPages(_ ptr: UnsafeMutablePointer<Void>, _ bytes: Int)

    Objective-C

    void NSDeallocateMemoryPages ( void *ptr, NSUInteger bytes );

    Discussion

    This function deallocates memory that was allocated with NSAllocateMemoryPages.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the binary log of the page size.

    Declaration

    Swift

    func NSLogPageSize() -> Int

    Objective-C

    NSUInteger NSLogPageSize ( void );

    Return Value

    The binary log of the page size.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the number of bytes in a page.

    Declaration

    Swift

    func NSPageSize() -> Int

    Objective-C

    NSUInteger NSPageSize ( void );

    Return Value

    The number of bytes in a page.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns information about the user’s system.

    Declaration

    Objective-C

    NSUInteger NSRealMemoryAvailable ( void );

    Return Value

    The number of bytes available in RAM.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Swift

    func NSRoundDownToMultipleOfPageSize(_ bytes: Int) -> Int

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func NSRoundUpToMultipleOfPageSize(_ bytes: Int) -> Int

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Allocates collectable memory.

    Garbage collection is deprecated in OS X v10.8; instead,you should use AutomaticReference Counting—see Transitioning to ARC Release Notes.

    Declaration

    Swift

    func NSAllocateCollectable(_ size: Int, _ options: Int) -> UnsafeMutablePointer<Void>

    Objective-C

    void * NSAllocateCollectable ( NSUInteger size, NSUInteger options );

    Parameters

    size

    The number of bytes of memory to allocate.

    options

    0 or NSScannedOption: A value of 0 allocates non-scanned 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

  • Reallocates collectable memory.

    Garbage collection is deprecated in OS X v10.8; instead,you should use AutomaticReference Counting—see Transitioning to ARC Release Notes.

    Declaration

    Swift

    func NSReallocateCollectable(_ ptr: UnsafeMutablePointer<Void>, _ size: Int, _ options: Int) -> UnsafeMutablePointer<Void>

    Objective-C

    void * NSReallocateCollectable ( void *ptr, NSUInteger size, NSUInteger options );

    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.

    options can be 0 or NSScannedOption: A value of 0 allocates non-scanned memory; a value of NSScannedOption allocates scanned memory.

    This function returns NULL if it’s unable to allocate the requested memory.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

  • Makes a newly allocated Core Foundation object eligible for collection.

    Garbage collection is deprecated in OS X v10.8; instead,you should use AutomaticReference Counting—see Transitioning to ARC Release Notes.

    Declaration

    Objective-C

    id NSMakeCollectable ( CFTypeRef cf );

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.5 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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 *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.)

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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 *zone, NSString *name );

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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 * 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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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 *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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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 * 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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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 * 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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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 * 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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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 * 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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.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

    Swift

    func NSDefaultMallocZone() -> NSZone

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.