Sign in Join
FPDoc Onlineexperiment

Format function

In unit sysutils

Format a string with given arguments.

Declaration

pascal
function Format(const Fmt: AnsiString; const Args: Array of const)
: AnsiString

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):

B
Boolean format. The next argument in the Args array should be a boolean or an integer (a nonzero value is taken as True, zero is taken as false). The argument is converted to a string using BoolToStr with True as the second argument, i.e. boolean strings are used. If a precision is specified, then the string will have at most Precision characters in it, as for the "S" format specifier.
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 its 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 or a character (unicode or ansi is acceptable for both). 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).

An unknown formatting character is ignored.

Errors

In case of error, an EConvertError exception is raised. Possible errors are:

  1. Errors in the format specifiers.
  2. The next argument is not of the type needed by a specifier.
  3. The number of arguments is not sufficient for all format specifiers.

See also

Example: ex71

pascal
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.

An experiment, built from development snapshots. Not the official Free Pascal or Lazarus documentation.