NSNumberFormatter (WebObjects 5.4.2 Reference)

Overview

Package

Class

Tree

Deprecated

Index

Help

WebObjects 5.4.2

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.webobjects.foundation
Class NSNumberFormatter

java.lang.Object
  java.text.Format
      com.webobjects.foundation.NSNumberFormatter

All Implemented Interfaces:: Serializable, Cloneable

public class NSNumberFormatter
extends Format
extends Format

NSNumberFormatter converts between java.lang.Number 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, so caution should be exercised when sharing them.

Creating an Instance of NSNumberFormatter

The most common technique for creating an 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 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:

Numbers
Pattern strings can include numeric characters. Wherever a number is included in a pattern string, the number is displayed unless an input character in the same relative position overwrites it. For example, suppose for 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.
Separators
Pattern 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.
Placeholders
You use the pound sign character (#) to represent numeric characters that will be input by the user. For example, for 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 for displaying patterns in the user interface.
Spaces
To 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.
Currency
The dollar sign character ($) is the canonical currency mark in pattern strings. If the setCurrencySymbol method is used, the new currency symbol will be used whenever the presence of "$" in the pattern string implies the use of a currency symbol. Note that the pattern string itself is not altered by changing the currency symbol.

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: thousands 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 the thousands separator:

  <blockquote>

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

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

    // use setThousandSeparator:
    numberFormatter.setThousandSeparator("_");
    </blockquote>

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

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

  <blockquote>

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

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 multiple characters are specified in the arguments to setThousandSeparator and setDecimalSeparator, an IllegalArgumentException will be thrown.

You can't set the same character to represent thousand and decimal separators. If you try, the two separator characters will be swapped.

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.

Valid Patterns

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

  <blockquote>
    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)");
    </blockquote>

See Also:: Format, NSNumberFormatter.thousandSeparator(), NSNumberFormatter.decimalSeparator(), NSNumberFormatter.roundingBehavior(), NSNumberFormatter.setPattern(java.lang.String), NSNumberFormatter.setNegativePattern(java.lang.String), NSNumberFormatter.setPositivePattern(java.lang.String), NSNumberFormatter.setThousandSeparator(java.lang.String), NSNumberFormatter.setDecimalSeparator(java.lang.String), NSNumberFormatter.setThousandSeparator(java.lang.String), NSNumberFormatter.setDecimalSeparator(java.lang.String), NSNumberFormatter.setDefaultLocalizesPattern(boolean), NSNumberFormatter.setLocalizesPattern(boolean), NSNumberFormatter.setRoundingBehavior(int), Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.text.Format
`Format.Field`

Field Summary
`static String`	`DefaultPattern` The default pattern string used by the no-argument constructor: `#,##0.##`.
`static BigDecimal`	`NSDecimalNotANumber` The constant BigDecimal object as a place holder for all numbers incapable of being represented as real numbers (NaN).
`static int`	`RoundBankers` Rounding mode : Bankers.
`static int`	`RoundDown` Rounding mode : Down.
`static int`	`RoundPlain` Rounding mode : Plain.
`static int`	`RoundUp` Rounding mode : Up.

Constructor Summary
`NSNumberFormatter()` Creates an NSNumberFormatter and sets its pattern to the default pattern.
`NSNumberFormatter(String pattern)` Creates an NSFormatter and sets its pattern to `pattern`.

