| Description |
The FormatDateTime function provides rich formatting of a TDateTime value DateTime into a string. Formatting is defined by the Formatting string.
The Formatting string can comprise a mix of ordinary characters (that are passed unchanged to the result string), and data formatting characters. This formatting is best explained by the example code.
The following (non-Asian) formatting character strings can be used in the Formatting string:
| y | = Year last 2 digits |
| yy | = Year last 2 digits |
| yyyy | = Year as 4 digits |
| m | = Month number no-leading 0 |
| mm | = Month number as 2 digits |
| mmm | = Month using ShortDayNames (Jan) |
| mmmm | = Month using LongDayNames (January) |
| d | = Day number no-leading 0 |
| dd | = Day number as 2 digits |
| ddd | = Day using ShortDayNames (Sun) |
| dddd | = Day using LongDayNames (Sunday) |
| ddddd | = Day in ShortDateFormat |
| dddddd | = Day in LongDateFormat |
| | |
| c | = Use ShortDateFormat + LongTimeFormat |
| h | = Hour number no-leading 0 |
| hh | = Hour number as 2 digits |
| n | = Minute number no-leading 0 |
| nn | = Minute number as 2 digits |
| s | = Second number no-leading 0 |
| ss | = Second number as 2 digits |
| z | = Milli-sec number no-leading 0s |
| zzz | = Milli-sec number as 3 digits |
| t | = Use ShortTimeFormat |
| tt | = Use LongTimeFormat |
| | |
| am/pm | = Use after h : gives 12 hours + am/pm |
| a/p | = Use after h : gives 12 hours + a/p |
| ampm | = As a/p but TimeAMString,TimePMString |
| / | = Substituted by DateSeparator value |
| : | = Substituted by TimeSeparator value |
Important : if you want to see characters such as dd in the formatted output, placing them in " marks will stop them being interpreted as date or time elements.
In addition to this formatting, various of the above options are affected by the following variables, withe their default values :
| DateSeparator | = / |
| TimeSeparator | = : |
| ShortDateFormat | = dd/mm/yyyy |
| LongDateFormat | = dd mmm yyyy |
| TimeAMString | = AM |
| TimePMString | = PM |
| ShortTimeFormat | = hh:mm |
| LongTimeFormat | = hh:mm:ss |
| ShortMonthNames | = Jan Feb ... |
| LongMonthNames | = January, February ... |
| ShortDayNames | = Sun, Mon ... |
| LongDayNames | = Sunday, Monday ... |
| TwoDigitYearCenturyWindow | = 50 |
Version 2 of this function is for use within threads. You furnish the FormatSettings record before invoking the call. It takes a local copy of global formatting variables that make the routine thread safe.
|
|
| Related commands |
|
|
|
|
| Example code : Showing all of the date field formatting data types |
var
myDate : TDateTime;
begin
// Set up our TDateTime variable with a full date and time :
// 5th of June 2000 at 01:02:03.004 (.004 milli-seconds)
myDate := EncodeDateTime(2000, 6, 5, 1, 2, 3, 4);
// Date only - numeric values with no leading zeroes (except year)
ShowMessage(' d/m/y = '+
FormatDateTime('d/m/y', myDate));
// Date only - numeric values with leading zeroes
ShowMessage(' dd/mm/yy = '+
FormatDateTime('dd/mm/yy', myDate));
// Use short names for the day, month, and add freeform text ('of')
ShowMessage(' ddd d of mmm yyyy = '+
FormatDateTime('ddd d of mmm yyyy', myDate));
// Use long names for the day and month
ShowMessage('dddd d of mmmm yyyy = '+
FormatDateTime('dddd d of mmmm yyyy', myDate));
// Use the ShortDateFormat settings only
ShowMessage(' ddddd = '+
FormatDateTime('ddddd', myDate));
// Use the LongDateFormat settings only
ShowMessage(' dddddd = '+
FormatDateTime('dddddd', myDate));
// Use the ShortDateFormat + LongTimeFormat settings
ShowMessage(' c = '+
FormatDateTime('c', myDate));
end;
|
| Show full unit code |
d/m/y = 5/6/00
dd/mm/yy = 05/06/00
ddd d of mmm yyyy = Mon 5 of Jun 2000
dddd d of mmmm yyyy = Monday 5 of June 2000
ddddd = 05/06/2000
dddddd = 05 June 2000
c = 05/06/2000 01:02:03
|
|
| Example code : Showing all of the time field formatting data types |
// Full Unit code.
// -----------------------------------------------------------
// You must store this code in a unit called Unit1 with a form
// called Form1 that has an OnCreate event called FormCreate.
unit Unit1;
interface
uses
SysUtils, // Unit containing the FormatDateTime command
DateUtils,
Forms, Dialogs;
type
TForm1 = class(TForm)
procedure FormCreate(Sender: TObject);
end;
var
Form1: TForm1;
implementation
{$R *.dfm} // Include form definitions
procedure TForm1.FormCreate(Sender: TObject);
var
myDate : TDateTime;
begin
// Set up our TDateTime variable with a full date and time :
// 5th of June 2000 at 01:02:03.004 (.004 milli-seconds)
myDate := EncodeDateTime(2000, 6, 5, 1, 2, 3, 4);
// Time only - numeric values with no leading zeroes
ShowMessage(' h:n:s.z = '+FormatDateTime('h:n:s.z', myDate));
// Time only - numeric values with leading zeroes
ShowMessage('hh:nn:ss.zzz = '+FormatDateTime('hh:nn:ss.zzz', myDate));
// Use the ShortTimeFormat settings only
ShowMessage(' t = '+FormatDateTime('t', myDate));
// Use the LongTimeFormat settings only
ShowMessage(' tt = '+FormatDateTime('tt', myDate));
// Use the ShortDateFormat + LongTimeFormat settings
ShowMessage(' c = '+FormatDateTime('c', myDate));
end;
end.
|
| Hide full unit code |
h:m:s.z = 1:2:3.4
hh:mm:ss.zzz = 01:02:03.004
t = 01:02
tt = 01:02:03
c = 05/06/2000 01:02:03
|
|
| Example code : Showing the effect of local date format settings |
var
myDate : TDateTime;
begin
// Set up our TDateTime variable with a full date and time :
// 5th of June 2049 at 01:02:03.004 (.004 milli-seconds)
//
// Note that 49 is treated as 2049 as follows :
// TwoDigitYearCenturyWindow => 50
// Current year => 2008 (at time of writing)
// Subtract TwoDigitYearCenturyWindow => 1958
// 2 digit year to be converted => 49
// Compare with the last 2 digits of 1958 => Less
// So the year is in the next century => 2049
// (58 would be converted to 1958)
myDate := StrToDateTime('05/06/49 01:02:03.004');
// Demonstrate default locale settings
// Use the DateSeparator and TimeSeparator values
ShowMessage('dd/mm/yy hh:nn:ss = '+
FormatDateTime('dd/mm/yy hh:nn:ss', myDate));
// Use ShortMonthNames
ShowMessage(' mmm = '+FormatDateTime('mmm', myDate));
// Use LongMonthNames
ShowMessage(' mmmm = '+FormatDateTime('mmmm', myDate));
// Use ShortDayNames
ShowMessage(' ddd = '+FormatDateTime('ddd', myDate));
// Use LongDayNames
ShowMessage(' dddd = '+FormatDateTime('dddd', myDate));
// Use the ShortDateFormat string
ShowMessage(' ddddd = '+FormatDateTime('ddddd', myDate));
// Use the LongDateFormat string
ShowMessage(' dddddd = '+FormatDateTime('dddddd', myDate));
// Use the TimeAmString
ShowMessage(' hhampm = '+FormatDateTime('hhampm', myDate));
// Use the ShortTimeFormat string
ShowMessage(' t = '+FormatDateTime('t', myDate));
// Use the LongTimeFormat string
ShowMessage(' tt = '+FormatDateTime('tt', myDate));
// Use the TwoDigitCenturyWindow
ShowMessage(' dd/mm/yyyy = '+
FormatDateTime('dd/mm/yyyy', myDate));
ShowMessage('');
// Now change the defaults
DateSeparator := '-';
TimeSeparator := '_';
ShortDateFormat := 'dd/mmm/yy';
LongDateFormat := 'dddd dd of mmmm of yyyy';
TimeAMString := 'morning';
TimePMString := 'afternoon';
ShortTimeFormat := 'hh:nn:ss';
LongTimeFormat := 'hh : nn : ss . zzz';
ShortMonthNames[6] := 'JUN';
LongMonthNames[6] := 'JUNE';
ShortDayNames[1] := 'SUN';
LongDayNames[1] := 'SUNDAY';
TwoDigitYearCenturyWindow := 75; // This means 49 is treated as 1949
// Set up our TDateTime variable with the same value as before
// except that we must use the new date and time separators
// The TwoDigitYearCenturyWindow variable only takes effect here
myDate := StrToDateTime('09-02-49 01_02_03.004');
// Use the DateSeparator and TimeSeparator values
ShowMessage('dd/mm/yy hh:nn:ss = '+
FormatDateTime('dd/mm/yy hh:nn:ss', myDate));
// Use ShortMonthNames
ShowMessage(' mmm = '+FormatDateTime('mmm', myDate));
// Use LongMonthNames
ShowMessage(' mmmm = '+FormatDateTime('mmmm', myDate));
// Use ShortDayNames
ShowMessage(' ddd = '+FormatDateTime('ddd', myDate));
// Use LongDayNames
ShowMessage(' dddd = '+FormatDateTime('dddd', myDate));
// Use the ShortDateFormat string
ShowMessage(' ddddd = '+FormatDateTime('ddddd', myDate));
// Use the LongDateFormat string
ShowMessage(' dddddd = '+FormatDateTime('dddddd', myDate));
// Use the TimeAmString
ShowMessage(' hhampm = '+FormatDateTime('hhampm', myDate));
// Use the ShortTimeFormat string
ShowMessage(' t = '+FormatDateTime('t', myDate));
// Use the LongTimeFormat string
ShowMessage(' tt = '+FormatDateTime('tt', myDate));
// Use the TwoDigitCenturyWindow
ShowMessage(' dd/mm/yyyy = '+
FormatDateTime('dd/mm/yyyy', myDate));
end;
|
| Show full unit code |
dd/mm/yy hh:mm:ss = 05/06/49 01:02:03
mmm = Jun
mmmm = June
ddd = Sat
dddd = Saturday
ddddd = 05/06/2049
dddddd = 05 June 2049
hhampm = 01AM
t = 01:02
tt = 01:02:03
dd/mm/yyyy = 05/06/2049
dd/mm/yy hh:nn:ss = 05-06-49 01_02_03
mmm = JUN
mmmm = JUNE
ddd = SUN
dddd = SUNDAY
ddddd = 05-JUN-49
dddddd = SUNDAY 05 of JUNE of 1949
hhampm = 01morning
t = 01_02_03
tt = 01 _ 02 _ 03 . 004
dd/mm/yyyy = 05-06-1949
|
|