esbdates.pas

好用的日期转换函数 Date/Time Routines to enhance your 32-bit Delphi Programming.

	If Subtracting Years results in landing on Feb 29 in a non-leap year, then
	this will be converted to Feb 28.This only applies to the
	integral component of the Years Subtracted. The fractional part always
	is Subtracted from the resultant Date/Time.

	@param DT Date/Time to process.
	@param Yrs Number of Years to Subtract - can be negative.
	@cat DTMath
	@cat YearMath
}
function SubtractYrs (const DT: TDateTime; const Yrs: Extended): TDateTime;

{: Returns Last Day of the Month, for a given Date/Time - Time portion preserved.
	Alternatively for a given Month Year.
	@param DT Date/Time to process.
	@cat DTMath
	@cat MonthMath
}
function GetLastDayOfMonth (const DT: TDateTime): TDateTime;

{: Returns First Day of the Month, for a given Date/Time - Time portion preserved.
	Alternatively for a given Month Year.
	@param DT Date/Time to process.
	@cat DTMath
	@cat MonthMath
}
function GetFirstDayOfMonth (const DT: TDateTime): TDateTime;

{: Returns the Start of the week containing given Date/Time, assumes that
	the Start of the Week is Sunday - Time portion preserved.
	@param DT Date/Time to process.
	@cat DTMath
	@cat WeekMath
}
function StartOfWeek (const DT: TDateTime): TDateTime;

{: Returns the End of the week containing given Date/Time, assumes that
	the End of the Week is Saturday - Time portion preserved.
	@param DT Date/Time to process.
	@cat DTMath
	@cat WeekMath
}
function EndOfWeek (const DT: TDateTime): TDateTime;

{: Converts a given number of Seconds (Floating) into a string
	specifying the number of days, hours, minutes, seconds.
	Routine donated by: Marcos Guzm醤 Monta馿z.
	@param Secs Number of Seconds as a float
	@cat DTMath
	@cat DTConv
}
function Hrs_Min_Sec (Secs: Extended): string;

{: Returns true if both DateTimes refer to the same Calendar Month,
	can have different years.
	@param DT1 First Date/Time to process.
	@param DT2 Second Date/Time to process.
	@cat DTMath
	@cat MonthMath
	@cat DTComparison
}
function DatesInSameMonth (const DT1, DT2: TDateTime): Boolean;

{: Returns true if both DateTimes refer to the same Year.
	@param DT1 First Date/Time to process.
	@param DT2 Second Date/Time to process.
	@cat DTMath
	@cat YearMath
	@cat DTComparison
}
function DatesInSameYear (const DT1, DT2: TDateTime): Boolean;

{: Returns true if both DateTimes refer to the exact same Month,
	cannot have different years.
	@param DT1 First Date/Time to process.
	@param DT2 Second Date/Time to process.
	@cat DTMath
	@cat MonthMath
	@cat DTComparison
}
function DatesInSameMonthYear (const DT1, DT2: TDateTime): Boolean;

{: Returns the Number of Days between DT2 and DT1. If result is 0 then
	they are the same Date, if result is negative then DT2 occurs before
	DT1. Today and yesterday are 1 day apart.
	@param DT1 First Date/Time to process.
	@param DT2 Second Date/Time to process.
	@cat DTMath
}
function DaysApart (const DT1, DT2: TDateTime): LongInt;

{: Returns the Exact Number of Weeks between DT2 and DT1. If result is 0 then
	they are in the same Day, if result is negative then DT2 occurs before
	DT1.
	@param DT1 First Date/Time to process.
	@param DT2 Second Date/Time to process.
	@cat DTMath
	@cat WeekMath
}
function ExactWeeksApart (const DT1, DT2: TDateTime): Extended;

{: Returns the Number of Weeks between DT2 and DT1. If result is 0 then
	they are in within a Week of each other, if result is negative then DT2
	occurs before DT1.
	@param DT1 First Date/Time to process.
	@param DT2 Second Date/Time to process.
	@cat DTMath
	@cat WeekMath
}
function WeeksApart (const DT1, DT2: TDateTime): LongInt;

{: Returns the Number of Calendar Weeks between DT2 and DT1. A Calendar Week is
	taken as starting with Sunday. If result is 0 then they are in within the
	same Calendar Week, if result is negative then DT2 occurs in a Calendar
	Week before DT1.
	@param DT1 First Date/Time to process.
	@param DT2 Second Date/Time to process.
	@cat DTMath
	@cat WeekMath
}
function CalendarWeeksApart (const DT1, DT2: TDateTime): LongInt;

{: Returns the Number of Calendar Months between DT2 and DT1. If result is 0
	then they are in within the same Calendar Month, if result is negative
	then DT2	occurs in a Calendar Month before DT1.
	@param DT1 First Date/Time to process.
	@param DT2 Second Date/Time to process.
	@cat DTMath
	@cat WeekMath
}
function CalendarMonthsApart (const DT1, DT2: TDateTime): LongInt;

