Initializing help system before first use

# formattext

Purpose
Create a text from a format string and its parameters.
Synopsis
`function formattext(fmt:string, a1, a2...):text`
`function formattext(fmt:string, l: list):text`
Arguments

fmt | Format string
ai | Parameters of the format string
l | List of parameters of the format string

Return value
Formatted text.
Example
The following:

    writeln(formattext("text1%8stext3", "text2"))
    writeln(formattext("text1%-8stext3", "text2"))
    r:=789.123456
    writeln(formattext("%1$r %1$4.2f%1$8.0f",r))

produces this output:

    text1     text2text3
    text1text2     text3
    789.123 789.12        789

Further information
1. This procedure behaves in a similar way as the sprintf function of the C language: the resulting text is generated by inserting each of the parameters ai in the format string at locations identified by a marker. This marker is of the form:

    %[index$][flags][width][.precision]conv

Where index (a non negative integer), flags (string of ' ', '-', '+', '0' and '#'), width (positive integer) and precision (non negative integer) are optional.
The index indicates which parameter to use for the conversion (first parameter has number 1), when it is not specified the marker position is used instead ( e.g. the third marker is used for the third parameter).
The flags essentially affect numerical conversions: with the flag '0' the value is zero padded; with '-' the value is left justified; with a space a blank is put before positive numbers and with '+' positive numbers are preceded by the '+' sign.
The width defines a minimum width for the field.
The precision gives the minimum number of digits to appear for an integer conversion. With a floating point value and a conversion 'a', 'A', 'e', 'E' or 'f' it states the number of digits to appear after the radix and for a 'g' conversion it is the maximum number of significant digits. The precision indicates a maximum number of characters to display with textual conversions.
The conversion specifier conv is a letter indicating how to process the corresponding parameter and what to ouput. Possible values for this character are:

diouxX | an integer value is output: the parameter must be an integer or a Boolean. The value is displayed as a decimal number ( 'd' or 'i'), an octal number ( 'o'), an unsigned number ( 'u') or a hexadecimal number ( 'x' or 'X')
eEfgraAjy | a real value is output: the parameter must be a real or an integer. If it is a real and parameter txtztol is true then any value smaller than parameter zerotol will be replaced 0. When using the 'r' conversion the optional part components of the marker are ignored and the value is converted using the current real printing format (according to the realfmt parameter). The conversions 'e' and 'E' format the number as [-]d.ddde+/-dd; conversion 'f' uses a format of the form [-]ddd.ddd and conversion 'g' selects format 'e' or 'f' depending on the value of the number. With 'a' and 'A' the value is converted to an hexadecimal representation of the form [-]0xh.hhhp[+/-]ddd where 'h' are hexadecimal digits and 'd' decimal digits. The conversions 'j' and 'y' produce a reversible textual representation of the real number ( i.e. converting the string back to real restores the exact original value). The format 'j' generates a decimal notation similar to the specification ECMA-262 ( e.g. "123.456") while the format 'y' produces a scientific notation in all cases ( e.g. "1.2345e2").
b | 'true' or 'false' is output: the parameter must be a Boolean
c | a character is output: the parameter must be an integer that is interpreted as a Unicode code point
s | a text string is output: the parameter must be a string or any type supporting conversion to text
p | a pointer expressed in hexadecimal is output: the parameter can be any referenced entity

2. To include the symbol '%' in the format string use the sequence '%%'.
Related topics
textfmt, setparam, realfmt, txtztol, zerotol
Module
mmsystem
Parent Topic Procedures and functions

© 2001-2026 Fair Isaac Corporation. All rights reserved. This documentation is the property of Fair Isaac Corporation (“FICO”). Receipt or possession of this documentation does not convey rights to disclose, reproduce, make derivative works, use, or allow others to use it except solely for internal evaluation purposes to determine whether to purchase a license to the software described in this documentation, or as otherwise set forth in a written software license agreement between you and FICO (or a FICO affiliate). Use of this documentation and the software described in it must conform strictly to the foregoing permitted uses, and no other use is permitted.