NSNumberFormatter

Inherits from:
java.text.Format : Object

Package:
com.webobjects.foundation

Class Description

Instances of NSNumberFormatter convert between BigDecimal numbers and textual representations of numeric values. The representation encompasses integers and floating-point numbers; floating-point numbers can be formatted to a specified decimal position. NSNumberFormatters can also impose ranges on the numeric values that can be formatted.

You can associate a number pattern with a WOString or WOTextField dynamic element. WebObjects uses an NSNumberFormatter object to perform the appropriate conversions.

Instances of NSNumberFormatter are mutable.

Creating an Instance of NSNumberFormatter

The most common technique for creating a NSNumberFormatter is to use the one-argument constructor, which takes as its argument a string whose contents can be one of the following:

"positivePattern" For example, "$###,##0.00" (the syntax of format strings is discussed in the following section).
"positivePattern;negativePattern" For example, "###,##0.00;(###,##0.00)".
"positivePattern;zeroPattern;negativePattern"For example, "$###,###.00;0.00;($###,##0.00)". Note that zero patterns are treated as string constants.

As implied in the above list, you're only required to specify a pattern for positive values. If you don't specify a pattern for negative and zero values, a default pattern based on the positive value pattern is used. For example, if your positive value pattern is "#,##0.00", an input value of "0" will be displayed as "0.00".

If you don't specify a pattern for negative values, the pattern specified for positive values is used, preceded by a minus sign (-).

If you specify a separate pattern for negative values, its separators should be parallel to those specified in the positive pattern string. In NSNumberFormatter, separators are either enabled or disabled for all patterns-both your negative and positive patterns should therefore use the same approach.

As an alternative to using the one-argument constructor is to use the no-argument constructor and invoking setPattern with the pattern. You can also use the setPositivePattern and setNegativePattern methods.

Pattern String Syntax

Pattern strings can include the following types of characters:

NumbersPattern strings can include numeric characters. Wherever you include a number in a pattern string, the number is displayed unless an input character in the same relative position overwrites it. For example, suppose you have the positive pattern string "9,990.00", and the value 53.88 is entered into a cell to which the pattern has been applied. The cell would display the value as 9,953.88.
SeparatorsPattern strings can include the period character (.) as a decimal separator, and comma character (,) as a thousand separator. If you want to use different characters as separators, you can set them using the setDecimalSeparator and setThousandSeparator methods.
PlaceholdersYou use the pound sign character (#) to represent numeric characters that will be input by the user. For example, suppose you have the positive pattern "$#,##0.00". If the characters 76329 were entered into a cell to which the pattern has been applied, they would be displayed as $76,329.00. Strictly speaking, however, you don't need to use placeholders. The format strings ",0.00", "#,#0.00", and "#,##0.00" are functionally equivalent. In other words, including separator characters in a pattern string signals NSNumberFormatter to use the separators, regardless of whether you use (or where you put) placeholders. The placeholder character's chief virtue lies in its ability to make pattern strings more human-readable, which is especially useful if you're displaying patterns in the user interface.
SpacesTo include a space in a pattern string, use the underscore character (_). This character inserts a space if no numeric character has been input to occupy that position.
CurrencyThe dollar sign character ($) is normally treated just like any other character that doesn't play a special role in NSNumberFormatter.

All other characters specified in a pattern string are displayed as typed. The following table shows examples of the how the value 1019.55 is displayed for different positive patterns:

Pattern String	Display
`"#,##0.00"`	1,019.55
`"$#,##0.00"`	$1,019.55
`"___,__0.00"`	1,019.55

Using Separators

NSNumberFormatter supports two different kinds of separators: thousand and decimal. By default these separators are represented by the comma (,) and period (.) characters respectively. The default pattern ("#,##0.##") enables them.

All of the following statements have the effect of enabling thousand separators:


// use setPattern:
numberFormatter.setPattern("#,###");

// use setHasThousandSeparators:
numberFormatter.setHasThousandSeparators(true);

// use setThousandSeparator:
numberFormatter.setThousandSeparator("_");

If you use the statement numberFormatter.setHasThousandSeparators(false), it disables thousand separators, even if you've set them through another means.

Both of the following statements have the effect of enabling decimal separators:


// use setFormat: numberFormatter.setFormat("0.00");
 // use setDecimalSeparator: numberFormatter.setDecimalSeparator("-");

When you enable or disable separators, it affects both positive and negative patterns. Consequently, both patterns must use the same separator scheme.

You can use the thousandSeparator and decimalSeparator methods to return a string containing the character the receiver uses to represent each separator. However, this shouldn't be taken as an indication of whether separators are enabled-even when separators are disabled, an NSNumberFormatter still knows the characters it uses to represent separators.

Separators must be single characters. If you specify multiple characters in the arguments to setThousandSeparator and setDecimalSeparator, only the first character is used.

You can't use the same character to represent thousand and decimal separators.

Localization

NSNumberFormatter provides methods to localize pattern strings. You can change the currency symbol, the decimal separator, and the thousands separator manually, or you can trust NSNumberFormatter to do it for you, based on locales. If you enable localization for an instance of NSNumberFormatter, it will check the current locale and localize pattern strings appropriately for that locale. By default, instances of NSNumberFormatter are not localized. You can enable localization for all new instances of NSNumberFormatter using setDefaultLocalizesPattern or for a specific instance of NSNumberFormatter using setLocalizesPattern. See the method descriptions for setDefaultLocalizesPattern and setLocalizesPattern for more information.

Constants

NSNumberFormatter provides the following constants for specifying rounding modes and special numbers.The rounding mode specifiers are used with roundingBehavior and setRoundingBehavior.

Constant	Type	Description
`RoundDown`	`int`	Rounding mode specifier: round towards negative infinity
`RoundUp`	`int`	Rounding mode specifier: round towards positive infinity
`RoundPlain`	`int`	Rounding mode specifier: round to nearest up
`RoundBankers`	`int`	Rounding mode specifier: round to nearest even
`NSDecimalNotANumber`	`java.math.BigDecimal`	Definition of Not A Number (NaN)
`DefaultPattern`	`String`	Default format for pattern strings: "#,##0.##".

Method Types

Constructors

NSNumberFormatter

Performing formatted conversions

objectValueForString
stringForObjectValue

Methods inherited from java.text.Format

format
parseObject

Accessing patterns

negativePattern
pattern
positivePattern
setNegativePattern
setPattern
setPositivePattern

Accessing floating point settings

allowsFloats
roundingBehavior
setAllowsFloats
setRoundingBehavior

Accessing decimal separator settings

decimalSeparator
setDecimalSeparator

Accessing thousand separator settings

hasThousandSeparators
setHasThousandSeparators
setThousandSeparator
thousandSeparator

Accessing strings for special numbers

setStringForNotANumber
setStringForNull
setStringForZero
stringForNotANumber
stringForNull
stringForZero

Limiting the input number

maximum
minimum
setMaximum
setMinimum

Localization Methods

availableLocales
currencySymbol
defaultLocale
defaultLocalizesPattern
locale
localizesPattern
setCurrencySymbol
setDefaultLocale
setDefaultLocalizesPattern
setLocale
setLocalizesPattern

Deprecated Methods

attributedStringForNil
attributedStringForNotANumber
attributedStringForZero
format
localizesFormat
negativeFormat
positiveFormat
setAttributedStringForNil
setAttributedStringForNotANumber
setAttributedStringForZero
setFormat
setLocalizesFormat
setNegativeFormat
setPositiveFormat

Constructors

NSNumberFormatter

public NSNumberFormatter()

Creates an NSNumberFormatter and sets its pattern to the default pattern: "#,##0.##".

public NSNumberFormatter(String pattern)

Creates an NSFormatter and sets its pattern to pattern. If pattern is illegal, the constructor throws an IllegalArgumentException. See "Pattern String Syntax" (page 208) for an explanation of what makes a pattern legal.

See Also: setPattern

Static Methods

availableLocales

public static java.util.Locale[] availableLocales()

Returns a list of all installed locales.

defaultLocale

public static java.util.Locale defaultLocale()

Returns the default locale for all instances of NSNumberFormatter.

defaultLocalizesPattern

public static boolean defaultLocalizesPattern()

Returns true to indicate that the receiver's format will be localized for all new instances of NSNumberFormatter in your application. By default, patterns are not localized.

See Also: setDefaultLocalizesPattern

setDefaultLocale

public static void setDefaultLocale(Locale newLocale)

Sets according to newLocale the default locale of the receiver. Throws an IllegalArgumentException if newLocale is null.

setDefaultLocalizesPattern

public static void setDefaultLocalizesPattern(boolean newDefault)

Sets according to newDefault whether all new NSNumberFormatter objects in your application created after this method is invoked are set to be localized by NSNumberFormatter based on the locale. NSNumberFormatter will choose the appropriate currency symbol, decimal separator, thousands separator, string for zero, and string for not a number based on locale if newDefault is true. By default, NSNumberFormatters are not localized.

See Also: defaultLocalizesPattern

Instance Methods

allowsFloats

public boolean allowsFloats()

Returns true if the receiver allows as input floating point values (that is, values that include the period character (.)), false otherwise. When this is set to false, only integer values can be provided as input. The default is true.

attributedStringForNil

public String attributedStringForNil()

Deprecated in the Java Foundation framework. Don't use this method. Use stringForNull instead.

attributedStringForNotANumber

public String attributedStringForNotANumber()

Deprecated in the Java Foundation framework. Don't use this method. Use stringForNotANumber instead.

attributedStringForZero

public String attributedStringForZero()

Deprecated in the Java Foundation framework. Don't use this method. Use stringForZero instead.

currencySymbol

public String currencySymbol()

Returns a string representing the symbol the receiver uses to represent currency.

See Also: setCurrencySymbol

decimalSeparator

public String decimalSeparator()

Returns a string containing the character the receiver uses to represent decimal separators. By default this is the period character (.).

format

public StringBuffer format( Object object, StringBuffer toAppendTo, java.text.FieldPosition position)

Formats object to produce a string, appends the string to toAppendTo, and returns the resulting StringBuffer. The position parameter specifies an alignment field to place the formatted object. When the method returns, this parameter contains the position of the alignment field. See Sun's java.text.Format documentation for more information.

See Also: stringForObjectValue

format

public String format()

Deprecated in the Java Foundation framework. Don't use this method. Use pattern instead.

hasThousandSeparators

public boolean hasThousandSeparators()

Returns true to indicate that the receiver's format includes thousand separators, false otherwise. The default is false.

locale

public java.util.Locale locale()

Returns the current locale.

localizesFormat

public boolean localizesFormat()

Deprecated in the Java Foundation framework. Don't use this method. Use localizesPattern instead.

localizesPattern

public boolean localizesPattern()

Returns true to indicate that the receiver's format will be localized for a specific instance of NSNumberFormatter. By default, instances of NSNumberFormatter are not localized.

maximum

public java.math.BigDecimal maximum()

Returns the highest number allowed as input by the receiver.

minimum

public java.math.BigDecimal minimum()

Returns the lowest number allowed as input by the receiver.

negativeFormat

public String negativeFormat()

Deprecated in the Java Foundation framework. Don't use this method. Use negativePattern instead.

negativePattern

public String negativePattern()

Returns a string containing the pattern the receiver uses to display negative numbers.

See Also: positivePattern, setPattern

objectValueForString

public Object objectValueForString(String inString) throws java.text.ParseException

Returns a number (a java.math.BigDecimal object) by parsing inString according to the receiver's pattern. Throws a ParseException if the conversion fails for any reason.

See Also: setPattern

parseObject

public Object parseObject( String source, java.text.ParsePosition status)

public Object parseObject(String source) throws java.text.ParseException

Parses a string to produce an object. See Sun's java.text.Format documentation for more information.

See Also: objectValueForString

pattern

public String pattern()

Returns a string containing the pattern the receiver uses to format numbers.

See Also: setPattern

positiveFormat

public String positiveFormat()

Deprecated in the Java Foundation framework. Don't use this method. Use positivePattern instead.

positivePattern

public String positivePattern()

Returns a string containing the pattern the receiver uses to format positive numbers.

See Also: setPattern, setNegativePattern

roundingBehavior

public int roundingBehavior()

Returns an integer indicating the rounding behavior used by the receiver.

setAllowsFloats

public void setAllowsFloats(boolean flag)

Sets according to flag whether the receiver allows as input floating point values (that is, values that include the period character (.)). By default, floating point values are allowed as input.

setAttributedStringForNil

public void setAttributedStringForNil(String string)

Deprecated in the Java Foundation framework. Don't use this method. Use setStringForNull instead.

setAttributedStringForNotANumber

public void setAttributedStringForNotANumber(String string)

Deprecated in the Java Foundation framework. Don't use this method. Use setStringForNotANumber instead.

setAttributedStringForZero

public void setAttributedStringForZero(String string)

Deprecated in the Java Foundation framework. Don't use this method. Use setStringForZero instead.

setCurrencySymbol

public void setCurrencySymbol(String newSymbol)

Sets the string the receiver uses to represent currency.

See Also: currencySymbol

setDecimalSeparator

public void setDecimalSeparator(String aString)

Sets the character the receiver uses as a decimal separator to newSeparator. If newSeparator contains multiple characters, only the first one is used. Throws an IllegalArgumentException if aString is null or has length other than one character.

setFormat

public void setFormat(String format)

Deprecated in the Java Foundation framework. Don't use this method. Use setPattern instead.

setHasThousandSeparators

public void setHasThousandSeparators(boolean flag)

Sets according to flag whether the receiver uses thousand separators. When flag is false, thousand separators are disabled for both positive and negative formats (even if you've set them through another means, such as setPattern). When flag is true, thousand separators are used. In addition to using this method to add thousand separators to your format, you can also use it to disable thousand separators if you've set them using another method. The default is false (though you in effect change this setting to true when you set thousand separators through any means, such as setPattern)

setLocale

public void setLocale(java.util.Locale newLocale)

Sets according to newLocale the current locale of the receiver. Throws an IllegalArgumentException if newLocale is null.

setLocalizesFormat

public void setLocalizesFormat(boolean newDefault)

Deprecated for the Foundation framework. Don't use this method. Use setLocalizesPatterninstead.

setLocalizesPattern

public void setLocalizesPattern(boolean newDefault)

Sets according to newDefault whether the receiver's pattern is set to be localized by NSNumberFormatter based on the locale. NSNumberFormatter will choose the appropriate currency symbol, decimal separator, thousands separator, string for zero, and string for not a number based on locale if newDefault is true. By default, NSNumberFormatters are not localized.

setMaximum

public void setMaximum(java.math.BigDecimal aMaximum)

Sets the highest number the receiver allows as input to aMaximum. Throws an IllegalArgumentException if aMaximum is not of type BigDecimal.

setMinimum

public void setMinimum(java.math.BigDecimal aMinimum)

Sets the lowest number the receiver allows as input to aMinimum. Throws an IllegalArgumentException if aMinimum is not of type BigDecimal.

setNegativeFormat

public void setNegativeFormat(String format)

Deprecated in the Java Foundation framework. Don't use this method. Use setNegativePattern instead.

setNegativePattern

public void setNegativePattern(String aString)

Sets the pattern the receiver uses to display positive numbers to pattern. If pattern is illegal, the method throws an IllegalArgumentException. See "Pattern String Syntax" (page 208) for an explanation of what makes a pattern legal. Invokes the private method validatePattern() which throws an IllegalArgumentException if the pattern is null, the pattern string is empty, or the string does not contain one of the characters in ",._#0123456789".

See Also: setPattern

setPattern

public void setPattern(String aPattern)

Sets the receiver's format to the string aPattern. This pattern can consist of one, two, or three parts separated by ";". The first part of the string represents the positive pattern, the second part of the string represents the zero value, and the last part of the string represents the negative pattern. If the string just has two parts, the first one becomes the positive pattern, and the second one becomes the negative pattern. If the string just has one part, it becomes the positive pattern, and default formats are provided for zero and negative values based on the positive format. For more discussion of this subject, see the section "Creating an Instance of NSNumberFormatter" (page 207) in the Class Description. If the positive, negative, or zero pattern is illegal, the method throws an IllegalArgumentException. See "Pattern String Syntax" (page 208) for an explanation of what makes a pattern legal.

The following code excerpt shows the three different approaches for setting an NSNumberFormatter object's format using setPattern:



NSNumberFormatter numberFormatter = new NSNumberFormatter();

// specify just positive format
numberFormatter.setPattern("$#,##0.00");

// specify positive and negative formats
numberFormatter.setPattern("$#,##0.00;($#,##0.00)");

// specify positive, zero, and negative formats
numberFormatter.setFormat("$#,###.00;0.00;($#,##0.00)");

See Also: pattern

setPositiveFormat

public void setPositiveFormat(String format)

Deprecated in the Java Foundation framework. Don't use this method. Use setPositivePattern instead.

setPositivePattern

public void setPositivePattern(String pattern)

See Also: setPattern

setRoundingBehavior

public void setRoundingBehavior(int newRoundingBehavior)

Sets the receiver's rounding behavior to newRoundingBehavior. Throws an IllegalArgumentException if newRoundingBehavior is not one of the standard rounding modes: NSRoundDown, NSRoundUp, NSRoundPlain, NSRoundBankers. Consult the Foundation functions and constants documentation for complete information on rounding modes.

setStringForNotANumber

public void setStringForNotANumber(String newString)

Sets the string the receiver uses to display "not a number" to newString. Throws an IllegalArgumentException if newString is null.

setStringForNull

public void setStringForNull(String newString)

Sets the string the receiver uses to display null values to newString. Throws an IllegalArgumentException if newString is null.

setStringForZero

public void setStringForZero(String aString)

Sets the string the receiver uses to display zero values to newString.

setThousandSeparator

public void setThousandSeparator(String newSeparator)

Sets the character the receiver uses as a thousand separator to newSeparator. If newSeparator contains multiple characters, only the first one is used. If you don't have thousand separators enabled through any other means (such as setPattern), using this method enables them. Throws an IllegalArgumentException if newSeparator is null or has length other than one character.

stringForNotANumber

public String stringForNotANumber()

Returns the string the receiver uses to display "not a number" values. By default "not a number" values are displayed as the string "NaN".

stringForNull

public String stringForNull()

Returns the string the receiver uses to display null values. By default, null values are displayed as an empty string.

stringForObjectValue

public String stringForObjectValue(Object object) throws IllegalArgumentException

Returns a string representing object formatted according to the receiver's pattern. Throws an IllegalArgumentException if object is not an instance of Number.

See Also: setPattern

stringForZero

public String stringForZero()

Returns the string the receiver uses to display zero values. By default zero values are displayed according to the format specified for positive values; for more discussion of this subject see the section "Creating an Instance of NSNumberFormatter" (page 207) in the Class Description.

thousandSeparator

public String thousandSeparator()

Returns a string containing the character the receiver uses to represent thousand separators. By default this is the comma character (,). Note that the return value doesn't indicate whether thousand separators are enabled.