NSNumberFormatter class reference

Authors

Fred Kiefer (FredKiefer@gmx.de)
Richard Frith-Macdonald (rfm@gnu.org)

Date: Generated at 2025-02-11 22:18:53 +0100

Software documentation for the NSNumberFormatter class

NSNumberFormatter : NSFormatter

Declared in:

Foundation/NSNumberFormatter.h

Availability: MacOS-X 10.0.0

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 NSDecimalNumber instances) 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...

Method summary

defaultFormatterBehavior

+ (NSNumberFormatterBehavior) defaultFormatterBehavior;

Availability: MacOS-X 10.4.0

Returns the formatter behavior previously set as the default using the +setDefaultFormatterBehavior: method.

localizedStringFromNumber: numberStyle:

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

Availability: MacOS-X 10.6.0

Description forthcoming.

setDefaultFormatterBehavior:

+ (void) setDefaultFormatterBehavior: (NSNumberFormatterBehavior)behavior;

Availability: MacOS-X 10.4.0

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

- (BOOL) allowsFloats;

Availability: MacOS-X 10.0.0

Returns whether number parsing will accept floating point values or generate an exception (only int values are valid). Default is YES.

alwaysShowsDecimalSeparator

- (BOOL) alwaysShowsDecimalSeparator;

Availability: MacOS-X 10.4.0

Description forthcoming.

attributedStringForNil

- (NSAttributedString*) attributedStringForNil;

Availability: MacOS-X 10.0.0

Returns the exact attributed string used for nil values. By default this is an empty string.

attributedStringForNotANumber

- (NSAttributedString*) attributedStringForNotANumber;

Availability: MacOS-X 10.0.0

Returns the exact attributed string used for NaN values. By default this is the string "NaN" with no attributes.

attributedStringForZero

- (NSAttributedString*) attributedStringForZero;

Availability: MacOS-X 10.0.0

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

- (NSString*) currencyCode;

Availability: MacOS-X 10.4.0

Description forthcoming.

currencyDecimalSeparator

- (NSString*) currencyDecimalSeparator;

Availability: MacOS-X 10.4.0

Description forthcoming.

currencyGroupingSeparator

- (NSString*) currencyGroupingSeparator;

Availability: MacOS-X 10.5.0

Description forthcoming.

currencySymbol

- (NSString*) currencySymbol;

Availability: MacOS-X 10.4.0

Description forthcoming.

decimalSeparator

- (NSString*) decimalSeparator;

Availability: MacOS-X 10.0.0

Returns thousands separator used; default is '.'.

exponentSymbol

- (NSString*) exponentSymbol;

Availability: MacOS-X 10.4.0

Description forthcoming.

format

- (NSString*) format;

Availability: MacOS-X 10.0.0

Returns the format string this instance was initialized with.

formatWidth

- (NSUInteger) formatWidth;

Availability: MacOS-X 10.4.0

Description forthcoming.

formatterBehavior

- (NSNumberFormatterBehavior) formatterBehavior;

Availability: MacOS-X 10.4.0

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

- (BOOL) generatesDecimalNumbers;

Availability: MacOS-X 10.4.0

Description forthcoming.

getObjectValue: forString: range: error:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

groupingSeparator

- (NSString*) groupingSeparator;

Availability: MacOS-X 10.4.0

Description forthcoming.

groupingSize

- (NSUInteger) groupingSize;

Availability: MacOS-X 10.4.0

Description forthcoming.

hasThousandSeparators

- (BOOL) hasThousandSeparators;

Availability: MacOS-X 10.0.0

Returns whether thousands separator should be used, regardless of whether it is set in format. (Default is YES if explicitly set in format.)

internationalCurrencySymbol

- (NSString*) internationalCurrencySymbol;

Availability: MacOS-X 10.4.0

Description forthcoming.

isLenient

- (BOOL) isLenient;

Availability: MacOS-X 10.5.0

Description forthcoming.

isPartialStringValidationEnabled

- (BOOL) isPartialStringValidationEnabled;

Availability: MacOS-X 10.5.0

Description forthcoming.

locale

- (NSLocale*) locale;

Availability: MacOS-X 10.4.0

Description forthcoming.

localizesFormat

- (BOOL) localizesFormat;

Availability: MacOS-X 10.0.0