Method Summary
`boolean`	`allowsFloats()` Indicates whether this NSNumberFormatter allows floating-point values as input.
`String`	`attributedStringForNil()` Deprecated. Use `NSNumberFormatter.stringForNull()`.
`String`	`attributedStringForNotANumber()` Deprecated. Use `NSNumberFormatter.stringForNotANumber()`.
`String`	`attributedStringForZero()` Deprecated. Use `NSNumberFormatter.stringForZero()`.
`static Locale[]`	`availableLocales()`
`String`	`currencySymbol()`
`String`	`decimalSeparator()` Returns the current decimal separator character as a String.
`static Locale`	`defaultLocale()`
`static boolean`	`defaultLocalizesPattern()` Returns true to indicate that the pattern will be localized for all new instances of NSNumberFormatter in your application.
`String`	`format()` Deprecated. Use `NSNumberFormatter.pattern()`.
`StringBuffer`	`format(Object obj, StringBuffer toAppendTo, FieldPosition pos)` Formats `obj` to produce a string, appends the string to `toAppendTo`, and returns the resulting StringBuffer.
`boolean`	`hasThousandSeparators()` Indicates whether this NSNumberFormatter's format includes a thousands separator.
`Locale`	`locale()`
`boolean`	`localizesFormat()` Deprecated. Use `NSNumberFormatter.localizesPattern()`.
`boolean`	`localizesPattern()` Indicates whether this NSNumberFormatter's pattern is localized.
`BigDecimal`	`maximum()` The default, no maximal value, is represented with the constant `NSDecimalNotANumber`.
`BigDecimal`	`minimum()` The default, no minimum value, is represented with the constant `NSDecimalNotANumber`.
`String`	`negativeFormat()` Deprecated. Use `NSNumberFormatter.negativePattern()`.
`String`	`negativePattern()`
`Object`	`objectValueForString(String inString)` Converts a string to a java.lang.Number using this NSNumberFormatter's pattern.
`Object`	`parseObject(String source)` Parses a string to produce an object.
`Object`	`parseObject(String source, ParsePosition status)` Parses a string using the current pattern to produce a Number object.
`String`	`pattern()`
`String`	`positiveFormat()` Deprecated. Use `NSNumberFormatter.positivePattern()`.
`String`	`positivePattern()`
`int`	`roundingBehavior()` Provides the rounding behavior that this NSNumberFormatter uses.
`void`	`setAllowsFloats(boolean allowsRealNumbers)` Sets whether this NSNumberFormatter allows as input floating-point values (that is, values that include the decimal-separator character).
`void`	`setAttributedStringForNil(String newString)` Deprecated. Use `NSNumberFormatter.setStringForNull(java.lang.String)`.
`void`	`setAttributedStringForNotANumber(String newString)` Deprecated. Use `NSNumberFormatter.setStringForNotANumber(java.lang.String)`.
`void`	`setAttributedStringForZero(String newString)` Deprecated. Use `NSNumberFormatter.setStringForZero(java.lang.String)`.
`void`	`setCurrencySymbol(String newSymbol)` Sets the string this NSNumberFormatter uses to represent currency.
`void`	`setDecimalSeparator(String newSeparator)` Sets the first character of `newSeparator` as the decimal separator for this NSNumberFormatter If `newSeparator` is the current thousands' separator for this formatter, the thousands' separator and the decimal separator are swapped.
`static void`	`setDefaultLocale(Locale newLocale)` Sets the default locale of this NSNumberFormatter.
`static void`	`setDefaultLocalizesPattern(boolean newDefault)` Sets whether all new NSNumberFormatter instances should localize their patterns based on the locale.
`void`	`setFormat(String pattern)` Deprecated. Use `NSNumberFormatter.setPattern(java.lang.String)`.
`void`	`setHasThousandSeparators(boolean newThousandsUsage)` Sets whether this NSNumberFormatter uses a thousands separator.
`void`	`setLocale(Locale newLocale)` Sets the locale of this NSNumberFormatter.
`void`	`setLocalizesFormat(boolean doLocalization)` Deprecated. Use `NSNumberFormatter.setLocalizesPattern(boolean)`.
`void`	`setLocalizesPattern(boolean newDefault)` Sets whether this NSNumberFormatter's pattern should be localized.
`void`	`setMaximum(BigDecimal newMaximum)` Sets the highest number this NSNumberFormatter allows as input.
`void`	`setMinimum(BigDecimal newMinimum)` Sets the minimum number this NSNumberFormatter allows as input.
`void`	`setNegativeFormat(String pattern)` Deprecated. Use `NSNumberFormatter.setNegativePattern(java.lang.String)`
`void`	`setNegativePattern(String pattern)` Sets the pattern this NSNumberFormatter uses to display negative numbers.
`void`	`setPattern(String pattern)` Sets this NSNumberFormatter's pattern.
`void`	`setPositiveFormat(String pattern)` Deprecated. Use `NSNumberFormatter.setPositivePattern(java.lang.String)`.
`void`	`setPositivePattern(String pattern)` Sets the pattern this NSNumberFormatter uses to display positive numbers.
`void`	`setRoundingBehavior(int newBehavior)` Sets this NSNumberFormatter's rounding behavior.
`void`	`setStringForNotANumber(String newString)` Sets the string this NSNumberFormatter uses to display values that are incapable of being displayed as real numbers.
`void`	`setStringForNull(String newString)` Sets the string this NSNumberFormatter uses to represent `null` values.
`void`	`setStringForZero(String newString)` Sets the string this NSNumberFormatter uses to display zero values.
`void`	`setThousandSeparator(String newSeparator)` Sets the first character of `newSeparator` as the thousands separator for this NSNumberFormatter If `newSeparator` is the current decimal separator for this formatter, the thousands' separator and the decimal separator are swapped.
`String`	`stringForNotANumber()` Returns the string this NSNumberFormatter displays for numeric values incapable of being displayed as real numbers.
`String`	`stringForNull()` Returns the string this NSNumberFormatter uses to display `null` values.
`String`	`stringForObjectValue(Object inNumber)` Formats an object into a string using this NSNumberFormatter's pattern.
`String`	`stringForZero()` Returns the zero-value string.
`String`	`thousandSeparator()` Returns a string containing the single character this NSNumberFormatter uses to represent the thousands separator.

