---

NSNumberFormatter Class Reference

Overview

Instances of NSNumberFormatter format the textual representation of cells that contain NSNumber objects and convert textual representations of numeric values into NSNumber objects. The representation encompasses integers, floats, and doubles; floats and doubles can be formatted to a specified decimal position. NSNumberFormatter objects can also impose ranges on the numeric values cells can accept.

Many new methods were added to NSNumberFormatter for Mac OS X v10.4 with the intent of making the class interface more like that of CFNumberFormatter, the Core Foundation service on which the class is based. The behavior of an NSNumberFormatter object can conform either to the range of behaviors existing prior to Mac OS X v10.4 or to the range of behavior since that release. (Methods added for and since Mac OS X v10.4 are indicated by a method’s availability statement.) You can determine the current formatter behavior with the formatterBehavior method and you can set the formatter behavior with the setFormatterBehavior: method.

Nomenclature note: 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 typically referred to as the “decimal point”).

Tasks

Configuring Formatter Behavior and Style

• – setFormatterBehavior:
• – formatterBehavior
• + setDefaultFormatterBehavior:
• + defaultFormatterBehavior
• – setNumberStyle:
• – numberStyle
• – setGeneratesDecimalNumbers:
• – generatesDecimalNumbers

Converting Between Numbers and Strings

• – getObjectValue:forString:range:error:
• – numberFromString:
• – stringFromNumber:

Managing Localization of Numbers

• – setLocalizesFormat:
• – localizesFormat
• – setLocale:
• – locale

Configuring Rounding Behavior

• – setRoundingBehavior:
• – roundingBehavior
• – setRoundingIncrement:
• – roundingIncrement
• – setRoundingMode:
• – roundingMode

Configuring Numeric Formats

• – setFormat:
• – formatWidth
• – setNegativeFormat:
• – negativeFormat
• – setPositiveFormat:
• – positiveFormat
• – setFormatWidth:
• – format
• – setMultiplier:
• – multiplier

Configuring Numeric Symbols

• – percentSymbol
• – setPercentSymbol:
• – perMillSymbol
• – setPerMillSymbol:
• – minusSign
• – setMinusSign:
• – plusSign
• – setPlusSign:
• – exponentSymbol
• – setExponentSymbol:
• – zeroSymbol
• – setZeroSymbol:
• – nilSymbol
• – setNilSymbol:
• – notANumberSymbol
• – setNotANumberSymbol:
• – negativeInfinitySymbol
• – setNegativeInfinitySymbol:
• – positiveInfinitySymbol
• – setPositiveInfinitySymbol:

Configuring the Format of Currency

• – setCurrencySymbol:
• – currencySymbol
• – setCurrencyCode:
• – currencyCode
• – setInternationalCurrencySymbol:
• – internationalCurrencySymbol
• – setCurrencyGroupingSeparator:
• – currencyGroupingSeparator

Configuring Numeric Prefixes and Suffixes

• – setPositivePrefix:
• – positivePrefix
• – setPositiveSuffix:
• – positiveSuffix
• – setNegativePrefix:
• – negativePrefix
• – setNegativeSuffix:
• – negativeSuffix

Configuring the Display of Numeric Values

• – setTextAttributesForNegativeValues:
• – textAttributesForNegativeValues
• – setTextAttributesForPositiveValues:
• – textAttributesForPositiveValues
• – setAttributedStringForZero:
• – attributedStringForZero
• – setTextAttributesForZero:
• – textAttributesForZero
• – setAttributedStringForNil:
• – attributedStringForNil
• – setTextAttributesForNil:
• – textAttributesForNil
• – setAttributedStringForNotANumber:
• – attributedStringForNotANumber
• – setTextAttributesForNotANumber:
• – textAttributesForNotANumber
• – setTextAttributesForPositiveInfinity:
• – textAttributesForPositiveInfinity
• – setTextAttributesForNegativeInfinity:
• – textAttributesForNegativeInfinity

