<!--
{
  "availability" : [
    "iOS: 2.0.0 -",
    "iPadOS: 2.0.0 -",
    "macCatalyst: 13.0.0 -",
    "macOS: 10.0.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/NumberFormatter",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "c:objc(cs)NSNumberFormatter"
  },
  "title" : "NumberFormatter"
}
-->

# NumberFormatter

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

```
class NumberFormatter
```

## Overview

Instances of [`NumberFormatter`](/documentation/Foundation/NumberFormatter) format the textual representation of cells that contain [`NSNumber`](/documentation/Foundation/NSNumber) objects and convert textual representations of numeric values into [`NSNumber`](/documentation/Foundation/NSNumber) objects. The representation encompasses integers, floats, and doubles; floats and doubles can be formatted to a specified decimal position. [`NumberFormatter`](/documentation/Foundation/NumberFormatter) objects can also impose ranges on the numeric values cells can accept.

> Tip:
> In Swift, you can use ``doc://com.apple.foundation/documentation/Foundation/IntegerFormatStyle``, ``doc://com.apple.foundation/documentation/Foundation/FloatingPointFormatStyle``, or ``doc://com.apple.foundation/documentation/Foundation/Decimal/FormatStyle`` rather than ``doc://com.apple.foundation/documentation/Foundation/NumberFormatter``. The ``doc://com.apple.foundation/documentation/Foundation/FormatStyle`` API offers a declarative idiom for customizing the formatting of various types. Also, Foundation caches identical ``doc://com.apple.foundation/documentation/Foundation/FormatStyle`` instances, so you don’t need to pass them around your app, or risk wasting memory with duplicate formatters.

### Significant Digits and Fraction Digits

The [`NumberFormatter`](/documentation/Foundation/NumberFormatter) class provides flexible options for displaying non-zero fractional parts of numbers.

If you set the [`usesSignificantDigits`](/documentation/Foundation/NumberFormatter/usesSignificantDigits) property to <doc://com.apple.documentation/documentation/Swift/true>, you can configure [`NumberFormatter`](/documentation/Foundation/NumberFormatter) to display significant digits using the [`minimumSignificantDigits`](/documentation/Foundation/NumberFormatter/minimumSignificantDigits) and [`maximumSignificantDigits`](/documentation/Foundation/NumberFormatter/maximumSignificantDigits) properties. If [`usesSignificantDigits`](/documentation/Foundation/NumberFormatter/usesSignificantDigits) is <doc://com.apple.documentation/documentation/Swift/false>, 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`](/documentation/Foundation/NumberFormatter/minimumIntegerDigits), [`maximumIntegerDigits`](/documentation/Foundation/NumberFormatter/maximumIntegerDigits), [`minimumFractionDigits`](/documentation/Foundation/NumberFormatter/minimumFractionDigits), and [`maximumFractionDigits`](/documentation/Foundation/NumberFormatter/maximumFractionDigits) properties. See Configuring Integer and Fraction Digits.

### Thread Safety

On iOS 7 and later [`NumberFormatter`](/documentation/Foundation/NumberFormatter) is thread-safe.

In macOS 10.9 and later [`NumberFormatter`](/documentation/Foundation/NumberFormatter) 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, [`NumberFormatter`](/documentation/Foundation/NumberFormatter) is not thread-safe, and you therefore must not mutate a number formatter simultaneously from multiple threads.

## Topics

### Configuring Formatter Behavior and Style

[`formatterBehavior`](/documentation/Foundation/NumberFormatter/formatterBehavior)

The formatter behavior of the receiver.

[`setDefaultFormatterBehavior(_:)`](/documentation/Foundation/NumberFormatter/setDefaultFormatterBehavior(_:))

Sets the default formatter behavior for new instances of `NSNumberFormatter` .

[`defaultFormatterBehavior()`](/documentation/Foundation/NumberFormatter/defaultFormatterBehavior())

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

[`numberStyle`](/documentation/Foundation/NumberFormatter/numberStyle)

The number style used by the receiver.

[`generatesDecimalNumbers`](/documentation/Foundation/NumberFormatter/generatesDecimalNumbers)

Determines whether the receiver creates instances of [`NSDecimalNumber`](/documentation/Foundation/NSDecimalNumber) when it converts strings to number objects.

### Converting Between Numbers and Strings

[`getObjectValue(_:for:range:)`](/documentation/Foundation/NumberFormatter/getObjectValue(_:for:range:))

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

[`number(from:)`](/documentation/Foundation/NumberFormatter/number(from:))

Returns an [`NSNumber`](/documentation/Foundation/NSNumber) object created by parsing a given string.

[`string(from:)`](/documentation/Foundation/NumberFormatter/string(from:))

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

[`localizedString(from:number:)`](/documentation/Foundation/NumberFormatter/localizedString(from:number:))

Returns a localized number string with the specified style.

### Managing Localization of Numbers

