Brief Intro to Foundation Functions

Foundation Functions

The Foundation Framework defines a number of functions and function-like macros. The Apple Foundation Functions Reference provides a definitive guide for these functions. Here you’ll examine Foundation functions that perform the following tasks:

• Assertions and logging
• String localization
• Numerical operations and byte ordering
• Runtime operations

Assertions

An assertion is a statement placed in code to check the existence of a condition. Assertions are used to provide runtime verification of assumptions that, if not present, should cause the program to terminate. Coding with assertions is one of the quickest and most effective ways to detect and correct bugs. Assertions can also document the logic of your program, thereby enhancing maintainability.

Each assertion contains a Boolean expression that you believe will be true when the assertion executes. If it is not true, the system will throw an error. By verifying that the expression is indeed true, the assertion confirms your assumptions about the behavior of your program, increasing your confidence that the program is free of errors.

The following are examples of situations where you would use assertions:

• Internal invariant: An assumption concerning program behavior. This assumption is often indicated with comments in code, but it can be documented and validated at runtime with an assertion.
• Control-flow invariant: An assumption concerning control flow, specifically locations in your code that should not be reached.
• Precondition: A condition that must be true before a method is invoked.
• Postcondition: A condition that must be true after a method is invoked.
• Class invariant: A condition that must be true for each class instance.

An example of an internal invariant is the conditional expression in Listing 13-1.

Listing 13-1.  Example of a Conditional Expression with an Internal Invariant

if (value >= 0)
{
  ...
}
else
{
  // value must be negative
  ...
}

As shown in Listing 13-1, these assumptions are often indicated with comments in code, but can be documented and validated at runtime with an assertion. The code excerpt from Listing 13-1 is updated in Listing 13-2 to express the invariant with an assertion.

Listing 13-2.  Example of an Internal Invariant Expressed with an Assertion

if (value >= 0)
{
  ...
}
else
{
  NSAssert((value < 0), @"Value not valid here, should be negative");
  ...
}

A common type of precondition is a conditional check of the input parameters for a method (or function). For public methods, preconditions are explicitly checked in code and throw the appropriate exception if the condition is not satisfied, hence they should not be checked with assertions. Assertions can be used to check preconditions for private methods and functions.

Assertions can be used to test postconditions for both public and private methods/functions.

A class invariant constrains the properties (i.e., internal state) and behavior of each instance of a class. Assertions can be used to define class invariants in a manner similar to that used to express the other situations discussed earlier.

Assertion Macros

The Foundation assertion functions are, in fact, macros that enable the creation of assertions in Objective-C code. Each assertion macro evaluates a condition and, if the condition evaluates to false, passes a string (and possibly additional printf-style arguments formatted into the string) describing the failure to an NSAssertionHandler instance. NSAssertionHandler is a Foundation Framework class used to handle false assertions, and each program thread has its own NSAssertionHandler object. So, when the condition of a Foundation assertion macro evaluates to false, it passes the condition describing the error to the NSAssertionHandler object for the current thread. This object in turn logs the error and then raises an exception (specifically, an NSInternalIncosistencyException) that causes the program to terminate. NSAssertionHandler instances are generally not created programmatically, but rather by an assertion function.

There are multiple Foundation assertion macros to support the creation of assertions within Objective-C methods and functions. Each assertion macro has at least one argument: a conditional expression that evaluates to true or false. Most also include an argument that contains a format string describing the error condition. The assertion macros support the substitution of zero to five arguments in a format string. The complete list of Foundation assertions functions is provided in Table 13-1.

Table 13-1. Foundation Assertion Functions