Configuring Separators and Grouping Size

• – setGroupingSeparator:
• – groupingSeparator
• – setUsesGroupingSeparator:
• – usesGroupingSeparator
• – setThousandSeparator:
• – thousandSeparator
• – setHasThousandSeparators:
• – hasThousandSeparators
• – setDecimalSeparator:
• – decimalSeparator
• – setAlwaysShowsDecimalSeparator:
• – alwaysShowsDecimalSeparator
• – setCurrencyDecimalSeparator:
• – currencyDecimalSeparator
• – setGroupingSize:
• – groupingSize
• – setSecondaryGroupingSize:
• – secondaryGroupingSize

Managing the Padding of Numbers

• – setPaddingCharacter:
• – paddingCharacter
• – setPaddingPosition:
• – paddingPosition

Managing Input Attributes

• – setAllowsFloats:
• – allowsFloats
• – setMinimum:
• – minimum
• – setMaximum:
• – maximum
• – setMinimumIntegerDigits:
• – minimumIntegerDigits
• – setMinimumFractionDigits:
• – minimumFractionDigits
• – setMaximumIntegerDigits:
• – maximumIntegerDigits
• – setMaximumFractionDigits:
• – maximumFractionDigits

Configuring Significant Digits

• – setUsesSignificantDigits:
• – usesSignificantDigits
• – setMinimumSignificantDigits:
• – minimumSignificantDigits
• – setMaximumSignificantDigits:
• – maximumSignificantDigits

Managing Leniency Behavior

• – setLenient:
• – isLenient

Managing the Validation of Partial Numeric Strings

• – setPartialStringValidationEnabled:
• – isPartialStringValidationEnabled

Class Methods

defaultFormatterBehavior

Returns an NSNumberFormatterBehavior constant that indicates default formatter behavior for new instances of NSNumberFormatter.

+ (NSNumberFormatterBehavior)defaultFormatterBehavior

Return Value

An NSNumberFormatterBehavior constant that indicates default formatter behavior for new instances of NSNumberFormatter.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• + setDefaultFormatterBehavior:

Declared In

NSNumberFormatter.h

setDefaultFormatterBehavior:

Sets the default formatter behavior for new instances of NSNumberFormatter .

+ (void)setDefaultFormatterBehavior:(NSNumberFormatterBehavior)behavior

Parameters

behavior

An NSNumberFormatterBehavior constant that indicates the revision of the class providing the default behavior.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• + defaultFormatterBehavior

Declared In

NSNumberFormatter.h

Instance Methods

allowsFloats

Returns a Boolean value that indicates whether the receiver allows floating-point values as input.

- (BOOL)allowsFloats

Return Value

YES if the receiver allows as input floating-point values (that is, values that include the period character [.]), otherwise NO.

Discussion

When this method returns NO, only integer values can be provided as input. The default is YES.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAllowsFloats:

Declared In

NSNumberFormatter.h

alwaysShowsDecimalSeparator

Returns a Boolean value that indicates whether the receiver always shows a decimal separator, even if the number is an integer.

- (BOOL)alwaysShowsDecimalSeparator

Return Value

YES if the receiver always shows a decimal separator, even if the number is an integer, otherwise NO.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setAlwaysShowsDecimalSeparator:

Declared In

NSNumberFormatter.h

attributedStringForNil

Returns the attributed string used to display nil values.

- (NSAttributedString *)attributedStringForNil

Return Value

The attributed string used to display nil values.

Discussion

By default nil values are displayed as an empty string.

Special Considerations

This method is for use with formatters using NSNumberFormatterBehavior10_0 behavior.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAttributedStringForNil:

Declared In

NSNumberFormatter.h

attributedStringForNotANumber

Returns the attributed string used to display “not a number” values.

- (NSAttributedString *)attributedStringForNotANumber

Return Value

