PATH  Documentation > Mac OS X > Foundation Reference: Java



Table of Contents

NSNumberFormatter


Inherits from:
NSFormatter : NSObject
Package:
com.apple.yellow.foundation


Class Description


Instances of NSNumberFormatter format the textual representation of cells that contain Numbers and convert textual representations of numeric values into Numbers. The representation encompasses integers, floats, and doubles; floats and doubles can be formatted to a specified decimal position. NSNumberFormatters can also impose ranges on the numeric values cells can accept.

NSControl provides delegation methods that permit you to validate cell contents and to handle errors in formatting. See the specification of the NSFormatter class for details.

When a cell with a NSNumberFormatter is copied, the new cell retains the NSNumberFormatter object instead of copying it. You remove an NSNumberFormatter from a cell by specifying null as the argument of NSCell's setFormatter method.

Instances of NSNumberFormatter are mutable.


Creating an Instance of NSNumberFormatter


The easiest way to use NSNumberFormatter is to drag a formatter from the palette onto a control in Interface Builder. However, if you're not using Interface Builder to create your user interface or if you simply want more fine-grained control over an NSNumberFormatter (for example, to change the text attributes of the values displayed), you can create and manipulate instances of the class programmatically.

To create an NSNumberFormatter, allocate an instance of NSNumberFormatter and use one or more of NSNumberFormatter's "set format" methods to set its format. You then use NSCell's setFormatter method to associate the NSNumberFormatter instance with a cell.

The value of a cell (NSCell) is represented by an object, which in this case would typically be an Number object. When this value needs to be displayed or edited, the cell passes its object to the NSNumberFormatter instance, which returns the formatted string. When the user enters a string, or when a string is programmatically written in a cell (using setStringValue), the cell obtains the equivalent Number object from the NSNumberFormatter.


Using the setFormat Method


The most common technique for assigning a format to an NSNumberFormatter object is to use the method setFormat. This method takes as an argument an String whose contents can be one of the following:

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

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

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

As an alternative to using the setFormat method, you can use the setPositiveFormat and setNegativeFormat methods.


Format String Syntax


Format strings can include the following types of characters:

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


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


Working with Values as Attributed Strings


In NSNumberFormatter, positive, negative, zero, nil, and "not a number" values are NSAttributedStrings, which let you apply attributes such as color or font to a range of characters in a string. (For more information on NSAttributedString, see the NSAttributedString class specification in the Foundation Kit Reference.)

Because the values displayed by NSNumberFormatter are attributed strings, you can customize aspects of their appearance, such as their color and font. The NSNumberFormatter methods you use to do this are as follows:

textAttributesForPositiveValues
setTextAttributesForPositiveValues
textAttributesForNegativeValues
setTextAttributesForNegativeValues
attributedStringForZero
setAttributedStringForZero
attributedStringForNil
setAttributedStringForNil
attributedStringForNotANumber
setAttributedStringForNotANumber

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, and by default they're disabled.

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

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

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

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

If you use the statement numberFormatter.setHasThousandSeparators(NO), 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 formats. Consequently, both formats 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.




Method Types


Constructors
NSNumberFormatter
Set formats
negativeFormat
setNegativeFormat
positiveFormat
setPositiveFormat
format
setFormat
Set characteristics for displaying values
textAttributesForNegativeValues
setTextAttributesForNegativeValues
textAttributesForPositiveValues
setTextAttributesForPositiveValues
attributedStringForZero
setAttributedStringForZero
attributedStringForNil
setAttributedStringForNil
attributedStringForNotANumber
setAttributedStringForNotANumber
attributedStringForObjectValue
Set separators
hasThousandSeparators
setHasThousandSeparators
thousandSeparator
setThousandSeparator
decimalSeparator
setDecimalSeparator
Enable localization
localizesFormat
setLocalizesFormat
Set float behavior
allowsFloats
setAllowsFloats
String Manipulation
isPartialStringValid
objectValueForString
replacementStringForString
stringForObjectValue


Constructors



NSNumberFormatter

public NSNumberFormatter()

Description forthcoming.


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.

See Also: setAllowsFloats



attributedStringForNil

public NSAttributedString attributedStringForNil()

Returns the NSAttributedString used to display nil values. By default nil values are displayed as an empty string.

See Also: setAttributedStringForNil



attributedStringForNotANumber

public NSAttributedString attributedStringForNotANumber()

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

See Also: setAttributedStringForNotANumber



attributedStringForObjectValue

public NSAttributedString attributedStringForObjectValue( Object anObject, NSDictionary aDictionary)

Description forthcoming. Throws FormattingError.

attributedStringForZero

public NSAttributedString attributedStringForZero()

