ArcObjects Library Reference (System)  

ICustomNumberFormat.FormatString Property

A user-defined format expression.

[Visual Basic .NET]
Public Property FormatString As String
[C#]
public string FormatString {get; set;}
[C++]
HRESULT get_FormatString(
  BSTR* str
);
[C++]
HRESULT put_FormatString(
  BSTR str
);
[C++]

Parameters

str [out, retval]   str is a parameter of type BSTR str [in]   str is a parameter of type BSTR

Product Availability

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

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.

See Also

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