Returns whether this format should defer to the locale in determining thousands separator and decimal point. The default is to NOT localize.

maximum

- (NSNumber*) maximum;

Availability: MacOS-X 10.0.0

Returns maximum value that will be accepted as valid in number parsing. Default is none.

maximumFractionDigits

- (NSUInteger) maximumFractionDigits;

Availability: MacOS-X 10.4.0

Description forthcoming.

maximumIntegerDigits

- (NSUInteger) maximumIntegerDigits;

Availability: MacOS-X 10.4.0

Description forthcoming.

maximumSignificantDigits

- (NSUInteger) maximumSignificantDigits;

Availability: MacOS-X 10.5.0

Description forthcoming.

minimum

- (NSNumber*) minimum;

Availability: MacOS-X 10.0.0

Returns minimum value that will be accepted as valid in number parsing. Default is none.

minimumFractionDigits

- (NSUInteger) minimumFractionDigits;

Availability: MacOS-X 10.4.0

Description forthcoming.

minimumIntegerDigits

- (NSUInteger) minimumIntegerDigits;

Availability: MacOS-X 10.4.0

Description forthcoming.

minimumSignificantDigits

- (NSUInteger) minimumSignificantDigits;

Availability: MacOS-X 10.5.0

Description forthcoming.

minusSign

- (NSString*) minusSign;

Availability: MacOS-X 10.4.0

Description forthcoming.

multiplier

- (NSNumber*) multiplier;

Availability: MacOS-X 10.4.0

Description forthcoming.

negativeFormat

- (NSString*) negativeFormat;

Availability: MacOS-X 10.0.0

Returns format used for negative numbers.

negativeInfinitySymbol

- (NSString*) negativeInfinitySymbol;

Availability: MacOS-X 10.4.0

Description forthcoming.

negativePrefix

- (NSString*) negativePrefix;

Availability: MacOS-X 10.4.0

Description forthcoming.

negativeSuffix

- (NSString*) negativeSuffix;

Availability: MacOS-X 10.4.0

Description forthcoming.

nilSymbol

- (NSString*) nilSymbol;

Availability: MacOS-X 10.4.0

Description forthcoming.

notANumberSymbol

- (NSString*) notANumberSymbol;

Availability: MacOS-X 10.4.0

Description forthcoming.

numberFromString:

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

Availability: MacOS-X 10.4.0

Returns the number for this string.

numberStyle

- (NSNumberFormatterStyle) numberStyle;

Availability: MacOS-X 10.4.0

Description forthcoming.

paddingCharacter

- (NSString*) paddingCharacter;

Availability: MacOS-X 10.4.0

Description forthcoming.

paddingPosition

- (NSNumberFormatterPadPosition) paddingPosition;

Availability: MacOS-X 10.4.0

Description forthcoming.

perMillSymbol

- (NSString*) perMillSymbol;

Availability: MacOS-X 10.4.0

Description forthcoming.

percentSymbol

- (NSString*) percentSymbol;

Availability: MacOS-X 10.4.0

Description forthcoming.

plusSign

- (NSString*) plusSign;

Availability: MacOS-X 10.4.0

Description forthcoming.

positiveFormat

- (NSString*) positiveFormat;

Availability: MacOS-X 10.0.0

Returns format used for positive numbers.

positiveInfinitySymbol

- (NSString*) positiveInfinitySymbol;

Availability: MacOS-X 10.4.0

Description forthcoming.

positivePrefix

- (NSString*) positivePrefix;

Availability: MacOS-X 10.4.0

Description forthcoming.

positiveSuffix

- (NSString*) positiveSuffix;

Availability: MacOS-X 10.4.0

Description forthcoming.

roundingBehavior

- (NSDecimalNumberHandler*) roundingBehavior;

Availability: MacOS-X 10.0.0

Returns object specifying the rounding behavior used when truncating decimal digits in formats. Default is [NSDecimalNumberHandler +defaultDecimalNumberHandler] .

roundingIncrement

- (NSNumber*) roundingIncrement;

Availability: MacOS-X 10.4.0

Description forthcoming.

roundingMode

- (NSNumberFormatterRoundingMode) roundingMode;

Availability: MacOS-X 10.4.0

Description forthcoming.

secondaryGroupingSize

- (NSUInteger) secondaryGroupingSize;

