Format
Format a string with given arguments.
Declaration
Source position: sysstrh.inc line 151
function Format(const Fmt: string; const Args: Array of const) : string;
function Format(const Fmt: string; const Args: Array of const;
const FormatSettings: TFormatSettings) : string;
Description
Format replaces all placeholders inFmt with the arguments passed in Args and returns the resulting string. A placeholder looks as follows:
'%' [[Index]':'] ['-'] [Width] ['.' Precision] ArgType
elements between single quotes must be typed as shown without the quotes, and elements between square brackets [ ] are optional. The meaning of the different elements are shown below:
- '%'
- starts the placeholder. If you want to insert a literal % character, then you must insert two of them : %%.
- Index ':'
- takes the Index-th element in the argument array as the element to insert. If index is omitted, then the zeroth argument is taken.
- '-'
- tells Format to left-align the inserted text. The default behaviour is to right-align inserted text. This can only take effect if the Width element is also specified.
- Width
- the inserted string must have at least Width characters. If not, the inserted string will be padded with spaces. By default, the string is left-padded, resulting in a right-aligned string. This behaviour can be changed by the usage of the '-' character.
- '.' Precision
- Indicates the precision to be used when converting the argument. The exact meaning of this parameter depends on ArgType.
The Index, Width and Precision parameters can be replaced by *, in which case their value will be read from the next element in the Args array. This value must be an integer, or an EConvertError exception will be raised.
The argument type is determined from ArgType. It can have one of the following values (case insensitive):
- D
- Decimal format. The next argument in the Args array should be an integer. The argument is converted to a decimal string. If precision is specified, then the string will have at least Precision digits in it. If needed, the string is (left) padded with zeroes.
- E
Scientific format. The next argument in the Args array should be a Floating point value. The argument is converted to a decimal string using scientific notation, using FloatToStrF , where the optional precision is used to specify the total number of decimals. (default a value of 15 is used). The exponent is formatted using maximally 3 digits.
In short, the E specifier formats it's argument as follows:
FloatToStrF(Argument,ffexponent,Precision,3)
- F
Fixed point format. The next argument in the Args array should be a floating point value. The argument is converted to a decimal string, using fixed notation (see FloatToStrF ). Precision indicates the number of digits following the decimal point.
In short, the F specifier formats it's argument as follows:
FloatToStrF(Argument,ffFixed,ffixed,9999,Precision)
- G
General number format. The next argument in the Args array should be a floating point value. The argument is converted to a decimal string using fixed point notation or scientific notation, depending on which gives the shortest result. Precision is used to determine the number of digits after the decimal point.
In short, the G specifier formats it's argument as follows:
FloatToStrF(Argument,ffGeneral,Precision,3)
- M
Currency format. the next argument in the Args array must be a floating point value. The argument is converted to a decimal string using currency notation. This means that fixed-point notation is used, but that the currency symbol is appended. If precision is specified, then then it overrides the CurrencyDecimals global variable used in the FloatToStrF
In short, the M specifier formats it's argument as follows:
FloatToStrF(Argument,ffCurrency,9999,Precision)
- N
- Number format. This is the same as fixed point format, except that thousand separators are inserted in the resulting string.
- P
- Pointer format. The next argument in the Args array must be a pointer (typed or untyped). The pointer value is converted to a string of length 8, representing the hexadecimal value of the pointer.
- S
- String format. The next argument in the Args array must be a string. The argument is simply copied to the result string. If Precision is specified, then only Precision characters are copied to the result string.
- U
- Unsigned decimal format. The next argument in the Args array should be an unsigned integer. The argument is converted to a decimal string. If precision is specified, then the string will have at least Precision digits in it. If needed, the string is (left) padded with zeroes.
- X
- hexadecimal format. The next argument in the Args array must be an integer. The argument is converted to a hexadecimal string with just enough characters to contain the value of the integer. If Precision is specified then the resulting hexadecimal representation will have at least Precision characters in it (with a maximum value of 32).
Errors
In case of error, an EConvertError exception is raised. Possible errors are:
Errors in the format specifiers. The next argument is not of the type needed by a specifier. The number of arguments is not sufficient for all format specifiers.
See also
| Name | Description |
|---|---|
| EConvertError | Conversion error. |
| FormatBuf | Format a string with given arguments and store the result in a buffer. |
Example
Program example71;
{$mode objfpc}
{ This program demonstrates the Format function }
Uses sysutils;
Var P : Pointer;
fmt,S : string;
{ Expected output:
[%d] => [10]
[%%] => [%]
[%10d] => [ 10]
[%.4d] => [0010]
[%10.4d] => [ 0010]
[%0:d] => [10]
[%0:10d] => [ 10]
[%0:10.4d] => [ 0010]
[%0:-10d] => [10 ]
[%0:-10.4d] => [0010 ]
[%-*.*d] => [00010]
}
Procedure TestInteger;
begin
Try
Fmt:='[%d]';S:=Format (Fmt,[10]);writeln(Fmt:12,' => ',s);
Fmt:='[%%]';S:=Format (Fmt,[10]);writeln(Fmt:12,' => ',s);
Fmt:='[%10d]';S:=Format (Fmt,[10]);writeln(Fmt:12,' => ',s);
fmt:='[%.4d]';S:=Format (fmt,[10]);writeln(Fmt:12,' => ',s);
Fmt:='[%10.4d]';S:=Format (Fmt,[10]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:d]';S:=Format (Fmt,[10]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:10d]';S:=Format (Fmt,[10]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:10.4d]';S:=Format (Fmt,[10]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:-10d]';S:=Format (Fmt,[10]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:-10.4d]';S:=Format (fmt,[10]);writeln(Fmt:12,' => ',s);
Fmt:='[%-*.*d]';S:=Format (fmt,[4,5,10]);writeln(Fmt:12,' => ',s);
except
On E : Exception do
begin
Writeln ('Exception caught : ',E.Message);
end;
end;
writeln ('Press enter');
readln;
end;
{ Expected output:
[%x] => [A]
[%10x] => [ A]
[%10.4x] => [ 000A]
[%0:x] => [A]
[%0:10x] => [ A]
[%0:10.4x] => [ 000A]
[%0:-10x] => [A ]
[%0:-10.4x] => [000A ]
[%-*.*x] => [0000A]
}
Procedure TestHexaDecimal;
begin
try
Fmt:='[%x]';S:=Format (Fmt,[10]);writeln(Fmt:12,' => ',s);
Fmt:='[%10x]';S:=Format (Fmt,[10]);writeln(Fmt:12,' => ',s);
Fmt:='[%10.4x]';S:=Format (Fmt,[10]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:x]';S:=Format (Fmt,[10]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:10x]';S:=Format (Fmt,[10]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:10.4x]';S:=Format (Fmt,[10]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:-10x]';S:=Format (Fmt,[10]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:-10.4x]';S:=Format (fmt,[10]);writeln(Fmt:12,' => ',s);
Fmt:='[%-*.*x]';S:=Format (fmt,[4,5,10]);writeln(Fmt:12,' => ',s);
except
On E : Exception do
begin
Writeln ('Exception caught : ',E.Message);
end;
end;
writeln ('Press enter');
readln;
end;
{ Expected output:
[0x%p] => [0x0012D687]
[0x%10p] => [0x 0012D687]
[0x%10.4p] => [0x 0012D687]
[0x%0:p] => [0x0012D687]
[0x%0:10p] => [0x 0012D687]
[0x%0:10.4p] => [0x 0012D687]
[0x%0:-10p] => [0x0012D687 ]
[0x%0:-10.4p] => [0x0012D687 ]
[%-*.*p] => [0012D687]
}
Procedure TestPointer;
begin
P:=Pointer(1234567);
try
Fmt:='[0x%p]';S:=Format (Fmt,[P]);writeln(Fmt:12,' => ',s);
Fmt:='[0x%10p]';S:=Format (Fmt,[P]);writeln(Fmt:12,' => ',s);
Fmt:='[0x%10.4p]';S:=Format (Fmt,[P]);writeln(Fmt:12,' => ',s);
Fmt:='[0x%0:p]';S:=Format (Fmt,[P]);writeln(Fmt:12,' => ',s);
Fmt:='[0x%0:10p]';S:=Format (Fmt,[P]);writeln(Fmt:12,' => ',s);
Fmt:='[0x%0:10.4p]';S:=Format (Fmt,[P]);writeln(Fmt:12,' => ',s);
Fmt:='[0x%0:-10p]';S:=Format (Fmt,[P]);writeln(Fmt:12,' => ',s);
Fmt:='[0x%0:-10.4p]';S:=Format (fmt,[P]);writeln(Fmt:12,' => ',s);
Fmt:='[%-*.*p]';S:=Format (fmt,[4,5,P]);writeln(Fmt:12,' => ',s);
except
On E : Exception do
begin
Writeln ('Exception caught : ',E.Message);
end;
end;
writeln ('Press enter');
readln;
end;
{ Expected output:
[%s]=> [This is a string]
[%0:s]=> [This is a string]
[%0:18s]=> [ This is a string]
[%0:-18s]=> [This is a string ]
[%0:18.12s]=> [ This is a st]
[%-*.*s]=> [This is a st ]
}
Procedure TestString;
begin
try
Fmt:='[%s]';S:=Format(fmt,['This is a string']);Writeln(fmt:12,'=> ',s);
fmt:='[%0:s]';s:=Format(fmt,['This is a string']);Writeln(fmt:12,'=> ',s);
fmt:='[%0:18s]';s:=Format(fmt,['This is a string']);Writeln(fmt:12,'=> ',s);
fmt:='[%0:-18s]';s:=Format(fmt,['This is a string']);Writeln(fmt:12,'=> ',s);
fmt:='[%0:18.12s]';s:=Format(fmt,['This is a string']);Writeln(fmt:12,'=> ',s);
fmt:='[%-*.*s]';s:=Format(fmt,[18,12,'This is a string']);Writeln(fmt:12,'=> ',s);
except
On E : Exception do
begin
Writeln ('Exception caught : ',E.Message);
end;
end;
writeln ('Press enter');
readln;
end;
{ Expected output:
[%e] => [1.2340000000000000E+000]
[%10e] => [1.2340000000000000E+000]
[%10.4e] => [1.234E+000]
[%0:e] => [1.2340000000000000E+000]
[%0:10e] => [1.2340000000000000E+000]
[%0:10.4e] => [1.234E+000]
[%0:-10e] => [1.2340000000000000E+000]
[%0:-10.4e] => [1.234E+000]
[%-*.*e] => [1.2340E+000]
}
Procedure TestExponential;
begin
Try
Fmt:='[%e]';S:=Format (Fmt,[1.234]);writeln(Fmt:12,' => ',s);
Fmt:='[%10e]';S:=Format (Fmt,[1.234]);writeln(Fmt:12,' => ',s);
Fmt:='[%10.4e]';S:=Format (Fmt,[1.234]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:e]';S:=Format (Fmt,[1.234]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:10e]';S:=Format (Fmt,[1.234]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:10.4e]';S:=Format (Fmt,[1.234]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:-10e]';S:=Format (Fmt,[1.234]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:-10.4e]';S:=Format (fmt,[1.234]);writeln(Fmt:12,' => ',s);
Fmt:='[%-*.*e]';S:=Format (fmt,[4,5,1.234]);writeln(Fmt:12,' => ',s);
except
On E : Exception do
begin
Writeln ('Exception caught : ',E.Message);
end;
end;
writeln ('Press enter');
readln;
end;
{ Expected output:
[%e] => [-1.2340000000000000E+000]
[%10e] => [-1.2340000000000000E+000]
[%10.4e] => [-1.234E+000]
[%0:e] => [-1.2340000000000000E+000]
[%0:10e] => [-1.2340000000000000E+000]
[%0:10.4e] => [-1.234E+000]
[%0:-10e] => [-1.2340000000000000E+000]
[%0:-10.4e] => [-1.234E+000]
[%-*.*e] => [-1.2340E+000]
}
Procedure TestNegativeExponential;
begin
Try
Fmt:='[%e]';S:=Format (Fmt,[-1.234]);writeln(Fmt:12,' => ',s);
Fmt:='[%10e]';S:=Format (Fmt,[-1.234]);writeln(Fmt:12,' => ',s);
Fmt:='[%10.4e]';S:=Format (Fmt,[-1.234]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:e]';S:=Format (Fmt,[-1.234]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:10e]';S:=Format (Fmt,[-1.234]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:10.4e]';S:=Format (Fmt,[-1.234]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:-10e]';S:=Format (Fmt,[-1.234]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:-10.4e]';S:=Format (fmt,[-1.234]);writeln(Fmt:12,' => ',s);
Fmt:='[%-*.*e]';S:=Format (fmt,[4,5,-1.234]);writeln(Fmt:12,' => ',s);
except
On E : Exception do
begin
Writeln ('Exception caught : ',E.Message);
end;
end;
writeln ('Press enter');
readln;
end;
{ Expected output:
[%e] => [1.2340000000000000E-002]
[%10e] => [1.2340000000000000E-002]
[%10.4e] => [1.234E-002]
[%0:e] => [1.2340000000000000E-002]
[%0:10e] => [1.2340000000000000E-002]
[%0:10.4e] => [1.234E-002]
[%0:-10e] => [1.2300000000000000E-002]
[%0:-10.4e] => [1.234E-002]
[%-*.*e] => [1.2340E-002]
}
Procedure TestSmallExponential;
begin
Try
Fmt:='[%e]';S:=Format (Fmt,[0.01234]);writeln(Fmt:12,' => ',s);
Fmt:='[%10e]';S:=Format (Fmt,[0.01234]);writeln(Fmt:12,' => ',s);
Fmt:='[%10.4e]';S:=Format (Fmt,[0.01234]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:e]';S:=Format (Fmt,[0.01234]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:10e]';S:=Format (Fmt,[0.01234]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:10.4e]';S:=Format (Fmt,[0.01234]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:-10e]';S:=Format (Fmt,[0.0123]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:-10.4e]';S:=Format (fmt,[0.01234]);writeln(Fmt:12,' => ',s);
Fmt:='[%-*.*e]';S:=Format (fmt,[4,5,0.01234]);writeln(Fmt:12,' => ',s);
except
On E : Exception do
begin
Writeln ('Exception caught : ',E.Message);
end;
end;
writeln ('Press enter');
readln;
end;
{ Expected output:
[%e] => [-1.2340000000000000E-002]
[%10e] => [-1.2340000000000000E-002]
[%10.4e] => [-1.234E-002]
[%0:e] => [-1.2340000000000000E-002]
[%0:10e] => [-1.2340000000000000E-002]
[%0:10.4e] => [-1.234E-002]
[%0:-10e] => [-1.2340000000000000E-002]
[%0:-10.4e] => [-1.234E-002]
[%-*.*e] => [-1.2340E-002]
}
Procedure TestSmallNegExponential;
begin
Try
Fmt:='[%e]';S:=Format (Fmt,[-0.01234]);writeln(Fmt:12,' => ',s);
Fmt:='[%10e]';S:=Format (Fmt,[-0.01234]);writeln(Fmt:12,' => ',s);
Fmt:='[%10.4e]';S:=Format (Fmt,[-0.01234]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:e]';S:=Format (Fmt,[-0.01234]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:10e]';S:=Format (Fmt,[-0.01234]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:10.4e]';S:=Format (Fmt,[-0.01234]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:-10e]';S:=Format (Fmt,[-0.01234]);writeln(Fmt:12,' => ',s);
Fmt:='[%0:-10.4e]';S:=Format (fmt,[-0.01234]);writeln(Fmt:12,' => ',s);
Fmt:='[%-*.*e]';S:=Format (fmt,[4,5,-0.01234]);writeln(Fmt:12,' => ',s);
except
On E : Exception do
begin
Writeln ('Exception caught : ',E.Message);
end;
end;
writeln ('Press enter');
readln;
end;
begin
TestInteger;
TestHexadecimal;
TestPointer;
teststring;
TestExponential;
TestNegativeExponential;
TestSmallExponential;
TestSmallNegExponential;
end.