22.4 Date and time functions

Date and time formatting characters

Various date and time formatting routines accept a format string. to format the date and or time. The following characters can be used to control the date and time formatting:

c: : shortdateformat + ’ ’ + shorttimeformat
d: : day of month
dd: : day of month (leading zero)
ddd: : day of week (abbreviation)
dddd: : day of week (full)
ddddd: : shortdateformat
dddddd: : longdateformat
m: : month
mm: : month (leading zero)
mmm: : month (abbreviation)
mmmm: : month (full)
y: : year (four digits)
yy: : year (two digits)
yyyy: : year (with century)
h: : hour
hh: : hour (leading zero)
n: : minute
nn: : minute (leading zero)
s: : second
ss: : second (leading zero)
t: : shorttimeformat
tt: : longtimeformat
am/pm: : use 12 hour clock and display am and pm accordingly
a/p: : use 12 hour clock and display a and p accordingly
/: : insert date seperator
:: : insert time seperator
”xx”: : literal text
’xx’: : literal text

TDateTime

Declaration:

TDateTime = Double;

Description:

Many functions return or require a TDateTime type, which contains a date and time in encoded form. The date and time are converted to a double as follows:

The date part is stored in the integer part of the double as the number of days passed since January 1, 1900.
The time part is stored in the fractional part of the double, as the number of milliseconds passed since midnight (00:00), divided by the total number of milliseconds in a day.

Date

Declaration:: Function Date: TDateTime;
Description:: Date returns the current date in TDateTime format. For more information about the TDateTime type, see TDateTime (715).
Errors:: None.
See also:: Time (731),Now (727), TDateTime (715).

Listing: sysutex/ex1.pp

Program Example1;

{ This program demonstrates the Date function }

uses sysutils;

Var YY,MM,DD : Word;

Begin
Writeln ('Date : ',Date);
DeCodeDate (Date,YY,MM,DD);
Writeln (format ('Date is (DD/MM/YY): %d/%d/%d ',[dd,mm,yy]));
End.

DateTimeToFileDate

Declaration:: Function DateTimeToFileDate(DateTime : TDateTime) : Longint;
Description:: DateTimeToFileDate function converts a date/time indication in TDateTime format to a filedate function, such as returned for instance by the FileAge (745) function.
Errors:: None.
See also:: Time (731), Date (715), FileDateToDateTime (724), DateTimeToSystemTime (718), DateTimeToTimeStamp (719)

Listing: sysutex/ex2.pp

Program Example2;

{ This program demonstrates the DateTimeToFileDate function }

Uses sysutils;

Begin
Writeln ('FileTime of now would be: ',DateTimeToFileDate (Now));
End.

DateTimeToStr

Declaration:: Function DateTimeToStr(DateTime: TDateTime): string;
Description:: DateTimeToStr returns a string representation of DateTime using the formatting specified in ShortDateTimeFormat. It corresponds to a call to FormatDateTime('c',DateTime) (see section 22.4, page 714).
Errors:: None.
See also:: FormatDateTime (724), TDateTime (715).

Listing: sysutex/ex3.pp

Program Example3;

{ This program demonstrates the DateTimeToStr function }

Uses sysutils;

Begin
Writeln ('Today is : ',DateTimeToStr(Now));
Writeln ('Today is : ',FormatDateTime('c',Now));
End.

DateTimeToString

Declaration:: Procedure DateTimeToString(var Result: string; const FormatStr: string; const DateTime: TDateTime);
Description:: DateTimeToString returns in Result a string representation of DateTime using the formatting specified in FormatStr.
for a list of characters that can be used in the FormatStr formatting string, see section 22.4, page 714.
Errors:: In case a wrong formatting character is found, an EConvertError is raised.
See also:: FormatDateTime (724), section 22.4, page 714.

Listing: sysutex/ex4.pp

Program Example4;

{ This program demonstrates the DateTimeToString function }

Uses sysutils;

Procedure today (Fmt : string);

Var S : AnsiString;

begin
  DateTimeToString (S,Fmt,Date);
  Writeln (S);
end;

Procedure Now (Fmt : string);

Var S : AnsiString;

begin
  DateTimeToString (S,Fmt,Time);
  Writeln (S);
end;