Methods inherited from class java.text.Format
`clone, format, formatToCharacterIterator`

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

RoundDown

public static final int RoundDown

Rounding mode : Down. Equivalent to BigDecimal.ROUND_FLOOR.

See Also:: NSNumberFormatter.roundingBehavior(), NSNumberFormatter.setRoundingBehavior(int), Constant Field Values

RoundUp

public static final int RoundUp

Rounding mode : Up. Equivalent to BigDecimal.ROUND_CEILING.

See Also:: NSNumberFormatter.roundingBehavior(), NSNumberFormatter.setRoundingBehavior(int), Constant Field Values

RoundPlain

public static final int RoundPlain

Rounding mode : Plain. The default. Equivalent to BigDecimal.ROUND_HALF_UP.

See Also:: NSNumberFormatter.roundingBehavior(), NSNumberFormatter.setRoundingBehavior(int), Constant Field Values

RoundBankers

public static final int RoundBankers

Rounding mode : Bankers. Equivalent to BigDecimal.ROUND_HALF_EVEN.

See Also:: NSNumberFormatter.roundingBehavior(), NSNumberFormatter.setRoundingBehavior(int), Constant Field Values

DefaultPattern

public static final String DefaultPattern

The default pattern string used by the no-argument constructor: #,##0.##.

See Also:: NSNumberFormatter.roundingBehavior(), NSNumberFormatter.setRoundingBehavior(int), Constant Field Values

NSDecimalNotANumber

public static final BigDecimal NSDecimalNotANumber

The constant BigDecimal object as a place holder for all numbers incapable of being represented as real numbers (NaN).

See Also:: NSNumberFormatter.roundingBehavior(), NSNumberFormatter.setRoundingBehavior(int)

Constructor Detail

NSNumberFormatter

public NSNumberFormatter()

Creates an NSNumberFormatter and sets its pattern to the default pattern.

See Also:: NSNumberFormatter.DefaultPattern

NSNumberFormatter

public NSNumberFormatter(String pattern)

Creates an NSFormatter and sets its pattern to pattern.

Parameters:: pattern - the format string
Throws:: java.lang.IllegalArgumentException - if the pattern is invalid
See Also:: NSNumberFormatter.setPattern(java.lang.String)

Method Detail

decimalSeparator

public String decimalSeparator()

Returns the current decimal separator character as a String. The default is "."

Returns:: the decimal separator as a single character String

setDecimalSeparator

public void setDecimalSeparator(String newSeparator)

Sets the first character of newSeparator as the decimal separator for this NSNumberFormatter If newSeparator is the current thousands' separator for this formatter, the thousands' separator and the decimal separator are swapped.

Parameters:: newSeparator - the new decimal separator as a one character String
Throws:: IllegalArgumentException - newSeparator is null or not exactly one character
See Also:: NSNumberFormatter.setPattern(java.lang.String), NSNumberFormatter.setThousandSeparator(java.lang.String)

thousandSeparator

public String thousandSeparator()

Returns a string containing the single character this NSNumberFormatter uses to represent the thousands separator. By default, the thousands separator is the comma character (,). Note that the return value doesn't indicate whether the thousands separator is enabled.

Returns:: the string containing the character to use as the thousands separator.

setThousandSeparator

public void setThousandSeparator(String newSeparator)

