Class

Number​Formatter

Instances of NSNumber​Formatter 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. NSNumber​Formatter objects can also impose ranges on the numeric values cells can accept.

Overview

Fraction Digits and Significant Digits

The NSNumber​Formatter class provides flexible options for displaying non-zero fractional parts of numbers.

If you set the uses​Significant​Digits property to true, you can configure NSNumber​Formatter to display significant digits using the minimum​Significant​Digits and maximum​Significant​Digits properties. If uses​Significant​Digits 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 minimum​Integer​Digits, maximum​Integer​Digits, minimum​Fraction​Digits, and maximum​Fraction​Digits properties.

Thread Safety

On iOS 7 and later NSNumber​Formatter is thread safe.

In macOS 10.9 and later NSNumber​Formatter 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, NSNumber​Formatter is not thread safe, and you therefore must not mutate a number formatter simultaneously from multiple threads.

Nested Types

Number​Formatter.Behavior

These constants specify the behavior of a number formatter. These constants are returned by the default​Formatter​Behavior() class method and the formatter​Behavior property.

Number​Formatter.Style

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

Number​Formatter.Rounding​Mode

These constants are used to specify how numbers should be rounded. These constants are used by the rounding​Mode property.

Number​Formatter.Pad​Position

These constants are used to specify how numbers should be padded. These constants are used by the padding​Position property.

Symbols

Configuring Formatter Behavior and Style

var formatter​Behavior:​ Number​Formatter.Behavior

The formatter behavior of the receiver.

class func set​Default​Formatter​Behavior(Number​Formatter.Behavior)

Sets the default formatter behavior for new instances of NSNumber​Formatter .

class func default​Formatter​Behavior()

Returns an NSNumber​Formatter​Behavior constant that indicates default formatter behavior for new instances of NSNumber​Formatter.

var number​Style:​ Number​Formatter.Style

The number style used by the receiver.

var generates​Decimal​Numbers:​ Bool

Determines whether the receiver creates instances of NSDecimal​Number when it converts strings to number objects.

Converting Between Numbers and Strings

func get​Object​Value(Autoreleasing​Unsafe​Mutable​Pointer<Any​Object?>?, for:​ String, range:​ Unsafe​Mutable​Pointer<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 localized​String(from:​ NSNumber, number:​ Number​Formatter.Style)

Returns a localized number string with the specified style.

Managing Localization of Numbers

var localizes​Format:​ 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 rounding​Behavior:​ NSDecimal​Number​Handler

The rounding behavior used by the receiver.

var rounding​Increment:​ NSNumber!

The rounding increment used by the receiver.

var rounding​Mode:​ Number​Formatter.Rounding​Mode

The rounding mode used by the receiver.

Configuring Numeric Formats

var format:​ String

The receiver’s format.

var formatting​Context:​ Formatter.Context

The capitalization formatting context used when formatting a number.

var format​Width:​ Int

The format width used by the receiver.

var negative​Format:​ String!

The format the receiver uses to display negative values.

var positive​Format:​ String!

The format the receiver uses to display positive values.

var multiplier:​ NSNumber?

The multiplier of the receiver.

Configuring Numeric Symbols

var percent​Symbol:​ String!

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

var per​Mill​Symbol:​ String!

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

var minus​Sign:​ String!

The string used by the receiver for the minus sign.

var plus​Sign:​ String!

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

var exponent​Symbol:​ String!

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

var zero​Symbol:​ String?

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

var nil​Symbol:​ String

The string the receiver uses to represent nil values.

var not​ANumber​Symbol:​ String!

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

var negative​Infinity​Symbol:​ String

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

var positive​Infinity​Symbol:​ String

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

Configuring the Format of Currency

var currency​Symbol:​ String!

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

var currency​Code:​ String!

The receiver’s currency code.

var international​Currency​Symbol:​ String!

The international currency symbol used by the receiver.

var currency​Grouping​Separator:​ String!

The currency grouping separator for the receiver.

Configuring Numeric Prefixes and Suffixes

var positive​Prefix:​ String!

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

var positive​Suffix:​ String!

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

var negative​Prefix:​ String!

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

var negative​Suffix:​ String!

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

Configuring the Display of Numeric Values

var text​Attributes​For​Negative​Values:​ [String :​ Any]?

The text attributes to be used in displaying negative values.

var text​Attributes​For​Positive​Values:​ [String :​ Any]?

The text attributes to be used in displaying positive values.

var attributed​String​For​Zero:​ NSAttributed​String

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

var text​Attributes​For​Zero:​ [String :​ Any]?

The text attributes used to display a zero value.

var attributed​String​For​Nil:​ NSAttributed​String

The attributed string the receiver uses to display nil values.

var text​Attributes​For​Nil:​ [String :​ Any]?

The text attributes used to display the nil symbol.

var attributed​String​For​Not​ANumber:​ NSAttributed​String

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

var text​Attributes​For​Not​ANumber:​ [String :​ Any]?

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

var text​Attributes​For​Positive​Infinity:​ [String :​ Any]?

The text attributes used to display the positive infinity symbol.

var text​Attributes​For​Negative​Infinity:​ [String :​ Any]?

The text attributes used to display the negative infinity symbol.

Configuring Separators and Grouping Size

var grouping​Separator:​ String!

The string used by the receiver for a grouping separator.

var uses​Grouping​Separator:​ Bool

Determines whether the receiver displays the group separator.

var thousand​Separator:​ String!

The character the receiver uses as a thousand separator.

var has​Thousand​Separators:​ Bool

Determines whether the receiver uses thousand separators.

var decimal​Separator:​ String!

The character the receiver uses as a decimal separator.

var always​Shows​Decimal​Separator:​ Bool

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

var currency​Decimal​Separator:​ String!

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

var grouping​Size:​ Int

The grouping size of the receiver.

var secondary​Grouping​Size:​ Int

The secondary grouping size of the receiver.

Managing the Padding of Numbers

var padding​Character:​ String!

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

var padding​Position:​ Number​Formatter.Pad​Position

The padding position used by the receiver.

Managing Input and Output Attributes

var allows​Floats:​ 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 minimum​Integer​Digits:​ Int

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

var maximum​Integer​Digits:​ Int

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

var minimum​Fraction​Digits:​ Int

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

var maximum​Fraction​Digits:​ Int

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

Configuring Significant Digits

var uses​Significant​Digits:​ Bool

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

var minimum​Significant​Digits:​ Int

The minimum number of significant digits for the receiver.

var maximum​Significant​Digits:​ Int

The maximum number of significant digits for the receiver.

Managing Leniency Behavior

var is​Lenient:​ 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 is​Partial​String​Validation​Enabled:​ Bool

Determines whether partial string validation is enabled for the receiver.

Constants

Number​Formatter.Style

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

Number​Formatter.Behavior

These constants specify the behavior of a number formatter. These constants are returned by the default​Formatter​Behavior() class method and the formatter​Behavior property.

Number​Formatter.Pad​Position

These constants are used to specify how numbers should be padded. These constants are used by the padding​Position property.

Number​Formatter.Rounding​Mode

These constants are used to specify how numbers should be rounded. These constants are used by the rounding​Mode property.

Relationships

Inherits From