Returns the NSAttributedString used 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" in the Class Description.

See Also: setAttributedStringForZero



decimalSeparator

public String decimalSeparator()

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

See Also: setDecimalSeparator



format

public String format()

Returns a String containing the format being used by the receiver.

See Also: setFormat



hasThousandSeparators

public boolean hasThousandSeparators()

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

See Also: setHasThousandSeparators



isPartialStringValid

public boolean isPartialStringValid(String aString)

Description forthcoming.

localizesFormat

public boolean localizesFormat()

Returns true to indicate that the receiver localizes formats, false otherwise. The default is false.

See Also: setLocalizesFormat



negativeFormat

public String negativeFormat()

Returns a String containing the format used by the receiver to display negative numbers.

See Also: setNegativeFormat, setFormat



objectValueForString

public Object objectValueForString(String aString)

Description forthcoming. Throws FormattingError.

positiveFormat

public String positiveFormat()

Returns a String containing the format used by the receiver to display positive numbers.

See Also: setPositiveFormat, setFormat



replacementStringForString

public String replacementStringForString(String aString)

Description forthcoming.

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.

See Also: allowsFloats



setAttributedStringForNil

public void setAttributedStringForNil(NSAttributedString newAttributedString)

Sets the NSAttributedString the receiver uses to display nil values to newAttributedString.

See Also: attributedStringForNil



setAttributedStringForNotANumber

public void setAttributedStringForNotANumber(NSAttributedString newAttributedString)

Sets the NSAttributedString the receiver uses to display "not a number" values to newAttributedString.

See Also: attributedStringForNotANumber



setAttributedStringForZero

public void setAttributedStringForZero(NSAttributedString newAttributedString)

Sets the NSAttributedString the receiver uses to display zero values to newAttributedString.

See Also: attributedStringForZero



setDecimalSeparator

public void setDecimalSeparator(String newSeparator)

Sets the character the receiver uses as a decimal separator to newSeparator. If newSeparator contains multiple characters, only the first one is used. If you don't have decimal separators enabled through another means (such as setFormat), using this method enables them.

See Also: decimalSeparator



setFormat

public void setFormat(String aFormat)

Sets the receiver's format to the string aFormat. aFormatcan consist of one, two, or three parts separated by ";". The first part of the string represents the positive format, the second part of the string represents the zero value, and the last part of the string represents the negative format. If the string just has two parts, the first one becomes the positive format, and the second one becomes the negative format. If the string just has one part, it becomes the positive format, 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" in the Class Description.

See Also: format



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

See Also: hasThousandSeparators



setLocalizesFormat

public void setLocalizesFormat(boolean flag)

Sets according to flag whether the dollar sign character ($), decimal separator character (.), and thousand separator character (,) are converted to appropriately localized characters as specified by the user's localization preference. While this feature may be useful in certain types of applications, it's probably more likely that you would tie a particular application to a particular currency (that is, that you would "hard-code" the currency symbol and separators instead of having them dynamically change based on the user's configuration). The reason for this, of course, is that NSNumberFormatter doesn't perform currency conversions, it just formats numeric data. You wouldn't want one user interpreting the value "56324" as US currency and another user who's accessing the same data interpreting it as Japanese currency, simply based on each user's localization preferences.

See Also: localizesFormat



setNegativeFormat

public void setNegativeFormat(String aFormat)

Sets the format the receiver uses to display negative values to aFormat.

See Also: negativeFormat, setFormat



setPositiveFormat

public void setPositiveFormat(String aFormat)

Sets the format the receiver uses to display positive values to aFormat.

See Also: positiveFormat, setFormat



setTextAttributesForNegativeValues

public void setTextAttributesForNegativeValues(NSDictionary newAttributes)

Sets the text attributes to be used in displaying negative values to newAttributes.

See Also: textAttributesForNegativeValues



setTextAttributesForPositiveValues

public void setTextAttributesForPositiveValues(NSDictionary newAttributes)

Sets the text attributes to be used in displaying positive values to newAttributes.

See Also: textAttributesForPositiveValues



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 setFormat), using this method enables them.

See Also: thousandSeparator



stringForObjectValue

public String stringForObjectValue(Object anObject)

Description forthcoming. Throws FormattingException.

textAttributesForNegativeValues

public NSDictionary textAttributesForNegativeValues()

Returns an NSDictionary containing the text attributes that have been set for negative values.

See Also: setTextAttributesForNegativeValues



textAttributesForPositiveValues

public NSDictionary textAttributesForPositiveValues()

Returns an NSDictionary containing the text attributes that have been set for positive values.

See Also: setTextAttributesForPositiveValues



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.

See Also: setThousandSeparator




Table of Contents