Sets the first character of newSeparator as the thousands separator for this NSNumberFormatter If newSeparator is the current decimal separator for this formatter, the thousands' separator and the decimal separator are swapped. If using the thousands separator is disabled through any other means (such as setPattern), using this method enables them.

Parameters:: newSeparator - the new thousand separator. It must be exactly 1 character.
Throws:: IllegalArgumentException - if newSeparator is null or not exactly one character
See Also:: NSNumberFormatter.setPattern(java.lang.String), NSNumberFormatter.setDecimalSeparator(java.lang.String)

roundingBehavior

public int roundingBehavior()

Provides the rounding behavior that this NSNumberFormatter uses. The possible values are listed in the See Also section.

Returns:: The integer indicating the rounding behavior of this NSNumberFormatter.
See Also:: NSNumberFormatter.RoundDown, NSNumberFormatter.RoundUp, NSNumberFormatter.RoundPlain, NSNumberFormatter.RoundBankers

setRoundingBehavior

public void setRoundingBehavior(int newBehavior)

Sets this NSNumberFormatter's rounding behavior.

Parameters:: newBehavior - the rounding behavior to use
Throws:: IllegalArgumentException - newRoundingBehavior not valid
See Also:: NSNumberFormatter.roundingBehavior()

stringForZero

public String stringForZero()

Returns the zero-value string. By default zero values are displayed according to the format specified for positive values.

Returns:: the string this NSNumberFormatter uses to display zero values.

setStringForZero

public void setStringForZero(String newString)

Sets the string this NSNumberFormatter uses to display zero values.

Parameters:: newString - the string representing zero values

stringForNull

public String stringForNull()

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

Returns:: the string this NSNumberFormatter uses to display null values

setStringForNull

public void setStringForNull(String newString)

Sets the string this NSNumberFormatter uses to represent null values.

Parameters:: newString - the string representing null values
Throws:: IllegalArgumentException - if newString is null

stringForNotANumber

public String stringForNotANumber()

Returns the string this NSNumberFormatter displays for numeric values incapable of being displayed as real numbers.

NSNumberFormatters use the constant NSDecimalNotANumber to represent such numbers as BigDecimals.

Returns:: the string used to display numbers outside the set of real numbers.

setStringForNotANumber

public void setStringForNotANumber(String newString)

Sets the string this NSNumberFormatter uses to display values that are incapable of being displayed as real numbers.

NSNumberFormatters use the constant NSDecimalNotANumber to represent such numbers. NSDecimalNotANumber is a java.math.BigDecimal object.

By default, imaginary numbers are represented with the string "NaN".

Parameters:: newString - the string used for numbers outside the set of real numbers.
Throws:: IllegalArgumentException - if newString is null

attributedStringForZero

@Deprecated
public String attributedStringForZero()

Deprecated. Use NSNumberFormatter.stringForZero().

Returns:: stringForZero

setAttributedStringForZero

@Deprecated
public void setAttributedStringForZero(String newString)

Deprecated. Use NSNumberFormatter.setStringForZero(java.lang.String).

Parameters:: newString - the input string

attributedStringForNil

@Deprecated
public String attributedStringForNil()

Deprecated. Use NSNumberFormatter.stringForNull().

Returns:: stringForNull

setAttributedStringForNil

@Deprecated
public void setAttributedStringForNil(String newString)

Deprecated. Use NSNumberFormatter.setStringForNull(java.lang.String).

Parameters:: newString - setStringForNull

attributedStringForNotANumber

@Deprecated
public String attributedStringForNotANumber()

Deprecated. Use NSNumberFormatter.stringForNotANumber().

Returns:: stringForNotANumber

setAttributedStringForNotANumber

@Deprecated
public void setAttributedStringForNotANumber(String newString)

Deprecated. Use NSNumberFormatter.setStringForNotANumber(java.lang.String).

Parameters:: newString - the input string

hasThousandSeparators

public boolean hasThousandSeparators()

Indicates whether this NSNumberFormatter's format includes a thousands separator.

Returns:: true if a thousands separator is used.

setHasThousandSeparators

public void setHasThousandSeparators(boolean newThousandsUsage)

Sets whether this NSNumberFormatter uses a thousands separator. When newThousandsUsage is false, the thousands separator is disabled for both positive and negative formats (even if it is set through other means, such as setPattern). When newThousandsUsage is true, a thousands separator is used.

