# NSNumberFormatter class reference

FredKiefer@gmx.de
rfm@gnu.org
Generated at 2025-02-13 06:02:40 +0000
2000 Free Software Foundation, Inc.
Software documentation for the NSNumberFormatter class
Foundation/NSNumberFormatter.h

This class is currently not fully implemented! All set methods will work, but stringForObject: will ignore the format completely. The documentation below describes what the behavior SHOULD be...

A specialization of the NSFormatter class for generating string representations of numbers ([NSNumber] and NSDecimalNumberinstances) and for parsing numeric values in strings.

See the NSFormatter documentation for description of the basic methods for formatting and parsing that are available.

There are no convenience initializers or constructors for this class. Instead, to obtain an instance, call alloc init and then -setFormat: .

The basic format of a format string uses "#" signs to represent digits, and other characters to represent themselves, in a context-dependent way. Thus, for example, `@"#,###.00"` means to print the number ending in.00 if it has no decimal part, otherwise print two decimal places, and to print one comma if it is greater than 1000. Thus, 1000 prints as "1,000.00", and 1444555.979 prints as "1444,555.98" (see -setRoundingBehavior:).

After setting the format, you may change the thousands separator and decimal point using set methods, or by calling -setLocalizesFormat: .

You may set separate formats to be used for positive numbers, negative numbers, and zero independently.

In addition, this class supports attributed strings (see NSAttributedString), so that you can specify font and color attributes, among others, to display aspects of a number. You can assign specific sets of attributes for positive and negative numbers, and for specific cases including 0, NaN, and `nil`...

