iOS Developer Library

Developer

Foundation Framework Reference NSNumberFormatter Class Reference

Options
Deployment Target:

On This Page
Language:

NSNumberFormatter

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.

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 YEStrue, you can configure NSNumberFormatter to display significant digits using the minimumSignificantDigits and maximumSignificantDigits properties. If usesSignificantDigits is NOfalse, 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.

OS X 10.4 Formatting Behavior

Many new methods were added to NSNumberFormatter for 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 OS X v10.4 or to the range of behavior since that release. (Methods added for and since OS X v10.4 are indicated by a method’s availability statement.) You can get and set the current formatter behavior with the formatterBehavior property.

Thread Safety

On iOS 7 and later NSNumberFormatter is thread safe.

On OS X 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 on OS X, NSNumberFormatter is not thread safe, and you therefore must not mutate a number formatter simultaneously from multiple threads.

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

    Declaration

    Swift

    func getObjectValue(_ obj: AutoreleasingUnsafeMutablePointer<AnyObject?>, forString string: String, range rangep: UnsafeMutablePointer<NSRange>) throws

    Objective-C

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

    Parameters

    anObject

    On return, contains an instance of NSDecimalNumber or NSNumber based on the current value of the generatesDecimalNumbers property. Returns nil by reference if conversion failed.

    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 in the NSCocoaErrorDomain with code NSFormattingError that explains why the conversion failed. If you pass in nil for error you are indicating that you are not interested in error information.

    Return Value

    YEStrue if the conversion from string to cell-content object was successful, otherwise NOfalse.

    Discussion

    If a string contains any characters other than numerical digits or locale-appropriate group or decimal separators, parsing will fail.

    Any leading or trailing space separator characters in a string are ignored. For example, the strings “ 5”, “5 ”, and “5” all produce the number 5.

    If there is an error, this method calls control:didFailToFormatString:errorDescription: on the delegate.

    Availability

    Available in iOS 2.0 and later.

  • Returns an NSNumber object created by parsing a given string.

    Declaration

    Swift

    func numberFromString(_ string: String) -> NSNumber?

    Objective-C

    - (NSNumber *)numberFromString:(NSString *)string

    Parameters

    string

    An NSString object that is parsed to generate the returned number object.

    Return Value

    An NSNumber object created by parsing string using the receiver’s format, or nil if no single number could be parsed.

    Discussion

    If a string contains any characters other than numerical digits or locale-appropriate group or decimal separators, parsing will fail.

    Any leading or trailing space separator characters in a string are ignored. For example, the strings “ 5”, “5 ”, and “5” all produce the number 5.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func stringFromNumber(_ number: NSNumber) -> String?

    Objective-C

    - (NSString *)stringFromNumber:(NSNumber *)number

    Parameters

    number

    An NSNumber object that is parsed to create the returned string object.

    Return Value

    A string containing the formatted value of number using the receiver’s current settings.

    Availability

    Available in iOS 2.0 and later.

  • Returns a localized number string with the specified style.

    Declaration

    Swift

    class func localizedStringFromNumber(_ num: NSNumber, numberStyle nstyle: NSNumberFormatterStyle) -> String

    Objective-C

    + (NSString *)localizedStringFromNumber:(NSNumber *)num numberStyle:(NSNumberFormatterStyle)localizationStyle

    Parameters

    num

    The number to localize

    localizationStyle

    The localization style to use. See NSNumberFormatterStyle for the supported values.

    Return Value

    An appropriately formatted NSString.

    Availability

    Available in iOS 4.0 and later.

  • The locale of the receiver.

    Declaration

    Swift

    @NSCopying var locale: NSLocale!

    Objective-C

    @property(copy) NSLocale *locale

    Discussion

    The locale determines the default values for many formatter attributes, such as ISO country and language codes, currency code, calendar, system of measurement, and decimal separator.

    Availability

    Available in iOS 2.0 and later.

  • The capitalization formatting context used when formatting a number.

    Declaration

    Swift

    var formattingContext: NSFormattingContext

    Objective-C

    @property NSFormattingContext formattingContext

    Discussion

    Defaults to NSFormattingContextUnknown.

    Availability

    Available in iOS 8.0 and later.

  • The format width used by the receiver.

    Declaration

    Swift

    var formatWidth: Int

    Objective-C

    @property 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 contained in paddingPosition.

    Availability

    Available in iOS 2.0 and later.

  • The format the receiver uses to display negative values.

    Declaration

    Swift

    var negativeFormat: String!

    Objective-C

    @property(copy) NSString *negativeFormat

    Availability

    Available in iOS 2.0 and later.

  • The format the receiver uses to display positive values.

    Declaration

    Swift

    var positiveFormat: String!

    Objective-C

    @property(copy) NSString *positiveFormat

    Availability

    Available in iOS 2.0 and later.

  • The multiplier of the receiver.

    Declaration

    Swift

    @NSCopying var multiplier: NSNumber?

    Objective-C

    @property(copy) NSNumber *multiplier

    Discussion

    A multiplier is a factor used in conversions between numbers and strings (that is, numbers as stored and numbers as displayed). When the input value is a string, the multiplier is used to divide, and when the input value is a number, the multiplier is used to multiply. These operations allow the formatted values to be different from the values that a program manipulates internally.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var percentSymbol: String!

    Objective-C

    @property(copy) NSString *percentSymbol

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var perMillSymbol: String!

    Objective-C

    @property(copy) NSString *perMillSymbol

    Availability

    Available in iOS 2.0 and later.

  • The string used by the receiver for the minus sign.

    Declaration

    Swift

    var minusSign: String!

    Objective-C

    @property(copy) NSString *minusSign

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var plusSign: String!

    Objective-C

    @property(copy) NSString *plusSign

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var exponentSymbol: String!

    Objective-C

    @property(copy) NSString *exponentSymbol

    Discussion

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

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var zeroSymbol: String?

    Objective-C

    @property(copy) NSString *zeroSymbol

    Discussion

    By default this is 0; you might want to set it to, for example, “ - ”, similar to the way that a spreadsheet might when a column is defined as accounting.

    Availability

    Available in iOS 2.0 and later.

  • The string the receiver uses to represent nil values.

    Declaration

    Swift

    var nilSymbol: String

    Objective-C

    @property(copy) NSString *nilSymbol

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var notANumberSymbol: String!

    Objective-C

    @property(copy) NSString *notANumberSymbol

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var negativeInfinitySymbol: String

    Objective-C

    @property(copy) NSString *negativeInfinitySymbol

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var positiveInfinitySymbol: String

    Objective-C

    @property(copy) NSString *positiveInfinitySymbol

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var currencySymbol: String!

    Objective-C

    @property(copy) 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 iOS 2.0 and later.

  • The receiver’s currency code.

    Declaration

    Swift

    var currencyCode: String!

    Objective-C

    @property(copy) NSString *currencyCode

    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 iOS 2.0 and later.

  • The international currency symbol used by the receiver.

    Declaration

    Swift

    var internationalCurrencySymbol: String!

    Objective-C

    @property(copy) 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 iOS 2.0 and later.

  • The currency grouping separator for the receiver.

    Declaration

    Swift

    var currencyGroupingSeparator: String!

    Objective-C

    @property(copy) NSString *currencyGroupingSeparator

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var positivePrefix: String!

    Objective-C

    @property(copy) NSString *positivePrefix

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var positiveSuffix: String!

    Objective-C

    @property(copy) NSString *positiveSuffix

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var negativePrefix: String!

    Objective-C

    @property(copy) NSString *negativePrefix

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var negativeSuffix: String!

    Objective-C

    @property(copy) NSString *negativeSuffix

    Availability

    Available in iOS 2.0 and later.

  • The string used by the receiver for a grouping separator.

    Declaration

    Swift

    var groupingSeparator: String!

    Objective-C

    @property(copy) NSString *groupingSeparator

    Discussion

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

    Availability

    Available in iOS 2.0 and later.

  • Determines whether the receiver displays the group separator.

    Declaration

    Swift

    var usesGroupingSeparator: Bool

    Objective-C

    @property BOOL usesGroupingSeparator

    Availability

    Available in iOS 2.0 and later.

  • The character the receiver uses as a decimal separator.

    Declaration

    Swift

    var decimalSeparator: String!

    Objective-C

    @property(copy) NSString *decimalSeparator

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var alwaysShowsDecimalSeparator: Bool

    Objective-C

    @property BOOL alwaysShowsDecimalSeparator

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var currencyDecimalSeparator: String!

    Objective-C

    @property(copy) NSString *currencyDecimalSeparator

    Availability

    Available in iOS 2.0 and later.

  • The grouping size of the receiver.

    Declaration

    Swift

    var groupingSize: Int

    Objective-C

    @property NSUInteger groupingSize

    Availability

    Available in iOS 2.0 and later.

  • The secondary grouping size of the receiver.

    Declaration

    Swift

    var secondaryGroupingSize: Int

    Objective-C

    @property NSUInteger secondaryGroupingSize

    Discussion

    Some locales allow the specification of another grouping size for larger numbers. For example, some locales may represent a number such as 61, 242, 378.46 (as in the United States) as 6,12,42,378.46. In this case, the secondary grouping size (covering the groups of digits furthest from the decimal point) is 2.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var allowsFloats: Bool

    Objective-C

    @property BOOL allowsFloats

    Discussion

    By default, floating point values are allowed.

    Availability

    Available in iOS 2.0 and later.

  • The lowest number allowed as input by the receiver.

    Declaration

    Swift

    @NSCopying var minimum: NSNumber?

    Objective-C

    @property(copy) NSNumber *minimum

    Availability

    Available in iOS 2.0 and later.

  • The highest number allowed as input by the receiver.

    Declaration

    Swift

    @NSCopying var maximum: NSNumber?

    Objective-C

    @property(copy) NSNumber *maximum

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var lenient: Bool

    Objective-C

    @property(getter=isLenient) BOOL lenient

    Discussion

    If the formatter is set to be lenient, as with any guessing it may get the result number wrong (that is, a number other than that which was intended).

    Availability

    Available in iOS 2.0 and later.

  • Determines whether partial string validation is enabled for the receiver.

    Declaration

    Swift

    var partialStringValidationEnabled: Bool

    Objective-C

    @property(getter=isPartialStringValidationEnabled) BOOL partialStringValidationEnabled

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    enum NSNumberFormatterStyle : UInt { case NoStyle case DecimalStyle case CurrencyStyle case PercentStyle case ScientificStyle case SpellOutStyle case OrdinalStyle case CurrencyISOCodeStyle case CurrencyPluralStyle case CurrencyAccountingStyle }

    Objective-C

    enum { NSNumberFormatterNoStyle = kCFNumberFormatterNoStyle, NSNumberFormatterDecimalStyle = kCFNumberFormatterDecimalStyle, NSNumberFormatterCurrencyStyle = kCFNumberFormatterCurrencyStyle, NSNumberFormatterPercentStyle = kCFNumberFormatterPercentStyle, NSNumberFormatterScientificStyle = kCFNumberFormatterScientificStyle, NSNumberFormatterSpellOutStyle = kCFNumberFormatterSpellOutStyle NSNumberFormatterOrdinalStyle NS_ENUM_AVAILABLE (10_11, 9_0) = kCFNumberFormatterOrdinalStyle, NSNumberFormatterCurrencyISOCodeStyle NS_ENUM_AVAILABLE (10_11, 9_0) = kCFNumberFormatterCurrencyISOCodeStyle, NSNumberFormatterCurrencyPluralStyle NS_ENUM_AVAILABLE (10_11, 9_0) = kCFNumberFormatterCurrencyPluralStyle, NSNumberFormatterCurrencyAccountingStyle NS_ENUM_AVAILABLE (10_11, 9_0) = kCFNumberFormatterCurrencyAccountingStyle, }; typedef NSUInteger NSNumberFormatterStyle;

    Constants

    • NoStyle

      NSNumberFormatterNoStyle

      Specifies no style, such that an integer representation is used; for example, 1234.5678 is represented as “1235”.

      Available in iOS 2.0 and later.

    • DecimalStyle

      NSNumberFormatterDecimalStyle

      Specifies a decimal style format; for example, 1234.5678 is represented as “1234.5678”.

      Available in iOS 2.0 and later.

    • CurrencyStyle

      NSNumberFormatterCurrencyStyle

      Specifies a currency style format; for example, in the en_US_POSIX locale, 1234.5678 is represented as “$ 1234.57”.

      Available in iOS 2.0 and later.

    • PercentStyle

      NSNumberFormatterPercentStyle

      Specifies a percent style format; for example, 1234.5678 is represented as “123457%”.

      Available in iOS 2.0 and later.

    • ScientificStyle

      NSNumberFormatterScientificStyle

      Specifies a scientific style format; for example, 1234.5678 is represented as “1.234568E+003”.

      Available in iOS 2.0 and later.

    • SpellOutStyle

      NSNumberFormatterSpellOutStyle

      Specifies a spell-out format; for example, 1234.5678 is represented as “one thousand two hundred thirty-four point five six seven eight”.

      Available in iOS 2.0 and later.

    • OrdinalStyle

      NSNumberFormatterOrdinalStyle

      Specifies an ordinal format; for example, in the en_US_POSIX locale, 1234.5678 is represented as “1,235th”

      Available in iOS 9.0 and later.

    • CurrencyISOCodeStyle

      NSNumberFormatterCurrencyISOCodeStyle

      Specifies a currency style format using ISO 4217 currency codes; for example, in the en_US_POSIX locale, 1234.5678 is represented as “USD 1234.57”.

      Available in iOS 9.0 and later.

    • CurrencyPluralStyle

      NSNumberFormatterCurrencyPluralStyle

      Specifies a currency style format, using pluralized denominations; for example, in the en_US_POSIX locale, 1234.5678 is represented as “1234.57 US dollars”.

      Available in iOS 9.0 and later.

    • CurrencyAccountingStyle

      NSNumberFormatterCurrencyAccountingStyle

      Specifies a currency style format; for example, in the en_US_POSIX locale, 1234.5678 is represented as “$1234.57”. Unlike NSNumberFormatterCurrencyStyle, negative numbers representations are surrounded by parentheses rather than preceded by a negative symbol; for example, in the en_US_POSIX locale, -1234.5678 is represented as “($1,234.57)”.

      Available in iOS 9.0 and later.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    enum NSNumberFormatterBehavior : UInt { case BehaviorDefault case Behavior10_4 }

    Objective-C

    enum { NSNumberFormatterBehaviorDefault = 0, NSNumberFormatterBehavior10_0 = 1000, NSNumberFormatterBehavior10_4 = 1040, }; typedef NSUInteger NSNumberFormatterBehavior;

    Constants

    • BehaviorDefault

      NSNumberFormatterBehaviorDefault

      The number-formatter behavior set as the default for new instances. You can set the default formatter behavior with the class method setDefaultFormatterBehavior:.

      Available in iOS 2.0 and later.

    • NSNumberFormatterBehavior10_0

      The number-formatter behavior as it existed prior to OS X v10.4.

      Available in iOS 2.0 through iOS 2.1.

    • Behavior10_4

      NSNumberFormatterBehavior10_4

      The number-formatter behavior since OS X v10.4.

      Available in iOS 2.0 and later.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    enum NSNumberFormatterPadPosition : UInt { case BeforePrefix case AfterPrefix case BeforeSuffix case AfterSuffix }

    Objective-C

    enum { NSNumberFormatterPadBeforePrefix = kCFNumberFormatterPadBeforePrefix, NSNumberFormatterPadAfterPrefix = kCFNumberFormatterPadAfterPrefix, NSNumberFormatterPadBeforeSuffix = kCFNumberFormatterPadBeforeSuffix, NSNumberFormatterPadAfterSuffix = kCFNumberFormatterPadAfterSuffix }; typedef NSUInteger NSNumberFormatterPadPosition;

    Constants

    • BeforePrefix

      NSNumberFormatterPadBeforePrefix

      Specifies that the padding should occur before the prefix.

      Available in iOS 2.0 and later.

    • AfterPrefix

      NSNumberFormatterPadAfterPrefix

      Specifies that the padding should occur after the prefix.

      Available in iOS 2.0 and later.

    • BeforeSuffix

      NSNumberFormatterPadBeforeSuffix

      Specifies that the padding should occur before the suffix.

      Available in iOS 2.0 and later.

    • AfterSuffix

      NSNumberFormatterPadAfterSuffix

      Specifies that the padding should occur after the suffix.

      Available in iOS 2.0 and later.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    enum NSNumberFormatterRoundingMode : UInt { case RoundCeiling case RoundFloor case RoundDown case RoundUp case RoundHalfEven case RoundHalfDown case RoundHalfUp }

    Objective-C

    enum { NSNumberFormatterRoundCeiling = kCFNumberFormatterRoundCeiling, NSNumberFormatterRoundFloor = kCFNumberFormatterRoundFloor, NSNumberFormatterRoundDown = kCFNumberFormatterRoundDown, NSNumberFormatterRoundUp = kCFNumberFormatterRoundUp, NSNumberFormatterRoundHalfEven = kCFNumberFormatterRoundHalfEven, NSNumberFormatterRoundHalfDown = kCFNumberFormatterRoundHalfDown, NSNumberFormatterRoundHalfUp = kCFNumberFormatterRoundHalfUp }; typedef NSUInteger NSNumberFormatterRoundingMode;

    Constants

    • RoundCeiling

      NSNumberFormatterRoundCeiling

      Round towards positive infinity.

      Available in iOS 2.0 and later.

    • RoundFloor

      NSNumberFormatterRoundFloor

      Round towards negative infinity.

      Available in iOS 2.0 and later.

    • RoundDown

      NSNumberFormatterRoundDown

      Round towards zero.

      Available in iOS 2.0 and later.

    • RoundUp

      NSNumberFormatterRoundUp

      Round away from zero.

      Available in iOS 2.0 and later.

    • RoundHalfEven

      NSNumberFormatterRoundHalfEven

      Round towards the nearest integer, or towards an even number if equidistant.

      Available in iOS 2.0 and later.

    • RoundHalfDown

      NSNumberFormatterRoundHalfDown

      Round towards the nearest integer, or towards zero if equidistant.

      Available in iOS 2.0 and later.

    • RoundHalfUp

      NSNumberFormatterRoundHalfUp

      Round towards the nearest integer, or away from zero if equidistant.

      Available in iOS 2.0 and later.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.