Foundation Function	Description
NSAssert	Generates an assertion for an Objective-C method if a given condition evaluates to NO (false). Its arguments include the conditional expression and a format string (with no format specifier) that describes the error.
NSAssert1	Similar to NSAssert, its arguments include the conditional expression, a format string (with one format specifier), and an argument to be inserted into the format string.
NSAssert2, NSAssert3, NSAssert4, NSAssert5	Similar to NSAssert, its arguments include the conditional expression, a format string (with two, three, four, or five format specifiers), and two, three, four, or five arguments to be inserted into the format string.
NSParameterAssert	Generates an assertion for the parameter of an Objective-C method. Its arguments are the conditional expression for a parameter.
NSCAssert	Generates an assertion for an Objective-C function: if a given condition evaluates to NO (false). Its arguments include the conditional expression and a format string (with no format specifier) that describes the error.
NSCAssert1	Similar to NSCAssert, its arguments include the conditional expression, a format string (with one format specifier), and an argument to be inserted into the format string.
NSCAssert2, NSCAssert3, NSCAssert4, NSCAssert5	Similar to NSCAssert, its arguments include the conditional expression, a format string (with two, three, four, or five format specifiers), and two, three, four, or five arguments to be inserted into the format string.
NSCParameterAssert	Generates an assertion for the parameter of an Objective-C function. Its arguments are the conditional expression for a parameter.

The following statement uses the NSAssert function to assert that the value of the variable named age is within the prescribed range.

NSAssert((age > 0) && (age <=18), @"Variable age not within prescribed range");

In the next statement, the same assertion is performed again, this time using the NSAssert1 function to log the value of the variable if the assertion fails.

NSAssert1((age > 0) && (age <=18),
  @"Value %d for age not within prescribed range", age);

Assertions can be used to check parameters of private methods or functions. Parameter checking for public methods/functions is normally part of the corresponding published API; hence, these should be checked whether or not assertions are enabled. Listing 13-3 uses the NSParameterAssert function to assert that the parameters for the method encodeArchive:toFile: have valid values.

Listing 13-3.  Asserting Method Parameter Values Using NSParameterAssert

- (BOOL) encodeArchive:(id)objectGraph toFile:(NSString *)file
{
  NSParameterAssert(file != nil);
  NSParameterAssert([objectGraph conformsToProtocol:@protocol(NSCoding)]);
 ...
}

You can disable assertions in your code by defining the preprocessor macro; NS_BLOCK_ASSERTIONS, for example.

#define NS_BLOCK_ASSERTIONS

Logging

The Foundation Framework includes two functions, NSLog and NSLogv, for logging output to the system log facility. In Xcode, error messages from these functions are displayed in the Xcode output pane. By now you have become familiar with the NSLog function through the example source code provided in this book, so here you’ll examine the NSLogv function.

NSLogv, as with NSLog, logs an error message to the system log facility. It differs from NSLog in that it supports a variable argument list. The declaration for the NSLog function is

void NSLogv(NSString *format, va_list args);

The variable format is a format string, and the variable args is a data type used for providing a list of (variable) arguments to functions. So you may be wondering, when would you use NSLogv? If you have a method or function that takes a variable argument list, then NSLogv can be used to log messages with this list. For example, the variadic function printArgs declared as follows:

void printArgs(int numArgs, ...);

logs a number of function arguments to the system log facility, where the arguments are a variable list (specified by the ... variable argument symbol) and the number of arguments from this list to be logged (specified by the numArgs function argument). Given this function declaration, Listing 13-4 demonstrates how this function is implemented using the NSLogv function.

Listing 13-4.  Using NSLogv to Log a variadic Argument List

void printArgs(int numArgs, ...)
{
  va_list args;
  va_start(args, numArgs);
  va_end(args);
  NSMutableString *format = [[NSMutableString alloc] init];
  [format appendString:@"Arguments: "];
  for (int ii=0; ii<numArgs-1; ii++)
  {
    [format appendString:@"%@, "];
  }
  if (numArgs > 1)
  {
    [format appendString:@"%@"];
  }
  NSLogv(format, args);
}

If this function is invoked as follows:

printArgs(3, @"Hello", @"Objective-C", @"World!");

It logs to the console the following message:

Arguments: Hello, Objective-C, World!

Bundles

The Foundation Framework includes several function macros for retrieving localized strings. They are used to load strings from a program’s strings files. Before you begin examining these macros, let’s take a moment to discuss internationalization and localization.

Internationalization is the process of designing an application so that it can serve different languages and regions (i.e., locales) without being changed. Localization is the adaptation of an internationalized application to a local market. Localization can be applied to many parts of an application, including its visible text, icons and graphics, views, and data.

Localizing Strings

