Format function: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: Format function

New		Line
1	+	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 [`sysutils.format`](https://www.freepascal.org/docs-html/rtl/sysutils/format.html) on line documentation.
2	+
3	+	## Syntax
4	+
5	+	Format is overloaded with two ways to call it:
6	+
7	+	``` pascal
8	+	function Format( const Fmt: String; const Args: array of Const) : String;
9	+	function Format( const Fmt: String; const Args: array of Const; const FormatSettings: TFormatSettings) : String;
10	+	```
11	+
12	+	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]] 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.
13	+
14	+	The formatting rule for each given format specifier is:
15	+
16	+	`% [ArgumentIndex:] ['-'] [width] [. precision] ArgumentType`
17	+
18	+	\| \| \|
19	+	\|-----\|-------------------\|
20	+	\| d \| Decimal (integer) \|
21	+	\| e \| Scientific \|
22	+	\| f \| Fixed \|
23	+	\| g \| General \|
24	+	\| m \| Money \|
25	+	\| n \| Number (floating) \|
26	+	\| p \| Pointer \|
27	+	\| s \| String \|
28	+	\| u \| Unsigned decimal \|
29	+	\| x \| Hexadecimal \|
30	+
31	+	### Integer formatting
32	+
33	+	\| \| \|
34	+	\|----\|----\|
35	+	\| %d \| Will print the integer as it is. \|
36	+	\| %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. \|
37	+	\| %-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. \|
38	+	\| %.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. \|
39	+
40	+	### String formatting
41	+
42	+	\| \| \|
43	+	\|----\|----\|
44	+	\| %s \| Will print the string as it is. \|
45	+	\| %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). \|
46	+	\| %-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). \|
47	+
48	+	## Example of usage
49	+
50	+	``` pascal
51	+	procedure TForm1.Button1Click(Sender: TObject);
52	+	var
53	+	title, title2,
54	+	underline,
55	+	line, row1, row2, row3,
56	+	fmt : string;
57	+	i : integer;
58	+	begin
59	+	fmt := '%-12s';
60	+	title := format(fmt,['Column 1']) + format(fmt,['Column 2']) ;
61	+	for i := 1 to 12 do underline := underline + '-';
62	+	underline := underline + underline ;
63	+	fmt := '%-12d';
64	+	line := format(fmt,[15]) + format(fmt,[8]) ;
65	+	fmt := '%12s';
66	+	title2 := format(fmt,['Column 1']) + format(fmt,['Column 2']) ;
67	+	fmt := '%12d';
68	+	row1 := format(fmt,[15]) + format(fmt,[8]) ;
69	+	row2 := format(fmt,[1005]) + format(fmt,[809]) ;
70	+	fmt := '%12.5d';
71	+	row3 := format(fmt,[1005]) + format(fmt,[809]) ;
72	+	Memo1.Lines.Add( title );
73	+	Memo1.Lines.Add( underline );
74	+	Memo1.Lines.Add( line );
75	+	Memo1.Lines.Add( '' );
76	+	Memo1.Lines.Add( title2 );
77	+	Memo1.Lines.Add( underline );
78	+	Memo1.Lines.Add( row1 );
79	+	Memo1.Lines.Add( row2 );
80	+	Memo1.Lines.Add( row3 );
81	+	end;
82	+	```
83	+
84	+	The above statements will create a set of strings that look like:
85	+
86	+	`Column 1 Column 2 `\
87	+	`------------------------`\
88	+	`15 8 `
89	+
90	+	` Column 1 Column 2`\
91	+	`------------------------`\
92	+	` 15 8`\
93	+	` 1005 809`\
94	+	` 01005 00809`
95	+
96	+	## See also
97	+
98	+	- [[doc:rtl/sysutils/format.html\|Format]]
99	+	- [[doc:rtl/sysutils/floattostrf.html\|FloatToStrF]]
100	+	- [[doc:rtl/sysutils/formatfloat.html\|FormatFloat]]
101	+	- [[doc:rtl/sysutils/inttohex.html\|IntToHex]] - Convert an integer into a [[Hexadecimal\|hexadecimal]] string.
102	+
103	+	---
104	+	From the Free Pascal wiki, page "Format function", as it stood on 2022-08-06 after a change by Kai Burghardt, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history