com.webobjects.foundation
Class NSNumberFormatter

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

All Implemented Interfaces:

Cloneable, Serializable

public class NSNumberFormatter

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:

  
  // use setPattern:
  numberFormatter.setPattern("#,###");
 
  // use setHasThousandSeparators:
  numberFormatter.setHasThousandSeparators(true);
 
  // use setThousandSeparator:
  numberFormatter.setThousandSeparator("_");
  

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:

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

  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:

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

Nested Class Summary

Nested classes 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 stringForNull().
String	attributedStringForNotANumber() Deprecated. Use stringForNotANumber().
String	attributedStringForZero() Deprecated. Use 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 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 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 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 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 setStringForNull(java.lang.String).
void	setAttributedStringForNotANumber(String newString) Deprecated. Use setStringForNotANumber(java.lang.String).
void	setAttributedStringForZero(String newString) Deprecated. Use 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 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 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 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 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

DefaultPattern

public static final String DefaultPattern

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

See Also:

roundingBehavior(), setRoundingBehavior(int)

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:

roundingBehavior(), setRoundingBehavior(int)

RoundBankers

public static final int RoundBankers

Rounding mode : Bankers. Equivalent to BigDecimal.ROUND_HALF_EVEN.

See Also:

roundingBehavior(), setRoundingBehavior(int), Constant Field Values

RoundDown

public static final int RoundDown

Rounding mode : Down. Equivalent to BigDecimal.ROUND_FLOOR.

See Also:

roundingBehavior(), setRoundingBehavior(int), Constant Field Values

RoundPlain

public static final int RoundPlain

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

See Also:

roundingBehavior(), setRoundingBehavior(int), Constant Field Values

RoundUp

public static final int RoundUp

Rounding mode : Up. Equivalent to BigDecimal.ROUND_CEILING.

See Also:

roundingBehavior(), setRoundingBehavior(int), Constant Field Values

Constructor Detail

NSNumberFormatter

public NSNumberFormatter()

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

See Also:

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:

setPattern(java.lang.String)

Method Detail

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

attributedStringForNil

public String attributedStringForNil()

Deprecated. Use stringForNull().

Returns:

stringForNull

attributedStringForNotANumber

public String attributedStringForNotANumber()

Deprecated. Use stringForNotANumber().

Returns:

stringForNotANumber

attributedStringForZero

public String attributedStringForZero()

Deprecated. Use stringForZero().

Returns:

stringForZero

availableLocales

public static Locale[] availableLocales()

Returns:

list of all installed locales.

See Also:

NumberFormat.getAvailableLocales()

currencySymbol

public String currencySymbol()

Returns:

string representing the symbol this NSNumberFormatter uses for currency

See Also:

setCurrencySymbol(java.lang.String), DecimalFormatSymbols

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

defaultLocale

public static Locale defaultLocale()

Returns:

default locale for all instances of NSNumberFormatter.

See Also:

Locale, Locale.getDefault()

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:

setDefaultLocalizesPattern(boolean), DecimalFormatSymbols

format

public String format()

Deprecated. Use pattern().

Returns:

pattern

See Also:

pattern()

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.

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:

stringForObjectValue(java.lang.Object)

hasThousandSeparators

public boolean hasThousandSeparators()

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

Returns:

true if a thousands separator is used.

locale

public Locale locale()

Returns:

the current locale.

See Also:

Locale

localizesFormat

public boolean localizesFormat()

Deprecated. Use localizesPattern().

Returns:

true if this formatter localizes its pattern String

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

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.

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.

negativeFormat

public String negativeFormat()

Deprecated. Use negativePattern().

Returns:

negativePattern

negativePattern

public String negativePattern()

Returns:

the pattern this NSNumberFormatter uses to display negative numbers.

See Also:

setNegativePattern(java.lang.String), setPattern(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), stringForObjectValue(java.lang.Object)

parseObject

public Object parseObject(String source,
                          ParsePosition status)

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

Parameters:

source - the input string

status - the position where to parse

Returns:

the java.lang.Number object parsed from the string

See Also:

objectValueForString(java.lang.String)

parseObject

public Object parseObject(String source)
                   throws ParseException

Parses a string to produce an object.

Parameters:

source - the input string

Returns:

the object parsed from the string

Throws:

ParseException

See Also:

NSTimestampFormatter.setDefaultParseTimeZone(com.webobjects.foundation.NSTimeZone), objectValueForString(java.lang.String)

pattern

public String pattern()

Returns:

the patterns used by this NSNumberFormatter to format postive; zero; and negative numbers respectively

See Also:

setPattern(java.lang.String)

positiveFormat

public String positiveFormat()

Deprecated. Use positivePattern().

Returns:

positivePattern

positivePattern

public String positivePattern()

Returns:

the pattern this NSNumberFormatter uses to format positive numbers.

See Also:

setPattern(java.lang.String), setPositivePattern(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:

RoundDown, RoundUp, RoundPlain, RoundBankers

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

setAttributedStringForNil

public void setAttributedStringForNil(String newString)

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

Parameters:

newString - setStringForNull

setAttributedStringForNotANumber

public void setAttributedStringForNotANumber(String newString)

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

Parameters:

newString - the input string

setAttributedStringForZero

public void setAttributedStringForZero(String newString)

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

Parameters:

newString - the input string

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:

currencySymbol(), DecimalFormatSymbols

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:

setPattern(java.lang.String), setThousandSeparator(java.lang.String)

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

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:

defaultLocalizesPattern(), DecimalFormatSymbols

setFormat

public void setFormat(String pattern)

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

Parameters:

pattern - the new input pattern

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:

setPattern(java.lang.String)

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

setLocalizesFormat

public void setLocalizesFormat(boolean doLocalization)

Deprecated. Use setLocalizesPattern(boolean).

Parameters:

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

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

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

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

setNegativeFormat

public void setNegativeFormat(String pattern)

Deprecated. Use setNegativePattern(java.lang.String)

Use setNegativePattern instead.

Parameters:

pattern - the new pattern

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:

setPattern(java.lang.String), setPositivePattern(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:

pattern()

setPositiveFormat

public void setPositiveFormat(String pattern)

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

Parameters:

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

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:

setPattern(java.lang.String), setNegativePattern(java.lang.String)

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:

roundingBehavior()

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

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

setStringForZero

public void setStringForZero(String newString)

Sets the string this NSNumberFormatter uses to display zero values.

Parameters:

newString - the string representing zero values

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:

setPattern(java.lang.String), setDecimalSeparator(java.lang.String)

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.

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

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), objectValueForString(java.lang.String)

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.

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.