This is an old revision of the document!

Format

The Format function provides 'C' like formatting of simple data types into a string. It provides very precise control over this formatting. The Formatting parameter defines how the value is manipulated into the returned string.

NOTE: By default the resulting content and the content of the parameter “Format”, “DecimalSeparator”, “ThousandSeparator” will be parsed (all <#..> tags will be evaluated) before to apply this filter. You can control this behavior throught the parameter AnalyzeTagParams

The Formatting string can comprise a mix of ordinary characters (that are passed unchanged to the result string), and data formatting characters. This formatting is best explained by the example code. Ordinary characters must be quoted and data formatting characters must be one of the following :

%b

Boolean

The argument must be an integer or boolean value. The value is converted to a boolean string using the TrueStr and FalseStr params.

%[-][width][.prec]d

Decimal

The argument must be an integer value. The value is converted to a string of decimal digits. If the format string contains a precision specifier, it indicates that the resulting string must contain at least the specified number of digits; if the value has less digits, the resulting string is left-padded with zeros. A width specifier sets the minimum field width for a conversion. If the resulting string is shorter than the minimum field width, it is padded with blanks to increase the field width. The default is to right-justify the result by adding blanks in front of the value, but if the format specifier contains a left-justification indicator (an ”-” en dash character preceding the width specifier), the result is left-justified by adding blanks after the value.

%[-][width][.prec]u

Unsigned decimal

Similar to d, but no sign is output. A width specifier sets the minimum field width for a conversion. If the resulting string is shorter than the minimum field width, it is padded with blanks to increase the field width. The default is to right-justify the result by adding blanks in front of the value, but if the format specifier contains a left-justification indicator (an ”-” en dash character preceding the width specifier), the result is left-justified by adding blanks after the value.

%[-][width][.prec]e

Scientific

The argument must be a floating-point value. The value is converted to a string of the form ”-d.ddd…E+ddd”. The resulting string starts with a minus sign if the number is negative. One digit always precedes the decimal point. The total number of digits in the resulting string (including the one before the decimal point) is given by the precision specifier in the format string; a default precision of 15 is assumed if no precision specifier is present. The “E” exponent character in the resulting string is always followed by a plus or minus sign and at least three digits. A width specifier sets the minimum field width for a conversion. If the resulting string is shorter than the minimum field width, it is padded with blanks to increase the field width. The default is to right-justify the result by adding blanks in front of the value, but if the format specifier contains a left-justification indicator (an ”-” en dash character preceding the width specifier), the result is left-justified by adding blanks after the value.

%[-][width][.prec]f

Fixed

The argument must be a floating-point value. The value is converted to a string of the form ”-ddd.ddd…”. The resulting string starts with a minus sign if the number is negative. The number of digits after the decimal point is given by the precision specifier in the format string—a default of 2 decimal digits is assumed if no precision specifier is present. A width specifier sets the minimum field width for a conversion. If the resulting string is shorter than the minimum field width, it is padded with blanks to increase the field width. The default is to right-justify the result by adding blanks in front of the value, but if the format specifier contains a left-justification indicator (an ”-” en dash character preceding the width specifier), the result is left-justified by adding blanks after the value.

%[-][width][.prec]g

General

The argument must be a floating-point value. The value is converted to the shortest possible decimal string using fixed or scientific format. The number of significant digits in the resulting string is given by the precision specifier in the format string; a default precision of 15 is assumed if no precision specifier is present. Trailing zeros are removed from the resulting string, and a decimal point appears only if necessary. The resulting string uses the fixed-point format if the number of digits to the left of the decimal point in the value is less than or equal to the specified precision, and if the value is greater than or equal to 0.00001. Otherwise the resulting string uses scientific format. A width specifier sets the minimum field width for a conversion. If the resulting string is shorter than the minimum field width, it is padded with blanks to increase the field width. The default is to right-justify the result by adding blanks in front of the value, but if the format specifier contains a left-justification indicator (an ”-” en dash character preceding the width specifier), the result is left-justified by adding blanks after the value.

%[-][width][.prec]n

Number

The argument must be a floating-point value. The value is converted to a string of the form ”-d,ddd,ddd.ddd…”. The n format corresponds to the f format, except that the resulting string contains thousand separators. A width specifier sets the minimum field width for a conversion. If the resulting string is shorter than the minimum field width, it is padded with blanks to increase the field width. The default is to right-justify the result by adding blanks in front of the value, but if the format specifier contains a left-justification indicator (an ”-” en dash character preceding the width specifier), the result is left-justified by adding blanks after the value.

%[-][width][.prec]m

Money

The argument must be a floating-point value. The value is converted to a string that represents a currency amount. The conversion is controlled by the CurrencyString, CurrencyFormat, NegCurrFormat, ThousandSeparator, DecimalSeparator, and CurrencyDecimals parameters. If the format string contains a precision specifier, it overrides the value given by the CurrencyDecimals parameters. A width specifier sets the minimum field width for a conversion. If the resulting string is shorter than the minimum field width, it is padded with blanks to increase the field width. The default is to right-justify the result by adding blanks in front of the value, but if the format specifier contains a left-justification indicator (an ”-” en dash character preceding the width specifier), the result is left-justified by adding blanks after the value.

%[-][width][.prec]s

String

The argument must be a string. The string or character is inserted in place of the format specifier. The precision specifier, if present in the format string, specifies the maximum length of the resulting string. If the argument is a string that is longer than this maximum, the string is truncated. A width specifier sets the minimum field width for a conversion. If the resulting string is shorter than the minimum field width, it is padded with blanks to increase the field width. The default is to right-justify the result by adding blanks in front of the value, but if the format specifier contains a left-justification indicator (an ”-” en dash character preceding the width specifier), the result is left-justified by adding blanks after the value.

%[-][width][.prec]x

Hexadecimal

The argument must be an integer value. The value is converted to a string of hexadecimal digits. If the format string contains a precision specifier, it indicates that the resulting string must contain at least the specified number of digits; if the value has fewer digits, the resulting string is left-padded with zeros. A width specifier sets the minimum field width for a conversion. If the resulting string is shorter than the minimum field width, it is padded with blanks to increase the field width. The default is to right-justify the result by adding blanks in front of the value, but if the format specifier contains a left-justification indicator (an ”-” en dash character preceding the width specifier), the result is left-justified by adding blanks after the value.

%[0][#][,][.][E+][E-][;]

Float

The argument must be an floating-point value.

Specifier	Represents
0	Digit placeholder. If the value being formatted has a digit in the position where '0' appears in the format string, then that digit is copied to the output string. Otherwise, a '0' is stored in that position in the output string.
#	Digit placeholder. If the value being formatted has a digit in the position where '#' appears in the format string, then that digit is copied to the output string. Otherwise, nothing is stored in that position in the output string.
.	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. The actual character used as a decimal separator in the output string is determined by the DecimalSeparator parameter.
,	Thousand separator. If the format string contains one or more ',' characters, the output will have thousand separators inserted between each group of three digits to the left of the decimal point. The placement and number of ',' characters in the format string does not affect the output, except to indicate that thousand separators are wanted. The actual character used as a thousand separator in the output is determined by the ThousandSeparator parameter.
E+	Scientific notation. If any of the strings 'E+', 'E-', 'e+', or 'e-' are contained in the format string, the number is formatted using scientific notation. A group of up to four '0' characters can immediately follow the 'E+', 'E-', 'e+', or 'e-' to determine the minimum number of digits in the exponent. The 'E+' and 'e+' formats cause a plus sign to be output for positive exponents and a minus sign to be output for negative exponents. The 'E-' and 'e-' formats output a sign character only for negative exponents.
'xx'/"xx"	Characters enclosed in single or double quotation marks are output as such and do not affect formatting.
;	Separates sections for positive, negative, and zero numbers in the format string.

The locations of the leftmost '0' before the decimal point in the format string and the rightmost '0' after the decimal point in the format string determine the range of digits that are always present in the output string.

The number being formatted is always rounded to as many decimal places as there are digit placeholders ('0' or '#') to the right of the decimal point. If the format string contains no decimal point, the value being formatted is rounded to the nearest whole number.

If the number being formatted has more digits to the left of the decimal separator than there are digit placeholders to the left of the '.' character in the format string, the extra digits are output before the first digit placeholder.

To allow different formats for positive, negative, and zero values, the format string can contain between one and three sections separated by semicolons, as follows:

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.

Three sections: The first section applies to positive values, the second applies to negative values, and the third applies to zeros.

If the section for negative values or the section for zero values is empty, that is if there is nothing between the semicolons that delimit the section, the section for positive values is used instead.

If the section for positive values is empty or if the entire format string is empty, the value is formatted using general floating-point formatting with 15 significant digits, corresponding to a call to FloatToStrF with the ffGeneral format. General floating-point formatting is also used if the value has more than 18 digits to the left of the decimal point and the format string does not specify scientific notation.

Date Time

Date Time Format strings are composed of specifiers that represent values to be inserted into the formatted string. Some specifiers (such as “d”) simply format numbers or strings. Other specifiers (such as ”/”) refer to locale-specific strings. In the following table, specifiers are given in lowercase. Case is ignored in formats, except for the “am/pm” and “a/p” specifiers.

Specifier	Displays
c	Displays the date using the format given by the ShortDateFormat parameter, followed by the time using the format given by the LongTimeFormat parameter. The time is not displayed if the date-time value indicates midnight precisely.
d	Displays the day as a number without a leading zero (1-31).
dd	Displays the day as a number with a leading zero (01-31).
ddd	Displays the day as an abbreviation (Sun-Sat) using the strings given by the ShortDayNames parameter.
dddd	Displays the day as a full name (Sunday-Saturday) using the strings given by the LongDayNames parameter.
ddddd	Displays the date using the format given by the ShortDateFormat parameter.
dddddd	Displays the date using the format given by the LongDateFormat parameter.
m	Displays the month as a number without a leading zero (1-12). If the m specifier immediately follows an h or hh specifier, the minute rather than the month is displayed.
mm	Displays the month as a number with a leading zero (01-12). If the mm specifier immediately follows an h or hh specifier, the minute rather than the month is displayed.
mmm	Displays the month as an abbreviation (Jan-Dec) using the strings given by the ShortMonthNames parameter.
mmmm	Displays the month as a full name (January-December) using the strings given by the LongMonthNames parameter.
yy	Displays the year as a two-digit number (00-99).
yyyy	Displays the year as a four-digit number (0000-9999).
h	Displays the hour without a leading zero (0-23).
hh	Displays the hour with a leading zero (00-23).
n	Displays the minute without a leading zero (0-59).
nn	Displays the minute with a leading zero (00-59).
s	Displays the second without a leading zero (0-59).
ss	Displays the second with a leading zero (00-59).
z	Displays the millisecond without a leading zero (0-999).
zzz	Displays the millisecond with a leading zero (000-999).
t	Displays the time using the format given by the ShortTimeFormat parameter.
tt	Displays the time using the format given by the LongTimeFormat parameter.
am/pm	Uses the 12-hour clock for the preceding h or hh specifier, and displays 'am' for any hour before noon, and 'pm' for any hour after noon. The am/pm specifier can use lower, upper, or mixed case, and the result is displayed accordingly.
a/p	Uses the 12-hour clock for the preceding h or hh specifier, and displays 'a' for any hour before noon, and 'p' for any hour after noon. The a/p specifier can use lower, upper, or mixed case, and the result is displayed accordingly.
ampm	Uses the 12-hour clock for the preceding h or hh specifier, and displays the contents of the TimeAMString parameter for any hour before noon, and the contents of the TimePMString parameter for any hour after noon.
/	Displays the date separator character given by the DateSeparator parameter
:	Displays the time separator character given by the TimeSeparator parameter.
'xx'/"xx"	Characters enclosed in single or double quotation marks are displayed as such, and do not affect formatting.

NOTE: Various local options or parameters, such as DecimalSeparator or ThousandSeparator are used for some 
of these formatting options.

Example

<#MyVar setValue="-123">
<#MyVar Format="'Decimal = '%.5d">

<#MyVar setValue="123">
<#MyVar Format="'Unsigned decimal = '%u">

<#MyVar setValue="12345.678">
<#MyVar Format="'Exponent = '%e">

<#MyVar setValue="12345.678">
<#MyVar Format="'Fixed = '%.2f">

<#MyVar setValue="12345.0001">
<#MyVar Format="'General = '%g">

<#MyVar setValue="12345.678872">
<#MyVar Format="'Number = '%.3n">

<#MyVar setValue="12345.678">
<#MyVar Format="'Money = '%.2m">

<#MyVar setValue="Hello">
<#MyVar Format="'String = '%s">

<#MyVar setValue="140">
<#MyVar Format="'Hexadecimal = '%x">

<#MyVar setValue="12345.678">
<#MyVar Format="'Float = '%0.##">

<#MyVar setValue="NOW">
<#MyVar Format="'Date = 'mm/dd/yyyy">

The above example will output:

Decimal = -00123
Unsigned decimal = 123
Exponent = 1.23456780000000E+004
Fixed = 12345.68
General = 12345.0001
Number = 12,345.679
Money = $12,345.68
String = Hello
Hexadecimal = 8C
Float = 12345.68
Date = 11/25/2012

doc.arkadia.com

User Tools

Site Tools

Format

Example

Page Tools