System Template
format()
Format values using a format string.
Syntax
string = rb.page.format(format_str, ...)
Parameters
The 'format' method takes 2 parameters:
| Name | Type/Value | Range/Length | Description | | format_str | string | | Required. Format specifier string. | | ... | string | | Required. Parameters to be formatted by the method. |
Results
The 'format' method returns string:
| Type/Value | Range/Length | Description |
| string |
| This method returns the formatted string.
|
Remarks This is a string formatting method. For anyone familiar with 'C' or 'C++' - it
is very similar to the 'sprintf' family of functions. The first paramter is a format string,
the subsequent parameters are values to be substituted into the string. The format string itself is s superset of the 'C' definition. Parameter substitution
is identified by a '%' character (a conversion specification) within the format string. This
specification is followed by the format to be used for the paramters, terminating with a
'conversion specifier'. The general form of a specifier is %['['delimStr']']+[flagChar*][Width][.precision]conversionSpecifier
Flag CharactersEach conversion specification is contains zero or more 'flag' characters. Te available flags are: | Flag | Description |
|---|
| # | The value should be converted to an ``alternate form''. For x and X
conversions, a non-zero result has the string `0x' (or `0X' for X conversions) prepended to it.
For e, E, f, g, and G conversions, the result will always contain a decimal point, even if
no digits follow it (normally, a decimal point appears in the results of those conversions only
if a digit follows). For g and G conversions, trailing zeros are not removed from the result as
they would otherwise be.
| | 0 | The value should be zero padded. The converted value is padded on
the left or right with zeros rather than blanks.
| | - | The converted value is to be left adjusted on the field boundary. (The default is right justification.)
The converted value is padded on the right rather than on the left with blanks or zeros. A - overrides
a 0 if both are given.
| | + | A sign (+ or -) always be placed before a number produced by a signed conversion. By default a
sign is used only for negative numbers. A + overrides a space if both are used.
|
Flag CharactersAn optional decimal digit string specifying a minimum field width. If the
converted value has fewer characters than the field width, it will be padded with spaces on the left
(or right, if the left-adjustment flag has been given). A negative field width is
taken as a `-' flag followed by a positive field width. In no case does a non-existent or small field
width cause truncation of a field; if the result of a conversion is wider than the field width, the
field is expanded to contain the conversion result. The precisionAn optional precision, in the form of a period (`.') followed by an optional decimal digit string.
If the precision is given as just `.', or the precision is negative, the precision is
taken to be zero. This gives the minimum number of digits to appear for d, u, x, and X conversions,
the number of digits to appear after the radix character for e, E, f, and F conversions,
the maximum number of significant digits for g and G conversions, or the maximum number of characters
to be printed from a string for s and S conversions.
Valid 'formatchar' values are: | Character | Behaviour |
|---|
| s | | | d |
The argument is converted to an integer and represented in signed decimal notation.
The precision, if any, gives the minimum number of digits that must appear; if
the converted value requires fewer digits, it is padded on the left with zeros.
The default precision is 1. When 0 is printed with an explicit precision 0, the output is empty.
| | u, x, X |
The argument is converted to an unsigned 32 bit integer and represented as either and unsigned
decimal (u), or unsigned hexadecimal (x and X) notation. The letters abcdef are used for x
conversions; the letters ABCDEF are used for X conversions. The precision, if any, gives
the minimum number of digits that must appear; if the converted value requires fewer digits,
it is padded on the left with zeros. The default precision is 1. When 0 is printed with
an explicit precision 0, the output is empty.
| | e, E |
The double argument is rounded and converted in the style [-]d.ddde+/-dd where there is one digit
before the decimal-point character and the number of digits after it is equal to the precision;
if the precision is missing, it is taken as 6; if the precision is zero, no decimal-point character
appears. An E conversion uses the letter E (rather than e) to introduce the exponent.
The exponent always contains at least two digits; if the value is zero, the exponent is 00.
| | f |
The double argument is rounded and converted to decimal notation in the style [-]ddd.ddd, where
the number of digits after the decimal-point character is equal to the precision specification.
If the precision is missing, it is taken as 6; if the precision is explicitly zero, no decimal-
point character appears. If a decimal point appears, at least one digit appears before it.
| | g, G |
The double argument is converted in style f or e (or E for G conversions). The precision specifies
the number of significant digits. If the precision is missing, 6 digits are given; if the
precision is zero, it is treated as 1. Style e is used if the exponent from its conversion is
less than -4 or greater than or equal to the precision. Trailing zeros are removed from the
fractional part of the result; a decimal point appears only if it is followed by at least one
digit.
| | G |
Convert the argument to a string. If a precision is specified, no more than the number
specified are written.
| | % |
A '%' is written.
|
The Presentation Engine will convert arguments to the correct type. So all the numeric forms
will attempt to convert strings to numbers. The string form (%s) will convert numbers to
strings before formatting.
Repeated SpecificationsThe Presentation Engine accepts 'arrays' as parameters to be formatted. Arrays are dealt with
by 'repeating' the format specification for each element in the array. So - for example: rb.page.format("%s",['Hello','Tiny','Blue','World,]);
Will produce a string 'HelloTinyBlueWorld'. To make formatting easier - the specifier may contain
a 'delimiting string'. Include this immediate after the '%' in square brackets (note - the delimiter cannot
contain a square bracket!). The delimit string is inserted between each repetition of the format specification - as it is applied to each
element of the array. The string is not put before the first array element or after the last array
element. eg. rb.page.format("[-]%s",['Hello','Tiny','Blue','World,]);
Will generate the string 'Hello-Tiny-Blue-World'. Example
<rb:script>
var text = ["Hello",World"];
var str = rb.page.format("<h1>%[-]s</h1>",text);
</rb:script>
The format specifier in this call will repear the format '%s' on each member of the
'text' array, separating each entry with a hyphen - so the output will be:
<h1>Hello-World</h1>
|