Parameters:: newThousandsUsage - true for this NSNumberFormatter to use a thousands separator
See Also:: NSNumberFormatter.setPattern(java.lang.String)

allowsFloats

public boolean allowsFloats()

Indicates whether this NSNumberFormatter allows floating-point values as input. By default, floating-point values are allowed.

Returns:: true if this NSNumberFormatter allows as input floating-point values (that is, values that include the period character (.))

setAllowsFloats

public void setAllowsFloats(boolean allowsRealNumbers)

Sets whether this NSNumberFormatter allows as input floating-point values (that is, values that include the decimal-separator character). By default, floating-point values are allowed as input.

Parameters:: allowsRealNumbers - true to allow floating-point numbers

minimum

public BigDecimal minimum()

The default, no minimum value, is represented with the constant NSDecimalNotANumber.

Returns:: the lowest number allowed as input by this NSNumberFormatter, or NSDecimalNotANumber if no lower bound exists.

setMinimum

public void setMinimum(BigDecimal newMinimum)

Sets the minimum number this NSNumberFormatter allows as input. The default, no minimum value, is represented with the constant NSDecimalNotANumber.

Parameters:: newMinimum - the lowest number allowable, or NSDecimalNotANumber to remove the minimum.
Throws:: IllegalArgumentException - if newMinimum is null

maximum

public BigDecimal maximum()

The default, no maximal value, is represented with the constant NSDecimalNotANumber.

Returns:: the largest number allowed as input by this NSNumberFormatter, or NSDecimalNotANumber if no upper bound exists.

setMaximum

public void setMaximum(BigDecimal newMaximum)

Sets the highest number this NSNumberFormatter allows as input. The default, no maximal value, is represented with the constant NSDecimalNotANumber.

Parameters:: newMaximum - the highest number allowable, or NSDecimalNotANumber to remove the maximum
Throws:: IllegalArgumentException - newMaximum is null

negativePattern

public String negativePattern()

Returns:: the pattern this NSNumberFormatter uses to display negative numbers.
See Also:: NSNumberFormatter.setNegativePattern(java.lang.String), NSNumberFormatter.setPattern(java.lang.String)

setNegativePattern

public void setNegativePattern(String pattern)

Sets the pattern this NSNumberFormatter uses to display negative numbers.

Parameters:: pattern - the pattern to use to display negative numbers
Throws:: IllegalArgumentException - pattern is null, empty, or does not contain any of the characters in the string ",._#0123456789".
See Also:: NSNumberFormatter.setPattern(java.lang.String), NSNumberFormatter.setPositivePattern(java.lang.String)

positivePattern

public String positivePattern()

Returns:: the pattern this NSNumberFormatter uses to format positive numbers.
See Also:: NSNumberFormatter.setPattern(java.lang.String), NSNumberFormatter.setPositivePattern(java.lang.String)

setPositivePattern

public void setPositivePattern(String pattern)

Sets the pattern this NSNumberFormatter uses to display positive numbers.

Parameters:: pattern - the pattern to use to display positive numbers
Throws:: IllegalArgumentException - pattern is null, empty, or doesn't contain any of the characters in the string ",._#0123456789".
See Also:: NSNumberFormatter.setPattern(java.lang.String), NSNumberFormatter.setNegativePattern(java.lang.String)

pattern

public String pattern()

Returns:: the patterns used by this NSNumberFormatter to format postive; zero; and negative numbers respectively
See Also:: NSNumberFormatter.setPattern(java.lang.String)

setPattern

public void setPattern(String pattern)

Sets this NSNumberFormatter's pattern. 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 has just two parts, the first one becomes the positive pattern, and the second one becomes the negative pattern. If the string has just one part, it becomes the positive pattern, and default formats are provided for zero and negative values based on the positive format. The following code excerpt shows the three different approaches for setting an NSNumberFormatter object's format using setPattern:

 NSNumberFormatter numberFormatter = new NSNumberFormatter();
 numberFormatter.setPattern("$#,##0.00"); // specify just positive format
 numberFormatter.setPattern("$#,##0.00;($#,##0.00)"); // specify positive and negative formats
 numberFormatter.setPattern("$#,###.00;0.00;($#,##0.00)"); // specify positive, zero, and negative formats

Parameters:: pattern - the format in which the object is to be formatted
Throws:: IllegalArgumentException - if the pattern is null, invalid, or has more than 3 segments.
See Also:: NSNumberFormatter.pattern()

