Next Previous

Number Formatters

NSNumberFormatter provides two convenient methods—stringFromNumber: and numberFromString:—that you can use to create a string representation of a number and to create a number object from a string respectively. To create a localized string representation of a number without creating a formatter object, you can use the class method localizedStringFromNumber:numberStyle:.

If you have more sophisticated requirements when parsing a string, in addition to the methods inherited from NSFormatter (such as getObjectValue:forString:errorDescription:), the getObjectValue:forString:range:error: method allows you to specify a subrange of the string to be parsed, and it returns the range of the string that was actually parsed. (In the case of failure, it indicates where the failure occurred.) It also returns an NSError object that can contain rich information about the problem.

There are many attributes you can get and set on a number formatter. When you present information to the user, you should typically simply use the NSNumberFormatter style constants to specify pre-defined sets of attributes that determine how a formatted number is displayed. If you need to generate a representation of a number in a precise format, however, you should use a format string.

Use Formatter Styles to Present Numbers With the User’s Preferences

NSNumberFormatter makes it easy for you to format different sorts of number using the settings a user configured in the International preferences panel in System Preferences. The NSNumberFormatter style constants—NSNumberFormatterDecimalStyle, NSNumberFormatterCurrencyStyle, NSNumberFormatterPercentStyle, NSNumberFormatterScientificStyle, or NSNumberFormatterSpellOutStyle (which generates a textual representation of a number)—specify sets of attributes that determine how a number is displayed according to the user’s preferences.

You specify the style of a number formatter using setNumberStyle:. Listing 1 illustrates how you can format a date using formatter styles.

Listing 1 Formatting a number using a formatter style

NSNumberFormatter *numberFormatter = [[NSNumberFormatter alloc] init];

[numberFormatter setNumberStyle:NSNumberFormatterDecimalStyle];

NSString *formattedNumberString = [numberFormatter stringFromNumber:@122344.4563];

NSLog(@"formattedNumberString: %@", formattedNumberString);

// Output for locale en_US: "formattedNumberString: formattedNumberString: 122,344.453"

Use Format Strings to Specify Custom Formats

The format string uses the format patterns from the Unicode Technical Standard #35. The version of the standard varies with release of the operating system:

OS X v10.9 and iOS 7 use version tr35-31.
OS X v10.8 and iOS 6 use version tr35-25.
iOS 5 uses version tr35-19.
OS X v10.7 and iOS 4.3 use version tr35-17.
iOS 4.0, iOS 4.1, and iOS 4.2 use version tr35-15.
iOS 3.2 uses version tr35-12.
OS X v10.6, iOS 3.0, and iOS 3.1 use version tr35-10.
OS X v10.5 uses version tr35-6.
OS X v10.4 uses version tr35-4.

Note with the Unicode format string format, you should enclose literal text in the format string between apostrophes ('').

You specify the format string of a number formatter using setPositiveFormat: and setNegativeFormat:. Listing 2 illustrates how you can format a date using formatter styles.

Listing 2 Formatting a number using a format string

NSNumberFormatter *numberFormatter = [[NSNumberFormatter alloc] init];

[numberFormatter setPositiveFormat:@"###0.##"];

NSString *formattedNumberString = [numberFormatter stringFromNumber:@122344.4563];

NSLog(@"formattedNumberString: %@", formattedNumberString);

// Output for locale en_US: "formattedNumberString: formattedNumberString: 122,344.45"

Percentages

If you use a format string with a “%” character to format percentages, the results may be confusing. Consider the following example:

NSNumberFormatter *numberFormatter = [[NSNumberFormatter alloc] init];

[numberFormatter setPositiveFormat:@"0.00%;0.00%;-0.00%"];

NSLog(@"%@", [numberFormatter stringFromNumber:@4.0]);

// Output: "400.00%".

Because the format string is specified to use percentages, NSNumberFormatter interprets the number four as a fraction (where 1 is 100%) and renders it as such (4 = 4/1 = 400%).

If you want to represent a number as a percentage, you should use the NSNumberFormatterPercentStyle style—this also ensures that percentages are formatted appropriately for the locale:

NSNumberFormatter *numberFormatter = [[NSNumberFormatter alloc] init];

[numberFormatter setNumberStyle:NSNumberFormatterPercentStyle];

NSLocale *usLocale = [[NSLocale alloc] initWithLocaleIdentifier:@"en_US"];

[numberFormatter setLocale:usLocale];

NSLog(@"en_US: %@", [numberFormatter stringFromNumber:@4.0]);

// Output: "en_US: 400%".

NSLocale *faLocale = [[NSLocale alloc] initWithLocaleIdentifier:@"fa_IR"];

[numberFormatter setLocale:faLocale];

NSLog(@"fa_IR: %@", [numberFormatter stringFromNumber:@4.0]);

// Output: "fa_IR: ‪‪٪۴۰۰‬.‬"

Nomenclature

NSNumberFormatter provides several methods (such as setMaximumFractionDigits:) that allow you to manage the number of fraction digits allowed as input by an instance. “Fraction digits” are the numbers after the decimal separator (in English locales, the decimal separator is typically referred to as the “decimal point”).

Next Previous