Format function: what changed

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

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