- Inherits from:
- NSFormatter : NSObject
- Package:
- com.apple.yellow.foundation
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.
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.
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:
"
positiveFormat"
For
example, "$###,##0.00"
(the
syntax of format strings is discussed in the following section)."
positiveFormat;
negativeFormat"
For
example, "###,##0.00;(###,##0.00)"
."
positiveFormat;
zeroFormat;
negativeFormat"
For
example, "$###,###.00;0.00;($###,##0.00)"
.
Note that zero formats are treated as string constants.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 strings can include the following types of characters:
"9,990.00"
,
and the value 53.88 is entered into a cell to which the format has
been applied. The cell would display the value as 9,953.88..
) 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.
When you enable localization for an NSNumberFormatter object by
using the method setLocalizesFormat, separators
are converted to characters appropriate to the environment in which
the application is running.#
)
to represent numeric characters that will be input by the user.
For example, suppose you have the positive format "$#,##0.00"
.
If the characters 76329 were entered into a cell to which the format
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 format 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
format strings more human-readable, which is especially useful if
you're displaying formats in the user interface._
).
This character inserts a space if no numeric character has been
input to occupy that position.$
)
is normally treated just like any other character that doesn't
play a special role in NSNumberFormatter. However, when you enable
localization for an NSNumberFormatter object by using the method setLocalizesFormat,
the dollar sign character is converted to the currency symbol appropriate
for the environment in which the application is running.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 |
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:
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.
- 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
public NSNumberFormatter()
public boolean allowsFloats()
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
public NSAttributedString attributedStringForNil()
See Also: setAttributedStringForNil
public NSAttributedString attributedStringForNotANumber()
See Also: setAttributedStringForNotANumber
public NSAttributedString attributedStringForObjectValue(
Object anObject,
NSDictionary aDictionary)
public NSAttributedString attributedStringForZero()
See Also: setAttributedStringForZero
public String decimalSeparator()
.
).
Note that the return value doesn't indicate whether decimal separators are
enabled.See Also: setDecimalSeparator
public String format()
See Also: setFormat
public boolean hasThousandSeparators()
true
to
indicate that the receiver's format includes thousand separators, false
otherwise. The
default is false
.See Also: setHasThousandSeparators
public boolean isPartialStringValid(String aString)
public boolean localizesFormat()
true
to
indicate that the receiver localizes formats, false
otherwise. The
default is false
.See Also: setLocalizesFormat
public String negativeFormat()
See Also: setNegativeFormat, setFormat
public Object objectValueForString(String aString)
public String positiveFormat()
See Also: setPositiveFormat, setFormat
public String replacementStringForString(String aString)
public void setAllowsFloats(boolean flag)
.
)). By
default, floating point values are allowed as input.See Also: allowsFloats
public void setAttributedStringForNil(NSAttributedString newAttributedString)
See Also: attributedStringForNil
public void setAttributedStringForNotANumber(NSAttributedString newAttributedString)
See Also: attributedStringForNotANumber
public void setAttributedStringForZero(NSAttributedString newAttributedString)
See Also: attributedStringForZero
public void setDecimalSeparator(String newSeparator)
See Also: decimalSeparator
public void setFormat(String aFormat)
";"
.
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
public void setHasThousandSeparators(boolean flag)
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
public void setLocalizesFormat(boolean flag)
$
),
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
public void setNegativeFormat(String aFormat)
See Also: negativeFormat, setFormat
public void setPositiveFormat(String aFormat)
See Also: positiveFormat, setFormat
public void setTextAttributesForNegativeValues(NSDictionary newAttributes)
See Also: textAttributesForNegativeValues
public void setTextAttributesForPositiveValues(NSDictionary newAttributes)
See Also: textAttributesForPositiveValues
public void setThousandSeparator(String newSeparator)
See Also: thousandSeparator
public String stringForObjectValue(Object anObject)
public NSDictionary textAttributesForNegativeValues()
See Also: setTextAttributesForNegativeValues
public NSDictionary textAttributesForPositiveValues()
See Also: setTextAttributesForPositiveValues
public String thousandSeparator()
,
).
Note that the return value doesn't indicate whether thousand separators
are enabled.See Also: setThousandSeparator