{: Is given Date/Time in a Leap Year. Thanks to Dr John Stockton
	for suggesting a faster methodology.
	@param DT Date/Time to process.
	@cat DTMath
	@cat DTComparison
}
function DateIsLeapYear (const DT: TDateTime): Boolean;

{: Returns the number of days in the Month represented by the given Date.
	@param DT Date/Time to process.
	@cat DTMath
	@cat MonthMath
}
function DaysInMonth (const DT: TDateTime): Byte;

{: Returns the number of days in the current Month.
	@cat DTMath
	@cat MonthMath
}
function DaysInThisMonth: Byte;

{: Returns the Number of days left in the Month represented by the given Date.
	@param DT Date/Time to process.
	@cat DTMath
	@cat MonthMath
}
function DaysLeftInMonth (const DT: TDateTime): Byte;

{: Returns the number of days left in the current Month.
	@param DT Date/Time to process.
	@cat DTMath
	@cat MonthMath
}
function DaysLeftInThisMonth: Byte;

{: Returns the number of days in the Year represented by the given Date.
	@param DT Date/Time to process.
	@cat DTMath
	@cat YearMath
}
function DaysInYear (const DT: TDateTime): Word;

{: Returns the Day Number in the Year represented by the given Date.
	@param DT Date/Time to process.
	@cat DTMath
	@cat YearMath
}
function DayOfYear (const DT: TDateTime): Word;

{: Returns the Day Number in this Year represented by today.
	@cat DTMath
	@cat YearMath
}
function ThisDayOfYear: Word;

{: Returns the number of days left in the Year represented by the given Date.
	@param DT Date/Time to process.
	@cat DTMath
	@cat YearMath
}
function DaysLeftInYear (const DT: TDateTime): Word;

{: Returns the number of days left in this Year.
	@cat DTMath
	@cat YearMath
}
function DaysLeftInThisYear: Word;

{: Returns 1 if Date in Jan through Jun or 2 if Date in Jul through Dec.
	@param DT Date/Time to process.
	@cat DTMath
}
function WhichSemester (const DT: TDateTime): Byte;

{: Returns 1 if Date in Jan through Mar, 2 if Date in Apr through Jun,
	3 if Date in Jul through Sep, 4 if Date in Oct through Dec.
	@param DT Date/Time to process.
	@cat DTMath
}
function WhichQuarter (const DT: TDateTime): Byte;

{: Returns First Day of the Quarter, for a given Date/Time - Time portion,
	preserved.
	@param DT Date/Time to process.
	@cat DTMath
}
function GetFirstDayOfQuarter (const DT: TDateTime): TDateTime;

{: Returns Last Day of the Quarter, for a given Date/Time - Time portion
	preserved.
	@param DT Date/Time to process.
	@cat DTMath
}
function GetLastDayOfQuarter (const DT: TDateTime): TDateTime;

{: Returns First Day of the Quarter, for a given Quarter and Year.
	@param Qtr Quarter No, 1 through 4.
	@param Year 4-digit Year such as 1999.
	@cat DTMath
}
function GetFirstDayofQuarter2 (const Qtr: Byte; const Year: Word): TDateTime;

{: Returns Last Day of the Quarter, for a given Quarter and Year.
	@param Qtr Quarter No, 1 through 4.
	@param Year 4-digit Year such as 1999.
	@cat DTMath
}
function GetLastDayofQuarter2 (const Qtr: Byte; const Year: Word): TDateTime;

{: Returns the Age (in years) of a "person" given their Date of Birth (DOB)
	and the Date of Reference (DT). If DT occurs before DB then -1 is
	returned.
	@param DOB Date of Birth.
	@param DT Date in question.
	@returns Age in Integral Years at the Date in question.
	@cat DTMath
	@cat YearMath
}
function AgeAtDate (const DOB, DT: TDateTime): Integer;

{: Returns the current Age (in years) of a "person" given their Date of Birth
	(DOB) using the System Date. If DOB occurs after the System Date then -1
	is returned.
	@param DOB Date of Birth.
	@returns Age in Integral Years at the current Date.
	@cat DTMath
}
function AgeNow (const DOB: TDateTime): Integer;

{: Returns the Age (in months) of a "person" given their Date of Birth (DOB)
	and the Date of Reference (DT). If DT occurs before DB then -1 is returned.
	Routine donated by David Gobbett.
	@param DOB Date of Birth.
	@param DT Date in question.
	@returns Age in Integral Months at the Date in question.
	@cat DTMath
	@cat MonthMath
	@cat YearMath
}
function AgeAtDateInMonths (const DOB, DT: TDateTime): Integer;

