Mac 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.

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 determine the current formatter behavior with the formatterBehavior method and you can set the formatter behavior with the setFormatterBehavior: method.

Nomenclature note: NSNumberFormatter provides several methods (such as setMaximumFractionDigits:) that allow you to manage the number of fraction digits allowed as input by an instance: “fraction digits” are the numbers after the decimal separator (in English locales typically referred to as the “decimal point”).

  • 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.

    Declaration

    Swift

    var localizesFormat: Bool

    Objective-C

    @property BOOL localizesFormat

    Discussion

    While the currency-symbol part of this feature may be useful in certain types of applications, it’s probably more likely that you would tie a particular application to a particular currency (that is, that you would “hard-code” the currency symbol and separators instead of having them dynamically change based on the user’s configuration). The reason for this, of course, is that NSNumberFormatter doesn’t perform currency conversions, it just formats numeric data. You wouldn’t want one user interpreting the value "56324" as US currency and another user who’s accessing the same data interpreting it as Japanese currency, simply based on each user’s localization preferences.

    Availability

    Available in OS X v10.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 OS X v10.4 and later.

  • The receiver’s format.

    Declaration

    Swift

    var format: String

    Objective-C

    @property(copy) NSString *format

    Availability

    Available in OS X v10.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 OS X v10.10 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 OS X v10.4 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 OS X v10.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 OS X v10.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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 and later.

  • The currency grouping separator for the receiver.

    Declaration

    Swift

    var currencyGroupingSeparator: String!

    Objective-C

    @property(copy) NSString *currencyGroupingSeparator

    Availability

    Available in OS X v10.5 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 and later.

  • The text attributes to be used in displaying negative values.

    Declaration

    Swift

    var textAttributesForNegativeValues: [String : AnyObject]?

    Objective-C

    @property(copy) NSDictionary <NSString *,id> *textAttributesForNegativeValues

    Discussion

    This property is a dictionary that contains the attributes used to display negative values.

    Availability

    Available in OS X v10.0 and later.

  • The text attributes to be used in displaying positive values.

    Declaration

    Swift

    var textAttributesForPositiveValues: [String : AnyObject]?

    Objective-C

    @property(copy) NSDictionary <NSString *,id> *textAttributesForPositiveValues

    Discussion

    This property is a dictionary that contains the attributes used to display positive values.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    @NSCopying var attributedStringForZero: NSAttributedString

    Objective-C

    @property(copy) NSAttributedString *attributedStringForZero

    Discussion

    By default zero values are displayed according to the format specified for positive values; for more discussion of this subject see Data Formatting Guide.

    Special Considerations

    This method is for use with formatters using NSNumberFormatterBehavior10_0 behavior.

    Availability

    Available in OS X v10.0 and later.

  • The text attributes used to display a zero value.

    Declaration

    Swift

    var textAttributesForZero: [String : AnyObject]?

    Objective-C

    @property(copy) NSDictionary <NSString *,id> *textAttributesForZero

    Discussion

    This property is a dictionary that contains the text attributes used to display zero values.

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    @NSCopying var attributedStringForNil: NSAttributedString

    Objective-C

    @property(copy) NSAttributedString *attributedStringForNil

    Discussion

    By default nil values are displayed as an empty string.

    Special Considerations

    This method is for use with formatters using NSNumberFormatterBehavior10_0 behavior.

    Availability

    Available in OS X v10.0 and later.

  • The text attributes used to display the nil symbol.

    Declaration

    Swift

    var textAttributesForNil: [String : AnyObject]?

    Objective-C

    @property(copy) NSDictionary <NSString *,id> *textAttributesForNil

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    @NSCopying var attributedStringForNotANumber: NSAttributedString

    Objective-C

    @property(copy) NSAttributedString *attributedStringForNotANumber

    Discussion

    By default “not a number” values are displayed as the string “NaN”.

    Special Considerations

    This method is for use with formatters using NSNumberFormatterBehavior10_0 behavior.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var textAttributesForNotANumber: [String : AnyObject]?

    Objective-C

    @property(copy) NSDictionary <NSString *,id> *textAttributesForNotANumber

    Availability

    Available in OS X v10.4 and later.

  • The text attributes used to display the positive infinity symbol.

    Declaration

    Swift

    var textAttributesForPositiveInfinity: [String : AnyObject]?

    Objective-C

    @property(copy) NSDictionary <NSString *,id> *textAttributesForPositiveInfinity

    Discussion

    This property is a dictionary that contains the text attributes used to display the positive infinity string.

    Availability

    Available in OS X v10.4 and later.

  • The text attributes used to display the negative infinity symbol.

    Declaration

    Swift

    var textAttributesForNegativeInfinity: [String : AnyObject]?

    Objective-C

    @property(copy) NSDictionary <NSString *,id> *textAttributesForNegativeInfinity

    Discussion

    This property is a dictionary that contains the text attributes used to display the negative infinity string.

    Availability

    Available in OS X v10.4 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 OS X v10.4 and later.

  • Determines whether the receiver displays the group separator.

    Declaration

    Swift

    var usesGroupingSeparator: Bool

    Objective-C

    @property BOOL usesGroupingSeparator

    Availability

    Available in OS X v10.4 and later.

  • The character the receiver uses as a thousand separator.

    Declaration

    Swift

    var thousandSeparator: String!

    Objective-C

    @property(copy) NSString *thousandSeparator

    Discussion

    If you don’t have thousand separators enabled through any other means (such as format), using this method enables them.

    Special Considerations

    This method is for use with formatters using NSNumberFormatterBehavior10_0 behavior.

    Availability

    Available in OS X v10.0 and later.

  • Determines whether the receiver uses thousand separators.

    Declaration

    Swift

    var hasThousandSeparators: Bool

    Objective-C

    @property BOOL hasThousandSeparators

    Availability

    Available in OS X v10.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 OS X v10.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 OS X v10.4 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 OS X v10.4 and later.

  • The grouping size of the receiver.

    Declaration

    Swift

    var groupingSize: Int

    Objective-C

    @property NSUInteger groupingSize

    Availability

    Available in OS X v10.4 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 OS X v10.4 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 OS X v10.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 OS X v10.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 OS X v10.0 and later.

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

    Declaration

    Swift

    var minimumIntegerDigits: Int

    Objective-C

    @property NSUInteger minimumIntegerDigits

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    var minimumFractionDigits: Int

    Objective-C

    @property NSUInteger minimumFractionDigits

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    var maximumIntegerDigits: Int

    Objective-C

    @property NSUInteger maximumIntegerDigits

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    var maximumFractionDigits: Int

    Objective-C

    @property NSUInteger maximumFractionDigits

    Availability

    Available in OS X v10.4 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 OS X v10.5 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 OS X v10.5 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 }; typedef NSUInteger NSNumberFormatterStyle;

    Constants

    • NoStyle

      NSNumberFormatterNoStyle

      Specifies no style.

      Available in OS X v10.4 and later.

    • DecimalStyle

      NSNumberFormatterDecimalStyle

      Specifies a decimal style format.

      Available in OS X v10.4 and later.

    • CurrencyStyle

      NSNumberFormatterCurrencyStyle

      Specifies a currency style format.

      Available in OS X v10.4 and later.

    • PercentStyle

      NSNumberFormatterPercentStyle

      Specifies a percent style format.

      Available in OS X v10.4 and later.

    • ScientificStyle

      NSNumberFormatterScientificStyle

      Specifies a scientific style format.

      Available in OS X v10.4 and later.

    • SpellOutStyle

      NSNumberFormatterSpellOutStyle

      Specifies a spell-out format; for example, “23” becomes “twenty-three”.

      Available in OS X v10.4 and later.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

  • These constants specify the behavior of a number formatter. These constants are returned by the defaultFormatterBehavior class method and the formatterBehavior instance methods; you set them with the setDefaultFormatterBehavior: class method and the setFormatterBehavior: instance method.

    Declaration

    Swift

    enum NSNumberFormatterBehavior : UInt { case BehaviorDefault case Behavior10_0 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 OS X v10.4 and later.

    • Behavior10_0

      NSNumberFormatterBehavior10_0

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

      Available in OS X v10.4 and later.

    • Behavior10_4

      NSNumberFormatterBehavior10_4

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

      Available in OS X v10.4 and later.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 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 OS X v10.4 and later.

    • AfterPrefix

      NSNumberFormatterPadAfterPrefix

      Specifies that the padding should occur after the prefix.

      Available in OS X v10.4 and later.

    • BeforeSuffix

      NSNumberFormatterPadBeforeSuffix

      Specifies that the padding should occur before the suffix.

      Available in OS X v10.4 and later.

    • AfterSuffix

      NSNumberFormatterPadAfterSuffix

      Specifies that the padding should occur after the suffix.

      Available in OS X v10.4 and later.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 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 OS X v10.4 and later.

    • RoundFloor

      NSNumberFormatterRoundFloor

      Round towards negative infinity.

      Available in OS X v10.4 and later.

    • RoundDown

      NSNumberFormatterRoundDown

      Round towards zero.

      Available in OS X v10.4 and later.

    • RoundUp

      NSNumberFormatterRoundUp

      Round away from zero.

      Available in OS X v10.4 and later.

    • RoundHalfEven

      NSNumberFormatterRoundHalfEven

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

      Available in OS X v10.4 and later.

    • RoundHalfDown

      NSNumberFormatterRoundHalfDown

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

      Available in OS X v10.4 and later.

    • RoundHalfUp

      NSNumberFormatterRoundHalfUp

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

      Available in OS X v10.4 and later.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.