negativeFormat

@Deprecated
public String negativeFormat()

Deprecated. Use NSNumberFormatter.negativePattern().

Returns:: negativePattern

setNegativeFormat

@Deprecated
public void setNegativeFormat(String pattern)

Deprecated. Use NSNumberFormatter.setNegativePattern(java.lang.String)

Use setNegativePattern instead.

Parameters:: pattern - the new pattern

positiveFormat

@Deprecated
public String positiveFormat()

Deprecated. Use NSNumberFormatter.positivePattern().

Returns:: positivePattern

setPositiveFormat

@Deprecated
public void setPositiveFormat(String pattern)

Deprecated. Use NSNumberFormatter.setPositivePattern(java.lang.String).

Parameters:: pattern - the new pattern this NSNumberFormatter is to use to display positive numbers

format

@Deprecated
public String format()

Deprecated. Use NSNumberFormatter.pattern().

Returns:: pattern
See Also:: NSNumberFormatter.pattern()

setFormat

@Deprecated
public void setFormat(String pattern)

Deprecated. Use NSNumberFormatter.setPattern(java.lang.String).

Parameters:: pattern - the new input pattern

localizesFormat

@Deprecated
public boolean localizesFormat()

Deprecated. Use NSNumberFormatter.localizesPattern().

Returns:: true if this formatter localizes its pattern String

setLocalizesFormat

@Deprecated
public void setLocalizesFormat(boolean doLocalization)

Deprecated. Use NSNumberFormatter.setLocalizesPattern(boolean).

Parameters:: doLocalization - true if this formatter should localize its pattern String, otherwise false

stringForObjectValue

public String stringForObjectValue(Object inNumber)
                            throws IllegalArgumentException

Formats an object into a string using this NSNumberFormatter's pattern. This method is equivalent to java.text.Format.format

Parameters:: inNumber - the java.lang.Number object to be formatted
Returns:: the pretty printed String
Throws:: IllegalArgumentException - inNumber is not a java.lang.Number
See Also:: Format.format(Object obj), NSNumberFormatter.objectValueForString(java.lang.String)

objectValueForString

public Object objectValueForString(String inString)
                            throws ParseException

Converts a string to a java.lang.Number using this NSNumberFormatter's pattern. This method is equivalent to java.Text.Format.parseObject

