DelphiBasics
DateTimeToString
Procedure		 Rich formatting of a TDateTime variable into a string SysUtils unit
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
DateSeparatorThe character used to separate display date fields
DateTimeToStrConverts TDateTime date and time values to a string
LongDateFormatLong version of the date to string format
LongDayNamesAn array of days of the week names, starting 1 = Sunday
LongMonthNamesAn array of days of the month names, starting 1 = January
LongTimeFormatLong version of the time to string format
ShortDateFormatCompact version of the date to string format
ShortDayNamesAn array of days of the week names, starting 1 = Sunday
ShortMonthNamesAn array of days of the month names, starting 1 = Jan
ShortTimeFormatShort version of the time to string format
StrToDateTimeConverts a date+time string into a TDateTime value
TimeAMStringDetermines AM value in DateTimeToString procedure
TimePMStringDetermines PM value in DateTimeToString procedure
TimeSeparatorThe character used to separate display time fields
TwoDigitYearCenturyWindowSets the century threshold for 2 digit year string conversions
 Download this web site as a Windows program.




 
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 :
  // 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)
  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 = 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
var
  myDate : TDateTime;
  formattedDateTime : string;

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
  DateTimeToString(formattedDateTime, 'h:n:s.z', myDate);
  ShowMessage('     h:n:s.z = '+formattedDateTime);

  // Time only - numeric values with leading zeroes
  DateTimeToString(formattedDateTime, 'hh:nn:ss.zzz', myDate);
  ShowMessage('hh:nn: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 = 05/06/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 :
  // 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
  DateTimeToString(formattedDateTime, 'dd/mm/yy hh:nn:ss', myDate);
  ShowMessage('dd/mm/yy hh:nn: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: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('05-06-49 01_02_03.004');

  // Use the DateSeparator and TimeSeparator values
  DateTimeToString(formattedDateTime, 'dd/mm/yy hh:nn:ss', myDate);
  ShowMessage('dd/mm/yy hh:nn: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 = 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
 
Delphi Programming © Neil Moffatt . All rights reserved.  |  Home Page