DelphiBasics
  Home  |  Dates and times
 Documents
 Tutorials

 Writing your first program
 Writing your second program
 Amending this program
 
 Delphi data types
   Numbers
   Text
   Sets and enumerations
   Arrays
   Records
 
 Programming logic
   Looping
   SubRoutines
   Exception handling
 
 Dates and times
 
 Files
 
 Pointers
 
 Printing text and graphics
 
 Object Orientation basics
   Memory leaks!
   Inheritance
   Abstraction
   Interfaces
   An example class
 
 References

 Standard components
 
 Articles

 Learn to program in Pascal - online education course

 Castalia for Delphi
 A brief history of Delphi
 
 Usability : file handling
 Usability : reference books
 
  Dates and times
Why have a tutorial just on dates and times?
Because they are a surprisingly complex and rich subject matter. And very useful, especially since Delphi provides extensive support for calculations, conversions and names.
 

The TDateTime data type
Date and time processing depends on the TDateTime variable. It is used to hold a date and time combination. It is also used to hold just date or time values - the time and date value is ignored respectively. TDateTime is defined in the System unit. Date constants and routines are defined in SysUtils and DateUtils units.
 
Let us look at some simple examples of assigning a value to a TDateTime variable:
 
 var
   date1, date2, date3 : TDateTime;       // TDateTime variables
 begin
   date1 := Yesterday;      // Set to the start of yesterday
   date2 := Date;           // Set to the start of the current day
   date3 := Tomorrow;       // Set to the start of tomorrow
   date4 := Now;            // Set to the current day and time
 end;

 date1 is set to something like 12/12/2002 00:00:00
 date2 is set to something like 13/12/2002 00:00:00
 date3 is set to something like 14/12/2002 00:00:00
 date4 is set to something like 13/12/2002 08:15:45

Note : the start of the day is often called midnight in Delphi documentation, but this is misleading, since it would be midnight of the wrong day.
 

Some named date values
Delphi provides some useful day and month names, saving you the tedium of defining them in your own code. Here they are:
 
Short and long month names
Note that these month name arrays start with index = 1.
 
 var
   month : Integer;
 begin
   for month := 1 to 12 do    // Display the short and long month names
   begin
     ShowMessage(ShortMonthNames[month]);
     ShowMessage(LongMonthNames[month]);
   end;
 end;

 The ShowMessage routine display the following information:
 
 Jan
 January
 Feb
 February
 Mar
 March
 Apr
 April
 May
 May
 Jun
 June
 Jul
 July
 Aug
 August
 Sep
 September
 Oct
 October
 Nov
 November
 Dec
 December

Short and long day names
It is important to note that these day arrays start with index 1 = Sunday. This is not a good standard (it is not ISO 8601 compliant), so be careful when using with ISO 8601 compliant routines such as DayOfTheWeek
 
 var
   day : Integer;
 begin
   for day := 1 to 12 do    // Display the short and long day names
   begin
     ShowMessage(ShortDayNames[day]);
     ShowMessage(LongDayNames[day]);
   end;
 end;

 The ShowMessage routine display the following information:
 
 Sun
 Sunday
 Mon
 Monday
 Tue
 Tuesday
 Wed
 Wednesday
 Thu
 Thursday
 Fri
 Friday
 Sat
 Saturday


Date and time calculations
The largest benefit of TDateTime is the range of calculations Delphi can do for you. These can be found on the Delphi Basics home page, in the Dates and Times/Calculations option.
 
In the following examples, click on the name to learn more:
 
 DayOfTheMonth  Gives the day of month index for a TDateTime value
 DaysBetween    Gives the whole number of days between 2 dates
 DaysInAMonth   Gives the number of days in a month
 DaysInAYear    Gives the number of days in a year
 DecodeDate     Extracts the year, month, day values from a TDateTime var.
 EncodeDate     Build a TDateTime value from year, month and day values
 IncDay         Increments a TDateTime variable by + or - number of days
 IsLeapYear     Returns true if a given calendar year is a leap year
 MinsPerDay     Gives the number of minutes in a day


Displaying date and time values
There are a number of routines that convert date and or time values to strings for display or file storage purposes, such as dateTimeToStr and TimeToString. But the most important is the FormatDateTime. It provides comprehensive formatting control, as illustrated by the following examples.
 
Using default formatting options
 var
   myDate : TDateTime;
 
 begin
   // Set up our TDateTime variable with a full date and time :
   // 09/02/2000 at 05:06:07.008 (.008 milli-seconds)
   myDate := EncodeDateTime(2000, 2, 9, 5, 6, 7, 8);
 
   // 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));
 
   ShowMessage('');
 
   // 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;

 The ShowMessage routine shows the following outputs :
 
               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 05:06:07
 
             h:n:s.z = 5:6:7.008
        hh:nn:ss.zzz = 05:06:07.008
                   t = 05:06
                  tt = 05:06:07
                   c = 09/02/2000 05:06:07

The above output uses default values of a number of formatting control variables. These are covered in the next section:
 
Formatting control variables
The variables and their default values are given below. Note that these control conversions of date time values to strings, and sometimes from strings to date time values (such as DateSeparator).
 
 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

 

Delphi Programming Neil Moffatt 2002 - 2013. All rights reserved.  |  Contact the author  |  Home Page