Home  |  Delphi .net Home  |  System.String  |  Format Method
  
Format  
Method  
Formats numbers, datetimes and enumerations into a string
String Class
System NameSpace
CF1.  Function Format ( Formatting : String; Value : TObject ) : String; Static;
CF2.  Function Format ( Formatting : String; ValueA : TObject; ValueB : TObject ) : String; Static;
CF3.  Function Format ( Formatting : String; ValueA : TObject; ValueB : TObject; ValueC : TObject ) : String; Static;
CF4.  Function Format ( Formatting : String; ValueArray : Array of TObject ) : String; Static;
CF5.  Function Format ( FormatProvider : IFormatProvider; Formatting : String; ValueArray : Array of TObject ) : String; Static;
CF : Methods with this mark are Compact Framework Compatible
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
 
Short Date, such as : 24/08/2004
Long date, such as 24 August 2004
Short time, such as 12:23
Long time, such as 12:23:45
Full datetime, such as 24 August 2004 12:23
Full datetime, such as 24 August 2004 12:23:45
General datetime, such as 24/08/2004 12:23
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
Sortable datetime, such as 2004-08-24T12:23:45
Universal sortable datetime
Y or y Year plus month, such as August 2004

 
3. Enumeration formatting characters
 
Decimal
Fixed
General
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
 Author links

 Buy Website Traffic at
 Buywebsitetrafficexperts.com

 Buy Proxies at
 Buyproxies.io
 
 
 
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.
   [] 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.
   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
 
 
Delphi Programming Neil Moffatt 2002 - 2017. All rights reserved.  |  Contact the author