Availability: MacOS-X 10.4.0

Description forthcoming.

setAllowsFloats:

- (void) setAllowsFloats: (BOOL)flag;

Availability: MacOS-X 10.0.0

Sets whether number parsing will accept floating point values or generate an exception (only int values are valid). Default is YES.

setAlwaysShowsDecimalSeparator:

- (void) setAlwaysShowsDecimalSeparator: (BOOL)flag;

Availability: MacOS-X 10.4.0

Description forthcoming.

setAttributedStringForNil:

- (void) setAttributedStringForNil: (NSAttributedString*)newAttributedString;

Availability: MacOS-X 10.0.0

Sets the exact attributed string used for nil values. By default this is an empty string.

setAttributedStringForNotANumber:

- (void) setAttributedStringForNotANumber: (NSAttributedString*)newAttributedString;

Availability: MacOS-X 10.0.0

Sets the exact attributed string used for NaN values. By default this is the string "NaN" with no attributes.

setAttributedStringForZero:

- (void) setAttributedStringForZero: (NSAttributedString*)newAttributedString;

Availability: MacOS-X 10.0.0

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:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setCurrencyDecimalSeparator:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setCurrencyGroupingSeparator:

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

Availability: MacOS-X 10.5.0

Description forthcoming.

setCurrencySymbol:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setDecimalSeparator:

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

Availability: MacOS-X 10.0.0

Sets thousands separator used; default is '.'.

setExponentSymbol:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setFormat:

- (void) setFormat: (NSString*)aFormat;

Availability: MacOS-X 10.0.0

Sets format string. See class description for more information.

setFormatWidth:

- (void) setFormatWidth: (NSUInteger)number;

Availability: MacOS-X 10.4.0

Description forthcoming.

setFormatterBehavior:

- (void) setFormatterBehavior: (NSNumberFormatterBehavior)behavior;

Availability: MacOS-X 10.4.0

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:

- (void) setGeneratesDecimalNumbers: (BOOL)flag;

Availability: MacOS-X 10.4.0

Description forthcoming.

setGroupingSeparator:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setGroupingSize:

- (void) setGroupingSize: (NSUInteger)number;

Availability: MacOS-X 10.4.0

Description forthcoming.

setHasThousandSeparators:

- (void) setHasThousandSeparators: (BOOL)flag;

Availability: MacOS-X 10.0.0

Sets whether thousands separator should be used, regardless of whether it is set in format. (Default is YES if explicitly set in format.)

setInternationalCurrencySymbol:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setLenient:

- (void) setLenient: (BOOL)flag;

Availability: MacOS-X 10.5.0

Description forthcoming.

setLocale:

- (void) setLocale: (NSLocale*)locale;

Availability: MacOS-X 10.4.0

Description forthcoming.

setLocalizesFormat:

- (void) setLocalizesFormat: (BOOL)flag;

Availability: MacOS-X 10.0.0

Set whether this format should defer to the locale in determining thousands separator and decimal point. The default is to NOT localize.

setMaximum:

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

Availability: MacOS-X 10.0.0

Sets maximum value that will be accepted as valid in number parsing. Default is none.

setMaximumFractionDigits:

- (void) setMaximumFractionDigits: (NSUInteger)number;

Availability: MacOS-X 10.4.0

Description forthcoming.

setMaximumIntegerDigits:

- (void) setMaximumIntegerDigits: (NSUInteger)number;

Availability: MacOS-X 10.4.0

Description forthcoming.

setMaximumSignificantDigits:

- (void) setMaximumSignificantDigits: (NSUInteger)number;

Availability: MacOS-X 10.5.0

Description forthcoming.

setMinimum:

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

Availability: MacOS-X 10.0.0

Sets minimum value that will be accepted as valid in number parsing. Default is none.

setMinimumFractionDigits:

- (void) setMinimumFractionDigits: (NSUInteger)number;

Availability: MacOS-X 10.4.0

Description forthcoming.

setMinimumIntegerDigits:

- (void) setMinimumIntegerDigits: (NSUInteger)number;

Availability: MacOS-X 10.4.0

Description forthcoming.

setMinimumSignificantDigits:

- (void) setMinimumSignificantDigits: (NSUInteger)number;

Availability: MacOS-X 10.5.0

Description forthcoming.

setMinusSign:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setMultiplier:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setNegativeFormat:

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

