Previous: Byte Data Output Functions, Up: The Output Library [Index]
void <prefix>_form(text s, ...);
Outputs the filled out s form.
The form is filled according the formatting directives.
By default, formatting directives are replaced with the next argument in the
arguments list. Some formatting directive classes allow specifying which
arguments should be used. If such an indication is included with the
formatting directive, the indicated argument becomes the current one and the
next one to be used will default to the one following it. The first argument
after form corresponds the position 1.
Only arguments of types in a limited set are shown in the output. The types set includes the intrinsic types and the byte data, date and time types. Unless otherwise specified, if the type of the processed argument is not in the allowed set no output corresponding the formatting directive occurs.
See The Date And Time Library.
The recognized formatting directives are:
Replaced with the next argument, unless the ‘~’ is followed by a (nonsigned) decimal, case in which the argument in the position corresponding the decimal is used. The arguments are formatted according to their types.
A second sign indicating the replacement follows the ‘%’ sign.
If the sign is one of ‘~’, ‘%’, ‘/’ and ‘)’, the directive is replaced with the sign and no argument is used.
Otherwise, the second sign indicates the output type and a single ‘-’ sign and a (nonsigned) decimal, in this order, may be present between the directive leading and trailing signs. The decimal specifies the minimum number of output characters. White space will be introduced accordingly, before or after the formatted argument if a ‘-’ sign is included with the formatting directive. The recognized output type indications together with corresponding output types are:
character
decimal
real
decimal (same as ‘%d’)
binary, most significant byte first, same as <prefix>‘_msbfcardinal’
octal
string
varint, same as <prefix>‘_msbfvcardinal’
hexadecimal
For the ‘%s’ directive, the type of the corresponding argument is expected one of the intrinsic string type and the byte array type. For the ‘%v’ directive, the argument type is expected one of the integral intrinsic types (cardinal or integer) and positive. For the remaining directives, the argument type is expected one of the numeric intrinsic types (cardinal, integer or real).
For the ‘%m’ directive the number of output characters is set by the optional leading decimal, and defaults to 4.
For the ‘%v’ directive, the optional padding is with byte 128 and always before the formatted argument.
A second ‘/’ sign follows and marks the end of the formatting directive specification. In between, a (nonsigned) decimal immediately following the leading ‘/’ and a series of formatting modifiers may be present. The decimal indicates the argument to be used, by position. The output modifiers are introduced by lowercase alphabet signs and may allow or take an argument following their lead sign.
No corresponding argument types are implied by the ‘/’ directives, and the formatting modifiers are used only as they apply.
The modifiers allowing a decimal or a positional argument include:
argument indicates the length of the comma separated blocks, applies to integral types only
argument indicates the maximum number of decimal digits, applies the reals only
argument indicates the minimum number of digits, applies to integral types only
argument indicates the minimum number of characters included for the fractional part, applies the reals only. The number is the argument plus one - argument corresponding the number of decimal digits and the one the ‘.’ sign. If less decimal digits are included in the output, white space will introduced accordingly.
argument indicates the minimum number of output characters (white space or the fill character if one indicated will be introduced as required)
argument indicates the output base, applies to integral types only
Decimals modifier arguments appear in the format specification.
Positional modifier arguments are indicated by a ‘~’ sign and they are replaced with the next argument, unless the ‘~’ is followed by a (nonsigned) decimal, case in which the argument in the position corresponding the decimal is used (just like for the ~ formatting directive). The argument is expected a nonnegative integral covertible.
If no position was given for the argument to format after the leading ‘/’, the argument after the last interpreted positional modifier argument is formatted. In either case, the next formatting directive starts processing arguments with the one after the formatted argument.
That is, the position of the formatted argument only after those of the formatting directive arguments.
Missing arguments reset modifiers to their respective defaults.
The modifiers always taking an argument include:
character argument indicates the information to be formatted. Applies to date type.
character argument sets the fill for padding to field minimum width
The meaningful modifiers not allowing an argument include:
sets the output type to character (byte), applies to numeric types only. It outputs as many bytes as specified by f (though no more than 16, 0 honored), 1 by default, the least significant ones in the binary representation of the argument, in the decreasing order of their significance.
specifies that output is to be escaped for shell use, applies to string types only
specifies that output is to be escaped for characters 0 through 31, ‘"’, ‘\’ and 127 through 255, applies to string types only
specifies that should filling is to be introduced to meet the minimum number of output characters indication, it should be introduced after the formatted argument
specifies the use of upper cases in integral output
specifies no output if the argument is zero. Applies to numerical types only. Ignored if c is present. s and w still observed.
The output modifiers may appear in the formatting directive any number of times.
Date type information selectors by the ‘i’ information modifier include:
asks for the date as /iY/-/f2im/-/f2id/, with the year a 4 digit number
asks for the hour of the day (integer) (the ‘d_d_hour’ one)
asks for the minute of the hour (integer) (the ‘d_h_minute’ one)
asks for the subsecond
asks for the second of the minute (integer) (the ‘d_m_second’ one)
asks for the time as /f2iH/:/f2iM/:/f2iS/
asks for the microsecond (integer) (the ‘d_microsecond’ one)
asks for the year (integer) (the ‘d_year’ one)
asks for the day of the month (integer) (the ‘d_m_day’ one)
asks for the month of the year (integer) (the ‘d_y_month’ one)
See Date Functions.
Where the formatting directive does not say otherwise, the numeric types are formatted in base 10. The reals are formatted with as many decimal digits as significant.
Examples:
| Format and Arguments | Output |
|---|---|
"A ~ B ~ C ~", 1, .5, "TWO" | A 1 B .5 C TWO |
"*~3 *~2 *~1", -888, 707z, "eastern" | *eastern *707 *-888 |
"[%d][%f][%s]", 1001, -.25, "ocean" | [1001][-.25][ocean] |
"%7d.%-7f.%7s", 1 << 16, 111, "blue" | 65536.111 . blue |
"// - // - //", 1, 2, 3 | 1 - 2 - 3 |
"/f4/ - /x8/ - /w8/", 128, 256, 512 | 0128 - 400 - 512 |
"/f4f/ - /x8x2/ - /w8ww6/", 128, 256, 512 | 128 - 100000000 - 512 |
"/3b4f16x2/ . /2p6/ . /1s.w8/", "X", -.03125, 511 | |
0000,0001,1111,1111 . -.03125 . .......X | |
"/f~x~/.%d", 8, 16, 65535, 9.0 | 0000ffff.9 |
"/1s_w~4x~3/.%d", 65535, 9.0, 8, 16 | __________177777.9 |
"/f4c/", 0x61696d65 | aime |
"[~]", now() | [2021-06-01 10:25:45] |
"/iY/ /1imf2/ /1f2id/", date().solve(1994, 7, 8) | 1994 07 08 |
Previous: Byte Data Output Functions, Up: The Output Library [Index]