The attributed string used to display “not a number” values.

Discussion

By default “not a number” values are displayed as the string “NaN”.

Special Considerations

This method is for use with formatters using NSNumberFormatterBehavior10_0 behavior.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAttributedStringForNotANumber:

Declared In

NSNumberFormatter.h

attributedStringForZero

Returns the attributed string used to display zero values.

- (NSAttributedString *)attributedStringForZero

Return Value

The attributed string used to display zero values.

Discussion

By default zero values are displayed according to the format specified for positive values; for more discussion of this subject see Data Formatting Programming Guide for Cocoa.

Special Considerations

This method is for use with formatters using NSNumberFormatterBehavior10_0 behavior.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAttributedStringForZero:

Declared In

NSNumberFormatter.h

currencyCode

Returns the receiver’s currency code as a string.

- (NSString *)currencyCode

Return Value

The receiver’s currency code as a string.

Discussion

A currency code is a three-letter code that is, in most cases, composed of a country’s two-character Internet country code plus an extra character to denote the currency unit. For example, the currency code for the Australian dollar is “AUD”. Currency codes are based on the ISO 4217 standard.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setCurrencyCode:

Declared In

NSNumberFormatter.h

currencyDecimalSeparator

Returns the receiver’s currency decimal separator as a string.

- (NSString *)currencyDecimalSeparator

Return Value

The receiver’s currency decimal separator as a string.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – currencyDecimalSeparator

Declared In

NSNumberFormatter.h

currencyGroupingSeparator

Returns the currency grouping separator for the receiver.

- (NSString *)currencyGroupingSeparator

Return Value

The currency grouping separator for the receiver.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSNumberFormatter.h

currencySymbol

Returns the receiver’s local currency symbol.

- (NSString *)currencySymbol

Discussion

A country typically has a local currency symbol and an international currency symbol. The local symbol is used within the country, while the international currency symbol is used in international contexts to specify that country’s currency unambiguously. The local currency symbol is often represented by a Unicode code point.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – internationalCurrencySymbol
• – setCurrencySymbol:

Declared In

NSNumberFormatter.h

decimalSeparator

Returns a string containing the character the receiver uses to represent decimal separators.

- (NSString *)decimalSeparator

Return Value

A string containing the character the receiver uses to represent decimal separators.

Discussion

The return value doesn’t indicate whether decimal separators are enabled.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setDecimalSeparator:

Declared In

NSNumberFormatter.h

exponentSymbol

Returns the string the receiver uses as an exponent symbol.

- (NSString *)exponentSymbol

Return Value

The string the receiver uses as an exponent symbol.

Discussion

The exponent symbol is the “E” or “e” in the scientific notation of numbers, as in 1.0e+56.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setExponentSymbol:

Declared In

NSNumberFormatter.h

format

Returns the format used by the receiver.

- (NSString *)format

Return Value

The format used by the receiver.

Special Considerations

This method is for use with formatters using NSNumberFormatterBehavior10_0 behavior.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setFormat:

Declared In

NSNumberFormatter.h

formatterBehavior

Returns an NSNumberFormatterBehavior constant that indicates the formatter behavior of the receiver.

- (NSNumberFormatterBehavior)formatterBehavior

Return Value

An NSNumberFormatterBehavior constant that indicates the formatter behavior of the receiver.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setFormatterBehavior:

Declared In

NSNumberFormatter.h

formatWidth

Returns the format width of the receiver.

- (NSUInteger)formatWidth

Discussion

The format width is the number of characters of a formatted number within a string that is either left justified or right justified based on the value returned from paddingPosition.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setFormatWidth:

Declared In

NSNumberFormatter.h

generatesDecimalNumbers

Returns a Boolean value that indicates whether the receiver creates instances of NSDecimalNumber when it converts strings to number objects.

- (BOOL)generatesDecimalNumbers

Return Value

