Difference between revisions of "Format function"

From Free Pascal wiki
Jump to navigationJump to search
(Categorization)
 
(16 intermediate revisions by 7 users not shown)
Line 1: Line 1:
−
= Format =
+
{{Format function}}
  
 +
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.
  
−
The format function formats a series of strings and numeric values and stores the resulting in string.
+
== Syntax ==
 +
Format is overloaded with two ways to call it:
  
−
To see the the right result in all cases, you should use the monospaced font (fixed-width).
+
<syntaxhighlight lang=pascal>
−
Examples of monospaced fonts include Courier, Courier New, Lucida Console
+
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;
 +
</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|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 most basic rule that string formatting follows is this:
 
−
% [argument index] [flag] [width] [.precision] argument type
 
  
 +
The formatting rule for each given ''format specifier'' is:
 +
% [ArgumentIndex:] ['-'] [width] [. precision] ArgumentType
  
−
== Argument type ==
+
{| class="wikitable"
−
 
+
|-
−
* d = Decimal (integer)
+
| d || Decimal (integer)
−
* e = Scientific
+
|-
−
* f = Fixed
+
| e || Scientific
−
* g = General
+
|-
−
* m = Money
+
| f || Fixed
−
* n = Number (floating)
+
|-
−
* p = Pointer
+
| g || General
−
* s = String
+
|-
−
* u = Unsigned decimal
+
| m || Money
−
* x = Hexadecimal
+
|-
−
 
+
| n || Number (floating)
−
== Integer formatting ==
+
|-
 +
| p || Pointer
 +
|-
 +
| s || String
 +
|-
 +
| u || Unsigned decimal
 +
|-
 +
| x || Hexadecimal
 +
|}
  
 +
=== Integer formatting ===
 
{| class="wikitable"  
 
{| class="wikitable"  
 
|-
 
|-
Line 33: Line 48:
 
|-
 
|-
 
| &nbsp; %8d     
 
| &nbsp; %8d     
−
| Will pint the integer as it is. If the number of digits is less than 8, the output will be padded on the left.
+
| Will print the integer as it is. If the number of digits is less than 8, the output will be padded on the left.
 
|-
 
|-
 
| &nbsp; %-8d   
 
| &nbsp; %-8d   
−
| Will pint the integer as it is. If the number of digits is less than 8, the output will be padded on the right.
+
| Will print the integer as it is. If the number of digits is less than 8, the output will be padded on the right.
 
|-
 
|-
 
| &nbsp; %.8d  
 
| &nbsp; %.8d  
−
| Will pint the integer as it is. If the number of digits is less than 8, the output will be padded on the left with zeroes.
+
| 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 ==
+
=== String formatting ===
−
 
 
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 51: Line 64:
 
|-
 
|-
 
| &nbsp; %8s     
 
| &nbsp; %8s     
−
| Will pint the string as it is. If the string has less than 8 characters, the output will be padded on the left.
+
| 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).
 
|-
 
|-
 
| &nbsp; %-8s   
 
| &nbsp; %-8s   
−
| Will pint the string as it is. If the string has less than 8 characters, the output will be padded on the left.
+
| 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 to use ==
+
== Example of usage ==
−
 
 
−
<syntaxhighlight>
 
−
...
 
  
 +
<syntaxhighlight lang=pascal>
 
procedure TForm1.Button1Click(Sender: TObject);
 
procedure TForm1.Button1Click(Sender: TObject);
 
var
 
var
Line 94: Line 104:
 
   Memo1.Lines.Add( row3 );
 
   Memo1.Lines.Add( row3 );
 
end;  
 
end;  
−
 
−
...
 
−
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
 
+
The above statements will create a set of strings that look like:
−
The above program will print out :
 
  
 
  Column 1    Column 2     
 
  Column 1    Column 2     
Line 111: Line 117:
 
         1005        809
 
         1005        809
 
         01005      00809
 
         01005      00809
−
 
−
 
−
 
  
 
== See also ==
 
== See also ==
−
 
 
* [[doc:rtl/sysutils/format.html| Format ]]
 
* [[doc:rtl/sysutils/format.html| Format ]]
 
* [[doc:rtl/sysutils/floattostrf.html| FloatToStrF ]]
 
* [[doc:rtl/sysutils/floattostrf.html| FloatToStrF ]]
 
* [[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:FPC]]
 

Latest revision as of 17: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

Retrieved from "http://wiki.freepascal.org/index.php?title=Format_function&oldid=153258"