esbdates.pas

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

{: A Speed Optimised Routine for getting the Month portion of a Date based on
	Routine by Ken Otto that is many times faster than using DecodeDate in
	SysUtils.
	@cat DTConv
}
function OptDate2Month (const DT: TDateTime) : Word;

{: A Speed Optimised Routine for getting the Day portion of a Date based on
	Routine by Ken Otto that is many times faster than using DecodeDate in
	SysUtils.
	@cat DTConv
}
function OptDate2Day (const DT: TDateTime) : Word;

{: Returns the current Year - from Today's Date.
	This Integer routine is faster than <See Routine=ThisYear>.
	@cat DTConv
	@cat YearMath
}
function OptThisYear: Integer;

{: Returns the current Month - from Today's Date.
	This Integer routine is faster than <See Routine=ThisMonth>.
	@cat DTConv
	@cat MonthMath
}
function OptThisMonth: Integer;

{: Returns the current Day - from Today's Date.
	This Integer routine is faster than <See Routine=ThisDay>.
	@cat DTConv
}
function OptThisDay: Integer;

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

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

{: 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 OptDaysLeftInYear (const DT: TDateTime): Integer;

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

//--- Year Based Routines ---

{: Is given Year a Leap Year. Thanks to Dr John Stockton
	for suggesting a faster methodology.
	@param Year the Year to be processed - should be 4 digit, eg 1999.
	@cat YearMath
	@cat DTComparison
}
function IsLeapYear (Year: Word): Boolean;

{: Returns the GoldenNumber for a given Year. Values are 1 -> 19.
	The relationship between the Moon's Phases and the Year, repeats
	itself every 19 years.
	@param Year the Year to be processed - should be 4 digit, eg 1999.
	@cat YearMath
}
function GetGoldenNumber (const Year: Word): Integer;

{: Return the Epact, which is a measure of the age of the moon (ie the number
	of days that have passed since an "official" new moon) on a particular date.
	@param Year the Year to be processed - should be 4 digit, eg 1999.
	@cat YearMath
}
function GetEpact (const Year: Word): Integer;

{:Returns the Date of Easter Sunday for given Year - based on current Calendar.
	@param Year the Year to be processed - should be 4 digit, eg 1999.
	@cat YearMath
}
function GetEasterSunday (const Year: Word): TDateTime;

{:Returns the Date of Good Friday for given Year - based on current Calendar.
	@param Year the Year to be processed - should be 4 digit, eg 1999.
	@cat YearMath
}
function GetGoodFriday (const Year: Word): TDateTime;

{: Returns First Day of the Year, for a given Year.
	@param Year the Year to be processed - should be 4 digit, eg 1999.
	@cat YearMath
}
function GetFirstDayOfYear (const Year: Word): TDateTime;

{: Returns Last Day of the Year, for a given Year.
	@param Year the Year to be processed - should be 4 digit, eg 1999.
	@cat YearMath
}
function GetLastDayOfYear (const Year: Word): TDateTime;

{: Returns First Sunday of the Year, for a given Year. Used in
	Week No Routines.
	@param Year the Year to be processed - should be 4 digit, eg 1999.
	@cat YearMath
	@cat WeekMath
}
function GetFirstSundayOfYear (const Year: Word): TDateTime;

//--- Conversions ---

{: Returns Date as a String using ShortDateFormat from Regional
	Settings. If the Date is Zero, then an Empty String will be returned.<p>
	If an error occurs an Empty String is Returned.
	@param DT Date/Time to Convert.
	@cat DTConv
}
function Date2Str (const DT: TDateTime): String;

{: Returns the Day of the Month number from a given date/time.
	@param DT Date/Time to Convert.
	@returns the Day of the Month.
	@cat DTConv
}
function Date2Day (const DT: TDateTime): Word;

{: Returns the Month number from a given date/time, 1 = Jan, etc.
	@param DT Date/Time to Convert.
	@returns the Month where 1 = Jan, through 12 = Dec.
	@cat DTConv
	@cat MonthMath
}
function Date2Month (const DT: TDateTime): Word;

{: Returns the Year from a given date/time.
	@param DT Date/Time to Convert.
	@returns the Year component, including Century.
	@cat DTConv
	@cat YearMath
}
function Date2Year (const DT: TDateTime): Word;

{: Returns the Time Portion as a string HH:MM with time separator
	from the Regional Settings. If DT is 0, then an Empty String will be
	returned.<p>
	@param DT Date/Time to Convert.
	@cat DTConv
}
function Time2Str (const DT: TDateTime): String;

{: Returns the Hour from a given date/time.
	@param DT Date/Time to Convert.
	@returns the Hour component.
	@cat DTConv
}
function Time2Hr (const DT: TDateTime): Word;

{: Returns the Minute from a given date/time.
	@param DT Date/Time to Convert.
	@returns the Minute component.
	@cat DTConv
}
function Time2Min (const DT: TDateTime): Word;

{: Returns the Second from a given date/time.
	@param DT Date/Time to Convert.
	@returns the Second component.
	@cat DTConv
}
function Time2Sec (const DT: TDateTime): Word;

{: Returns the Millisecond from a given date/time.
	@param DT Date/Time to Convert.
	@returns the Millisecond component.
	@cat DTConv
}
function Time2MSec (const DT: TDateTime): Word;

{: Returns the current Year - from Today's Date.
	@cat DTConv
	@cat YearMath
}
function ThisYear: Word;

{: Returns the current Month - from Today's Date.
	@cat DTConv
	@cat MonthMath
}
function ThisMonth: Word;

{: Returns the current Day - from Today's Date.
	@cat DTConv
}
function ThisDay: Word;

{: Returns the current Hour - from the current Time.
	@cat DTConv
}
function ThisHr: Word;

{: Returns the current Minute - from the current Time.
	@cat DTConv
}
function ThisMin: Word;

{: Returns the current Second - from the current Time.
	@cat DTConv
}
function ThisSec: Word;

{: Returns the current Millisecond - from the current Time.
	@cat DTConv
}
function ThisMSec: Word;

{: Converts a string containing a Time into a DateTime.
	@param S The String to convert.
	@cat DTConv
}
function Str2Time (S: String): TDateTime;

{: Converts a string containing a Date into a DateTime. If the Item
	has no month and/or year then the current month and year will be assumed. <p>
	<See Var=ESB2DigitYr> contols the different ways in which 2 Digit Years
	are handled in	Str2Date.<p>

	edyNone - Nothing is done, left to Delphi to handle. <p>
	edyCutOff - the  ESB2DigitCutOff is used to decide which century
		the date lies in. If 1900 + Yr less than <See Var=ESB2DigitCutOff>
		then it is assumed that 2000 + Yr is wanted, otherwise 1900 + Yr
		is used.<p>
	edyHistoric  - asssumes that the yr is this year or earlier.
	@param InDate The String to convert.
	@cat DTConv
}
function Str2Date (S: String): TDateTime;

{: An enhanced routine to converts a string containing a Date into a DateTime,
	donated by Tom Grieve. If the Item has no month and/or year then the current
	month and year will be assumed. <p>
	<See Var=ESB2DigitYr> contols the different ways in which 2 Digit Years
	are handled in	Str2Date.<p> This routine also handles Dates of the form
	'03 Jun 2001' where the month is in alphabetic form.<p>

	edyNone - Nothing is done, left to Delphi to handle. <p>
	edyCutOff - the  ESB2DigitCutOff is used to decide which century
		the date lies in. If 1900 + Yr less than <See Var=ESB2DigitCutOff>
		then it is assumed that 2000 + Yr is wanted, otherwise 1900 + Yr
		is used.<p>
	edyHistoric  - asssumes that the yr is this year or earlier.
	@param S The String to convert.
	@cat DTConv
}
function EnhStr2Date (InDate: String): TDateTime;

{: Converts a string containing a Date into a DateTime. If the Item
	has no month and/or year then the current month and year will be assumed. <p>
	If a 2 Digit Year is used then it is assumted that it is this year or earlier.
	@param S The String to convert.
	@cat DTConv
}
function Str2HistoricDate (S: String): TDateTime;

{: Converts a string containing a Date into a DateTime. If the Item
	has no month and/or year then the current month and year will be assumed. <p>
	If a 2 Digit Year is used then CutOff is used to decide which century
	the date lies in. If 1900 + Yr less than CutOff then it is assumed that
	2000 + Yr is wanted, otherwise 1900 + Yr is used.
	@param S The String to convert.
	@cat DTConv
}
function Str2CutOffDate (S: string; const CutOff: Word): TDateTime;

{: Returns the Long Month Description for the supplied Date. Relies
	on Regional Settings.
	@param DT Date/Time to convert.
	@returns the Long Month Name of the Month component.
	@cat DTConv
	@cat MonthMath
}
function Date2LongMonth (const DT: TDateTime): string;

{: Returns the Short Month Description for the supplied Date. Relies
	on Regional Settings.
	@param DT Date/Time to convert.
	@returns the Short Month Name of the Month component.
	@cat DTConv
	@cat MonthMath
}
function Date2ShortMonth (const DT: TDateTime): string;

{: Returns the Long Day of Week Description for the supplied Date. Relies
	on Regional Settings.
	@param DT Date/Time to convert.
	@returns the Long Day of Week Name for the given Date.
	@cat DTConv
}
function Date2LongDOW (const DT: TDateTime): string;

{: Given a Month Name this routines searches through the Short and then
	Long Month Names supplied in the Registry to do a Left Match, and
	then return the Month Number. So for English Names, 'Ma' would return
	3 for 'March' .
	@param MonthName Name of the Month to search for.
	@returns the Month Number, 1 through 12 - 0 implies not found.
	@cat DTConv
	@cat MonthMath
}
function MonthName2Month (const MonthName: string): Word;

{: Given a Day Name this routines searches through the Short and then
	Long Day Names supplied in the Registry to do a Left Match, and
	then return the Day Number. So for English Names, 'T' would return
	3 for 'Tuesday'.
	@param DayName Name of the Day of Week to search for.
	@returns the DOW Number, 1 through 7 - 0 implies not found. 1 is Sunday.
	@cat DTConv
}
function DayName2DOW (const DayName: string): Byte;

{: Converts a String in ISO Format, eg '2000-07-19 12:10:22' to a TDateTime.
	Leading and trailing spaces are ignored - seconds can be omitted - in
	fact the whole time can be omitted. Routine suggest by Wolfgang Werner.
	@param ISODT String representing ISO Formatted Date Time - 'yyyy-mm-dd hh:mm:ss'.
	@return String converted to TDateTime - 0 if any errors
	@cat DTConv
}

function ISODateTime2DateTime (const ISODT: String): TDateTime;

{: Returns the number of Hours the specified number of Days represents.
	@param Value Number of Days
	@returns the Number of Hours
	@cat DTConv
}
function Days2Hrs (const Value: Extended): Extended;

{: Returns the number of Days the specified number of Hours represents.
	@param Value Number of Hours
	@returns the Number of Days
	@cat DTConv
}
function Hrs2Days (const Value: Extended): Extended;

{: Returns the number of Hours the specified number of Mintues represents.
	@param Value Number of Minutes
	@returns the Number of Hours
	@cat DTConv
}
function Mins2Hrs (const Value: Extended): Extended;

{: Returns the number of Minutes the specified number of Hours represents.
	@param Value Number of Hours
	@returns the Number of Minutes
	@cat DTConv
}
function Hrs2Mins (const Value: Extended): Extended;

{: Returns the number of Minutes the specified number of Seconds represents.
	@param Value Number of Minutes
	@returns the Number of Seconds
	@cat DTConv
}
function Mins2Secs (const Value: Extended): Extended;

{: Returns the number of Seconds the specified number of Mintues represents.
	@param Value Number of Seconds
	@returns the Number of Minutes
	@cat DTConv
}
function Secs2Mins (const Value: Extended): Extended;

{: Returns the number of Seconds the specified number of Days represents.
	@param Value Number of Days
	@returns the Number of Seconds
	@cat DTConv
}
function Days2Secs (const Value: Extended): Extended;

{: Returns the number of Days the specified number of Seconds represents.
	@param Value Number of Seconds
	@returns the Number of Days
	@cat DTConv
}
function Secs2Days (const Value: Extended): Extended;

{: Returns the number of Hours the specified number of Seconds represents.
	@param Value Number of Seconds
	@returns the Number of Hours
	@cat DTConv
}