YES if the receiver creates instances of NSDecimalNumber when it converts strings to number objects, NO if it creates instance of NSNumber.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setGeneratesDecimalNumbers:

Declared In

NSNumberFormatter.h

getObjectValue:forString:range:error:

Returns by reference a cell-content object after creating it from a range of characters in a given string.

- (BOOL)getObjectValue:(out id *)anObject forString:(NSString *)aString range:(inout NSRange *)rangep error:(out NSError **)error

Parameters

anObject

On return, contains an instance of NSDecimalNumber or NSNumber based on the current value of generatesDecimalNumbers. The default is to return NSDecimalNumber instances

aString

A string object with the range of characters specified in rangep that is used to create anObject.

rangep

A range of characters in aString. On return, contains the actual range of characters used to create the object.

error

If an error occurs, upon return contains an NSError object that explains the reason why the conversion failed. If you pass in nil for error you are indicating that you are not interested in error information.

Return Value

YES if the conversion from string to cell-content object was successful, otherwise NO.

Discussion

If there is an error, the delegate (if any) of the control object managing the cell can then respond to the failure in the NSController delegation method control:didFailToFormatString:errorDescription:.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – numberFromString:
• – stringFromNumber:

Declared In

NSNumberFormatter.h

groupingSeparator

Returns a string containing the receiver’s grouping separator.

- (NSString *)groupingSeparator

Return Value

A string containing the receiver’s grouping separator.

Discussion

For example, the grouping separator used in the United States is the comma (“10,000”) whereas in France it is the period (“10.000”).

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setGroupingSeparator:

Declared In

NSNumberFormatter.h

groupingSize

Returns the receiver’s primary grouping size.

- (NSUInteger)groupingSize

Return Value

The receiver’s primary grouping size.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setGroupingSize:

Declared In

NSNumberFormatter.h

hasThousandSeparators

Returns a Boolean value that indicates whether the receiver’s format includes thousand separators.

- (BOOL)hasThousandSeparators

Return Value

YES if the receiver’s format includes thousand separators, otherwise NO.

Discussion

The default is NO.

Special Considerations

This method is for use with formatters using NSNumberFormatterBehavior10_0 behavior.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setHasThousandSeparators:

Declared In

NSNumberFormatter.h

internationalCurrencySymbol

Returns the international currency symbol used by the receiver.

- (NSString *)internationalCurrencySymbol

Discussion

A country typically has a local currency symbol and an international currency symbol. The local symbol is used within the country, while the international currency symbol is used in international contexts to specify that country’s currency unambiguously. The international currency symbol is often represented by a Unicode code point.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – currencySymbol
• – setInternationalCurrencySymbol:

Declared In

NSNumberFormatter.h

isLenient

Returns a Boolean value that indicates whether the receiver uses heuristics to guess at the date which is intended by a string.

- (BOOL)isLenient

Return Value

YES if the receiver uses heuristics to guess at the date which is intended by the string, otherwise NO.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setLenient:

Declared In

NSNumberFormatter.h

isPartialStringValidationEnabled

Returns a Boolean value that indicates whether partial string validation is enabled.

- (BOOL)isPartialStringValidationEnabled

Return Value

YES if partial string validation is enabled, otherwise NO.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setPartialStringValidationEnabled:

Declared In

NSNumberFormatter.h

locale

Returns the locale of the receiver.

- (NSLocale *)locale

Return Value

The locale of the receiver.

Discussion

A number formatter’s locale specifies default localization attributes, such as ISO country and language codes, currency code, calendar, system of measurement, and decimal separator.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setLocale:

Declared In

NSNumberFormatter.h

localizesFormat

Returns a Boolean value that indicates whether the receiver localizes formats.

- (BOOL)localizesFormat

Return Value

YES if the receiver localizes formats, otherwise NO.

Discussion

The default is NO.

Special Considerations

This method is for use with formatters using NSNumberFormatterBehavior10_0 behavior.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• –&