Localizing visible text is a key part of the localization process. Strings in code that require localization must be extracted, localized, and reinserted back in the code in order to display properly in the specified locale. Apple provides a tool, genstrings, which can be used to facilitate text localization. The genstrings tool searches your code for uses of the localization function macros and uses the information they contain to build the initial set of strings files (resource files that contain localizable strings) for your application. For example, if your source code contains a statement that utilizes the localization function macro NSLocalizedString to return a localized version of the string Yes, as follows:

NSString *yes = NSLocalizedString(@"Yes", @"Word for yes");

the genstrings tool will parse this statement and use it to build a strings file. The genstrings tool can parse C and Objective-C source code files with the .c or .m filename extensions. You can also specify the output directory where genstrings places the resulting strings files. In most cases, you would want to specify the directory containing the project resources for your development language.

The following example uses the genstrings tool to parse all Objective-C source files in the current directory and store the resulting strings file in the en.lproj subdirectory, which must already exist.

genstrings -o en.lproj *.m

The first time you run the genstrings tool, it creates a set of new strings files for you. Subsequent executions on the sme file(s) replace the contents of those strings files with the current string entries found in your source code.

Localized Strings Functions

Once you have localized strings in a strings file, the Foundation localized string function macros can be used to retrieve the appropriate localized string for a specified locale. The Foundation Framework defines four function macros for getting localized strings, shown in Table 13-2.

Table 13-2. Foundation Localized String Functions

Foundation Function	Description
NSLocalizedString	Retrieves a localized version of a string on the main application bundle in the default strings table.
NSLocalizedStringFromTable	Retrieves a localized version of a string on the main application bundle in the specified strings table.
NSLocalizedStringFromTableInBundle	Retrieves a localized version of a string on the specified application bundle and strings table.
NSLocalizedStringWithDefaultValue	Retrieves a localized version of a string on the specified application bundle and strings table, using the default value if the key is not found.

The localized string functions depend on an NSBundle class instance. Each function invokes an NSBundle object’s localizedStringForKey:value:table: method, providing the function arguments as parameters for the method.

So, the localization functions both provide expressions that can be parsed by the genstrings tool to create an application’s strings file, and retrieve a localized version of a string. They also let you associate translation comments with each entry.

For example, if your program has a strings table in a file named Localizable.strings that includes the following strings:

"Yes" = "Yes"
"No" = "No"

the NSLocalizedStringFromTable function would retrieve the string Yes with the following statement.

NSString *yes = NSLocalizedStringFromTable(@"Yes", @"Localizable.strings",
                @"Word for yes");

Conversely, if the Localizable.strings file for the French locale contained the values

"Yes" = "Oui"
"No" = "Non"

Then the preceding statement would retrieve the string Oui.

Decimal Numbers and Byte Ordering

The Foundation Framework includes functions for performing decimal number operations. The arithmetic operations supported include decimal arithmetic, rounding, comparison, copy, normalizing, and string representations.

The functions take one or more NSDecimal numbers as arguments, along with (potentially) other parameters. NSDecimal is a Foundation data type used to describe a decimal number.

NSDecimalAdd, NSDecimalSubtract, NSDecimalMultiply, and NSDecimalDivide perform the associated arithmetic operations on NSDecimal instances. NSDecimalMultiplyByPowerOf10 multiplies a number by an input power of 10. Each takes as an input argument an NSRoundingMode Foundation constant that specifies how the result is rounded. The available rounding modes are:

• NSRoundDown: Rounds the returned value down.
• NSRoundUp: Rounds the returned value up.
• NSRoundPlain: Rounds to the closest possible return value. When the value is halfway between two positive numbers, it rounds up. When the value is halfway between two negative numbers, it rounds down.
• NSRoundBankers: Rounds to the closest possible return value. When the value is halfway between two numbers, it returns the value whose last digit is even.

Rounding can be explicitly performed using the NSDecimalRound function, or automatically performed for the NSDecimal arithmetic functions if the result has more digits than the maximum number of significant digits allowed (38).

NSDecimalPower raises a number to the specified power. NSDecimalNormalize and NSDecimalCompact both change the representation of a decimal number. NSDecimalCompact formats a decimal so that it takes up the minimum amount of memory. All of the NSDecimal functions expect compact decimal arguments. NSDecimalNormalize updates the format of its two decimal arguments such that they have the same exponent. NSDecimalAdd and NSDecimalSubtract invoke NSDecimalNormalize. NSDecimalRound rounds the input decimal according to the input NSRoundingMode constant.