[`localizesFormat`](/documentation/Foundation/NumberFormatter/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`](/documentation/Foundation/NumberFormatter/locale)

The locale of the receiver.

### Configuring Rounding Behavior

[`roundingBehavior`](/documentation/Foundation/NumberFormatter/roundingBehavior)

The rounding behavior used by the receiver.

[`NSDecimalNumberHandler`](/documentation/Foundation/NSDecimalNumberHandler)

A class that adopts the decimal number behaviors protocol.

[`roundingIncrement`](/documentation/Foundation/NumberFormatter/roundingIncrement)

The rounding increment used by the receiver.

[`roundingMode`](/documentation/Foundation/NumberFormatter/roundingMode-swift.property)

The rounding mode used by the receiver.

### Configuring Integer and Fraction Digits

[`minimumIntegerDigits`](/documentation/Foundation/NumberFormatter/minimumIntegerDigits)

The minimum number of digits before the decimal separator.

[`maximumIntegerDigits`](/documentation/Foundation/NumberFormatter/maximumIntegerDigits)

The maximum number of digits before the decimal separator.

[`minimumFractionDigits`](/documentation/Foundation/NumberFormatter/minimumFractionDigits)

The minimum number of digits after the decimal separator.

[`maximumFractionDigits`](/documentation/Foundation/NumberFormatter/maximumFractionDigits)

The maximum number of digits after the decimal separator.

### Configuring Significant Digits

[`usesSignificantDigits`](/documentation/Foundation/NumberFormatter/usesSignificantDigits)

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

[`minimumSignificantDigits`](/documentation/Foundation/NumberFormatter/minimumSignificantDigits)

The minimum number of significant digits for the number formatter.

[`maximumSignificantDigits`](/documentation/Foundation/NumberFormatter/maximumSignificantDigits)

The maximum number of significant digits for the number formatter.

### Configuring Numeric Formats

[`format`](/documentation/Foundation/NumberFormatter/format)

The receiver’s format.

[`formattingContext`](/documentation/Foundation/NumberFormatter/formattingContext)

The capitalization formatting context used when formatting a number.

[`formatWidth`](/documentation/Foundation/NumberFormatter/formatWidth)

The format width used by the receiver.

[`negativeFormat`](/documentation/Foundation/NumberFormatter/negativeFormat)

The format the receiver uses to display negative values.

[`positiveFormat`](/documentation/Foundation/NumberFormatter/positiveFormat)

The format the receiver uses to display positive values.

[`multiplier`](/documentation/Foundation/NumberFormatter/multiplier)

The multiplier of the receiver.

### Configuring Numeric Symbols

[`percentSymbol`](/documentation/Foundation/NumberFormatter/percentSymbol)

The string used to represent a percent symbol.

[`perMillSymbol`](/documentation/Foundation/NumberFormatter/perMillSymbol)

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

[`minusSign`](/documentation/Foundation/NumberFormatter/minusSign)

The string used to represent a minus sign.

[`plusSign`](/documentation/Foundation/NumberFormatter/plusSign)

The string used to represent a plus sign.

[`exponentSymbol`](/documentation/Foundation/NumberFormatter/exponentSymbol)

The string used to represent an exponent symbol.

[`zeroSymbol`](/documentation/Foundation/NumberFormatter/zeroSymbol)

The string used to represent a zero value.

[`nilSymbol`](/documentation/Foundation/NumberFormatter/nilSymbol)

The string used to represent a `nil` value.

[`notANumberSymbol`](/documentation/Foundation/NumberFormatter/notANumberSymbol)

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

[`negativeInfinitySymbol`](/documentation/Foundation/NumberFormatter/negativeInfinitySymbol)

The string used to represent a negative infinity symbol.

[`positiveInfinitySymbol`](/documentation/Foundation/NumberFormatter/positiveInfinitySymbol)

The string used to represent a positive infinity symbol.

### Configuring the Format of Currency

[`currencySymbol`](/documentation/Foundation/NumberFormatter/currencySymbol)

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

[`currencyCode`](/documentation/Foundation/NumberFormatter/currencyCode)

The receiver’s currency code.

[`internationalCurrencySymbol`](/documentation/Foundation/NumberFormatter/internationalCurrencySymbol)

The international currency symbol used by the receiver.

[`currencyGroupingSeparator`](/documentation/Foundation/NumberFormatter/currencyGroupingSeparator)

The currency grouping separator for the receiver.

### Configuring Numeric Prefixes and Suffixes

[`positivePrefix`](/documentation/Foundation/NumberFormatter/positivePrefix)

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

[`positiveSuffix`](/documentation/Foundation/NumberFormatter/positiveSuffix)

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

[`negativePrefix`](/documentation/Foundation/NumberFormatter/negativePrefix)

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

[`negativeSuffix`](/documentation/Foundation/NumberFormatter/negativeSuffix)

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

### Configuring the Display of Numeric Values

[`textAttributesForNegativeValues`](/documentation/Foundation/NumberFormatter/textAttributesForNegativeValues)

The text attributes to be used in displaying negative values.

[`textAttributesForPositiveValues`](/documentation/Foundation/NumberFormatter/textAttributesForPositiveValues)

The text attributes to be used in displaying positive values.

[`attributedStringForZero`](/documentation/Foundation/NumberFormatter/attributedStringForZero)

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

[`textAttributesForZero`](/documentation/Foundation/NumberFormatter/textAttributesForZero)

The text attributes used to display a zero value.

[`attributedStringForNil`](/documentation/Foundation/NumberFormatter/attributedStringForNil)

The attributed string the receiver uses to display `nil` values.

[`textAttributesForNil`](/documentation/Foundation/NumberFormatter/textAttributesForNil)

The text attributes used to display the `nil` symbol.

[`attributedStringForNotANumber`](/documentation/Foundation/NumberFormatter/attributedStringForNotANumber)

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

[`textAttributesForNotANumber`](/documentation/Foundation/NumberFormatter/textAttributesForNotANumber)

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

[`textAttributesForPositiveInfinity`](/documentation/Foundation/NumberFormatter/textAttributesForPositiveInfinity)

The text attributes used to display the positive infinity symbol.

[`textAttributesForNegativeInfinity`](/documentation/Foundation/NumberFormatter/textAttributesForNegativeInfinity)

The text attributes used to display the negative infinity symbol.

### Configuring Separators and Grouping Size

[`groupingSeparator`](/documentation/Foundation/NumberFormatter/groupingSeparator)

The string used by the receiver for a grouping separator.

[`usesGroupingSeparator`](/documentation/Foundation/NumberFormatter/usesGroupingSeparator)

Determines whether the receiver displays the group separator.

[`thousandSeparator`](/documentation/Foundation/NumberFormatter/thousandSeparator)

The character the receiver uses as a thousand separator.

[`hasThousandSeparators`](/documentation/Foundation/NumberFormatter/hasThousandSeparators)

Determines whether the receiver uses thousand separators.

[`decimalSeparator`](/documentation/Foundation/NumberFormatter/decimalSeparator)

The character the receiver uses as a decimal separator.

[`alwaysShowsDecimalSeparator`](/documentation/Foundation/NumberFormatter/alwaysShowsDecimalSeparator)

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

[`currencyDecimalSeparator`](/documentation/Foundation/NumberFormatter/currencyDecimalSeparator)

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

[`groupingSize`](/documentation/Foundation/NumberFormatter/groupingSize)

The grouping size of the receiver.

[`secondaryGroupingSize`](/documentation/Foundation/NumberFormatter/secondaryGroupingSize)

The secondary grouping size of the receiver.

### Managing the Padding of Numbers

[`paddingCharacter`](/documentation/Foundation/NumberFormatter/paddingCharacter)

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

[`paddingPosition`](/documentation/Foundation/NumberFormatter/paddingPosition)

The padding position used by the receiver.

### Managing Input and Output Attributes

[`allowsFloats`](/documentation/Foundation/NumberFormatter/allowsFloats)

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

[`minimum`](/documentation/Foundation/NumberFormatter/minimum)

The lowest number allowed as input by the receiver.

[`maximum`](/documentation/Foundation/NumberFormatter/maximum)

The highest number allowed as input by the receiver.

### Managing Leniency Behavior

[`isLenient`](/documentation/Foundation/NumberFormatter/isLenient)

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

[`isPartialStringValidationEnabled`](/documentation/Foundation/NumberFormatter/isPartialStringValidationEnabled)

Determines whether partial string validation is enabled for the receiver.

### Constants

[`NumberFormatter.Style`](/documentation/Foundation/NumberFormatter/Style)

The predefined number format styles used by the [`numberStyle`](/documentation/Foundation/NumberFormatter/numberStyle) property.

[`NumberFormatter.Behavior`](/documentation/Foundation/NumberFormatter/Behavior)

These constants specify the behavior of a number formatter. These constants are returned by the [`defaultFormatterBehavior()`](/documentation/Foundation/NumberFormatter/defaultFormatterBehavior()) class method and the [`formatterBehavior`](/documentation/Foundation/NumberFormatter/formatterBehavior) property.

[`NumberFormatter.PadPosition`](/documentation/Foundation/NumberFormatter/PadPosition)

These constants are used to specify how numbers should be padded. These constants are used by the [`paddingPosition`](/documentation/Foundation/NumberFormatter/paddingPosition) property.

[`NumberFormatter.RoundingMode`](/documentation/Foundation/NumberFormatter/RoundingMode-swift.enum)

These constants are used to specify how numbers should be rounded. These constants are used by the [`roundingMode`](/documentation/Foundation/NumberFormatter/roundingMode-swift.property) property.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)