| Description |
Format provides a very rich and well organised set of formatting options for the integer, decimal, datetime and enumeration data types.
For a full tutorial on this subject, see the String Formatting tutorial.
The data parameters to the Format function may be passed as a discrete set of up to 3 variables, or as an unlimited array of variables.
The formatting string comprises 0, 1 or more sections of plain text, interspersed with formatting string sections. These formatting sections are delimited by {} brackets.
You may use { and } in the plain text by repeating each : {{ and }} respectively.
The formatting sections each have the following general syntax :
{Index[,Width][:Formatting]}
Where :
| Index | Is the parameter number (0 indexed) |
| Width | Defines the whole field width |
| Formatting | Defines a specific format to use |
The formatting value has the following syntax :
FormattingChar[Precision]
Unlike the non-.Net Delphi Format Run Time Library function, the .Net formatting character set is split into 3 groups, applicable to the general data type. For example, the D formatting character applied to a number yields a Decimal string, but applied to a DateTime will yield a LongDate string.
The optional Precision forces the number of decimal places or significant digits as appropriate.
1. Number formatting characters
| C or c | Currency such as ?1,234.56 |
| D or d | Integer formatting such as 123456 |
| E or e | Exponential (Scientific) such as 1.23456E+003 |
| F or f | Fixed Point such as 1234.56 |
| G or g | General : type dependent |
| N or n | Number : -d,ddd,ddd.ddd... format |
| P or p | Percent such as 69.5% |
| R or r | Round-trip - guarantees reverse formatting |
| X or x | Hex such as E06FC (using X) or e06fc (using x) |
2. DateTime formatting characters
| d | Short Date, such as : 24/08/2004 |
| D | Long date, such as 24 August 2004 |
| t | Short time, such as 12:23 |
| T | Long time, such as 12:23:45 |
| f | Full datetime, such as 24 August 2004 12:23 |
| F | Full datetime, such as 24 August 2004 12:23:45 |
| g | General datetime, such as 24/08/2004 12:23 |
| G | General datetime, such as 24/08/2004 12:23:45 |
| M or m | Month, such as 24 August |
| R or r | Culture independant, such as Tue 24 August 2004 12:23:45 GMT |
| s | Sortable datetime, such as 2004-08-24T12:23:45 |
| u | Universal sortable datetime |
| Y or y | Year plus month, such as August 2004 |
3. Enumeration formatting characters
| D | Decimal |
| F | Fixed |
| G | General |
| X | Hex |
|
| | Notes | Important : The Delphi primitives Integer, Single, Double etc are implemented as structures in .Net. These structures are not treated as objects by Delphi (they are in C# for example), so you must cast them to TObject or System.Object.
The formatting facility provided by String.Format is also provided by Console.WriteLine, and in limited scope in the ToString method of all classes that support the IFormattable interface.
The FormatProvider option allows for customised formatting and is beyond the scope of Delphi Basics.
NumberFormatInfo defines the flavour of number formatting.
DateTimeFormatInfo defines the flavour of datetime formatting.
|
|
| Microsoft MSDN Links |
system
system.String
|
|
|
| Illustrating the general parameter formatting |
program Project1;
{$APPTYPE CONSOLE}
var
number : Decimal;
text : String;
formatting : String;
result : String;
begin
number := 123456.78;
text := 'Hello';
Console.WriteLine('[] surrounds each element for clarity');
Console.WriteLine('Result shown using UK culture information');
Console.WriteLine;
Console.WriteLine('Composite formatting - using a parameter list');
Console.WriteLine('Note : the same parameter can be used multiple times');
Console.WriteLine;
formatting := '[{0}] [{0,15}] [{0:C}] [{0,15:E}] [{1}]';
result := System.String.Format(formatting, number, text);
Console.WriteLine(result);
Console.ReadLine;
end.
| | Show full unit code | [] surrounds each element for clarity
Result shown using UK culture information
Composite formatting - using a parameter list
Note : the same parameter can be used multiple times
[123456.78] [ 123456.78] [?123,456.78] [ 1.234568E+005] [Hello]
| | | Illustrating the formatting character options | program Project1;
{$APPTYPE CONSOLE}
var
decNumber : Decimal;
intNumber : Integer;
floatNum : Single;
when : DateTime;
enum : system.DayOfWeek;
begin
decNumber := 123456.789;
intNumber := 123456789;
floatNum := 0.25;
when := DateTime.Now;
enum := DayOfWeek.Tuesday;
Console.WriteLine('Number formatting examples :');
Console.WriteLine;
Console.WriteLine(System.String.Format('C : Currency : {0:C}',
decNumber));
Console.WriteLine(System.String.Format('D : Integer (D) : {0:D}',
System.Object (intNumber)));
Console.WriteLine(System.String.Format('E : Exponential : {0:E}',
decNumber));
Console.WriteLine(System.String.Format('F : Fixed : {0:F}',
decNumber));
Console.WriteLine(System.String.Format('G : General : {0:G}',
decNumber));
Console.WriteLine(System.String.Format('N : Number : {0:N}',
decNumber));
Console.WriteLine(System.String.Format('P : Percent : {0:P}',
System.Object (floatNum)));
Console.WriteLine(System.String.Format('R : Round-trip : {0:R}',
System.Object (floatNum)));
Console.WriteLine(System.String.Format('X : Hexadecimal (X): {0:X}',
System.Object (intNumber)));
Console.WriteLine(System.String.Format('x : Hexadecimal (x): {0:x}',
System.Object (intNumber)));
Console.WriteLine;
Console.WriteLine('DateTime formatting examples :');
Console.WriteLine;
Console.WriteLine(System.String.Format('d : Short Date : {0:d}', when));
Console.WriteLine(System.String.Format('D : Long Date : {0:D}', when));
Console.WriteLine(System.String.Format('t : Short Time : {0:t}', when));
Console.WriteLine(System.String.Format('T : Long Time : {0:T}', when));
Console.WriteLine(System.String.Format('f : Full date : {0:f}', when));
Console.WriteLine(System.String.Format('F : Long full date : {0:F}', when));
Console.WriteLine(System.String.Format('g : General : {0:g}', when));
Console.WriteLine(System.String.Format('G : Long general : {0:G}', when));
Console.WriteLine(System.String.Format('M : Month : {0:M}', when));
Console.WriteLine(System.String.Format('R : RFC1123 : {0:R}', when));
Console.WriteLine(System.String.Format('s : Sortable : {0:s}', when));
Console.WriteLine(System.String.Format('u : Universal sort : {0:u}', when));
Console.WriteLine(System.String.Format('Y : Year : {0:Y}', when));
Console.WriteLine;
Console.WriteLine('Enumeration formatting examples :');
Console.WriteLine;
Console.WriteLine(System.String.Format('G : General : {0:G}', enum));
Console.WriteLine(System.String.Format('F : Fixed : {0:F}', enum));
Console.WriteLine(System.String.Format('D : Decimal : {0:D}', enum));
Console.WriteLine(System.String.Format('X : Hexadecimal (X): {0:X}', enum));
Console.WriteLine(System.String.Format('x : Hexadecimal (x): {0:x}', enum));
Console.ReadLine;
end.
| | Show full unit code | Number formatting examples :
C : Currency : ?123,456.79
D : Integer (D) : 123456789
E : Exponential : 1.23456789E+005
F : Fixed : 123456.79
G : General : 123456.789
N : Number : 123,456,79
P : Percent : 25.00%
R : Round-trip : 0.25
X : Hexadecimal (X): 75BCD15
x : Hexadecimal (x): 75bcd15
DateTime formatting examples :
d : Short Date : 24/08/2004
D : Long Date : 24 August 2004
t : Short Time : 16:45
T : Long Time : 16:45:31
f : Full date : 24 August 2004 16:45
F : Long full date : 24 August 2004 16:45:31
g : General : 24/08/2004 16:45
G : Long general : 24/08/2004 16:45:31
M : Month : 24 August
R : RFC1123 : Tue, 24 August 2004 16:45:31 GMT
s : Sortable : 2004-08-24T15:45:31
u : Universal sort : 2004-08-24 15:45:31Z
y : Year : August 2004
Enumeration formatting examples :
G : General : Tuesday
F : Fixed : Tuesday
D : Decimal : 2
X : Hexadecimal (X): 00000002
x : Hexadecimal (x): 00000002
|
| |
|
|
|