{: Returns the current Age (in months) of a "person" given their Date of Birth
	(DOB) using the System Date. If DOB occurs after the System Date then -1
	is returned.
	Routine donated by David Gobbett.
	@param DOB Date of Birth.
	@returns Age in Integral Months at the current Date.
	@cat DTMath
	@cat MonthMath
}
function AgeNowInMonths (const DOB: TDateTime): Integer;

{: Returns the Age (in weeks) of a "person" given their Date of Birth (DOB)
	and the Date of Reference (DT). If DT occurs before DB then -1 is returned.
	Routine donated by David Gobbett.
	@param DOB Date of Birth.
	@param DT Date in question.
	@returns Age in Integral Weeks at the Date in question.
	@cat DTMath
	@cat WeekMath
}
function AgeAtDateInWeeks (const DOB, DT: TDateTime): Integer;

{: Returns the current Age (in weeks) of a "person" given their Date of Birth (DOB)
	using the System Date. If DOB occurs after the System Date then -1 is returned.
	Routine donated by David Gobbett.
	@param DOB Date of Birth.
	@returns Age in Integral Weeks at the current Date.
	@cat DTMath
	@cat WeekMath
}
function AgeNowInWeeks (const DOB: TDateTime): Integer;

{: Returns the current Age as a Description useful for Hospital Applications.
	Returns Age in weeks if < 2 Months Old, in Months if less than 1 year old
	otherwise in years.
	@param DOB Date of Birth.
	@returns Age as a string.
	@cat DTMath
}
function AgeNowDescr (const DOB: TDateTime): String;

//--- Week No Routines ---

{: Converts Dates into a Week No in the Current Year. Weeks are assumed to
	start with Sunday. The week that Jan 1 occurs is the 1st week of the year,
	the Sunday AFTER Jan 1 would be the start of the 2nd week of the year.
	Note that this does mean that there can be 53 weeks in a year!
	@param DT Date/Time to be processed.
	@cat DTMath
	@cat WeekMath
}
function Date2WeekNo (const DT: TDateTime): Integer;

{: Returns true if the two Dates are in the same WeekNo. Will return false
	if Dates from Different Years.
	@param DT1 First Date/Time to be processed.
	@param DT2 Second Date/Time to be processed.
	@cat DTMath
	@cat WeekMath
	@cat DTComparison
}
function DatesInSameWeekNo (const DT1, DT2: TDateTime): Boolean;

{:Returns true No of Weeks, based on WeekNo, that the two dates are
	apart. A Negative result implies DT2 occurs before D1. Will return -999
	if Dates from Different Years.
	@param DT1 First Date/Time to be processed.
	@param DT2 Second Date/Time to be processed.
	@cat DTMath
	@cat WeekMath
}
function WeekNosApart (const DT1, DT2: TDateTime): Integer;

{: Returns the WeekNo of the current Date (System Date).
	@cat DTMath
	@cat WeekMath
}
function ThisWeekNo: Integer;

{: Returns the Start of the Week for the given WeekNo in the given year,
	assuming that the Start of the Week is Sunday.
	@param WeekNo Week Number in given year.
	@param Year 4 digit year such as 1999.
	@cat DTMath
	@cat WeekMath
}
function StartOfWeekNo (const WeekNo, Year: Word): TDateTime;

{: Returns the End of the Week for the given WeekNo in the given year,
	assuming that the End of the Week is Saturday.
	@param WeekNo Week Number in given year.
	@param Year 4 digit year such as 1999.
	@cat DTMath
	@cat WeekMath
}
function EndOfWeekNo (const WeekNo, Year: Word): TDateTime;

{: Returns the Date for a given Day of Week, a given WeekNo, and the given Year,
	assuming that the Start of the Week is Sunday, and that DOW uses 1 for Sunday.
	@param DOW Day of Week, 1 = Sunday, 7 = Saturday.
	@param WeekNo Week Number in given year.
	@param Year 4 digit year such as 1999.
	@cat DTMath
	@cat WeekMath
}
function DWY2Date (const DOW, WeekNo, Year: Word): TDateTime;

// --- ISO-8601 Compliant Routines ---

{: Returns Day Of Week According to ISO-8601 which has Monday as 1 and
	Sunday as 7.
	@param DT Date/Time to be processed.
	@cat DTMath
	@cat WeekMath
}
function ISODayOfWeek (const DT: TDateTime): Integer;

{: Most years have 52 weeks, but years that start on a Thursday and leap
	years that start on a Wednesday (or Thursday) have 53 weeks. Based on
	code supplied by Niklas Astram.
	@param Year 4-digit year such as 1999.
	@cat WeekMath
	@cat YearMath
}
function ISOWeeksInYear (const Year: Word): Byte;

{: Returns First Monday of the Year, for a given Year. Used in