Date/Time Routines - Delphi Programming

Compares two TDateTime values (returns "less", "equal" or "greater"). Ignores the Time part if both values "fall" on the same day.

CompareDateTime function

Compares two TDateTime values (returns "less", "equal" or "greater").

Declaration:
type TValueRelationship = -1..1
function CompareDateTime(const ADate, BDate: TDateTime) : TValueRelationship

Description:
Compares two TDateTime values (returns "less", "equal" or "greater").

TValueRelationship represents the relationship between two values. Each of three TValueRelationship values has a "liked" symbolic constant:
-1 [LessThanValue] The first value is less than the second value.
0 [EqualsValue] The two values are equal.
1 [GreaterThanValue] The first value is greater than the second value.

CompareDate results in:

LessThanValue if ADate is earlier than BDate.
EqualsValue if date and time parts of both ADate and BDate are the same
GreaterThanValue if ADate is later than BDate.

Example:

var ThisMoment, FutureMoment : TDateTime;
ThisMoment := Now;
FutureMoment := IncDay(ThisMoment, 6); //adds 6 days
//CompareDateTime(ThisMoment, FutureMoment) returns LessThanValue (-1)
//CompareDateTime(FutureMoment, ThisMoment) returns GreaterThanValue (1)

CompareTime function

Compares two TDateTime values (returns "less", "equal" or "greater"). Ignores the Date part if both values occur at the same time.

Declaration:
type TValueRelationship = -1..1
function CompareDate(const ADate, BDate: TDateTime) : TValueRelationship

Description:
Compares two TDateTime values (returns "less", "equal" or "greater"). Ignores the Time part if both values occur at the same time.

TValueRelationship represents the relationship between two values. Each of three TValueRelationship values has a "liked" symbolic constant:
-1 [LessThanValue] The first value is less than the second value.
0 [EqualsValue] The two values are equal.
1 [GreaterThanValue] The first value is greater than the second value.

CompareDate results in:

LessThanValue if ADate occurs earlier in the day specified by BDate.
EqualsValue if time parts of both ADate and BDate are the same, ignoring the Date part.
GreaterThanValue if ADate occurs later in the day specified by BDate.

Example:

var ThisMoment, AnotherMoment : TDateTime;
ThisMoment := Now;
AnotherMoment := IncHour(ThisMoment, 6); //adds 6 hours
//CompareDate(ThisMoment, AnotherMoment) returns LessThanValue (-1)
//CompareDate(AnotherMoment, ThisMoment) returns GreaterThanValue (1

Date function

Returns the current system date.

Declaration:
type TDateTime = type Double;

function date: TDateTime;

Description:
Returns the current system date.

The integral part of a TDateTime value is the number of days that have passed since 12/30/1899. The fractional part of a TDateTime value is fraction of a 24 hour day that has elapsed.

To find the fractional number of days between two dates, simply subtract the two values. Likewise, to increment a date and time value by a certain fractional number of days, simply add the fractional number to the date and time value.

Example:   ShowMessage('Today is ' + DateToStr(Date));

DateTimeToStr function

Converts a TDateTime value to a string (date and time).

Declaration:
type TDateTime = type Double;

function DayOfWeek(Date: TDateTime): integer;

Description:
Returns the day of the week for a given date.

DayOfWeek returns an integer between 1 and 7, where Sunday is the first day of the week and Saturday is the seventh.
DayOfTheWeek is not compliant with the ISO 8601 standard.

Example:

const Days: array[1..7] of string =
('Sunday', 'Monday', 'Tuesday',
'Wednesday', 'Thursday',
'Friday', 'Saturday')
ShowMessage('Today is ' + Days[DayOfWeek(Date)]);
//Today is Monday

DaysBetween function

Gives the number of whole days between two specified dates.

Declaration:
function DaysBetween(const ANow, AThen: TDateTime): Integer;

Description:
Gives the number of whole days between two specified dates.

Function counts only whole days. What this means is that it will return 0 as the result for difference between 05/01/2003 23:59:59 and 05/01/2003 23:59:58 - where the actual difference is one *whole* day minus 1 second.

Example:

var dtNow, dtBirth : TDateTime;
DaysFromBirth : integer;
dtNow := Now;
dtBirth := EncodeDate(1973, 1, 29);
DaysFromBirth := DaysBetween(dtNow, dtBirth);
ShowMessage('Zarko Gajic "exists" ' +
IntToStr(DaysFromBirth) + ' whole days!');

DateOf function

Returns only the Date portion of the TDateTime value, by setting Time part to 0.

Declaration:
function DateOf(Date: TDateTime) : TDateTime

Description:
Returns only the Date portion of the TDateTime value, by setting Time part to 0.

DateOf sets the time portion to 0, which means midnight.

Example:

var ThisMoment, ThisDay : TDateTime;
ThisMoment := Now; // -> 06/27/2003 10:29:16:138
ThisDay := DateOf(ThisMoment);
//This Day:= 06/27/2003 00:00:00:000

DecodeDate function

Separates Year, Month, and Day values from a TDateTime value.

Declaration:
procedure DecodeDate(Date: TDateTime; var Year, Month, Day: Word);;

Description:
Separates Year, Month, and Day values from a TDateTime value.

If the given TDateTime value is less than or equal to zero, the year, month, and day return parameters are all set to zero.

Example:

var Y, M, D: Word;
DecodeDate(Date, Y, M, D);
if Y = 2000 then
ShowMessage('You''re in a "wrong" century!);

EncodeDate function
Creates a TDateTime value from Year, Month, and Day values.

Declaration:
function EncodeDate(Year, Month, Day: Word): TDateTime

Description:
Creates a TDateTime value from Year, Month, and Day values.

The Year must be between 1 and 9999. Valid Month values are 1 through 12. Valid Day values are 1 through 28, 29, 30, or 31, depending on the Month value.
If the function fails, EncodeDate raises an EConvertError exception.

Example:

var Y, M, D: Word;
dt: TDateTime;
y:=2001;
M:=2;
D:=18;
dt:=EncodeDate(Y,M,D);
ShowMessage('Borna will be
one year old on ' + DateToStr(dt))

FormatDateTime function
Formats a TDateTime value to a string.

Declaration:
function FormatDateTime(const Fmt: string; Value: TDateTime): string;

Description:
Formats a TDateTime value to a string.

FormatDateTime uses the format specified by the Fmt parameter. For the supported format specifiers go see Delphi Help files.

Example:

var s: string;
d: TDateTime;
...
d:=Now; // today + current time
s:=FormatDateTime('dddd',d);
// s:=Wednesday
s:=FormatDateTime('"Today is " dddd " minute " nn',d)
// s:=Today is Wednesday minute 24

IncDay function

Adds or substracts a given number of days from a date value.

Declaration:
function IncDay(ADate: TDateTime; Days: Integer = 1) : TDateTime;

Description:
Adds or substracts a given number of days from a date value.

If the Days parameter is negative the date returned is < ADate. The Time part of day specified by the Date parameter is copied to the result.

Example:

var Date: TDateTime;
EncodeDate(Date, 2003, 1, 29) //January 29, 2003
IncDay(Date, -1)
//January 28, 2003

Now function

Returns the current system date and time.

Declaration:
type TDateTime = type Double;

function Now: TDateTime;

Description:
Returns the current system date and time.

The integral part of a TDateTime value is the number of days that have passed since 12/30/1899. The fractional part of a TDateTime value is fraction of a 24 hour day that has elapsed.

To find the fractional number of days between two dates, simply subtract the two values. Likewise, to increment a date and time value by a certain fractional number of days, simply add the fractional number to the date and time value.

Example:  ShowMessage('Now is ' + DateTimeToStr(Now));

YearsBetween function

Gives the number of whole years between two specified dates.

Declaration:
function YearsBetween(const SomeDate, AnotherDate: TDateTime): Integer;

Description:
Gives the number of whole years between two specified dates.

YearsBetween returns an approximation based on an assumption of 365.25 days per year.

Example:

var dtSome, dtAnother : TDateTime;
DaysFromBirth : integer;
dtSome := EncodeDate(2003, 1, 1);
dtAnother := EncodeDate(2003, 12, 31);
YearsBetween(dtSome, dtAnother) == 1 //non-leap year
dtSome := EncodeDate(2000, 1, 1);
dtAnother := EncodeDate(2000, 12, 31);
YearsBetween(dtSome, dtAnother) == 0 // leap year