Text formatting in Rittle is performed by the function “format”:
format fmt [, parameter1, parameter2, …]
The function takes undefined number of parameters (minimum one – the format specifications), and returns a single text which can be assigned to a variable, output, etc.
The function name “format” can be replaced with its alias in Rittle – the character ‘$’.
The format specification text is the only mandatory parameter. It is a text, which also may contain instructions to take more parameters. The formed output text is taken from the input “fmt” with all references to parameters processed and replaced with their results.
Format instructions in the input text always start with a ‘|’ character, and have the following general format:
| type [modifiers [length [.precision]] [modifiers]]
It is important to note that no spaces are allowed within a format instruction (except for specifying fill characters which will be discussed later).
“type” is a single character which specifies the data type of the parameter:
‘d’ or ‘D’ Decimal number
Only decimal numbers can have the “.precision” part of the instruction.
‘x’ or ‘X’ Hexadecimal number
The case register of the type determines the case register of the hexadecimal letters.
‘b’ or ‘B’ Binary number
‘t’ or ‘T’ Text
Modifiers are characters which instruct how the output result should be formatted. Some modifiers can only work with specific data types, or require explicitly defined length.
Supported modifiers:
‘+’ Forced sign (works only with decimal numbers)
‘-‘ Space for ‘-‘ sign (works only with decimal numbers)
‘<’ Left-aligned result (require specified field length)
‘>’ Right-aligned result (require specified field length)
‘^’ Centred result (require specified field length)
‘*’ Fill with characters (require specified field length)
(followed by a mandatory character which specifies the fill character)
The modifier ‘*’ can be found twice within an instruction. The first occurrence specifies the fill character before the result. The second occurrence specifies the fill character after the result. Both fill characters are considered as space by default, unless changed with the modifier.
The “length” part defines the minimum total size of the output field. If the parameter is numeric and the suggested length is insufficient to accommodate it, then the output field automatically beyond the defined length value. Text data however does not expand beyond specified length but is trimmed to the specification.
Without defined length the output will be as long as it needs to be.
Decimal numbers may also need to contain digits after a decimal point. To specify the number of required digits in the output, the part “.precision” is used.
Both “length” and “.precision” (whenever used) must be integer decimal numbers greater than 0.
If “length” is missing, but “precision” is present in the format specification, the number is output with the needed number of digits before the decimal point, and only the specified number of digits after it.
Examples:
print $”Current time: |d*02>:|d*02>:|d*02>”, h, m, s; ‘ print time hh:mm:ss
var text s= $”|t^80*<*>”,
“ TITLE LINE ”; ‘ the text “TITLE LINE” centred
‘ within an 80-character field
var text s= $”Amount:
|>10.2, New: |>-10.2”, total, new ‘ create formatted
‘ text with numbers