defaultFormatterBehavior
Returns the formatter behavior previously set as the default using the +setDefaultFormatterBehavior: method.
localizedStringFromNumber:
num
numberStyle:
localizationStyle
Description forthcoming.
setDefaultFormatterBehavior:
behavior
Sets the default behavior of number formatters.
NB. If GNUstep has been built without the ICU library, NSNumberFormatterBehavior10_0 is currently used irrespective of this setting.
allowsFloats
Returns whether number parsing will accept floating point values or generate an exception (only int values are valid). Default is `YES`.
alwaysShowsDecimalSeparator
Description forthcoming.
attributedStringForNil
Returns the exact attributed string used for `nil` values. By default this is an empty string.
attributedStringForNotANumber
Returns the exact attributed string used for NaN values. By default this is the string "NaN" with no attributes.
attributedStringForZero
Returns the exact attributed string used for zero values. By default this is based on the format for zero values, if set, or the format for positive values otherwise.
currencyCode
Description forthcoming.
currencyDecimalSeparator
Description forthcoming.
currencyGroupingSeparator
Description forthcoming.
currencySymbol
Description forthcoming.
decimalSeparator
Returns thousands separator used; default is '.'.
exponentSymbol
Description forthcoming.
format
Returns the format string this instance was initialized with.
formatWidth
Description forthcoming.
formatterBehavior
Returns the behavior of the receiver, either the default behavior set for number formatters, or the behavior specified by an earlier call to the -setFormatterBehavior: method.
generatesDecimalNumbers
Description forthcoming.
getObjectValue:
anObject
forString:
aString
range:
rangep
error:
error
Description forthcoming.
groupingSeparator
Description forthcoming.
groupingSize
Description forthcoming.
hasThousandSeparators
Returns whether thousands separator should be used, regardless of whether it is set in format. (Default is `YES` if explicitly set in format.)
internationalCurrencySymbol
Description forthcoming.
isLenient
Description forthcoming.
isPartialStringValidationEnabled
Description forthcoming.
locale
Description forthcoming.
localizesFormat
Returns whether this format should defer to the locale in determining thousands separator and decimal point. The default is to NOT localize.
maximum
Returns maximum value that will be accepted as valid in number parsing. Default is none.
maximumFractionDigits
Description forthcoming.
maximumIntegerDigits
Description forthcoming.
maximumSignificantDigits
Description forthcoming.
minimum
Returns minimum value that will be accepted as valid in number parsing. Default is none.
minimumFractionDigits
Description forthcoming.
minimumIntegerDigits
Description forthcoming.
minimumSignificantDigits
Description forthcoming.
minusSign
Description forthcoming.
multiplier
Description forthcoming.
negativeFormat
Returns format used for negative numbers.
negativeInfinitySymbol
Description forthcoming.
negativePrefix
Description forthcoming.
negativeSuffix
Description forthcoming.
nilSymbol
Description forthcoming.
notANumberSymbol
Description forthcoming.
numberFromString:
string
Returns the number for this string.
numberStyle
Description forthcoming.
paddingCharacter
Description forthcoming.
paddingPosition
Description forthcoming.
perMillSymbol
Description forthcoming.
percentSymbol
Description forthcoming.
plusSign
Description forthcoming.
positiveFormat
Returns format used for positive numbers.
positiveInfinitySymbol
Description forthcoming.
positivePrefix
Description forthcoming.
positiveSuffix
Description forthcoming.
roundingBehavior
Returns object specifying the rounding behavior used when truncating decimal digits in formats. Default is [NSDecimalNumberHandler +defaultDecimalNumberHandler].
roundingIncrement
Description forthcoming.
roundingMode
Description forthcoming.
secondaryGroupingSize
Description forthcoming.
setAllowsFloats:
flag
Sets whether number parsing will accept floating point values or generate an exception (only int values are valid). Default is `YES`.
setAlwaysShowsDecimalSeparator:
flag
Description forthcoming.
setAttributedStringForNil:
newAttributedString
Sets the exact attributed string used for `nil` values. By default this is an empty string.
setAttributedStringForNotANumber:
newAttributedString
Sets the exact attributed string used for NaN values. By default this is the string "NaN" with no attributes.
setAttributedStringForZero:
newAttributedString
Sets the exact attributed string used for zero values. By default this is based on the format for zero values, if set, or the format for positive values otherwise.
setCurrencyCode:
string
Description forthcoming.
setCurrencyDecimalSeparator:
string
Description forthcoming.
setCurrencyGroupingSeparator:
string
Description forthcoming.
setCurrencySymbol:
string
Description forthcoming.
setDecimalSeparator:
newSeparator
Sets thousands separator used; default is '.'.
setExponentSymbol:
string
Description forthcoming.
setFormat:
aFormat
Sets format string. See class description for more information.
setFormatWidth:
number
Description forthcoming.
setFormatterBehavior:
behavior
Sets the behavior of the formatter.
NB. If GNUstep has been built without the ICU library, NSNumberFormatterBehavior10_0 is currently used irrespective of this setting.
setGeneratesDecimalNumbers:
flag
Description forthcoming.
setGroupingSeparator:
string
Description forthcoming.
setGroupingSize:
number
Description forthcoming.
setHasThousandSeparators:
flag
Sets whether thousands separator should be used, regardless of whether it is set in format. (Default is `YES` if explicitly set in format.)
setInternationalCurrencySymbol:
string
Description forthcoming.
setLenient:
flag
Description forthcoming.
setLocale:
locale
Description forthcoming.
setLocalizesFormat:
flag
Set whether this format should defer to the locale in determining thousands separator and decimal point. The default is to NOT localize.
setMaximum:
aMaximum
Sets maximum value that will be accepted as valid in number parsing. Default is none.
setMaximumFractionDigits:
number
Description forthcoming.
setMaximumIntegerDigits:
number
Description forthcoming.
setMaximumSignificantDigits:
number
Description forthcoming.
setMinimum:
aMinimum
Sets minimum value that will be accepted as valid in number parsing. Default is none.
setMinimumFractionDigits:
number
Description forthcoming.
setMinimumIntegerDigits:
number
Description forthcoming.
setMinimumSignificantDigits:
number
Description forthcoming.
setMinusSign:
string
Description forthcoming.
setMultiplier:
number
Description forthcoming.
setNegativeFormat:
aFormat
Sets format used for negative numbers. See class description for more information.
setNegativeInfinitySymbol:
string
Description forthcoming.
setNegativePrefix:
string
Description forthcoming.
setNegativeSuffix:
string
Description forthcoming.
setNilSymbol:
string
Description forthcoming.
setNotANumberSymbol:
string
Description forthcoming.
setNumberStyle:
style
Description forthcoming.
setPaddingCharacter:
string
Description forthcoming.
setPaddingPosition:
position
Description forthcoming.
setPartialStringValidationEnabled:
enabled
Description forthcoming.
setPerMillSymbol:
string
Description forthcoming.
setPercentSymbol:
string
Description forthcoming.
setPlusSign:
string
Description forthcoming.
setPositiveFormat:
aFormat
Sets format used for positive numbers. See class description for more information.
setPositiveInfinitySymbol:
string
Description forthcoming.
setPositivePrefix:
string
Description forthcoming.
setPositiveSuffix:
string
Description forthcoming.
setRoundingBehavior:
newRoundingBehavior
Sets object specifying the rounding behavior used when truncating decimal digits in formats. Default is [NSDecimalNumberHandler +defaultDecimalNumberHandler].
setRoundingIncrement:
number
Description forthcoming.
setRoundingMode:
mode
Description forthcoming.
setSecondaryGroupingSize:
number
Description forthcoming.
setTextAttributesForNegativeInfinity:
newAttributes
Description forthcoming.
setTextAttributesForNegativeValues:
newAttributes
Sets the attributes to apply to negative values (whole string), when -attributedStringForObjectValue:withDefaultAttributes: is called. Default is none.
setTextAttributesForNil:
newAttributes
Description forthcoming.
setTextAttributesForNotANumber:
newAttributes
Description forthcoming.
setTextAttributesForPositiveInfinity:
newAttributes
Description forthcoming.
setTextAttributesForPositiveValues:
newAttributes
Sets the attributes to apply to positive values (whole string), when -attributedStringForObjectValue:withDefaultAttributes: is called. Default is none.
setTextAttributesForZero:
newAttributes
Description forthcoming.
setThousandSeparator:
newSeparator
Sets thousands separator used; default is ','.
setUsesGroupingSeparator:
flag
Description forthcoming.
setUsesSignificantDigits:
flag
Description forthcoming.
setZeroSymbol:
string
Description forthcoming.
stringFromNumber:
number
Returns the string version of this number based on the format specified.
textAttributesForNegativeInfinity
Description forthcoming.
textAttributesForNegativeValues
Returns the attributes to apply to negative values (whole string), when -attributedStringForObjectValue:withDefaultAttributes: is called. Default is none.
textAttributesForNil
Description forthcoming.
textAttributesForNotANumber
Description forthcoming.
textAttributesForPositiveInfinity
Description forthcoming.
textAttributesForPositiveValues
Returns the attributes to apply to positive values (whole string), when -attributedStringForObjectValue:withDefaultAttributes: is called. Default is none.
textAttributesForZero
Description forthcoming.
thousandSeparator
Returns thousands separator used; default is ','.
usesGroupingSeparator
Description forthcoming.
usesSignificantDigits
Description forthcoming.
zeroSymbol
Description forthcoming.