Next Page > Hide TOC

NSNumberFormatter

Overview

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.

Tasks

Constructors

• NSNumberFormatter

Setting and Getting Formats

• negativeFormat
• setNegativeFormat
• positiveFormat
• setPositiveFormat
• format
• setFormat

Setting and Getting Characteristics for Displaying Values

• textAttributesForNegativeValues
• setTextAttributesForNegativeValues
• textAttributesForPositiveValues
• setTextAttributesForPositiveValues
• attributedStringForZero
• setAttributedStringForZero
• attributedStringForNil
• setAttributedStringForNil
• attributedStringForNotANumber
• setAttributedStringForNotANumber
• attributedStringForObjectValue

Setting and Getting Separators

• hasThousandSeparators
• setHasThousandSeparators
• thousandSeparator
• setThousandSeparator
• decimalSeparator
• setDecimalSeparator

Enabling Localization

• localizesFormat
• setLocalizesFormat

Setting and Getting Float Behavior

• allowsFloats
• setAllowsFloats

String Manipulation

• isPartialStringValid
• objectValueForString
• replacementStringForString
• stringForObjectValue

Instance Methods

allowsFloats

Returns true if the receiver allows as input floating-point values (that is, values that include the period character [.]), false otherwise.

public boolean allowsFloats()

Discussion

When this method returns false, only integer values can be provided as input. The default is true.

See Also

• setAllowsFloats

attributedStringForNil

Returns the NSAttributedString used to display null values.

public NSAttributedString attributedStringForNil()

Discussion

By default null values are displayed as an empty string.

See Also

• setAttributedStringForNil

attributedStringForNotANumber

Returns the NSAttributedString used to display “not a number” values.

public NSAttributedString attributedStringForNotANumber()

Discussion

By default “not a number” values are displayed as the string “NaN”.

See Also

• setAttributedStringForNotANumber

attributedStringForObjectValue

Return an NSAttributedString if the string for display should have some attributes.

public NSAttributedString attributedStringForObjectValue(Object anObject, NSDictionary attributes)

Discussion

For instance, you might want negative values in a financial application to appear in red text. Invoke your implementation of stringForObjectValue to get the nonattributed string. Then create an NSAttributedString with it. The default attributes for text in the cell are passed in with attributes; use this NSDictionary to reset the attributes of the string when a change in value warrants it (for example, a negative value becomes positive). If an NSAttributedString cannot be created for anObject, an NSFormatter.FormattingException is thrown. For information on creating attributed strings, see the NSAttributedString class.

attributedStringForZero

Returns the NSAttributedString used to display zero values.

public NSAttributedString attributedStringForZero()

Discussion

By default zero values are displayed according to the format specified for positive values; for more discussion of this subject see “Data Formatting”.

See Also

• setAttributedStringForZero

decimalSeparator

Returns a String containing the character the receiver uses to represent decimal separators.

public String decimalSeparator()

Discussion

Note that the return value doesn’t indicate whether decimal separators are enabled.

See Also

• setDecimalSeparator

format

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

public String format()

See Also

• setFormat

hasThousandSeparators

Returns true to indicate that the receiver’s format includes thousand separators, false otherwise.

public boolean hasThousandSeparators()

Discussion

The default is false.

See Also

• setHasThousandSeparators

isPartialStringValid

Since this method is invoked each time the user presses a key while the cursor is in the cell, it lets you verify the cell text as the user types it.

public boolean isPartialStringValid(String partialString)

Discussion

partialString is the text currently in the cell. Return true if typed text is acceptable and false if it is not. If you return false, the cell displays partialString minus the last character typed.

See Also

• replacementStringForString

localizesFormat

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

public boolean localizesFormat()

Discussion

The default is false.

See Also

• setLocalizesFormat

negativeFormat

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

public String negativeFormat()

See Also

• setNegativeFormat
• setFormat

objectValueForString

Returns an object created from aString.

public Object objectValueForString(String aString)

