Class

NumberFormatter

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.

Overview

Fraction Digits and Significant Digits

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

If you set the usesSignificantDigits property to true, you can configure NSNumberFormatter to display significant digits using the minimumSignificantDigits and maximumSignificantDigits properties. If usesSignificantDigits is false, these properties are ignored.

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.

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.

Nested Types

NSNumberFormatterBehavior

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

NSNumberFormatterStyle

These constants specify predefined number format styles. These constants are used by the numberStyle property.

NSNumberFormatterRoundingMode

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

NSNumberFormatterPadPosition

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

Symbols

Configuring Formatter Behavior and Style

var formatterBehavior: NumberFormatter.Behavior

The formatter behavior of the receiver.

class func setDefaultFormatterBehavior(NumberFormatter.Behavior)

Sets the default formatter behavior for new instances of NSNumberFormatter .

class func defaultFormatterBehavior()

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

var numberStyle: NumberFormatter.Style

The number style used by the receiver.

var generatesDecimalNumbers: Bool

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

Converting Between Numbers and Strings

func getObjectValue(AutoreleasingUnsafeMutablePointer<AnyObject?>?, for: String, range: UnsafeMutablePointer<NSRange>?)

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

func number(from: String)

Returns an NSNumber object created by parsing a given string.

func string(from: NSNumber)

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

class func localizedString(from: NSNumber, number: NumberFormatter.Style)

Returns a localized number string with the specified style.

Managing Localization of Numbers

var localizesFormat: Bool

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.

var locale: Locale!

The locale of the receiver.

Configuring Rounding Behavior

var roundingBehavior: NSDecimalNumberHandler

The rounding behavior used by the receiver.

var roundingIncrement: NSNumber!

The rounding increment used by the receiver.

var roundingMode: NumberFormatter.RoundingMode

The rounding mode used by the receiver.

Configuring Numeric Formats

var format: String

The receiver’s format.

var formattingContext: Formatter.Context

The capitalization formatting context used when formatting a number.

var formatWidth: Int

The format width used by the receiver.

var negativeFormat: String!

The format the receiver uses to display negative values.

var positiveFormat: String!

The format the receiver uses to display positive values.

var multiplier: NSNumber?

The multiplier of the receiver.

Configuring Numeric Symbols

var percentSymbol: String!

The string used by the receiver to represent the percent symbol.

var perMillSymbol: String!

The string used by the receiver to represent the per-mill (per-thousand) symbol.

var minusSign: String!

The string used by the receiver for the minus sign.

var plusSign: String!

The string used by the receiver to represent the plus sign.

var exponentSymbol: String!

The string used by the receiver to represent the exponent symbol.

var zeroSymbol: String?

The string the receiver uses as the symbol to show the value zero.

var nilSymbol: String

The string the receiver uses to represent nil values.

var notANumberSymbol: String!

The string the receiver uses to represent NaN (“not a number”).

var negativeInfinitySymbol: String

The string used by the receiver for the negative infinity symbol.

var positiveInfinitySymbol: String

The string used by the receiver for the positive infinity symbol.

Configuring the Format of Currency

var currencySymbol: String!

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

var currencyCode: String!

The receiver’s currency code.

var internationalCurrencySymbol: String!

The international currency symbol used by the receiver.

var currencyGroupingSeparator: String!

The currency grouping separator for the receiver.

Configuring Numeric Prefixes and Suffixes

var positivePrefix: String!

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

var positiveSuffix: String!

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

var negativePrefix: String!

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

var negativeSuffix: String!

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

Configuring the Display of Numeric Values

var textAttributesForNegativeValues: [String : Any]?

The text attributes to be used in displaying negative values.

var textAttributesForPositiveValues: [String : Any]?

The text attributes to be used in displaying positive values.

var attributedStringForZero: NSAttributedString

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

var textAttributesForZero: [String : Any]?

The text attributes used to display a zero value.

var attributedStringForNil: NSAttributedString

The attributed string the receiver uses to display nil values.

var textAttributesForNil: [String : Any]?

The text attributes used to display the nil symbol.

var attributedStringForNotANumber: NSAttributedString

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

var textAttributesForNotANumber: [String : Any]?

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

var textAttributesForPositiveInfinity: [String : Any]?

The text attributes used to display the positive infinity symbol.

var textAttributesForNegativeInfinity: [String : Any]?

The text attributes used to display the negative infinity symbol.

Configuring Separators and Grouping Size

var groupingSeparator: String!

The string used by the receiver for a grouping separator.

var usesGroupingSeparator: Bool

Determines whether the receiver displays the group separator.

var thousandSeparator: String!

The character the receiver uses as a thousand separator.

var hasThousandSeparators: Bool

Determines whether the receiver uses thousand separators.

var decimalSeparator: String!

The character the receiver uses as a decimal separator.

var alwaysShowsDecimalSeparator: Bool

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

var currencyDecimalSeparator: String!

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

var groupingSize: Int

The grouping size of the receiver.

var secondaryGroupingSize: Int

The secondary grouping size of the receiver.

Managing the Padding of Numbers

var paddingCharacter: String!

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

var paddingPosition: NumberFormatter.PadPosition

The padding position used by the receiver.

Managing Input and Output Attributes

var allowsFloats: Bool

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

var minimum: NSNumber?

The lowest number allowed as input by the receiver.

var maximum: NSNumber?

The highest number allowed as input by the receiver.

Configuring Integer and Fraction Digits

var minimumIntegerDigits: Int

The number of integer digits allowed as input and output by the receiver.

var maximumIntegerDigits: Int

The maximum number of integer digits allowed as input and output by the receiver.

var minimumFractionDigits: Int

The minimum number of digits after the decimal separator allowed as input and output by the receiver.

var maximumFractionDigits: Int

The maximum number of digits after the decimal separator allowed as input and output by the receiver.

Configuring Significant Digits

var usesSignificantDigits: Bool

Determines whether the receiver uses minimum and maximum significant digits properties.

var minimumSignificantDigits: Int

The minimum number of significant digits for the receiver.

var maximumSignificantDigits: Int

The maximum number of significant digits for the receiver.

Managing Leniency Behavior

var isLenient: Bool

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

var isPartialStringValidationEnabled: Bool

Determines whether partial string validation is enabled for the receiver.

Constants

NumberFormatter.Style