1 procedure DateTimeToString ( var Result : string; const Formatting : string; DateTime : TDateTime ) ;
2 procedure DateTimeToString ( var Result : string; const Formatting : string; DateTime : TDateTime; const FormatSettings : TFormatSettings ) ;
Description
The DateTimeToString procedure provides rich formatting of a TDateTime value DateTime into a string Result. 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
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 ...
TwoDigitCenturyWindow = 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
DateSeparator The character used to separate display date fields
DateTimeToStr Converts TDateTime date and time values to a string
LongDateFormat Long version of the date to string format
LongDayNames An array of days of the week names, starting 1 = Sunday
LongMonthNames An array of days of the month names, starting 1 = January
LongTimeFormat Long version of the time to string format
ShortDateFormat Compact version of the date to string format
ShortDayNames An array of days of the week names, starting 1 = Sunday
ShortMonthNames An array of days of the month names, starting 1 = Jan
ShortTimeFormat Short version of the time to string format
StrToDateTime Converts a date+time string into a TDateTime value
TimeAMString Determines AM value in DateTimeToString procedure
TimePMString Determines PM value in DateTimeToString procedure
TimeSeparator The character used to separate display time fields
TwoDigitYearCenturyWindow Sets the century threshold for 2 digit year string conversions
Example code : Showing all of the date field formatting data types
var
myDate : TDateTime;
formattedDateTime : string;
begin
// Set up our TDateTime variable with a full date and time :
// 09/02/2000 at 01:02:03.004 (.004 milli-seconds)
myDate := EncodeDateTime(2000, 2, 9, 1, 2, 3, 4);
// Date only - numeric values with no leading zeroes (except year)
DateTimeToString(formattedDateTime, 'd/m/y', myDate);
ShowMessage(' d/m/y = '+formattedDateTime);
// Date only - numeric values with leading zeroes
DateTimeToString(formattedDateTime, 'dd/mm/yy', myDate);
ShowMessage(' dd/mm/yy = '+formattedDateTime);
// Use short names for the day, month, and add freeform text ('of')
DateTimeToString(formattedDateTime, 'ddd d of mmm yyyy', myDate);
ShowMessage(' ddd d of mmm yyyy = '+formattedDateTime);
// Use long names for the day and month
DateTimeToString(formattedDateTime, 'dddd d of mmmm yyyy', myDate);
ShowMessage('dddd d of mmmm yyyy = '+formattedDateTime);
// Use the ShortDateFormat settings only
DateTimeToString(formattedDateTime, 'ddddd', myDate);
ShowMessage(' ddddd = '+formattedDateTime);
// Use the LongDateFormat settings only
DateTimeToString(formattedDateTime, 'dddddd', myDate);
ShowMessage(' dddddd = '+formattedDateTime);
// Use the ShortDateFormat + LongTimeFormat settings
DateTimeToString(formattedDateTime, 'c', myDate);
ShowMessage(' c = '+formattedDateTime);
end;
Show full unit code
d/m/y = 9/2/00
dd/mm/yy = 09/02/00
ddd d of mmm yyyy = Wed 9 of Feb 2000
dddd d of mmmm yyyy = Wednesday 9 of February 2000
ddddd = 09/02/2000
dddddd = 09 February 2000
c = 09/02/2000 01:02:03
Example code : Showing all of the time field formatting data types
var
myDate : TDateTime;
formattedDateTime : string;
begin
// Set up our TDateTime variable with a full date and time :
// 09/02/2000 at 01:02:03.004 (.004 milli-seconds)
myDate := EncodeDateTime(2000, 2, 9, 1, 2, 3, 4);
// Time only - numeric values with no leading zeroes
DateTimeToString(formattedDateTime, 'h:m:s.z', myDate);
ShowMessage(' h:m:s.z = '+formattedDateTime);
// Time only - numeric values with leading zeroes
DateTimeToString(formattedDateTime, 'hh:mm:ss.zzz', myDate);
ShowMessage('hh:mm:ss.zzz = '+formattedDateTime);
// Use the ShortTimeFormat settings only
DateTimeToString(formattedDateTime, 't', myDate);
ShowMessage(' t = '+formattedDateTime);
// Use the LongTimeFormat settings only
DateTimeToString(formattedDateTime, 'tt', myDate);
ShowMessage(' tt = '+formattedDateTime);
// Use the ShortDateFormat + LongTimeFormat settings
DateTimeToString(formattedDateTime, 'c', myDate);
ShowMessage(' c = '+formattedDateTime);
end;
Show 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 = 09/02/2000 01:02:03
Example code : Showing the effect of local date format settings
var
myDate : TDateTime;
formattedDateTime : string;
begin
// Set up our TDateTime variable with a full date and time
myDate := StrToDateTime('09/02/49 01:02:03.004');
// Demonstrate default locale settings
// Use the DateSeparator and TimeSeparator values
DateTimeToString(formattedDateTime, 'dd/mm/yy hh:mm:ss', myDate);
ShowMessage('dd/mm/yy hh:mm:ss = '+formattedDateTime);
// Use ShortMonthNames
DateTimeToString(formattedDateTime, 'mmm', myDate);
ShowMessage(' mmm = '+formattedDateTime);
// Use LongMonthNames
DateTimeToString(formattedDateTime, 'mmmm', myDate);
ShowMessage(' mmmm = '+formattedDateTime);
// Use ShortDayNames
DateTimeToString(formattedDateTime, 'ddd', myDate);
ShowMessage(' ddd = '+formattedDateTime);
// Use LongDayNames
DateTimeToString(formattedDateTime, 'dddd', myDate);
ShowMessage(' dddd = '+formattedDateTime);
// Use the ShortDateFormat string
DateTimeToString(formattedDateTime, 'ddddd', myDate);
ShowMessage(' ddddd = '+formattedDateTime);
// Use the LongDateFormat string
DateTimeToString(formattedDateTime, 'dddddd', myDate);
ShowMessage(' dddddd = '+formattedDateTime);
// Use the TimeAmString
DateTimeToString(formattedDateTime, 'hhampm', myDate);
ShowMessage(' hhampm = '+formattedDateTime);
// Use the ShortTimeFormat string
DateTimeToString(formattedDateTime, 't', myDate);
ShowMessage(' t = '+formattedDateTime);
// Use the LongTimeFormat string
DateTimeToString(formattedDateTime, 'tt', myDate);
ShowMessage(' tt = '+formattedDateTime);
// Use the TwoDigitCenturyWindow
DateTimeToString(formattedDateTime, 'dd/mm/yyyy', myDate);
ShowMessage(' dd/mm/yyyy = '+formattedDateTime);
ShowMessage('');
// Now change the defaults
DateSeparator := '-';
TimeSeparator := '_';
ShortDateFormat := 'dd/mmm/yy';
LongDateFormat := 'dddd dd of mmmm of yyyy';
TimeAMString := 'morning';
TimePMString := 'afternoon';
ShortTimeFormat := 'hh:mm:ss';
LongTimeFormat := 'hh : mm : ss . zzz';
ShortMonthNames[2] := 'FEB';
LongMonthNames[2] := 'FEBRUARY';
ShortDayNames[4] := 'WED';
LongDayNames[4] := 'WEDNESDAY';
TwoDigitYearCenturyWindow := 75;
// 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
DateTimeToString(formattedDateTime, 'dd/mm/yy hh:mm:ss', myDate);
ShowMessage('dd/mm/yy hh:mm:ss = '+formattedDateTime);
// Use ShortMonthNames
DateTimeToString(formattedDateTime, 'mmm', myDate);
ShowMessage(' mmm = '+formattedDateTime);
// Use LongMonthNames
DateTimeToString(formattedDateTime, 'mmmm', myDate);
ShowMessage(' mmmm = '+formattedDateTime);
// Use ShortDayNames
DateTimeToString(formattedDateTime, 'ddd', myDate);
ShowMessage(' ddd = '+formattedDateTime);
// Use LongDayNames
DateTimeToString(formattedDateTime, 'dddd', myDate);
ShowMessage(' dddd = '+formattedDateTime);
// Use the ShortDateFormat string
DateTimeToString(formattedDateTime, 'ddddd', myDate);
ShowMessage(' ddddd = '+formattedDateTime);
// Use the LongDateFormat string
DateTimeToString(formattedDateTime, 'dddddd', myDate);
ShowMessage(' dddddd = '+formattedDateTime);
// Use the TimeAmString
DateTimeToString(formattedDateTime, 'hhampm', myDate);
ShowMessage(' hhampm = '+formattedDateTime);
// Use the ShortTimeFormat string
DateTimeToString(formattedDateTime, 't', myDate);
ShowMessage(' t = '+formattedDateTime);
// Use the LongTimeFormat string
DateTimeToString(formattedDateTime, 'tt', myDate);
ShowMessage(' tt = '+formattedDateTime);
// Use the TwoDigitCenturyWindow
DateTimeToString(formattedDateTime, 'dd/mm/yyyy', myDate);
ShowMessage(' dd/mm/yyyy = '+formattedDateTime);
end;
Show full unit code
dd/mm/yy hh:mm:ss = 09/02/49 01:02:03
mmm = Feb
mmmm = February
ddd = Tue
dddd = Tuesday
ddddd = 09/02/2049
dddddd = 09 February 2049
hhampm = 01AM
t = 01:02
tt = 01:02:03
dd/mm/yyyy = 09/02/2049
dd/mm/yy hh:mm:ss = 09-02-49 01_02_03
mmm = FEB
mmmm = FEBRUARY
ddd = WED
dddd = WEDNESDAY
ddddd = 09-FEB-49
dddddd = WEDNESDAY 09 of FEBRUARY of 1949
hhampm = 01morning
t = 01_02_03
tt = 01 _ 02 _ 03 . 004
dd/mm/yyyy = 09-02-1949