Availability: MacOS-X 10.0.0

Sets format used for negative numbers. See class description for more information.

setNegativeInfinitySymbol:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setNegativePrefix:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setNegativeSuffix:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setNilSymbol:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setNotANumberSymbol:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setNumberStyle:

- (void) setNumberStyle: (NSNumberFormatterStyle)style;

Availability: MacOS-X 10.4.0

Description forthcoming.

setPaddingCharacter:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setPaddingPosition:

- (void) setPaddingPosition: (NSNumberFormatterPadPosition)position;

Availability: MacOS-X 10.4.0

Description forthcoming.

setPartialStringValidationEnabled:

- (void) setPartialStringValidationEnabled: (BOOL)enabled;

Availability: MacOS-X 10.5.0

Description forthcoming.

setPerMillSymbol:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setPercentSymbol:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setPlusSign:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setPositiveFormat:

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

Availability: MacOS-X 10.0.0

Sets format used for positive numbers. See class description for more information.

setPositiveInfinitySymbol:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setPositivePrefix:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setPositiveSuffix:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setRoundingBehavior:

- (void) setRoundingBehavior: (NSDecimalNumberHandler*)newRoundingBehavior;

Availability: MacOS-X 10.0.0

Sets object specifying the rounding behavior used when truncating decimal digits in formats. Default is [NSDecimalNumberHandler +defaultDecimalNumberHandler] .

setRoundingIncrement:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setRoundingMode:

- (void) setRoundingMode: (NSNumberFormatterRoundingMode)mode;

Availability: MacOS-X 10.4.0

Description forthcoming.

setSecondaryGroupingSize:

- (void) setSecondaryGroupingSize: (NSUInteger)number;

Availability: MacOS-X 10.4.0

Description forthcoming.

setTextAttributesForNegativeInfinity:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setTextAttributesForNegativeValues:

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

Availability: MacOS-X 10.0.0

Sets the attributes to apply to negative values (whole string), when -attributedStringForObjectValue:withDefaultAttributes: is called. Default is none.

setTextAttributesForNil:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setTextAttributesForNotANumber:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setTextAttributesForPositiveInfinity:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setTextAttributesForPositiveValues:

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

Availability: MacOS-X 10.0.0

Sets the attributes to apply to positive values (whole string), when -attributedStringForObjectValue:withDefaultAttributes: is called. Default is none.

setTextAttributesForZero:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

setThousandSeparator:

- (void) setThousandSeparator: (NSString*)newSeparator;

Availability: MacOS-X 10.0.0

Sets thousands separator used; default is ','.

setUsesGroupingSeparator:

- (void) setUsesGroupingSeparator: (BOOL)flag;

Availability: MacOS-X 10.4.0

Description forthcoming.

setUsesSignificantDigits:

- (void) setUsesSignificantDigits: (BOOL)flag;

Availability: MacOS-X 10.5.0

Description forthcoming.

setZeroSymbol:

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

Availability: MacOS-X 10.4.0

Description forthcoming.

stringFromNumber:

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

Availability: MacOS-X 10.4.0

Returns the string version of this number based on the format specified.

textAttributesForNegativeInfinity

- (NSDictionary*) textAttributesForNegativeInfinity;

Availability: MacOS-X 10.4.0

Description forthcoming.

textAttributesForNegativeValues

- (NSDictionary*) textAttributesForNegativeValues;

Availability: MacOS-X 10.0.0

Returns the attributes to apply to negative values (whole string), when -attributedStringForObjectValue:withDefaultAttributes: is called. Default is none.

textAttributesForNil

- (NSDictionary*) textAttributesForNil;

Availability: MacOS-X 10.4.0

Description forthcoming.

textAttributesForNotANumber

- (NSDictionary*) textAttributesForNotANumber;

Availability: MacOS-X 10.4.0

Description forthcoming.

textAttributesForPositiveInfinity

- (NSDictionary*) textAttributesForPositiveInfinity;

Availability: MacOS-X 10.4.0

Description forthcoming.

textAttributesForPositiveValues

- (NSDictionary*) textAttributesForPositiveValues;

Availability: MacOS-X 10.0.0

Returns the attributes to apply to positive values (whole string), when -attributedStringForObjectValue:withDefaultAttributes: is called. Default is none.