Smart Pascal : DateTimeToString command

SmartPascal
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

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 :
  // 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