Discussion

If an object cannot be created from aString, an NSFormatter.ParsingException is thrown.

See Also

• stringForObjectValue

positiveFormat

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

public String positiveFormat()

See Also

• setPositiveFormat
• setFormat

replacementStringForString

Checks whether aString is a valid string for the cell.

public String replacementStringForString(String aString)

Discussion

If it is, returns it unmodified. Otherwise, corrects it and returns the modified string. For example, this method might convert all lowercase letters to uppercase or insert separator characters in a telephone number.

See Also

• isPartialStringValid

setAllowsFloats

Sets according to flag whether the receiver allows as input floating-point values (that is, values that include the period character [.]).

public void setAllowsFloats(boolean flag)

Discussion

By default, floating point values are allowed as input.

See Also

• allowsFloats

setAttributedStringForNil

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

public void setAttributedStringForNil(NSAttributedString newAttributedString)

See Also

• attributedStringForNil

setAttributedStringForNotANumber

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

public void setAttributedStringForNotANumber(NSAttributedString newAttributedString)

See Also

• attributedStringForNotANumber

setAttributedStringForZero

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

public void setAttributedStringForZero(NSAttributedString newAttributedString)

See Also

• attributedStringForZero

setDecimalSeparator

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.

public void setDecimalSeparator(String newSeparator)

See Also

• decimalSeparator

setFormat

Sets the receiver’s format to the string aFormat.

public void setFormat(String aFormat)

Discussion

aFormat can 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 has just two parts, the first one becomes the positive format, and the second one becomes the negative format. If the string has just 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 “Data Formatting”.

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

NSNumberFormatter numberFormatter = new NSNumberFormatter();

// specify just positive format

numberFormatter.setFormat("$#,##0.00");

// specify positive and negative formats

numberFormatter.setFormat("$#,##0.00;($#,##0.00)");

// specify positive, zero, and negative formats

numberFormatter.setFormat("$#,###.00;0.00;($#,##0.00)");

See Also

• format

setHasThousandSeparators

Sets according to flag whether the receiver uses thousand separators.

public void setHasThousandSeparators(boolean flag)

Discussion

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

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.

public void setLocalizesFormat(boolean flag)

Discussion

While the currency-symbol part of 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

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

public void setNegativeFormat(String aFormat)

See Also

• negativeFormat
• setFormat

setPositiveFormat

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

public void setPositiveFormat(String aFormat)

See Also

• positiveFormat
• setFormat

setTextAttributesForNegativeValues

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

public void setTextAttributesForNegativeValues(NSDictionary newAttributes)

See Also

• textAttributesForNegativeValues

setTextAttributesForPositiveValues

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

public void setTextAttributesForPositiveValues(NSDictionary newAttributes)

See Also

• textAttributesForPositiveValues

setThousandSeparator

Sets the character the receiver uses as a thousand separator to newSeparator.

public void setThousandSeparator(String newSeparator)

Discussion

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

Returns the string that textually represents the cell’s object for display and for editing.

public String stringForObjectValue(Object anObject)

Discussion

First tests the passed-in object to see if it’s of the correct class. If it isn’t, returns null; if it is of the correct class, returns a properly formatted and, if necessary, localized string. If a string cannot be created for anObject, an NSFormatter.FormattingException is thrown.

See Also

• attributedStringForObjectValue
• objectValueForString

textAttributesForNegativeValues

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

public NSDictionary textAttributesForNegativeValues()

See Also

• setTextAttributesForNegativeValues

textAttributesForPositiveValues

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

public NSDictionary textAttributesForPositiveValues()

See Also

• setTextAttributesForPositiveValues

thousandSeparator

Returns a String containing the character the receiver uses to represent thousand separators.

public String thousandSeparator()

Discussion

By default this is the comma character (,). Note that the return value doesn’t indicate whether thousand separators are enabled.

See Also

• setThousandSeparator

Next Page > Hide TOC