NSDecimalCopy copies the value of a decimal number to another NSDecimalNumber instance. NSDecimalCompare compares two decimal numbers, returning the result of the comparison as an NSComparisonResult value (a Foundation constant) that can have one of the following values:

• NSOrderedDescending: The left operand is greater than the right operand.
• NSOrderedAscending: The left operand is less than the right operand.
• NSOrderedSame: The two operands are equal.

Using the NSDecimal Functions

Now you’ll create a program that demonstrates the use of the Foundation decimal arithmetic functions. In Xcode, create a new project by selecting New Project . . . from the Xcode File menu. In the New Project Assistant pane, create a command-line application. In the Project Options window, specify DecimalAddition for the Product Name, choose Foundation for the Project Type, and select ARC memory management by selecting the Use Automatic Reference Counting check box. Specify the location in your file system where you want the project to be created (if necessary select New Folder and enter the name and location for the folder), uncheck the Source Control check box, and then click the Create button.

OK, the DecimalAddition project is created. Now select the main.m file and update the main() function, as shown in Listing 13-5.

Listing 13-5.  Performing Decimal Arithmetic Using the NSDecimalAdd and NSDecimalRound Functions

#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
  @autoreleasepool
  {
    // Create two NSDecimal numbers using the NSDecimalNumber class
    NSDecimal dec1 = [[NSDecimalNumber decimalNumberWithString:@"1.534"]
                       decimalValue];
    NSDecimal dec2 = [[NSDecimalNumber decimalNumberWithString:@"2.011"]
                       decimalValue];
     
    // Declare result and rounded result variables for the calculations
    NSDecimal result;
    NSDecimal roundedResult;
     
    // Now perform the decimal addition
    NSDecimalAdd(&result, &dec1, &dec2, NSRoundPlain);
    NSLog(@"Sum = %@", NSDecimalString(&result, nil));
     
    // Demonstrate rounding the result using the available rounding modes
    NSDecimalRound(&roundedResult, &result, 2, NSRoundUp);
    NSLog(@"Sum (round up) = %@", NSDecimalString(&roundedResult, nil));
    NSDecimalRound(&roundedResult, &result, 2, NSRoundDown);
    NSLog(@"Sum (round down) = %@", NSDecimalString(&roundedResult, nil));
    NSDecimalRound(&roundedResult, &result, 2, NSRoundPlain);
    NSLog(@"Sum (round plain) = %@", NSDecimalString(&roundedResult, nil));
    NSDecimalRound(&roundedResult, &result, 2, NSRoundBankers);
    NSLog(@"Sum (round bankers) = %@", NSDecimalString(&roundedResult, nil));
  }
  return 0;
}

As shown in Listing 13-5, the NSDecimalNumber class is used to create two decimal numbers of the Foundation type NSDecimal. The NSDecimalAdd function is then used to add the two numbers. Because the number of digits in the result is less than the maximum allowed, no rounding is performed and the result printed by the NSLog function is 3.545. Next, the NSDecimalRound function is used to explicitly round the result to two digits after the decimal point; each of the available rounding modes is used to demonstrate how they affect the result. When you compile and run the program, you should observe messages in the output pane comparable to those shown in Figure 13-1.

Figure 13-1. DecimalAddition program output

As you can see in Figure 13-1, the selected rounding mode affects the result as explained earlier.

The NSDecimalNumber class provides methods that duplicate much of the functionality of the NSDecimal functions; hence, you have the choice of which to use to perform decimal arithmetic. The NSDecimal functions provide better performance and lower memory utilization than the NSDecimalNumber class. However, the NSDecimalNumber class performs these decimal operations using objects, and enables you to directly store the results of these operations in an object-oriented collection like an instance of NSArray or NSDictionary.

Byte Ordering

The Foundation Framework includes a set of functions that perform byte ordering; specifically, these functions can be used to swap the order of bytes of a number as stored in memory. Byte ordering is important when a binary file created on one computer is read on another computer with a different byte order. Big endian machines (such as a Motorola 680x0 CPU) store data with the most significant byte in the lowest memory address. A little endian machine (such as an Intel CPU) stores the most significant byte in the highest memory address. For example, the decimal value of 4132 (hexadecimal 1024) would be stored as shown in Table 13-3.