Begin
  Today ('"Today is "dddd dd mmmm y');
  Today ('"Today is "d mmm yy');
  Today ('"Today is "d/mmm/yy');
  Now ('''The time is ''am/pmh:n:s');
  Now ('''The time is ''hh:nn:ssam/pm');
  Now ('''The time is ''tt');
End.

DateTimeToSystemTime

Declaration:: Procedure DateTimeToSystemTime(DateTime: TDateTime; var SystemTime: TSystemTime);
Description:: DateTimeToSystemTime converts a date/time pair in DateTime, with TDateTime format to a system time SystemTime.
Errors:: None.
See also:: DateTimeToFileDate (716), SystemTimeToDateTime (730), DateTimeToTimeStamp (719)

Listing: sysutex/ex5.pp

Program Example5;

{ This program demonstrates the DateTimeToSystemTime function }

Uses sysutils;

Var ST : TSystemTime;

Begin
  DateTimeToSystemTime(Now,ST);
  With St do
    begin
    Writeln ('Today is    ',year,'/',month,'/',Day);
    Writeln ('The time is ',Hour,':',minute,':',Second,'.',MilliSecond);
    end;
End.

DateTimeToTimeStamp

Declaration:: Function DateTimeToTimeStamp(DateTime: TDateTime): TTimeStamp;
Description:: DateTimeToSystemTime converts a date/time pair in DateTime, with TDateTime format to a TTimeStamp format.
Errors:: None.
See also:: DateTimeToFileDate (716), SystemTimeToDateTime (730), DateTimeToSystemTime (718)

Listing: sysutex/ex6.pp

Program Example6;

{ This program demonstrates the DateTimeToTimeStamp function }

Uses sysutils;

Var TS : TTimeStamp;

Begin
  TS:=DateTimeToTimeStamp (Now);
  With TS do
    begin
    Writeln ('Now is ',time,' millisecond past midnight');
    Writeln ('Today is ' ,Date,' days past 1/1/0001');
    end;
End.

DateToStr

Declaration:: Function DateToStr(Date: TDateTime): string;
Description:: DateToStr converts Date to a string representation. It uses ShortDateFormat as it’s formatting string. It is hence completely equivalent to a FormatDateTime('ddddd', Date).
Errors:: None.
See also:: TimeToStr (732), DateTimeToStr (717), FormatDateTime (724), StrToDate (728)

Listing: sysutex/ex7.pp

Program Example7;

{ This program demonstrates the DateToStr function }

Uses sysutils;

Begin
Writeln(Format ('Today is: %s',[DateToStr(Date)]));
End.

DayOfWeek

Declaration:: Function DayOfWeek(DateTime: TDateTime): integer;
Description:: DayOfWeek returns the day of the week from DateTime. Sunday is counted as day 1, Saturday is counted as day 7. The result of DayOfWeek can serve as an index to the LongDayNames constant array, to retrieve the name of the day.
Errors:: None.
See also:: Date (715), DateToStr (720)

Listing: sysutex/ex8.pp

Program Example8;

{ This program demonstrates the DayOfWeek function }

Uses sysutils;

Begin
Writeln ('Today''s day is ',LongDayNames[DayOfWeek(Date)]);
End.

DecodeDate

Declaration:: Procedure DecodeDate(Date: TDateTime; var Year, Month, Day: word);
Description:: DecodeDate decodes the Year, Month and Day stored in Date, and returns them in the Year, Month and Day variables.
Errors:: None.
See also:: EncodeDate (722), DecodeTime (721).

Listing: sysutex/ex9.pp

Program Example9;

{ This program demonstrates the DecodeDate function }

Uses sysutils;

Var YY,MM,DD : Word;

Begin
DecodeDate(Date,YY,MM,DD);
Writeln (Format ('Today is %d/%d/%d',[dd,mm,yy]));
End.

DecodeTime

Declaration:: Procedure DecodeTime(Time: TDateTime; var Hour, Minute, Second, MilliSecond: word);
Description:: DecodeDate decodes the hours, minutes, second and milliseconds stored in Time, and returns them in the Hour, Minute and Second and MilliSecond variables.
Errors:: None.
See also:: EncodeTime (723), DecodeDate (721).

Listing: sysutex/ex10.pp

Program Example10;

{ This program demonstrates the DecodeTime function }

Uses sysutils;

Var HH,MM,SS,MS: Word;

Begin
DecodeTime(Time,HH,MM,SS,MS);
Writeln (format('The time is %d:%d:%d.%d',[hh,mm,ss,ms]));
End.

EncodeDate

Declaration:

Function EncodeDate(Year, Month, Day :word): TDateTime;

Description:

EncodeDate encodes the Year, Month and Day variables to a date in TDateTime format. It does the opposite of the DecodeDate (721) procedure.

The parameters must lie withing valid ranges (boundaries included):

Year: must be between 1 and 9999.
Month: must be within the range 1-12.
Day: msut be between 1 and 31.

Errors:

In case one of the parameters is out of it’s valid range, 0 is returned.

See also:

EncodeTime (723), DecodeDate (721).

Listing: sysutex/ex11.pp

Program Example11;

{ This program demonstrates the EncodeDate function }

Uses sysutils;

Var YY,MM,DD : Word;

Begin
DecodeDate (Date,YY,MM,DD);
WriteLn ('Today is : ',FormatDateTime ('dd mmmm yyyy',EnCodeDate(YY,Mm,Dd)));
End.

EncodeTime

Declaration:

Function EncodeTime(Hour, Minute, Second, MilliSecond:word): TDateTime;

Description:

EncodeTime encodes the Hour, Minute, Second, MilliSecond variables to a TDateTime format result. It does the opposite of the DecodeTime (721) procedure.

The parameters must have a valid range (boundaries included):

Hour: must be between 0 and 23.
Minute,second: must both be between 0 and 59.
Millisecond: must be between 0 and 999.

Errors:

In case one of the parameters is outside of it’s valid range, 0 is returned.

See also:

EncodeDate (722), DecodeTime (721).

Listing: sysutex/ex12.pp

Program Example12;

{ This program demonstrates the EncodeTime function }

Uses sysutils;

Var Hh,MM,SS,MS : Word;

Begin
DeCodeTime (Time,Hh,MM,SS,MS);
Writeln ('Present Time is : ',FormatDateTime('hh:mm:ss',EnCodeTime (HH,MM,SS,MS)));
End.

FileDateToDateTime

Declaration:: Function FileDateToDateTime(Filedate : Longint) : TDateTime;
Description:: FileDateToDateTime converts the date/time encoded in filedate to a TDateTime encoded form. It can be used to convert date/time values returned by the FileAge (745) or FindFirst (753)/FindNext (754) functions to TDateTime form.
Errors:: None.
See also:: DateTimeToFileDate (716)

Listing: sysutex/ex13.pp

Program Example13;

{ This program demonstrates the FileDateToDateTime function }

Uses sysutils;

Var
ThisAge : Longint;

Begin
Write ('ex13.pp created on :');
ThisAge:=FileAge('ex13.pp');
Writeln (DateTimeToStr(FileDateToDateTime(ThisAge)));
End.

FormatDateTime

Declaration:: Function FormatDateTime(FormatStr: string; DateTime: TDateTime):string;
Description:: FormatDateTime formats the date and time encoded in DateTime according to the formatting given in FormatStr. The complete list of formatting characters can be found in section 22.4, page 714.
Errors:: On error (such as an invalid character in the formatting string), and EConvertError exception is raised.
See also:: DateTimeToStr (717), DateToStr (720), TimeToStr (732), StrToDateTime (729)

Listing: sysutex/ex14.pp

Program Example14;

{ This program demonstrates the FormatDateTime function }

Uses sysutils;

Var ThisMoment : TDateTime;

Begin
  ThisMoment:=Now;
  Writeln ('Now : ',FormatDateTime('hh:nn',ThisMoment));
  Writeln ('Now : ',FormatDateTime('DD MM YYYY',ThisMoment));
  Writeln ('Now : ',FormatDateTime('c',ThisMoment));
End.

IncMonth

Declaration:: Function IncMonth(const DateTime: TDateTime; NumberOfMonths: integer): TDateTime;
Description:: IncMonth increases the month number in DateTime with NumberOfMonths. It wraps the result as to get a month between 1 and 12, and updates the year accordingly. NumberOfMonths can be negative, and can be larger than 12 (in absolute value).
Errors:: None.
See also:: Date (715), Time (731), Now (727)

Listing: sysutex/ex15.pp

Program Example15;

{ This program demonstrates the IncMonth function }

Uses sysutils;

Var ThisDay : TDateTime;

Begin
  ThisDay:=Date;
  Writeln ('ThisDay : ',DateToStr(ThisDay));
  Writeln ('6 months ago :',DateToStr(IncMonth(ThisDay,-6)));
  Writeln ('6 months from now :' ,DateToStr(IncMonth(ThisDay,6)));
  Writeln ('12 months ago :',DateToStr(IncMonth(ThisDay,-12)));
  Writeln ('12 months from now :' ,DateToStr(IncMonth(ThisDay,12)));
  Writeln ('18 months ago :',DateToStr(IncMonth(ThisDay,-18)));
  Writeln ('18 months from now :' ,DateToStr(IncMonth(ThisDay,18)));
End.

IsLeapYear

Declaration:: Function IsLeapYear(Year: Word): boolean;
Description:: IsLeapYear returns True if Year is a leap year, False otherwise.
Errors:: None.
See also:: IncMonth (725), Date (715)

Listing: sysutex/ex16.pp

Program Example16;

{ This program demonstrates the IsLeapYear function }

Uses sysutils;

Var YY,MM,dd : Word;

Procedure TestYear (Y : Word);

begin
  Writeln (Y,' is leap year : ',IsLeapYear(Y));
end;

Begin
  DeCodeDate(Date,YY,mm,dd);
  TestYear(yy);
  TestYear(2000);
  TestYear(1900);
  TestYear(1600);
  TestYear(1992);
  TestYear(1995);
End.

MSecsToTimeStamp

Declaration:: Function MSecsToTimeStamp(MSecs: Comp): TTimeStamp;
Description:: MSecsTiTimeStamp converts the given number of milliseconds to a TTimeStamp date/time notation.
Use TTimeStamp variables if you need to keep very precise track of time.
Errors:: None.
See also:: TimeStampToMSecs (732), DateTimeToTimeStamp (719),

Listing: sysutex/ex17.pp

Program Example17;

{ This program demonstrates the MSecsToTimeStamp function }

Uses sysutils;

Var MS : Comp;
    TS : TTimeStamp;
    DT : TDateTime;
Begin
  TS:=DateTimeToTimeStamp(Now);
  Writeln ('Now in days since 1/1/0001      : ',TS.Date);
  Writeln ('Now in millisecs since midnight : ',TS.Time);
  MS:=TimeStampToMSecs(TS);
  Writeln ('Now in millisecs since 1/1/0001 : ',MS);
  MS:=MS-1000*3600*2;
  TS:=MSecsToTimeStamp(MS);
  DT:=TimeStampToDateTime(TS);
  Writeln ('Now minus 1 day : ',DateTimeToStr(DT));
End.

Now

Declaration:: Function Now: TDateTime;
Description:: Now returns the current date and time. It is equivalent to Date+Time.
Errors:: None.
See also:: Date (715), Time (731)

Listing: sysutex/ex18.pp

Program Example18;

{ This program demonstrates the Now function }

Uses sysutils;

Begin
Writeln ('Now : ',DateTimeToStr(Now));
End.

StrToDate

Declaration:: Function StrToDate(const S: string): TDateTime;
Description:: StrToDate converts the string S to a TDateTime date value. The Date must consist of 1 to three digits, separated by the DateSeparator character. If two numbers are given, they are supposed to form the day and month of the current year. If only one number is given, it is supposed to represent the day of the current month. (This is not supported in Delphi)
The order of the digits (y/m/d, m/d/y, d/m/y) is determined from the ShortDateFormat variable.
Errors:: On error (e.g. an invalid date or invalid character), an EConvertError exception is raised.
See also:: StrToTime (729), DateToStr (720)n TimeToStr (732).

Listing: sysutex/ex19.pp

Program Example19;

{ This program demonstrates the StrToDate function }

Uses sysutils;

Procedure TestStr (S : String);

begin
  Writeln (S,' : ',DateToStr(StrToDate(S)));
end;

Begin

  Writeln ('ShortDateFormat ',ShortDateFormat);
  TestStr(DateTimeToStr(Date));
  TestStr('05/05/1999');
  TestStr('5/5');
  TestStr('5');
End.

StrToDateTime

Declaration:: Function StrToDateTime(const S: string): TDateTime;
Description:: StrToDateTime converts the string S to a TDateTime date and time value. The Date must consist of 1 to three digits, separated by the DateSeparator character. If two numbers are given, they are supposed to form the day and month of the current year. If only one number is given, it is supposed to represent the day of the current month. (This is not supported in Delphi)
The order of the digits (y/m/d, m/d/y, d/m/y) is determined from the ShortDateFormat variable.
Errors:: On error (e.g. an invalid date or invalid character), an EConvertError exception is raised.
See also:: StrToDate (728), StrToTime (729), DateTimeToStr (717)

Listing: sysutex/ex20.pp

Program Example20;

{ This program demonstrates the StrToDateTime function }

Uses sysutils;

Procedure TestStr (S : String);

begin
  Writeln (S,' : ',DateTimeToStr(StrToDateTime(S)));
end;

Begin

  Writeln ('ShortDateFormat ',ShortDateFormat);
  TestStr(DateTimeToStr(Now));
  TestStr('05-05-1999 15:50');
  TestStr('5-5 13:30');
  TestStr('5 1:30PM');
End.

StrToTime

Declaration:: Function StrToTime(const S: string): TDateTime;
Description:: StrToTime converts the string S to a TDateTime time value. The time must consist of 1 to 4 digits, separated by the TimeSeparator character. If two numbers are given, they are supposed to form the hour and minutes.
Errors:: On error (e.g. an invalid date or invalid character), an EConvertError exception is raised.
See also:: StrToDate (728), StrToDateTime (729), TimeToStr (732)

Listing: sysutex/ex21.pp

Program Example21;

{ This program demonstrates the StrToTime function }

Uses sysutils;

Procedure TestStr (S : String);

begin
  Writeln (S,' : ',TimeToStr(StrToTime(S)));
end;

Begin
  teststr (TimeToStr(Time));
  teststr ('12:00');
  teststr ('15:30');
  teststr ('3:30PM');
End.

SystemTimeToDateTime

Declaration:: Function SystemTimeToDateTime(const SystemTime: TSystemTime): TDateTime;
Description:: SystemTimeToDateTime converts a TSystemTime record to a TDateTime style date/time indication.
Errors:: None.
See also:: DateTimeToSystemTime (718)

Listing: sysutex/ex22.pp

Program Example22;

{ This program demonstrates the SystemTimeToDateTime function }

Uses sysutils;

Var ST : TSystemTime;

Begin
  DateTimeToSystemTime(Now,ST);
  With St do
    begin
    Writeln ('Today is    ',year,'/',month,'/',Day);
    Writeln ('The time is ',Hour,':',minute,':',Second,'.',MilliSecond);
    end;
  Writeln ('Converted : ',DateTimeToStr(SystemTimeToDateTime(ST)));
End.

Time

Declaration:: Function Time: TDateTime;
Description:: Time returns the current time in TDateTime format. The date part of the TDateTimeValue is set to zero.
Errors:: None.
See also:: Now (727), Date (715)

Listing: sysutex/ex23.pp

Program Example23;

{ This program demonstrates the Time function }

Uses sysutils;

Begin
Writeln ('The time is : ',TimeToStr(Time));
End.

TimeStampToDateTime

Declaration:: Function TimeStampToDateTime(const TimeStamp: TTimeStamp): TDateTime;
Description:: TimeStampToDateTime converts TimeStamp to a TDateTime format variable. It is the inverse operation of DateTimeToTimeStamp (719).
Errors:: None.
See also:: DateTimeToTimeStamp (719), TimeStampToMSecs (732)

Listing: sysutex/ex24.pp

Program Example24;

{ This program demonstrates the TimeStampToDateTime function }

Uses sysutils;

Var TS : TTimeStamp;
    DT : TDateTime;

Begin
  TS:=DateTimeToTimeStamp (Now);
  With TS do
    begin
    Writeln ('Now is ',time,' millisecond past midnight');
    Writeln ('Today is ' ,Date,' days past 1/1/0001');
    end;
  DT:=TimeStampToDateTime(TS);
  Writeln ('Together this is : ',DateTimeToStr(DT));
End.

TimeStampToMSecs

Declaration:: Function TimeStampToMSecs(const TimeStamp: TTimeStamp): comp;
Description:: TimeStampToMSecs converts TimeStamp to the number of seconds since 1/1/0001.
Use TTimeStamp variables if you need to keep very precise track of time.
Errors:: None.
See also:: MSecsToTimeStamp (726), TimeStampToDateTime (731)

For an example, see MSecsToTimeStamp (726).

TimeToStr

Declaration:: Function TimeToStr(Time: TDateTime): string;
Description:: TimeToStr converts the time in Time to a string. It uses the ShortTimeFormat variable to see what formatting needs to be applied. It is therefor entirely equivalent to a FormatDateTime('t',Time) call.
Errors:: None.
See also:

Listing: sysutex/ex25.pp

Program Example25;

{ This program demonstrates the TimeToStr function }

Uses sysutils;

Begin
Writeln ('The current time is : ',TimeToStr(Time));
End.

[next] [prev] [prev-tail] [front] [up]