Formatting the value box control in Axiom

A detailed explanation of the various formatting options for standard numeric format strings with a Value Box Control.

 

Standard Numeric Format Strings

Standard numeric format strings are used to format common numeric types. A standard format string takes the form {A:xx} where A is a single alphabetic character called the format specifier and xx is an optional integer called the precision specifier. 

 

The format specifier must be one of the built-in format characters as outlined below. The precision specifier can range from 0 to 99 and controls the number of significant digits or zeros to the right of a decimal. The format string cannot contain white spaces.

 

For example, the format string {C:02} will display the number as a currency with three decimal places. 

 

 

The following describes the standard numeric format strings. Note that the result string produced by these format specifiers is influenced by the settings in the Regional Options control panel. Computers using different settings will generate different result strings.

 

C – Currency

 

The number is converted to a string that represents a currency amount. The conversion is controlled by the currency format information of the NumberFormatInfo object used to format the number. The precision specifier indicates the desired number of decimal places. If the precision specifier is omitted, the default currency precision given by the NumberFormatInfo is used. 

 

E or e - Scientific / exponential

 

The number is converted to a string of the form “-d.ddd…E+ddd” or “-d.ddd…e+ddd”, where each ‘d’ indicates a digit (0-9). The string starts with a minus sign if the number is negative. One digit always precedes the decimal point. The precision specifier indicates the desired number of decimal places. If the precision specifier is omitted, a default of six digits after the decimal point is used. The case of the format specifier indicates whether to prefix the exponent with an ‘E’ or an ‘e’. The exponent always consists of a plus or minus sign and a minimum of three digits. The exponent is padded with zeros to meet this minimum, if required.

 

F or f - Fixed-point

 

The number is converted to a string of the form “-ddd.ddd…” where each ‘d’ indicates a digit (0-9). The string starts with a minus sign if the number is negative. The precision specifier indicate the desired number of decimal places. If the precision specifier is omitted, the default numeric precision given by the NumberFormatInfo is used.

G or g – General

 

The number is converted to the most compact of either fixed-point or scientific notation, depending on the type of the number and whether a precision specifier is present. If the precision specifier is omitted or zero, the type of the number determines the default precision, as indicated by the following list.

 

Byte or SByte: 3

Int16 or UInt16: 5

Int32 or UInt32: 10

Int64 or UInt64: 19

Single: 7

Double: 15

Decimal: 29

 

Fixed-point notation is used if the exponent that would result from expressing the number in scientific notation is greater than -5 and less than the precision specifier; otherwise, scientific notation is used. The result contains a decimal point if required and trailing zeros are omitted. If the precision specifier is present and the number of significant digits in the result exceeds the specified precision, then the excess trailing digits are removed by rounding. If scientific notation is used, the exponent in the result is prefixed with ‘E’ if the format specifier is ‘G’, or ‘e’ if the format specifier is ’g’. The exception to this preceding rule is if the number is a Decimal and the precision specifier is omitted. In that case, fixed-point notation is always used and trailing zeros are preserved.

 

N or n – Number

 

The number is converted to a string of the form “-d,ddd,ddd.ddd…”, where each ‘d’ indicates a digit (0-9). The string starts with a minus sign if the number is negative. Thousand seperators are inserted between each group of three digits to the left of the decimal point. The precision specifier indicates the desired number of decimal places. If the precision specifier is omitted, the default numeric precision given by the NumberFormatInfo is used.

 

P or p – Percent

 

The number is converted to a string that represents a percent as defined by the NumberFormatInfo.PercentNegativePattern property or the NumberFormatInfo.PrecentPositivePattern property. If the number is negative, the string produced is defined by the PercentNegativePattern and starts with a minus sign. The converted number is multiplied by 100 in order to be presented as a percentage. The precision specifier indicated the desired number of decimal places. If the precision specifier is omitted, the default numeric precision given by NumberFormatInfo is used.

 

Example Outputs

 

{0:C2} = “$0.00”

{0:C0} = “$0”

 

{0:E2} = “0.00E+000”

{0:E4} = “0.0000E+000”

 

{0:F3} = “0.000”

{0:F1} = “0.0”

 

{0:N2} = “0,000.00”

{0:N0} = “00,000,000”

 

when value is 0.102

{0.P1} = “10.2%”

{0:P3} = “10.200%”

 

when value is 10.2

{0:0.0##%’} = “10.2%”

{0:0.000%’} = “10.200%”

 

When value is 10.250

{0:0.0##’%’} = “10.25%”

 

 

 

 

Different formatting can be applied to a string based on whether the value is positive, negative, or zero. To produce this behavior, a custom format string can contain up to three sections separated by semicolons:

 

· One section - The format string applies to all values

 

· Two sections - The first section applies to positive values and zeros, and the second section applies to negative values. If the number to be formatted is negative, but becomes zero after rounding according to the format in the second section, then the resulting zero is formatted according to the first section.

 

· Three sections - The first section applies to positive values, the second section applies to negative values, and the third section applies to zeros. The second section might be left empty (by having nothing between the semicolons), in which case the first section applies to all nonzero values. If the number to be formatted is not zero, but becomes zero after rounding according to the format in the first or second section, then the resulting zero is formatted according to the third section.

 

Note: This type of formatting ignores any preexisting formatting associated with a number when the final value is formatted. For example, negative values are always displayed without a minus sign when section separators are used. If you want the final formatted value to have a minus sign, you should explicitly include the minus sign as part of the custom format specifier. The following example illustrates how section separators can be used to produce formatted strings.

 

For the following format string:

 

{0:$#,##0.00;(0:$#,##0.00);Zero}

 

If value is 19.95 the output is “$19.95”

If value is -19.95 the output is “($19.95)”

If value is 0 the output is “Zero”

 

 

For the following format string:

 

{0:RUNNING;;STOPPED}

 

If value is 0 the output is “STOPPED”

If values is not 0 the output is “RUNNING”