Table 13-3. Byte Ordering for Big Endian and Little Endian Machines

In order for binary files to be successfully transferred and processed between these big and little endian machines, the byte ordering of the data needs to be swapped. The NSSwap byte ordering functions perform big to little and little to big endian byte ordering for the following data types: short, int, long, long long, float, and double. The NSSwapHost functions swap from the current endian format to that specified for the input data type. The NSHostByteOrder function determines the host endian format. It returns a Foundation constant value of NS_LittleEndian or NS_BigEndian.

Interacting with the Runtime

The Foundation Framework includes several functions that utilize the Objective-C runtime library. These functions enable dynamic operations.

The NSGetSizeAndAlignment function is used to get the size of a character array in bytes. The following functions retrieve a string representation of a corresponding Objective-C type:

• NSStringFromSelector
• NSStringFromProtocol
• NSStringFromClass

The following statement retrieves a text string (sayHello:) for a selector specified with the @selector directive, and assigns this string to the variable methodName.

NSString *methodName = NSStringFromSelector(@selector(sayHello:));

The next set of functions perform the converse operation; they retrieve an Objective-C type from a string representation:

• NSSelectorFromString
• NSProtocolFromString
• NSClassFromString

The following statement dynamically retrieves a selector from the input string.

SEL methodSel = NSSelectorFromString(@"sayHello:");

File Paths

A set of Foundation functions provides operations for managing file paths, including retrieving the user name, home directory, temporary directory, and directory search paths. The following statement demonstrates use of the NSFullUserName function to retrieve the full name of the current user.

NSString *fullName = NSFullUserName();

The NSUserName function, in comparison, returns the logon name of the current user.

The following statement demonstrates use of the NSHomeDirectory function to retrieve the home directory for the current user.

NSString *homeDir = NSHomeDirectory();

The NSHomeDirectoryForUser function retrieves the home directory for the user specified in the input argument.

The NSTemporaryDirectory function retrieves the full path to the temporary directory for the current user.

The NSSearchPathForDirectoriesInDomains function returns a list of directory search paths for the specified directories in the specified domains. The syntax for the function is

NSSearchPathForDirectoriesInDomains(
  NSSearchPathDirectory directory,
  NSSearchPathDomainMask domainMask,
  BOOL expandTilde);

The NSSearchPathDirectory is a Foundation constant that specifies a variety of directories in the file system, for example the Documents directory. The NSSearchPathDomainMask is a Foundation constant used to specify the domain for the search; for example, the user’s home directory. The BOOL argument is set to YES if the paths returned should be expanded. Listing 13-6 demonstrates the use of the function to retrieve the documents directory for the current user.

Listing 13-6.  Retrieving the Documents Directory Using the NSSearchPathForDirectoriesInDomains Function

NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory,
                                                     NSUserDomainMask, YES);
NSString *documentsDirectory = paths[0];

Geometry

The Foundation Framework includes functions that assist in the performance of geometric calculations on points, ranges, rectangles, and sizes. A point represents a location in two-dimensional Euclidean geometry with x and y coordinates. A range represents a one-dimensional quantity beginning at a specified location of a specified length. A size represents a two-dimensional quantity of specified width and height. The point, range, and size Foundation functions perform operations to create, retrieve, test for equality, and return string representations of these quantities. The Foundation data types NSPoint represents points, NSRange represents ranges, and NSSize represents sizes. The following statement creates a new NSPoint from the specified values.

NSPoint point = NSMakePoint(0, 5);

The Foundation framework also includes numerous functions for manipulating rectangles, including operations to create, get, get components, query, test for equality, and return string representations. There are also functions that perform geometric operations (test for intersection, union, divide, point in rectangle, etc.). The Foundation data type NSRect represents rectangles. The following statement creates a rectangle at point {0, 0} and size [5, 10].

NSRect rect1 = NSMakeRect(0.0, 0.0, 5.0, 10.0);

The next set of statements creates a new rectangle at point {2.5, 5} and size [5, 10], and then calculates the intersection of the two rectangles.

NSRect rect2 = NSMakeRect(2.5, 5.0, 5.0, 10.0);
NSRect rect3 = NSIntersectionRect(rect1, rect2);