C++ Builder Tutorials

C++ Builder: objects for Date and Time

For working with date and time, you use TDateTime objects.

A TDateTime object internally holds a value (a floating point number), that represents the combination of a date and a time. The integer part is the number of days that have passed since December 30, 1899. The fractional part is the time of day.
TDateTime also supports negative values.

Some examples of TDateTime values and the corresponding date / time:

0 December 30, 1899, 12:00 A.M.
2.75 January 1, 1900, 6:00 P.M.
-1.25 December 29, 1899, 6:00 A.M.
35065 January 1, 1996, 12:00 A.M.


TDateTime Methods

For the examples below, we assume that DT has been declared as TDateTime object, and that its has been initialized.

DayOfWeek() returns the day of the week as an integer number.

DT->DecodeDate(&year, &month, &day) separates a TDateTime value into year, month, and day, and stores these values in the 3 parameters.

DT->DecodeTime(hour, minute, second, millisecond) separates a TDateTime value into hours, minutes, seconds, and milliseconds, and stores these values in the 4 parameters.

DT->FormatString(FS) returns a string that is a conversion of a TDateTime object, using the format FS.
Example:   S = "The date is: " + DT->FormatString("dddd mmmm yyyy");

int(DT) returns the integer part of the value contained in a TDateTime object. It gives the number of days that have passed since 12/30/1899.

double(DT) returns the date/time of a TDateTime object as a floating point number. The integral part is the number of days that have passed since 12/30/1899. The fractional part is the time of day, represented as a fraction of 24 hours.

String(DT) returns the string conversion of a TDateTime object, using the format of the LongTimeFormat global variable.


Date and Time functions

Date() returns an object that contains the current date and time. Example: DT = Date();

Time() returns an object that contains the time. Example: DT = Time();

TDateTime objects can be automatically converted to strings, using Windows' short date format. Example:

S String;
TDateTime D, T;
D = Date();
T = Time();
S = "The date is " + D + " and the time is " + T;

TDateTime objects also can be automatically converted to integers, giving the number of whole days. Example:

TDateTime D1, D2;
D1 = Date();
D2 = D1 - 20;
int NrOfDays;
NrOfDays = D1 - D2; // gives 20

Example project

Here's a short project, that illustrates the above concepts.

  1. Start a new project and drop 3 TEdit components on the main form.
  2. Below these, add 4 more TEdit components.
  3. Add a TButton and a TMemo.
  4. Create an OnClick event handler for the button:
    void __fastcall TForm1::Button1Click(TObject *Sender)
    {
      TDateTime Today, Date2, TheTime, Time2;
      unsigned short Year, Year2, Month, Month2, Day, Day2;
      unsigned short Hour, Hour2, Min, Min2, Sec, Sec2, MSec, MSec2;
      int NbrOfDays;
      double DiffSecs;
    
      Today = Date();
      TheTime = Time();
    
      Memo1->Lines->Add("Today: " + FormatDateTime("yyyy/mm/dd", Today));
      
      // Automatic conversion, Windows' short date format is used
      Memo1->Lines->Add("Today, auto-format: " + Today);
    
      // Note the use of ampersand symbol
      Today.DecodeDate(&Year, &Month, &Day);
      Memo1->Lines->Add("Y/M/D: " + IntToStr(Year) + "/" + IntToStr(Month) +
                        "/" + IntToStr(Day));
      // Automatic conversion, Windows' short date format is used
      Memo1->Lines->Add("The time: " + TheTime);
    
      TheTime.DecodeTime(&Hour, &Min, &Sec, &MSec);
      Memo1->Lines->Add("H/Min/Sec: " + IntToStr(Hour) + ":" + IntToStr(Min) + ":" +
                        IntToStr(Sec) + "." + IntToStr(MSec));
                        
      Hour2 = StrToInt(Edit4->Text);
      Min2  = StrToInt(Edit5->Text);
      Sec2  = StrToInt(Edit6->Text);
      MSec2 = StrToInt(Edit7->Text);
      Time2 = EncodeTime(Hour2, Min2, Sec2, MSec2);
      
      Memo1->Lines->Add("Time2: " + Time2);
      // 24 hours in a day, 60 minutes in an hour, 60 seconds in a minute
      DiffSecs = (double(Time2) - double(TheTime)) * 24 * 60 * 60;
      Memo1->Lines->Add("Difference, seconds: " + FloatToStr(DiffSecs));
      // Tomorrow is Today + 1  
      Memo1->Lines->Add("Tomorrow: " + FormatDateTime("yyyy/mm/dd", Today + 1));
    
      Year2  = StrToInt(Edit1->Text);
      Month2 = StrToInt(Edit2->Text);
      Day2   = StrToInt(Edit3->Text);
      Date2  = EncodeDate(Year2, Month2, Day2);
      
      Memo1->Lines->Add("Date2: " + FormatDateTime("yyyy/mm/dd", Date2));
      NbrOfDays = Date2 - Today; // automatic conversion to int
      Memo1->Lines->Add("Days difference: " + IntToStr(NbrOfDays));
    }