com.esri.arcgis.system
Interface ICustomNumberFormat

All Superinterfaces:

Serializable

All Known Implementing Classes:

CustomNumberFormat

public interface ICustomNumberFormat
extends Serializable

Provides access to members that format numbers in a customizable way.

Description

Use the ICustomNumberFormat interface to format numbers in a customized way using the FormatString member property. The associated INumberFormat’s ValueToString method is used to return a string formatted to fit whatever the FormatString property is set to. The StringToValue method reverses this formatting. The formatting is done based on the following sets of characters in the FormatString.

When To Use

Use the ICustomNumberFormat interface to format numbers in a customized format. Define your own format using the FormatString member property.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

See Also:

ILatLonFormat2, CustomNumberFormat, IRateFormat, IAngleFormat, NumericFormat, LatLonFormat, CurrencyFormat, INumericFormat, IFractionFormat, RateFormat, IScientificNumberFormat, ICustomNumberFormat, ILatLonFormat, IPercentageFormat, INumberFormat, ScientificFormat, FractionFormat, PercentageFormat, AngleFormat

Method Summary

String	getFormatString() A user-defined format expression.
void	setFormatString(String str) A user-defined format expression.

Method Detail

setFormatString

void setFormatString(String str)
                     throws IOException,
                            AutomationException

A user-defined format expression.

Description

The following table identifies characters you can use to create user-defined number formats that you can pass as a format expression in the FormatString property:

Character	Description
None	Display the number with no formatting.
(0)	Digit placeholder. Display a digit or a zero. If the expression has a digit in the position where the 0 appears in the format string, display it; otherwise, display a zero in that position. If the number has fewer digits than there are zeros (on either side of the decimal) in the format expression, display leading or trailing zeros. If the number has more digits to the right of the decimal separator than there are zeros to the right of the decimal separator in the format expression, round the number to as many decimal places as there are zeros. If the number has more digits to the left of the decimal separator than there are zeros to the left of the decimal separator in the format expression, display the extra digits without modification.
(#)	Digit placeholder. Display a digit or nothing. If the expression has a digit in the position where the # appears in the format string, display it; otherwise, display nothing in that position. This symbol works like the 0 digit placeholder, except that leading and trailing zeros aren't displayed if the number has the same or fewer digits than there are # characters on either side of the decimal separator in the format expression.
(.)	Decimal placeholder. In some locales, a comma is used as the decimal separator. The decimal placeholder determines how many digits are displayed to the left and right of the decimal separator. If the format expression contains only number signs to the left of this symbol, numbers smaller than 1 begin with a decimal separator. To display a leading zero displayed with fractional numbers, use 0 as the first digit placeholder to the left of the decimal separator. The actual character used as a decimal placeholder in the formatted output depends on the Number Format recognized by your system.
(,)	Thousand separator. In some locales, a period is used as a thousand separator. The thousand separator separates thousands from hundreds within a number that has four or more places to the left of the decimal separator. Standard use of the thousand separator is specified if the format contains a thousand separator surrounded by digit placeholders (0 or #). The actual character used as the thousand separator in the formatted output depends on the Number Format recognized by your system.
("ABC")	Literal string. You can place literal strings on either side of numeric placeholders. For example, you could define a format expression as "The formatted number is: ###,###.#0"

Remarks

The actual characters used as decimal placeholders and thousands separators in the formatted output depends on the Number Format recognized by the system at runtime. To change the way numbers are formatted, change the settings on the Numbers tab of Control Panel's Regional Settings applet.

To try out various formatting options using this interface, select CustomNumberFormat from the dropdown list in the NumberFormat Viewer developer sample.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:

str - The str (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

See Also:

ILatLonFormat2, CustomNumberFormat, IRateFormat, IAngleFormat, NumericFormat, LatLonFormat, CurrencyFormat, INumericFormat, IFractionFormat, RateFormat, IScientificNumberFormat, ICustomNumberFormat, ILatLonFormat, IPercentageFormat, INumberFormat, ScientificFormat, FractionFormat, PercentageFormat, AngleFormat

getFormatString

String getFormatString()
                       throws IOException,
                              AutomationException

A user-defined format expression.

Description

The following table identifies characters you can use to create user-defined number formats that you can pass as a format expression in the FormatString property:

Character	Description
None	Display the number with no formatting.
(0)	Digit placeholder. Display a digit or a zero. If the expression has a digit in the position where the 0 appears in the format string, display it; otherwise, display a zero in that position. If the number has fewer digits than there are zeros (on either side of the decimal) in the format expression, display leading or trailing zeros. If the number has more digits to the right of the decimal separator than there are zeros to the right of the decimal separator in the format expression, round the number to as many decimal places as there are zeros. If the number has more digits to the left of the decimal separator than there are zeros to the left of the decimal separator in the format expression, display the extra digits without modification.
(#)	Digit placeholder. Display a digit or nothing. If the expression has a digit in the position where the # appears in the format string, display it; otherwise, display nothing in that position. This symbol works like the 0 digit placeholder, except that leading and trailing zeros aren't displayed if the number has the same or fewer digits than there are # characters on either side of the decimal separator in the format expression.
(.)	Decimal placeholder. In some locales, a comma is used as the decimal separator. The decimal placeholder determines how many digits are displayed to the left and right of the decimal separator. If the format expression contains only number signs to the left of this symbol, numbers smaller than 1 begin with a decimal separator. To display a leading zero displayed with fractional numbers, use 0 as the first digit placeholder to the left of the decimal separator. The actual character used as a decimal placeholder in the formatted output depends on the Number Format recognized by your system.
(,)	Thousand separator. In some locales, a period is used as a thousand separator. The thousand separator separates thousands from hundreds within a number that has four or more places to the left of the decimal separator. Standard use of the thousand separator is specified if the format contains a thousand separator surrounded by digit placeholders (0 or #). The actual character used as the thousand separator in the formatted output depends on the Number Format recognized by your system.
("ABC")	Literal string. You can place literal strings on either side of numeric placeholders. For example, you could define a format expression as "The formatted number is: ###,###.#0"

All of the above can be combined to produce complex results. For example, using ValueToString with a value of 12345678.9 and a FormatString of ‘$#,###,###.#0 bucks’, the output should be “$12,345,678.90 bucks”.

The NumberFormatDialog class provides a graphical user interface for the properties of the number format objects. This class is defined in the esriFramework assembly.

Remarks

The actual characters used as decimal placeholders and thousands separators in the formatted output depends on the Number Format recognized by the system at runtime. To change the way numbers are formatted, change the settings on the Numbers tab of Control Panel's Regional Settings applet.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Returns:

The str

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

See Also:

ILatLonFormat2, CustomNumberFormat, IRateFormat, IAngleFormat, NumericFormat, LatLonFormat, CurrencyFormat, INumericFormat, IFractionFormat, RateFormat, IScientificNumberFormat, ICustomNumberFormat, ILatLonFormat, IPercentageFormat, INumberFormat, ScientificFormat, FractionFormat, PercentageFormat, AngleFormat