Difference between revisions of "Format function"

From Free Pascal wiki
Jump to navigationJump to search
("or placeholder")
 
(3 intermediate revisions by 3 users not shown)
Line 1: Line 1:
The '''format''' function formats a series of values into a string.  The format function is found in the unit ''[[SysUtils unit|SysUtils]]''.
+
{{Format function}}
For an in-depth explanation see the [http://lazarus-ccr.sourceforge.net/docs/rtl/sysutils/format.html on line documentation].
+
 
 +
The '''format''' [[Function|function]] formats a series of values into a [[String|string]].  The format function is found in the unit ''[[SysUtils unit|SysUtils]]''.
 +
For an in-depth explanation see the {{Doc|package=RTL|unit=sysutils|identifier=format|text=<syntaxhighlight lang="pascal" inline>sysutils.format</syntaxhighlight>}} on line documentation.
  
 
== Syntax ==
 
== Syntax ==
 
Format is overloaded with two ways to call it:
 
Format is overloaded with two ways to call it:
  
<syntaxhighlight>
+
<syntaxhighlight lang=pascal>
 
function Format( const Fmt: String; const Args: array of Const) : String;
 
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;  
 
function Format( const Fmt: String; const Args: array of Const; const FormatSettings: TFormatSettings) : String;  
 
</syntaxhighlight>
 
</syntaxhighlight>
  
The Fmt String argument contains ''format specifiers'' or ''placeholders'' (e.g. %d) which correspond to and are replaced in the result string by values from the Args array. An [[Const#Array of Const|array of const]] can hold a variable amount of values of different types, with the applicable types for the Format function being the variations of the [[Real]], [[Integer]], [[Pointer]] and [[String]] types. [[TFormatSettings]] is a record which holds information related to desired formatting of number, time, date and currency values.
+
The Fmt String argument contains ''format specifiers'' or ''placeholders'' (e.g. %d) which correspond to and are replaced in the result string by values from the Args array. An [[Const#Array of Const|array of const]] can hold a [[Variable|variable]] amount of values of different types, with the applicable types for the Format function being the variations of the [[Real]], [[Integer]], [[Pointer]] and [[String]] types. [[TFormatSettings]] is a [[Record|record]] which holds information related to desired formatting of number, time, date and currency values.
  
  
 
The formatting rule for each given ''format specifier'' is:
 
The formatting rule for each given ''format specifier'' is:
  % [ArgumentIndex] ['-'] [width] [. precision] ArgumentType
+
  % [ArgumentIndex:] ['-'] [width] [. precision] ArgumentType
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 68: Line 70:
 
|}
 
|}
  
== Example to use ==
+
== Example of usage ==
<syntaxhighlight>
+
 
 +
<syntaxhighlight lang=pascal>
 
procedure TForm1.Button1Click(Sender: TObject);
 
procedure TForm1.Button1Click(Sender: TObject);
 
var
 
var
Line 120: Line 123:
 
* [[doc:rtl/sysutils/formatfloat.html| FormatFloat ]]
 
* [[doc:rtl/sysutils/formatfloat.html| FormatFloat ]]
 
* [[doc:rtl/sysutils/inttohex.html| IntToHex ]] - Convert an integer into a [[Hexadecimal|hexadecimal]] string.
 
* [[doc:rtl/sysutils/inttohex.html| IntToHex ]] - Convert an integer into a [[Hexadecimal|hexadecimal]] string.
 
[[Category:RTL]]
 
[[Category:FPC]]
 

Latest revision as of 16:20, 6 August 2022

English (en) suomi (fi)

The format function formats a series of values into a string. The format function is found in the unit SysUtils. For an in-depth explanation see the sysutils.format on line documentation.

Syntax

Format is overloaded with two ways to call it:

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;

The Fmt String argument contains format specifiers or placeholders (e.g. %d) which correspond to and are replaced in the result string by values from the Args array. An array of const can hold a variable amount of values of different types, with the applicable types for the Format function being the variations of the Real, Integer, Pointer and String types. TFormatSettings is a record which holds information related to desired formatting of number, time, date and currency values.


The formatting rule for each given format specifier is:

% [ArgumentIndex:] ['-'] [width] [. precision] ArgumentType
d Decimal (integer)
e Scientific
f Fixed
g General
m Money
n Number (floating)
p Pointer
s String
u Unsigned decimal
x Hexadecimal

Integer formatting

  %d Will print the integer as it is.
  %8d Will print the integer as it is. If the number of digits is less than 8, the output will be padded on the left.
  %-8d Will print the integer as it is. If the number of digits is less than 8, the output will be padded on the right.
  %.8d Will print the integer as it is. If the number of digits is less than 8, the output will be padded on the left with zeroes.

String formatting

  %s Will print the string as it is.
  %8s Will print the string as it is. If the string has less than 8 characters, the output will be space-padded on the left (right-justified).
  %-8s Will print the string as it is. If the string has less than 8 characters, the output will be space-padded on the right (left-justified).

Example of usage

procedure TForm1.Button1Click(Sender: TObject);
var
  title,  title2,
  underline,
  line, row1, row2, row3,
  fmt : string;
  i : integer;
begin
  fmt := '%-12s';
  title := format(fmt,['Column 1']) + format(fmt,['Column 2']) ;
  for i := 1 to 12 do underline := underline + '-';
  underline := underline + underline ;
  fmt := '%-12d';
  line := format(fmt,[15]) + format(fmt,[8]) ;
  fmt := '%12s';
  title2 := format(fmt,['Column 1']) + format(fmt,['Column 2']) ;
  fmt := '%12d';
  row1 := format(fmt,[15]) + format(fmt,[8]) ;
  row2 := format(fmt,[1005]) + format(fmt,[809]) ;
  fmt := '%12.5d';
  row3 := format(fmt,[1005]) + format(fmt,[809]) ;
  Memo1.Lines.Add( title );
  Memo1.Lines.Add( underline );
  Memo1.Lines.Add( line );
  Memo1.Lines.Add( '' );
  Memo1.Lines.Add( title2 );
  Memo1.Lines.Add( underline );
  Memo1.Lines.Add( row1 );
  Memo1.Lines.Add( row2 );
  Memo1.Lines.Add( row3 );
end;

The above statements will create a set of strings that look like:

Column 1    Column 2    
------------------------
15          8           
    Column 1    Column 2
------------------------
          15           8
        1005         809
       01005       00809

See also