Class

NSNumberFormatter

A formatter that converts between numeric values and their textual representations.

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.

Significant Digits and Fraction Digits

The NSNumberFormatter class provides flexible options for displaying non-zero fractional parts of numbers.

If you set the usesSignificantDigits property to YES, you can configure NSNumberFormatter to display significant digits using the minimumSignificantDigits and maximumSignificantDigits properties. If usesSignificantDigits is NO, these properties are ignored. See Configuring Significant Digits.

Otherwise, you can configure the minimum and maximum number of integer and fraction digits, or the numbers before and after the decimal separator, respectively, using the minimumIntegerDigits, maximumIntegerDigits, minimumFractionDigits, and maximumFractionDigits properties. See Configuring Integer and Fraction Digits.

Thread Safety

On iOS 7 and later NSNumberFormatter is thread-safe.

In macOS 10.9 and later NSNumberFormatter is thread-safe so long as you are using the modern behavior in a 64-bit app.

On earlier versions of the operating system, or when using the legacy formatter behavior or running in 32-bit in macOS, NSNumberFormatter is not thread-safe, and you therefore must not mutate a number formatter simultaneously from multiple threads.

Topics

Configuring Formatter Behavior and Style

formatterBehavior

The formatter behavior of the receiver.

setDefaultFormatterBehavior:

Sets the default formatter behavior for new instances of NSNumberFormatter .

defaultFormatterBehavior

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

numberStyle

The number style used by the receiver.

generatesDecimalNumbers

Determines whether the receiver creates instances of NSDecimalNumber when it converts strings to number objects.

Converting Between Numbers and Strings

getObjectValue:forString:range:error:

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

numberFromString:

Returns an NSNumber object created by parsing a given string.

stringFromNumber:

Returns a string containing the formatted value of the provided number object.

localizedStringFromNumber:numberStyle:

Returns a localized number string with the specified style.

Managing Localization of Numbers

localizesFormat

Determines whether the dollar sign character ($), decimal separator character (.), and thousand separator character (,) are converted to appropriately localized characters as specified by the user’s localization preference.

locale

The locale of the receiver.

Configuring Rounding Behavior

roundingBehavior

The rounding behavior used by the receiver.

NSDecimalNumberHandler

A class that adopts the decimal number behaviors protocol.

roundingIncrement

The rounding increment used by the receiver.

roundingMode

The rounding mode used by the receiver.

Configuring Integer and Fraction Digits

minimumIntegerDigits

The minimum number of digits before the decimal separator.

maximumIntegerDigits

The maximum number of digits before the decimal separator.

minimumFractionDigits

The minimum number of digits after the decimal separator.

maximumFractionDigits

The maximum number of digits after the decimal separator.

Configuring Significant Digits

usesSignificantDigits

A Boolean value indicating whether the formatter uses minimum and maximum significant digits when formatting numbers.

minimumSignificantDigits

The minimum number of significant digits for the number formatter.

maximumSignificantDigits

The maximum number of significant digits for the number formatter.

Configuring Numeric Formats

format

The receiver’s format.

formattingContext

The capitalization formatting context used when formatting a number.

formatWidth

The format width used by the receiver.

negativeFormat

The format the receiver uses to display negative values.

positiveFormat

The format the receiver uses to display positive values.

multiplier

The multiplier of the receiver.

Configuring Numeric Symbols

percentSymbol

The string used to represent a percent symbol.

perMillSymbol

The string used to represent a per-mill (per-thousand) symbol.

minusSign

The string used to represent a minus sign.

plusSign

The string used to represent a plus sign.

exponentSymbol

The string used to represent an exponent symbol.

zeroSymbol

The string used to represent a zero value.

nilSymbol

The string used to represent a nil value.

notANumberSymbol

The string used to represent a NaN (“not a number”) value.

negativeInfinitySymbol

The string used to represent a negative infinity symbol.

positiveInfinitySymbol

The string used to represent a positive infinity symbol.

Configuring the Format of Currency

currencySymbol

The string used by the receiver as a local currency symbol.

currencyCode

The receiver’s currency code.

internationalCurrencySymbol

The international currency symbol used by the receiver.

currencyGroupingSeparator

The currency grouping separator for the receiver.

Configuring Numeric Prefixes and Suffixes

positivePrefix

The string the receiver uses as the prefix for positive values.

positiveSuffix

The string the receiver uses as the suffix for positive values.

negativePrefix

The string the receiver uses as a prefix for negative values.

negativeSuffix

The string the receiver uses as a suffix for negative values.

Configuring the Display of Numeric Values

textAttributesForNegativeValues

The text attributes to be used in displaying negative values.

textAttributesForPositiveValues

The text attributes to be used in displaying positive values.

attributedStringForZero

The attributed string that the receiver uses to display zero values.

textAttributesForZero

The text attributes used to display a zero value.

attributedStringForNil

The attributed string the receiver uses to display nil values.

textAttributesForNil

The text attributes used to display the nil symbol.

attributedStringForNotANumber

The attributed string the receiver uses to display “not a number” values.

textAttributesForNotANumber

The text attributes used to display the NaN (“not a number”) string.

textAttributesForPositiveInfinity

The text attributes used to display the positive infinity symbol.

textAttributesForNegativeInfinity

The text attributes used to display the negative infinity symbol.

Configuring Separators and Grouping Size

groupingSeparator

The string used by the receiver for a grouping separator.

usesGroupingSeparator

Determines whether the receiver displays the group separator.

thousandSeparator

The character the receiver uses as a thousand separator.

hasThousandSeparators

Determines whether the receiver uses thousand separators.

decimalSeparator

The character the receiver uses as a decimal separator.

alwaysShowsDecimalSeparator

Determines whether the receiver always shows the decimal separator, even for integer numbers.

currencyDecimalSeparator

The string used by the receiver as a currency decimal separator.

groupingSize

The grouping size of the receiver.

secondaryGroupingSize

The secondary grouping size of the receiver.

Managing the Padding of Numbers

paddingCharacter

The string that the receiver uses to pad numbers in the formatted string representation.

paddingPosition

The padding position used by the receiver.

Managing Input and Output Attributes

allowsFloats

Determines whether the receiver allows as input floating-point values (that is, values that include the period character [.]).

minimum

The lowest number allowed as input by the receiver.

maximum

The highest number allowed as input by the receiver.

Managing Leniency Behavior

lenient

Determines whether the receiver will use heuristics to guess at the number which is intended by a string.

Managing the Validation of Partial Numeric Strings

partialStringValidationEnabled

Determines whether partial string validation is enabled for the receiver.

Constants

NSNumberFormatterStyle

The predefined number format styles used by the numberStyle property.

NSNumberFormatterBehavior

These constants specify the behavior of a number formatter. These constants are returned by the defaultFormatterBehavior class method and the formatterBehavior property.

NSNumberFormatterPadPosition

These constants are used to specify how numbers should be padded. These constants are used by the paddingPosition property.

NSNumberFormatterRoundingMode

These constants are used to specify how numbers should be rounded. These constants are used by the roundingMode property.

Relationships

Inherits From

See Also

Numbers

NSInteger

Describes an integer.

NSUInteger

Describes an unsigned integer.

NSDecimal

A structure representing a base-10 number.

NSDecimalNumber

An object for representing and performing arithmetic on base-10 numbers.

NSNumber

An object wrapper for primitive scalar numeric values.