NSNumberFormatter Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
NSNumberFormatter.h
Related sample code

Overview

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”).

Tasks

Configuring Formatter Behavior and Style

Converting Between Numbers and Strings

Managing Localization of Numbers

Configuring Rounding Behavior

Configuring Numeric Formats

Configuring Numeric Symbols

Configuring the Format of Currency

Configuring Numeric Prefixes and Suffixes

Configuring the Display of Numeric Values

Configuring Separators and Grouping Size

Managing the Padding of Numbers

Managing Input and Output Attributes

Configuring Significant Digits

Managing Leniency Behavior

Managing the Validation of Partial Numeric Strings

Class Methods

defaultFormatterBehavior

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

+ (NSNumberFormatterBehavior)defaultFormatterBehavior
Return Value

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

localizedStringFromNumber:numberStyle:

Returns a localized number string with the specified style.

+ (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.
Declared In
NSNumberFormatter.h

setDefaultFormatterBehavior:

Sets the default formatter behavior for new instances of NSNumberFormatter .

+ (void)setDefaultFormatterBehavior:(NSNumberFormatterBehavior)behavior
Parameters
behavior

An NSNumberFormatterBehavior constant that indicates the revision of the class providing the default behavior.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

Instance Methods

allowsFloats

Returns a Boolean value that indicates whether the receiver allows floating-point values as input.

- (BOOL)allowsFloats
Return Value

YES if the receiver allows as input floating-point values (that is, values that include the period character [.]), otherwise NO.

Discussion

When this method returns NO, only integer values can be provided as input. The default is YES.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

alwaysShowsDecimalSeparator

Returns a Boolean value that indicates whether the receiver always shows a decimal separator, even if the number is an integer.

- (BOOL)alwaysShowsDecimalSeparator
Return Value

YES if the receiver always shows a decimal separator, even if the number is an integer, otherwise NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

currencyCode

Returns the receiver’s currency code as a string.

- (NSString *)currencyCode
Return Value

The receiver’s currency code as a string.

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.
Declared In
NSNumberFormatter.h

currencyDecimalSeparator

Returns the receiver’s currency decimal separator as a string.

- (NSString *)currencyDecimalSeparator
Return Value

The receiver’s currency decimal separator as a string.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

currencyGroupingSeparator

Returns the currency grouping separator for the receiver.

- (NSString *)currencyGroupingSeparator
Return Value

The currency grouping separator for the receiver.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

currencySymbol

Returns the receiver’s local currency symbol.

- (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.
Declared In
NSNumberFormatter.h

decimalSeparator

Returns a string containing the character the receiver uses to represent decimal separators.

- (NSString *)decimalSeparator
Return Value

A string containing the character the receiver uses to represent decimal separators.

Discussion

The return value doesn’t indicate whether decimal separators are enabled.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

exponentSymbol

Returns the string the receiver uses as an exponent symbol.

- (NSString *)exponentSymbol
Return Value

The string the receiver uses as an exponent symbol.

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.
Declared In
NSNumberFormatter.h

formatterBehavior

Returns an NSNumberFormatterBehavior constant that indicates the formatter behavior of the receiver.

- (NSNumberFormatterBehavior)formatterBehavior
Return Value

An NSNumberFormatterBehavior constant that indicates the formatter behavior of the receiver.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

formatWidth

Returns the format width of the receiver.

- (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 returned from paddingPosition.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

generatesDecimalNumbers

Returns a Boolean value that indicates whether the receiver creates instances of NSDecimalNumber when it converts strings to number objects.

- (BOOL)generatesDecimalNumbers
Return Value

YES if the receiver creates instances of NSDecimalNumber when it converts strings to number objects, NO if it creates instance of NSNumber.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

getObjectValue:forString:range:error:

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

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

On return, contains an instance of NSDecimalNumber or NSNumber based on the current value of generatesDecimalNumbers. The default is to return NSDecimalNumber instances

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

YES if the conversion from string to cell-content object was successful, otherwise NO.

Discussion

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

groupingSeparator

Returns a string containing the receiver’s grouping separator.

- (NSString *)groupingSeparator
Return Value

A string containing the receiver’s grouping separator.

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.
Declared In
NSNumberFormatter.h

groupingSize

Returns the receiver’s primary grouping size.

- (NSUInteger)groupingSize
Return Value

The receiver’s primary grouping size.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

internationalCurrencySymbol

Returns the international currency symbol used by the receiver.

- (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.
Declared In
NSNumberFormatter.h

isLenient

Returns a Boolean value that indicates whether the receiver uses heuristics to guess at the number which is intended by a string.

- (BOOL)isLenient
Return Value

YES if the receiver uses heuristics to guess at the number which is intended by the string; otherwise NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

isPartialStringValidationEnabled

Returns a Boolean value that indicates whether partial string validation is enabled.

- (BOOL)isPartialStringValidationEnabled
Return Value

YES if partial string validation is enabled, otherwise NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

locale

Returns the locale of the receiver.

- (NSLocale *)locale
Return Value

The locale of the receiver.

Discussion

A number formatter’s locale specifies default localization 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.
Declared In
NSNumberFormatter.h

maximum

Returns the highest number allowed as input by the receiver.

- (NSNumber *)maximum
Return Value

The highest number allowed as input by the receiver or nil, meaning no limit.

Discussion

For versions prior to OS X v10.4 (and number-formatter behavior set to NSNumberFormatterBehavior10_0) this method returns an NSDecimalNumber object.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

maximumFractionDigits

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

- (NSUInteger)maximumFractionDigits
Return Value

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

maximumIntegerDigits

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

- (NSUInteger)maximumIntegerDigits
Return Value

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

maximumSignificantDigits

Returns the maximum number of significant digits for the receiver.

- (NSUInteger)maximumSignificantDigits
Return Value

The maximum number of significant digits for the receiver.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

minimum

Returns the lowest number allowed as input by the receiver.

- (NSNumber *)minimum
Return Value

The lowest number allowed as input by the receiver or nil, meaning no limit.

Discussion

For versions prior to OS X v10.4 (and number-formatter behavior set to NSNumberFormatterBehavior10_0) this method returns an NSDecimalNumber object.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

minimumFractionDigits

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

- (NSUInteger)minimumFractionDigits
Return Value

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

minimumIntegerDigits

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

- (NSUInteger)minimumIntegerDigits
Return Value

The minimum number of integer digits allowed as input and output.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

minimumSignificantDigits

Returns the minimum number of significant digits for the receiver.

- (NSUInteger)minimumSignificantDigits
Return Value

The minimum number of significant digits for the receiver.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

minusSign

Returns the string the receiver uses to represent the minus sign.

- (NSString *)minusSign
Return Value

The string that represents the receiver’s minus sign.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

multiplier

Returns the multiplier used by the receiver as an NSNumber object.

- (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.
Declared In
NSNumberFormatter.h

negativeFormat

Returns the format used by the receiver to display negative numbers.

- (NSString *)negativeFormat
Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

negativeInfinitySymbol

Returns the symbol the receiver uses to represent negative infinity.

- (NSString *)negativeInfinitySymbol
Return Value

The symbol the receiver uses to represent negative infinity.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

negativePrefix

Returns the string the receiver inserts as a prefix to negative values.

- (NSString *)negativePrefix
Return Value

The string the receiver inserts as a prefix to negative values.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

negativeSuffix

Returns the string the receiver adds as a suffix to negative values.

- (NSString *)negativeSuffix
Return Value

The string the receiver adds as a suffix to negative values.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

nilSymbol

Returns the string the receiver uses to represent a nil value.

- (NSString *)nilSymbol
Return Value

The string the receiver uses to represent a nil value.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

notANumberSymbol

Returns the symbol the receiver uses to represent NaN (“not a number”) when it converts values.

- (NSString *)notANumberSymbol
Return Value

The symbol the receiver uses to represent NaN (“not a number”) when it converts values.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

numberFromString:

Returns an NSNumber object created by parsing a given string.

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

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSNumberFormatter.h

numberStyle

Returns the number-formatter style of the receiver.

- (NSNumberFormatterStyle)numberStyle
Return Value

An NSNumberFormatterStyle constant that indicates the number-formatter style of the receiver.

Discussion

Styles are essentially predetermined sets of values for certain properties. Examples of number-formatter styles are those used for decimal values, percentage values, and currency.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

paddingCharacter

Returns a string containing the padding character for the receiver.

- (NSString *)paddingCharacter
Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

paddingPosition

Returns the padding position of the receiver.

- (NSNumberFormatterPadPosition)paddingPosition
Discussion

The returned constant indicates whether the padding is before or after the number’s prefix or suffix.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

percentSymbol

Returns the string that the receiver uses to represent the percent symbol.

- (NSString *)percentSymbol
Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

perMillSymbol

Returns the string that the receiver uses for the per-thousands symbol.

- (NSString *)perMillSymbol
Return Value

The string that the receiver uses for the per-thousands symbol.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

plusSign

Returns the string the receiver uses for the plus sign.

- (NSString *)plusSign
Return Value

The string the receiver uses for the plus sign.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

positiveFormat

Returns the format used by the receiver to display positive numbers.

- (NSString *)positiveFormat
Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

positiveInfinitySymbol

Returns the string the receiver uses for the positive infinity symbol.

- (NSString *)positiveInfinitySymbol
Return Value

The string the receiver uses for the positive infinity symbol.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

positivePrefix

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

- (NSString *)positivePrefix
Return Value

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

positiveSuffix

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

- (NSString *)positiveSuffix
Return Value

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

roundingIncrement

Returns the rounding increment used by the receiver.

- (NSNumber *)roundingIncrement
Return Value

The rounding increment used by the receiver.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

roundingMode

Returns the rounding mode used by the receiver.

Return Value

The rounding mode used by the receiver.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

secondaryGroupingSize

Returns the size of secondary groupings for the receiver.

- (NSUInteger)secondaryGroupingSize
Return Value

The size of secondary groupings for the receiver.

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.
Declared In
NSNumberFormatter.h

setAllowsFloats:

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

- (void)setAllowsFloats:(BOOL)flag
Parameters
flag

YES if the receiver allows floating-point values, NO otherwise.

Discussion

By default, floating point values are allowed as input.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setAlwaysShowsDecimalSeparator:

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

- (void)setAlwaysShowsDecimalSeparator:(BOOL)flag
Parameters
flag

YES if the receiver should always show the decimal separator, NO otherwise.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setCurrencyCode:

Sets the receiver’s currency code.

- (void)setCurrencyCode:(NSString *)string
Parameters
string

A string specifying the receiver's new currency code.

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.
Declared In
NSNumberFormatter.h

setCurrencyDecimalSeparator:

Sets the string used by the receiver as a decimal separator.

- (void)setCurrencyDecimalSeparator:(NSString *)string
Parameters
string

The string to use as the currency decimal separator.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setCurrencyGroupingSeparator:

Sets the currency grouping separator for the receiver.

- (void)setCurrencyGroupingSeparator:(NSString *)string
Parameters
string

The currency grouping separator for the receiver.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setCurrencySymbol:

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

- (void)setCurrencySymbol:(NSString *)string
Parameters
string

A string that represents a local currency symbol.

Discussion

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.
Declared In
NSNumberFormatter.h

setDecimalSeparator:

Sets the character the receiver uses as a decimal separator.

- (void)setDecimalSeparator:(NSString *)newSeparator
Parameters
newSeparator

The string that specifies the decimal-separator character to use. If newSeparator contains multiple characters, only the first one is used.

Discussion

If you don’t have decimal separators enabled through another means (such as setFormat:), using this method enables them.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setExponentSymbol:

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

- (void)setExponentSymbol:(NSString *)string
Parameters
string

A string that represents an exponent symbol.

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.
Declared In
NSNumberFormatter.h

setFormatterBehavior:

Sets the formatter behavior of the receiver.

- (void)setFormatterBehavior:(NSNumberFormatterBehavior)behavior
Parameters
behavior

An NSNumberFormatterBehavior constant that indicates the revision of the NSNumberFormatter class providing the current behavior.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setFormatWidth:

Sets the format width used by the receiver.

- (void)setFormatWidth:(NSUInteger)number
Parameters
number

An integer that specifies the format width.

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 returned from paddingPosition.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setGeneratesDecimalNumbers:

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

- (void)setGeneratesDecimalNumbers:(BOOL)flag
Parameters
flag

YES if the receiver should generate NSDecimalNumber instances, NO if it should generate NSNumber instances.

Discussion

The default is YES.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setGroupingSeparator:

Specifies the string used by the receiver for a grouping separator.

- (void)setGroupingSeparator:(NSString *)string
Parameters
string

A string that specifies the grouping separator to use.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setGroupingSize:

Sets the grouping size of the receiver.

- (void)setGroupingSize:(NSUInteger)numDigits
Parameters
numDigits

An integer that specifies the grouping size.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setInternationalCurrencySymbol:

Sets the string used by the receiver for the international currency symbol.

- (void)setInternationalCurrencySymbol:(NSString *)string
Parameters
string

A string that represents an international currency symbol.

Discussion

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.
Declared In
NSNumberFormatter.h

setLenient:

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

- (void)setLenient:(BOOL)b
Parameters
b

YES if the receiver will use heuristics to guess at the number which is intended by the string; otherwise NO.

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.
Declared In
NSNumberFormatter.h

setLocale:

Sets the locale of the receiver.

- (void)setLocale:(NSLocale *)theLocale
Parameters
theLocale

An NSLocale object representing the new locale of the receiver.

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.
See Also
Declared In
NSNumberFormatter.h

setMaximum:

Sets the highest number the receiver allows as input.

- (void)setMaximum:(NSNumber *)aMaximum
Parameters
aMaximum

A number object that specifies a maximum input value.

Discussion

If aMaximum is nil, checking for the maximum value is disabled. For versions prior to OS X v10.4 (and number-formatter behavior set to NSNumberFormatterBehavior10_0) this method requires an NSDecimalNumber argument.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setMaximumFractionDigits:

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

- (void)setMaximumFractionDigits:(NSUInteger)number
Parameters
number

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setMaximumIntegerDigits:

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

- (void)setMaximumIntegerDigits:(NSUInteger)number
Parameters
number

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setMaximumSignificantDigits:

Sets the maximum number of significant digits for the receiver.

- (void)setMaximumSignificantDigits:(NSUInteger)number
Parameters
number

The maximum number of significant digits for the receiver.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setMinimum:

Sets the lowest number the receiver allows as input.

- (void)setMinimum:(NSNumber *)aMinimum
Parameters
aMinimum

A number object that specifies a minimum input value.

Discussion

If aMinimum is nil, checking for the minimum value is disabled. For versions prior to OS X v10.4 (and number-formatter behavior set to NSNumberFormatterBehavior10_0) this method requires an NSDecimalNumber argument.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setMinimumFractionDigits:

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

- (void)setMinimumFractionDigits:(NSUInteger)number
Parameters
number

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setMinimumIntegerDigits:

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

- (void)setMinimumIntegerDigits:(NSUInteger)number
Parameters
number

The minimum number of integer digits allowed as input and output.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setMinimumSignificantDigits:

Sets the minimum number of significant digits for the receiver.

- (void)setMinimumSignificantDigits:(NSUInteger)number
Parameters
number

The minimum number of significant digits for the receiver.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setMinusSign:

Sets the string used by the receiver for the minus sign.

- (void)setMinusSign:(NSString *)string
Parameters
string

A string that represents a minus sign.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setMultiplier:

Sets the multiplier of the receiver.

- (void)setMultiplier:(NSNumber *)number
Parameters
number

A number object that represents a 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.
Declared In
NSNumberFormatter.h

setNegativeFormat:

Sets the format the receiver uses to display negative values.

- (void)setNegativeFormat:(NSString *)aFormat
Parameters
aFormat

A string that specifies the format for negative values.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setNegativeInfinitySymbol:

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

- (void)setNegativeInfinitySymbol:(NSString *)string
Parameters
string

A string that represents a negative infinity symbol.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setNegativePrefix:

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

- (void)setNegativePrefix:(NSString *)string
Parameters
string

A string to use as the prefix for negative values.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setNegativeSuffix:

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

- (void)setNegativeSuffix:(NSString *)string
Parameters
string

A string to use as the suffix for negative values.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setNilSymbol:

Sets the string the receiver uses to represent nil values.

- (void)setNilSymbol:(NSString *)string
Parameters
string

A string that represents a nil value.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setNotANumberSymbol:

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

- (void)setNotANumberSymbol:(NSString *)string
Parameters
string

A string that represents a NaN symbol.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setNumberStyle:

Sets the number style used by the receiver.

- (void)setNumberStyle:(NSNumberFormatterStyle)style
Parameters
style

An NSNumberFormatterStyle constant that specifies a formatter style.

Discussion

Styles are essentially predetermined sets of values for certain properties. Examples of number-formatter styles are those used for decimal values, percentage values, and currency.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setPaddingCharacter:

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

- (void)setPaddingCharacter:(NSString *)string
Parameters
string

A string containing a padding character (or characters).

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setPaddingPosition:

Sets the padding position used by the receiver.

- (void)setPaddingPosition:(NSNumberFormatterPadPosition)position
Parameters
position

An NSNumberFormatterPadPosition constant that indicates a padding position (before or after prefix or suffix).

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setPartialStringValidationEnabled:

Sets whether partial string validation is enabled for the receiver.

- (void)setPartialStringValidationEnabled:(BOOL)enabled
Parameters
enabled

YES if partial string validation is enabled, otherwise NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setPercentSymbol:

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

- (void)setPercentSymbol:(NSString *)string
Parameters
string

A string that represents a percent symbol.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setPerMillSymbol:

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

- (void)setPerMillSymbol:(NSString *)string
Parameters
string

A string that represents a per-mill symbol.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setPlusSign:

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

- (void)setPlusSign:(NSString *)string
Parameters
string

A string that represents a plus sign.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSNumberFormatter.h

setPositiveFormat:

Sets the format the receiver uses to display positive values.

- (void)setPositiveFormat:(NSString *)aFormat
Parameters
aFormat

A string that specifies the format for positive values.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setPositiveInfinitySymbol:

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

- (void)setPositiveInfinitySymbol:(NSString *)string
Parameters
string

A string that represents a positive infinity symbol.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setPositivePrefix:

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

- (void)setPositivePrefix:(NSString *)string
Parameters
string

A string to use as the prefix for positive values.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setPositiveSuffix:

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

- (void)setPositiveSuffix:(NSString *)string
Parameters
string

A string to use as the suffix for positive values.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setRoundingIncrement:

Sets the rounding increment used by the receiver.

- (void)setRoundingIncrement:(NSNumber *)number
Parameters
number

A number object specifying a rounding increment.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setRoundingMode:

Sets the rounding mode used by the receiver.

- (void)setRoundingMode:(NSNumberFormatterRoundingMode)mode
Parameters
mode

An NSNumberFormatterRoundingMode constant that indicates a rounding mode.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setSecondaryGroupingSize:

Sets the secondary grouping size of the receiver.

- (void)setSecondaryGroupingSize:(NSUInteger)number
Parameters
number

An integer that specifies the size of secondary groupings.

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.
Declared In
NSNumberFormatter.h

setTextAttributesForNegativeInfinity:

Sets the text attributes used to display the negative infinity symbol.

- (void)setTextAttributesForNegativeInfinity:(NSDictionary *)newAttributes
Parameters
newAttributes

A dictionary containing text attributes for the display of the negative infinity symbol.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setTextAttributesForNegativeValues:

Sets the text attributes to be used in displaying negative values .

- (void)setTextAttributesForNegativeValues:(NSDictionary *)newAttributes
Parameters
newAttributes

A dictionary containing properties for the display of negative values.

Discussion

For example, this code excerpt causes negative values to be displayed in red:

NSNumberFormatter *numberFormatter =
    [[[NSNumberFormatter alloc] init] autorelease];
NSMutableDictionary *newAttrs = [NSMutableDictionary dictionary];
 
[numberFormatter setFormat:@"$#,##0.00;($#,##0.00)"];
[newAttrs setObject:[NSColor redColor] forKey:@"NSColor"];
[numberFormatter setTextAttributesForNegativeValues:newAttrs];
[[textField cell] setFormatter:numberFormatter];

An even simpler way to cause negative values to be displayed in red is to include the constant [Red] in your format string, as shown in this example:

[numberFormatter setFormat:@"$#,##0.00;[Red]($#,##0.00)"];

When you set a value’s text attributes to use color, the color appears only when the value’s cell doesn’t have input focus. When the cell has input focus, the value is displayed in standard black.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setTextAttributesForNil:

Sets the text attributes used to display the nil symbol.

- (void)setTextAttributesForNil:(NSDictionary *)newAttributes
Parameters
newAttributes

A dictionary containing text attributes for the display of the nil symbol.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setTextAttributesForNotANumber:

Sets the text attributes used to display the NaN ("not a number") string.

- (void)setTextAttributesForNotANumber:(NSDictionary *)newAttributes
Parameters
newAttributes

A dictionary containing text attributes for the display of the NaN symbol.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setTextAttributesForPositiveInfinity:

Sets the text attributes used to display the positive infinity symbol.

- (void)setTextAttributesForPositiveInfinity:(NSDictionary *)newAttributes
Parameters
newAttributes

A dictionary containing text attributes for the display of the positive infinity symbol.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setTextAttributesForPositiveValues:

Sets the text attributes to be used in displaying positive values.

- (void)setTextAttributesForPositiveValues:(NSDictionary *)newAttributes
Parameters
newAttributes

A dictionary containing text attributes for the display of positive values.

Discussion

See setTextAttributesForNegativeValues: for an example of how a related method might be used.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setTextAttributesForZero:

Sets the text attributes used to display a zero value.

- (void)setTextAttributesForZero:(NSDictionary *)newAttributes
Parameters
newAttributes

A dictionary containing text attributes for the display of zero values.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setUsesGroupingSeparator:

Controls whether the receiver displays the grouping separator.

- (void)setUsesGroupingSeparator:(BOOL)flag
Parameters
flag

YES if the receiver should display the grouping separator, NO otherwise.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setUsesSignificantDigits:

Sets whether the receiver uses significant digits.

- (void)setUsesSignificantDigits:(BOOL)b
Parameters
b

YES if the receiver uses significant digits, otherwise NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

setZeroSymbol:

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

- (void)setZeroSymbol:(NSString *)string
Parameters
string

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

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.

Special Considerations

On OS X v10.4, this method works correctly for 10_0-style number formatters but does not work correctly for 10_4-style number formatters. You can work around the problem by subclassing and overriding the methods that convert between strings and numbers to look for the zero cases first and provide different behavior, invoking super when not zero.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

stringFromNumber:

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

- (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.
Declared In
NSNumberFormatter.h

textAttributesForNegativeInfinity

Returns a dictionary containing the text attributes used to display the negative infinity string.

- (NSDictionary *)textAttributesForNegativeInfinity
Return Value

A dictionary containing the text attributes used to display the negative infinity string.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

textAttributesForNegativeValues

Returns a dictionary containing the text attributes that have been set for negative values.

- (NSDictionary *)textAttributesForNegativeValues
Return Value

A dictionary containing the text attributes that have been set for negative values.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

textAttributesForNil

Returns a dictionary containing the text attributes used to display the nil symbol.

- (NSDictionary *)textAttributesForNil
Return Value

A dictionary containing the text attributes used to display the nil symbol.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

textAttributesForNotANumber

Returns a dictionary containing the text attributes used to display the NaN ("not a number") symbol.

- (NSDictionary *)textAttributesForNotANumber
Return Value

A dictionary containing the text attributes used to display the NaN ("not a number") symbol.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

textAttributesForPositiveInfinity

Returns a dictionary containing the text attributes used to display the positive infinity symbol.

- (NSDictionary *)textAttributesForPositiveInfinity
Return Value

A dictionary containing the text attributes used to display the positive infinity symbol.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

textAttributesForPositiveValues

Returns a dictionary containing the text attributes that have been set for positive values.

- (NSDictionary *)textAttributesForPositiveValues
Return Value

A dictionary containing the text attributes that have been set for positive values.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

textAttributesForZero

Returns a dictionary containing the text attributes used to display a value of zero.

- (NSDictionary *)textAttributesForZero
Return Value

A dictionary containing the text attributes used to display a value of zero.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

usesGroupingSeparator

Returns a Boolean value that indicates whether the receiver uses the grouping separator.

- (BOOL)usesGroupingSeparator
Return Value

YES if the receiver uses the grouping separator, otherwise NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

usesSignificantDigits

Returns a Boolean value that indicates whether the receiver uses significant digits.

- (BOOL)usesSignificantDigits
Return Value

YES if the receiver uses significant digits, otherwise NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

zeroSymbol

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

- (NSString *)zeroSymbol
Return Value

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

Discussion

For a discussion of how this is used, see setZeroSymbol:.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSNumberFormatter.h

Constants

NSNumberFormatterStyle

These constants specify predefined number format styles. These constants are used by the numberStyle and setNumberStyle: methods.

enum {
   NSNumberFormatterNoStyle = kCFNumberFormatterNoStyle,
   NSNumberFormatterDecimalStyle = kCFNumberFormatterDecimalStyle,
   NSNumberFormatterCurrencyStyle = kCFNumberFormatterCurrencyStyle,
   NSNumberFormatterPercentStyle = kCFNumberFormatterPercentStyle,
   NSNumberFormatterScientificStyle = kCFNumberFormatterScientificStyle,
   NSNumberFormatterSpellOutStyle = kCFNumberFormatterSpellOutStyle
};
typedef NSUInteger NSNumberFormatterStyle;
Constants
NSNumberFormatterNoStyle

Specifies no style.

Available in iOS 2.0 and later.

Declared in NSNumberFormatter.h.

NSNumberFormatterDecimalStyle

Specifies a decimal style format.

Available in iOS 2.0 and later.

Declared in NSNumberFormatter.h.

NSNumberFormatterCurrencyStyle

Specifies a currency style format.

Available in iOS 2.0 and later.

Declared in NSNumberFormatter.h.

NSNumberFormatterPercentStyle

Specifies a percent style format.

Available in iOS 2.0 and later.

Declared in NSNumberFormatter.h.

NSNumberFormatterScientificStyle

Specifies a scientific style format.

Available in iOS 2.0 and later.

Declared in NSNumberFormatter.h.

NSNumberFormatterSpellOutStyle

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

Available in iOS 2.0 and later.

Declared in NSNumberFormatter.h.

NSNumberFormatterBehavior

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.

enum {
   NSNumberFormatterBehaviorDefault = 0,
   NSNumberFormatterBehavior10_0 = 1000,
   NSNumberFormatterBehavior10_4 = 1040,
};
typedef NSUInteger NSNumberFormatterBehavior;
Constants
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.

Declared in NSNumberFormatter.h.

NSNumberFormatterBehavior10_0

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

Available in iOS 2.0 through iOS 2.1.

Declared in NSNumberFormatter.h.

NSNumberFormatterBehavior10_4

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

Available in iOS 2.0 and later.

Declared in NSNumberFormatter.h.

NSNumberFormatterPadPosition

These constants are used to specify how numbers should be padded. These constants are used by the paddingPosition and setPaddingPosition: methods.

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

Specifies that the padding should occur before the prefix.

Available in iOS 2.0 and later.

Declared in NSNumberFormatter.h.

NSNumberFormatterPadAfterPrefix

Specifies that the padding should occur after the prefix.

Available in iOS 2.0 and later.

Declared in NSNumberFormatter.h.

NSNumberFormatterPadBeforeSuffix

Specifies that the padding should occur before the suffix.

Available in iOS 2.0 and later.

Declared in NSNumberFormatter.h.

NSNumberFormatterPadAfterSuffix

Specifies that the padding should occur after the suffix.

Available in iOS 2.0 and later.

Declared in NSNumberFormatter.h.

NSNumberFormatterRoundingMode

These constants are used to specify how numbers should be rounded. These constants are used by the roundingModeand setRoundingMode: methods.

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

Round towards positive infinity.

Available in iOS 2.0 and later.

Declared in NSNumberFormatter.h.

NSNumberFormatterRoundFloor

Round towards negative infinity.

Available in iOS 2.0 and later.

Declared in NSNumberFormatter.h.

NSNumberFormatterRoundDown

Round towards zero.

Available in iOS 2.0 and later.

Declared in NSNumberFormatter.h.

NSNumberFormatterRoundUp

Round away from zero.

Available in iOS 2.0 and later.

Declared in NSNumberFormatter.h.

NSNumberFormatterRoundHalfEven

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

Available in iOS 2.0 and later.

Declared in NSNumberFormatter.h.

NSNumberFormatterRoundHalfDown

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

Available in iOS 2.0 and later.

Declared in NSNumberFormatter.h.

NSNumberFormatterRoundHalfUp

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

Available in iOS 2.0 and later.

Declared in NSNumberFormatter.h.