Locale Formatting Features

Release 1.0 - ...

The Locale viper contains all locale related formatting vipers. Formatting vipers formerly available on viper classes such as Math and DateTime are marked as depecrated and have been moved to the Locale viper class.

The formatting vipers can be categorized in three groups; number formatting, date time formatting and timespan formatting. When an culture is not explicitly specified as parameter, the current culture of the render context is used. See also default culture settings.

Number Formatting

The formatting specifiers are derived from the formatting provided by the .NET framework. Numeric format strings control formatting operations in which a numeric data type is represented as a string.

Numeric format strings fall into two categories:

Standard numeric format strings
Standard numeric format strings consist of one of a set of standard numeric format specifiers. Each standard format specifier denotes a particular, commonly used string representation of numeric data.
Custom numeric format strings
Custom format strings consist of one or more custom numeric format specifiers. Combine custom numeric format specifiers to define an application-specific pattern that determines how numeric data is formatted.

Standard numeric format string

Standard numeric format strings are used to format common numeric types. A standard numeric format string takes the form Axx, where A is an alphabetic character called the format specifier, and xx is an optional integer called the precision specifier. The precision specifier ranges from 0 to 99 and affects the number of digits in the result. Any numeric format string that contains more than one alphabetic character, including white space, is interpreted as a custom numeric format string.

Format specifier	Name	Description
C or c	Currency	The number is converted to a string that represents a currency amount. The precision specifier indicates the desired number of decimal places.
D or d	Decimal	The number is converted to a string of decimal digits (0-9), prefixed by a minus sign if the number is negative. The precision specifier indicates the minimum number of digits desired in the resulting string. If required, the number is padded with zeros to its left to produce the number of digits given by the precision specifier.
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 digits after the decimal point. 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 indicates the desired number of decimal places.
G or g	General	The number is converted to the most compact of either fixed-point or scientific notation, depending on whether a precision specifier is present.
N or n	Number	The number is converted to a string of the form "-d,ddd,ddd.ddd�", where '-' indicates a negative number symbol if required, 'd' indicates a digit (0-9), ',' indicates a thousand separator between number groups, and '.' indicates a decimal point symbol. The precision specifier indicates the desired number of decimal places.
P or p	Percent	The number is converted to a string that represents a percent. The converted number is multiplied by 100 in order to be presented as a percentage. The precision specifier indicates the desired number of decimal places.
X or x	Hexadecimal	The number is converted to a string of hexadecimal digits. The case of the format specifier indicates whether to use uppercase or lowercase characters for the hexadecimal digits greater than 9. For example, use 'X' to produce "ABCDEF", and 'x' to produce "abcdef". The precision specifier indicates the minimum number of digits desired in the resulting string. If required, the number is padded with zeros to its left to produce the number of digits given by the precision specifier.
Any other single character	(Unknown specifier)	An unknown specifier causes an error.

Custom numeric format strings

A custom numeric format string, which you create and consists of one or more custom numeric format specifiers, defines how numeric data is formatted. A custom numeric format string is equivalently defined as any string that is not a standard numeric format string.

Format specifier	Name	Description
0	Zero placeholder	If the value being formatted has a digit in the position where the '0' appears in the format string, then that digit is copied to the result string. The position of the leftmost '0' before the decimal point and the rightmost '0' after the decimal point determines the range of digits that are always present in the result string. The "00" specifier causes the value to be rounded to the nearest digit preceding the decimal, where rounding away from zero is always used. For example, formatting 34.5 with "00" would result in the value 35.
#	Digit placeholder	If the value being formatted has a digit in the position where the '#' appears in the format string, then that digit is copied to the result string. Otherwise, nothing is stored in that position in the result string. Note that this specifier never displays the '0' character if it is not a significant digit, even if '0' is the only digit in the string. It will display the '0' character if it is a significant digit in the number being displayed. The "##" format string causes the value to be rounded to the nearest digit preceding the decimal, where rounding away from zero is always used. For example, formatting 34.5 with "##" would result in the value 35.
.	Decimal point	The first '.' character in the format string determines the location of the decimal separator in the formatted value; any additional '.' characters are ignored.
,	Thousand separator and number scaling	The ',' character serves as a thousand separator specifier.
%	Percentage placeholder	The presence of a '%' character in a format string causes a number to be multiplied by 100 before it is formatted. The appropriate symbol is inserted in the number itself at the location where the '%' appears in the format string.
E0 E+0 E-0 e0 e+0 e-0	Scientific notation	If any of the strings "E", "E+", "E-", "e", "e+", or "e-" are present in the format string and are followed immediately by at least one '0' character, then the number is formatted using scientific notation with an 'E' or 'e' inserted between the number and the exponent. The number of '0' characters following the scientific notation indicator determines the minimum number of digits to output for the exponent. The "E+" and "e+" formats indicate that a sign character (plus or minus) should always precede the exponent. The "E", "E-", "e", or "e-" formats indicate that a sign character should only precede negative exponents.
'ABC' "ABC"	Literal string	Characters enclosed in single or double quotes are copied to the result string, and do not affect formatting.
;	Section separator	The ';' character is used to separate sections for positive, negative, and zero numbers in the format string.
Other	All other characters	Any other

Advanced