Parameters:: inString - string containing a numeric value to be parsed
Returns:: java.lang.Number based on the parsed String (using this NSNumberFormatter's pattern)
Throws:: ParseException - conversion failure
See Also:: Format.parseObject(String source), NSNumberFormatter.stringForObjectValue(java.lang.Object)

format

public StringBuffer format(Object obj,
                           StringBuffer toAppendTo,
                           FieldPosition pos)

Formats obj to produce a string, appends the string to toAppendTo, and returns the resulting StringBuffer. The pos parameter specifies an alignment field to place the formatted object. When the method returns, this parameter contains the position of the alignment field.

Specified by:: format in class Format

Parameters:: obj - the input object to be appended to; toAppendTo - the string to be appended; pos - where the formatted field is to be placed
Returns:: the object appended with the string buffer
See Also:: NSNumberFormatter.stringForObjectValue(java.lang.Object)

parseObject

public Object parseObject(String source,
                          ParsePosition status)

Parses a string using the current pattern to produce a Number object.

Specified by:: parseObject in class Format

Parameters:: source - the input string; status - the position where to parse
Returns:: the java.lang.Number object parsed from the string
See Also:: NSNumberFormatter.objectValueForString(java.lang.String)

parseObject

public Object parseObject(String source)
                   throws ParseException

Parses a string to produce an object.

Overrides:: parseObject in class Format

Parameters:: source - the input string
Returns:: the object parsed from the string
Throws:: ParseException
See Also:: NSTimestampFormatter.setDefaultParseTimeZone(com.webobjects.foundation.NSTimeZone), NSNumberFormatter.objectValueForString(java.lang.String)

availableLocales

public static Locale[] availableLocales()

Returns:: list of all installed locales.
See Also:: NumberFormat.getAvailableLocales()

defaultLocale

public static Locale defaultLocale()

Returns:: default locale for all instances of NSNumberFormatter.
See Also:: Locale, Locale.getDefault()

setDefaultLocale

public static void setDefaultLocale(Locale newLocale)

Sets the default locale of this NSNumberFormatter.

Parameters:: newLocale - the new default locale of this NSNumberFormatter
Throws:: IllegalArgumentException - newLocale is null
See Also:: Locale

locale

public Locale locale()

Returns:: the current locale.
See Also:: Locale

setLocale

public void setLocale(Locale newLocale)

Sets the locale of this NSNumberFormatter. The locale does not have an active effect on the formatter until setLocalizesPattern(true) is invoked.

Parameters:: newLocale - the new locale to be set as the locale of this NSNumberFormatter
Throws:: IllegalArgumentException - newLocale is null
See Also:: Locale

defaultLocalizesPattern

public static boolean defaultLocalizesPattern()

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

Returns:: true if new instances of NSNumberFormatter use localized patterns
See Also:: NSNumberFormatter.setDefaultLocalizesPattern(boolean), DecimalFormatSymbols

setDefaultLocalizesPattern

public static void setDefaultLocalizesPattern(boolean newDefault)

Sets whether all new NSNumberFormatter instances should localize their patterns based on the locale. The NSNumberFormatter factory will choose the appropriate currency symbol, decimal separator, thousands separator, string for zero, and string for NaN based on locale. By default, NSNumberFormatters are not localized.

Parameters:: newDefault - to localize new instances
See Also:: NSNumberFormatter.defaultLocalizesPattern(), DecimalFormatSymbols

localizesPattern

public boolean localizesPattern()

Indicates whether this NSNumberFormatter's pattern is localized. By default, instances of NSNumberFormatter are not localized.

Returns:: true when this NSNumberFormatter's format uses localization
See Also:: DecimalFormatSymbols

setLocalizesPattern

public void setLocalizesPattern(boolean newDefault)

Sets whether this NSNumberFormatter's pattern should be localized. When newDefault is true, NSNumberFormatter chooses the appropriate currency symbol, thousands separator, string for zero, and string for NaN based on locale By default, NSNumberFormatters are not localized.

Parameters:: newDefault - true to localize this NSNumberFormatter
See Also:: DecimalFormatSymbols

currencySymbol

public String currencySymbol()

Returns:: string representing the symbol this NSNumberFormatter uses for currency
See Also:: NSNumberFormatter.setCurrencySymbol(java.lang.String), DecimalFormatSymbols

setCurrencySymbol

public void setCurrencySymbol(String newSymbol)

Sets the string this NSNumberFormatter uses to represent currency. The pattern string itself remains unchanged. The currency symbol is used instead of "$" whenever the pattern string implies a "$" should be used while formatting numbers.

Parameters:: newSymbol - the input symbol
See Also:: NSNumberFormatter.currencySymbol(), DecimalFormatSymbols

Overview

Package

Class

Tree

Deprecated

Index

Help

Last updated June 2008

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.webobjects.foundation Class NSNumberFormatter

Creating an Instance of NSNumberFormatter

Pattern String Syntax

Using Separators

Localization

Valid Patterns

RoundDown

RoundUp

RoundPlain

RoundBankers

DefaultPattern

NSDecimalNotANumber

NSNumberFormatter

NSNumberFormatter

decimalSeparator

setDecimalSeparator

thousandSeparator

setThousandSeparator

roundingBehavior

setRoundingBehavior

stringForZero

setStringForZero

stringForNull

setStringForNull

stringForNotANumber

setStringForNotANumber

attributedStringForZero

setAttributedStringForZero

attributedStringForNil

setAttributedStringForNil

attributedStringForNotANumber

setAttributedStringForNotANumber

hasThousandSeparators

setHasThousandSeparators

allowsFloats

setAllowsFloats

minimum

setMinimum

maximum

setMaximum

negativePattern

setNegativePattern

positivePattern

setPositivePattern

pattern

setPattern

negativeFormat

setNegativeFormat

positiveFormat

setPositiveFormat

format

setFormat

localizesFormat

setLocalizesFormat

stringForObjectValue

objectValueForString

format

parseObject

parseObject

availableLocales

defaultLocale

setDefaultLocale

locale

setLocale

defaultLocalizesPattern

setDefaultLocalizesPattern

localizesPattern

setLocalizesPattern

currencySymbol

setCurrencySymbol

com.webobjects.foundation
Class NSNumberFormatter