~drizzle-trunk/drizzle/development : contents of drizzled/calendar.h at revision 1377.8.31

~drizzle-trunk/drizzle/development : (revision 1377.8.31)

/* - mode: c; c-basic-offset: 2; indent-tabs-mode: nil; -*-
 *  vim:expandtab:shiftwidth=2:tabstop=2:smarttab:
 *
 *  Copyright (C) 2008 Sun Microsystems
 * 
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */

/**
 * @file 
 *
 * Structures and functions for:
 *
 * Calculating day number in Gregorian and Julian proleptic calendars.
 * Converting between day numbers and dates in the calendars.
 * Converting between different calendars.
 * Calculating differences between dates.
 *
 * Works used in research:
 *
 * @cite "Calendrical Calculations", Dershowitz and Reingold
 * @cite ISO 8601 http://en.wikipedia.org/wiki/ISO_8601
 * @cite http://www.ddj.com/hpc-high-performance-computing/197006254 
 * @cite http://en.wikipedia.org/wiki/Julian_day#Calculation
 */

#ifndef DRIZZLED_CALENDAR_H
#define DRIZZLED_CALENDAR_H

#define JULIAN_DAY_NUMBER_AT_ABSOLUTE_DAY_ONE INT64_C(1721425)

#define DAYS_IN_NORMAL_YEAR INT32_C(365)
#define DAYS_IN_LEAP_YEAR INT32_C(366)

#define GREGORIAN_START_YEAR 1582
#define GREGORIAN_START_MONTH 10
#define GREGORIAN_START_DAY 15

#define UNIX_EPOCH_MAX_YEARS 2038
#define UNIX_EPOCH_MIN_YEARS 1970

#define CALENDAR_YY_PART_YEAR 70

/**
 * The following constants define the system of calculating the number
 * of days in various periods of time in the Gregorian calendar.
 *
 * Leap years (years containing 366 days) occur:
 *
 * - When the year is evenly divisible by 4
 * - If the year is evenly divisible by 100, it must also
 *   be evenly divisible by 400.
 */
#define GREGORIAN_DAYS_IN_400_YEARS UINT32_C(146097)
#define GREGORIAN_DAYS_IN_100_YEARS UINT32_C(36524)
#define GREGORIAN_DAYS_IN_4_YEARS   UINT32_C(1461)

/**
 * Simple macro returning whether the supplied year
 * is a leap year in the supplied calendar.
 *
 * @param Year to evaluate
 * @param Calendar to use
 */
#define IS_LEAP_YEAR(y, c) (days_in_year((y),(c)) == 366)

/**
 * Simple macro returning whether the supplied year
 * is a leap year in the Gregorian proleptic calendar.
 */
#define IS_GREGORIAN_LEAP_YEAR(y) (days_in_year_gregorian((y)) == 366)

/**
 * Simple macro returning whether the supplied year
 * is a leap year in the Julian proleptic calendar.
 */
#define IS_JULIAN_LEAP_YEAR(y) (days_in_year_julian((y)) == 366)

namespace drizzled
{

/**
 * Different calendars supported by the temporal library
 */
enum calendar
{
  GREGORIAN= 1
, JULIAN= 2
, HEBREW= 3
, ISLAM= 4
};

/**
 * Calculates the Julian Day Number from the year, month 
 * and day supplied for a Gregorian Proleptic calendar date.
 *
 * @note
 *
 * Year month and day values are assumed to be valid.  This 
 * method does no bounds checking or validation.
 *
 * @param Year of date
 * @param Month of date
 * @param Day of date
 */
int64_t julian_day_number_from_gregorian_date(uint32_t year, uint32_t month, uint32_t day);

/**
 * Translates an absolute day number to a 
 * Julian day number.
 *
 * @param The absolute day number
 */
int64_t absolute_day_number_to_julian_day_number(int64_t absolute_day);

/**
 * Translates a Julian day number to an 
 * absolute day number.  
 *
 * @param The Julian day number
 */
int64_t julian_day_number_to_absolute_day_number(int64_t julian_day);

/**
 * Given a supplied Julian Day Number, populates a year, month, and day
 * with the date in the Gregorian Proleptic calendar which corresponds to
 * the given Julian Day Number.
 *
 * @param Julian Day Number
 * @param Pointer to year to populate
 * @param Pointer to month to populate
 * @param Pointer to the day to populate
 */
void gregorian_date_from_julian_day_number(int64_t julian_day
                                         , uint32_t *year_out
                                         , uint32_t *month_out
                                         , uint32_t *day_out);

/**
 * Given a supplied Absolute Day Number, populates a year, month, and day
 * with the date in the Gregorian Proleptic calendar which corresponds to
 * the given Absolute Day Number.
 *
 * @param Absolute Day Number
 * @param Pointer to year to populate
 * @param Pointer to month to populate
 * @param Pointer to the day to populate
 */
void gregorian_date_from_absolute_day_number(int64_t absolute_day
                                           , uint32_t *year_out
                                           , uint32_t *month_out
                                           , uint32_t *day_out);

/**
 * Returns the number of days in a particular year.
 *
 * @param year to evaluate
 * @param calendar to use
 */
uint32_t days_in_year(uint32_t year, enum calendar calendar);

/**
 * Returns the number of days in a particular Gregorian Proleptic calendar year.
 *
 * @param year to evaluate
 */
uint32_t days_in_year_gregorian(uint32_t year);

/**
 * Returns the number of days in a particular Julian Proleptic calendar year.
 *
 * @param year to evaluate
 */
uint32_t days_in_year_julian(uint32_t year);

#define NUM_LEAP_YEARS(y, c) ((c) == GREGORIAN \
    ? number_of_leap_years_gregorian((y)) \
    : number_of_leap_years_julian((y)))

/**
 * Returns the number of leap years that have
 * occurred in the Julian Proleptic calendar
 * up to the supplied year.
 *
 * @param year to evaluate (1 - 9999)
 */
int32_t number_of_leap_years_julian(uint32_t year);

/**
 * Returns the number of leap years that have
 * occurred in the Gregorian Proleptic calendar
 * up to the supplied year.
 *
 * @param year to evaluate (1 - 9999)
 */
int32_t number_of_leap_years_gregorian(uint32_t year);

/**
 * Returns the number of days in a month, given
 * a year and a month in the Gregorian calendar.
 *
 * @param Year in Gregorian Proleptic calendar
 * @param Month in date
 */
uint32_t days_in_gregorian_year_month(uint32_t year, uint32_t month);

/**
 * Returns the number of the day in a week.
 *
 * @see temporal_to_number_days()
 *
 * Return values:
 *
 * Day            Day Number  Sunday first day?
 * -------------- ----------- -----------------
 * Sunday         0           true
 * Monday         1           true
 * Tuesday        2           true
 * Wednesday      3           true
 * Thursday       4           true
 * Friday         5           true
 * Saturday       6           true
 * Sunday         6           false
 * Monday         0           false
 * Tuesday        1           false
 * Wednesday      2           false
 * Thursday       3           false
 * Friday         4           false
 * Saturday       5           false
 *
 * @param Number of days since start of Gregorian calendar.
 * @param Consider Sunday the first day of the week?
 */
uint32_t day_of_week(int64_t day_number, bool sunday_is_first_day_of_week);

/**
 * Given a year, month, and day, returns whether the date is 
 * valid for the Gregorian proleptic calendar.
 *
 * @param The year
 * @param The month
 * @param The day
 */
bool is_valid_gregorian_date(uint32_t year, uint32_t month, uint32_t day);

/**
 * Returns whether the supplied date components are within the 
 * range of the UNIX epoch.
 *
 * Times in the range of 1970-01-01T00:00:00 to 2038-01-19T03:14:07
 *
 * @param Year
 * @param Month
 * @param Day
 * @param Hour
 * @param Minute
 * @param Second
 */
bool in_unix_epoch_range(uint32_t year
                       , uint32_t month
                       , uint32_t day
                       , uint32_t hour
                       , uint32_t minute
                       , uint32_t second);

/**
 * Returns the number of the week from a supplied year, month, and
 * date in the Gregorian proleptic calendar.  We use strftime() and
 * the %U, %W, and %V format specifiers depending on the value
 * of the sunday_is_first_day_of_week parameter.
 *
 * @param Subject year
 * @param Subject month
 * @param Subject day
 * @param Is sunday the first day of the week?
 * @param Pointer to a uint32_t to hold the resulting year, which 
 *        may be incremented or decremented depending on flags
 */
uint32_t week_number_from_gregorian_date(uint32_t year
                                       , uint32_t month
                                       , uint32_t day
                                       , bool sunday_is_first_day_of_week);

/**
 * Returns the ISO week number of a supplied year, month, and
 * date in the Gregorian proleptic calendar.  We use strftime() and
 * the %V format specifier to do the calculation, which yields a
 * correct ISO 8601:1988 week number.
 *
 * The final year_out parameter is a pointer to an integer which will
 * be set to the year in which the week belongs, according to ISO8601:1988, 
 * which may be different from the Gregorian calendar year.
 *
 * @see http://en.wikipedia.org/wiki/ISO_8601
 *
 * @param Subject year
 * @param Subject month
 * @param Subject day
 * @param Pointer to a uint32_t to hold the resulting year, which 
 *        may be incremented or decremented depending on flags
 */
uint32_t iso_week_number_from_gregorian_date(uint32_t year
                                           , uint32_t month
                                           , uint32_t day
                                           , uint32_t *year_out);
/**
 * Takes a number in the form [YY]YYMM and converts it into
 * a number of months.
 *
 * @param Period in the form [YY]YYMM
 */
uint32_t year_month_to_months(uint32_t year_month);

/**
 * Takes a number of months and converts it to
 * a period in the form YYYYMM.
 *
 * @param Number of months
 */
uint32_t months_to_year_month(uint32_t months);

} /* namespace drizzled */

#endif /* DRIZZLED_CALENDAR_H */

813.1.2 by Jay Pipes First function cleanup for temporal handling: YEAR()	1	/* - mode: c; c-basic-offset: 2; indent-tabs-mode: nil; -*-
	2	* vim:expandtab:shiftwidth=2:tabstop=2:smarttab:
	3	*
	4	* Copyright (C) 2008 Sun Microsystems
	5	*
	6	* This program is free software; you can redistribute it and/or modify
	7	* it under the terms of the GNU General Public License as published by
	8	* the Free Software Foundation; either version 2 of the License, or
	9	* (at your option) any later version.
	10	*
	11	* This program is distributed in the hope that it will be useful,
	12	* but WITHOUT ANY WARRANTY; without even the implied warranty of
	13	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	14	* GNU General Public License for more details.
	15	*
	16	* You should have received a copy of the GNU General Public License
	17	* along with this program; if not, write to the Free Software
	18	* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
	19	*/
	20
	21	/**
	22	* @file
	23	*
	24	* Structures and functions for:
	25	*
	26	* Calculating day number in Gregorian and Julian proleptic calendars.
	27	* Converting between day numbers and dates in the calendars.
	28	* Converting between different calendars.
	29	* Calculating differences between dates.
	30	*
	31	* Works used in research:
	32	*
	33	* @cite "Calendrical Calculations", Dershowitz and Reingold
	34	* @cite ISO 8601 http://en.wikipedia.org/wiki/ISO_8601
	35	* @cite http://www.ddj.com/hpc-high-performance-computing/197006254
	36	* @cite http://en.wikipedia.org/wiki/Julian_day#Calculation
	37	*/
	38
	39	#ifndef DRIZZLED_CALENDAR_H
	40	#define DRIZZLED_CALENDAR_H
	41
1491.6.1 by Monty Taylor Merged Pawel.	42	#define JULIAN_DAY_NUMBER_AT_ABSOLUTE_DAY_ONE INT64_C(1721425)
	43
	44	#define DAYS_IN_NORMAL_YEAR INT32_C(365)
	45	#define DAYS_IN_LEAP_YEAR INT32_C(366)
	46
	47	#define GREGORIAN_START_YEAR 1582
	48	#define GREGORIAN_START_MONTH 10
	49	#define GREGORIAN_START_DAY 15
	50
	51	#define UNIX_EPOCH_MAX_YEARS 2038
	52	#define UNIX_EPOCH_MIN_YEARS 1970
	53
	54	#define CALENDAR_YY_PART_YEAR 70
	55
	56	/**
	57	* The following constants define the system of calculating the number
	58	* of days in various periods of time in the Gregorian calendar.
	59	*
	60	* Leap years (years containing 366 days) occur:
	61	*
	62	* - When the year is evenly divisible by 4
	63	* - If the year is evenly divisible by 100, it must also
	64	* be evenly divisible by 400.
	65	*/
	66	#define GREGORIAN_DAYS_IN_400_YEARS UINT32_C(146097)
	67	#define GREGORIAN_DAYS_IN_100_YEARS UINT32_C(36524)
	68	#define GREGORIAN_DAYS_IN_4_YEARS UINT32_C(1461)
	69
	70	/**
	71	* Simple macro returning whether the supplied year
	72	* is a leap year in the supplied calendar.
	73	*
	74	* @param Year to evaluate
	75	* @param Calendar to use
	76	*/
	77	#define IS_LEAP_YEAR(y, c) (days_in_year((y),(c)) == 366)
	78
	79	/**
	80	* Simple macro returning whether the supplied year
	81	* is a leap year in the Gregorian proleptic calendar.
	82	*/
	83	#define IS_GREGORIAN_LEAP_YEAR(y) (days_in_year_gregorian((y)) == 366)
	84
	85	/**
	86	* Simple macro returning whether the supplied year
	87	* is a leap year in the Julian proleptic calendar.
	88	*/
	89	#define IS_JULIAN_LEAP_YEAR(y) (days_in_year_julian((y)) == 366)
	90
1280.1.10 by Monty Taylor Put everything in drizzled into drizzled namespace.	91	namespace drizzled
	92	{
	93
813.1.2 by Jay Pipes First function cleanup for temporal handling: YEAR()	94	/**
	95	* Different calendars supported by the temporal library
	96	*/
	97	enum calendar
	98	{
	99	GREGORIAN= 1
	100	, JULIAN= 2
	101	, HEBREW= 3
	102	, ISLAM= 4
	103	};
	104
	105	/**
	106	* Calculates the Julian Day Number from the year, month
	107	* and day supplied for a Gregorian Proleptic calendar date.
	108	*
	109	* @note
	110	*
	111	* Year month and day values are assumed to be valid. This
	112	* method does no bounds checking or validation.
	113	*
	114	* @param Year of date
	115	* @param Month of date
	116	* @param Day of date
	117	*/
	118	int64_t julian_day_number_from_gregorian_date(uint32_t year, uint32_t month, uint32_t day);
	119
1491.6.1 by Monty Taylor Merged Pawel.	120	/**
	121	* Translates an absolute day number to a
	122	* Julian day number.
	123	*
	124	* @param The absolute day number
	125	*/
	126	int64_t absolute_day_number_to_julian_day_number(int64_t absolute_day);
	127
	128	/**
	129	* Translates a Julian day number to an
	130	* absolute day number.
	131	*
	132	* @param The Julian day number
	133	*/
	134	int64_t julian_day_number_to_absolute_day_number(int64_t julian_day);
813.1.2 by Jay Pipes First function cleanup for temporal handling: YEAR()	135
	136	/**
	137	* Given a supplied Julian Day Number, populates a year, month, and day
	138	* with the date in the Gregorian Proleptic calendar which corresponds to
	139	* the given Julian Day Number.
	140	*
	141	* @param Julian Day Number
	142	* @param Pointer to year to populate
	143	* @param Pointer to month to populate
	144	* @param Pointer to the day to populate
	145	*/
	146	void gregorian_date_from_julian_day_number(int64_t julian_day
	147	, uint32_t *year_out
	148	, uint32_t *month_out
	149	, uint32_t *day_out);
	150
1491.6.1 by Monty Taylor Merged Pawel.	151	/**
	152	* Given a supplied Absolute Day Number, populates a year, month, and day
	153	* with the date in the Gregorian Proleptic calendar which corresponds to
	154	* the given Absolute Day Number.
	155	*
	156	* @param Absolute Day Number
	157	* @param Pointer to year to populate
	158	* @param Pointer to month to populate
	159	* @param Pointer to the day to populate
	160	*/
	161	void gregorian_date_from_absolute_day_number(int64_t absolute_day
	162	, uint32_t *year_out
	163	, uint32_t *month_out
	164	, uint32_t *day_out);
	165
	166	/**
	167	* Returns the number of days in a particular year.
	168	*
	169	* @param year to evaluate
	170	* @param calendar to use
	171	*/
	172	uint32_t days_in_year(uint32_t year, enum calendar calendar);
	173
	174	/**
	175	* Returns the number of days in a particular Gregorian Proleptic calendar year.
	176	*
	177	* @param year to evaluate
	178	*/
	179	uint32_t days_in_year_gregorian(uint32_t year);
	180
	181	/**
	182	* Returns the number of days in a particular Julian Proleptic calendar year.
	183	*
	184	* @param year to evaluate
	185	*/
	186	uint32_t days_in_year_julian(uint32_t year);
	187
	188	#define NUM_LEAP_YEARS(y, c) ((c) == GREGORIAN \
	189	? number_of_leap_years_gregorian((y)) \
	190	: number_of_leap_years_julian((y)))
	191
	192	/**
	193	* Returns the number of leap years that have
	194	* occurred in the Julian Proleptic calendar
	195	* up to the supplied year.
	196	*
	197	* @param year to evaluate (1 - 9999)
	198	*/
	199	int32_t number_of_leap_years_julian(uint32_t year);
	200
	201	/**
	202	* Returns the number of leap years that have
	203	* occurred in the Gregorian Proleptic calendar
	204	* up to the supplied year.
	205	*
	206	* @param year to evaluate (1 - 9999)
	207	*/
	208	int32_t number_of_leap_years_gregorian(uint32_t year);
813.1.2 by Jay Pipes First function cleanup for temporal handling: YEAR()	209
	210	/**
	211	* Returns the number of days in a month, given
	212	* a year and a month in the Gregorian calendar.
	213	*
	214	* @param Year in Gregorian Proleptic calendar
	215	* @param Month in date
	216	*/
	217	uint32_t days_in_gregorian_year_month(uint32_t year, uint32_t month);
	218
	219	/**
	220	* Returns the number of the day in a week.
	221	*
	222	* @see temporal_to_number_days()
	223	*
	224	* Return values:
	225	*
	226	* Day Day Number Sunday first day?
	227	* -------------- ----------- -----------------
	228	* Sunday 0 true
	229	* Monday 1 true
	230	* Tuesday 2 true
	231	* Wednesday 3 true
	232	* Thursday 4 true
	233	* Friday 5 true
	234	* Saturday 6 true
	235	* Sunday 6 false
	236	* Monday 0 false
	237	* Tuesday 1 false
	238	* Wednesday 2 false
	239	* Thursday 3 false
	240	* Friday 4 false
	241	* Saturday 5 false
	242	*
	243	* @param Number of days since start of Gregorian calendar.
	244	* @param Consider Sunday the first day of the week?
	245	*/
	246	uint32_t day_of_week(int64_t day_number, bool sunday_is_first_day_of_week);
	247
	248	/**
1491.6.1 by Monty Taylor Merged Pawel.	249	* Given a year, month, and day, returns whether the date is
	250	* valid for the Gregorian proleptic calendar.
	251	*
	252	* @param The year
	253	* @param The month
	254	* @param The day
	255	*/
	256	bool is_valid_gregorian_date(uint32_t year, uint32_t month, uint32_t day);
	257
	258	/**
813.1.2 by Jay Pipes First function cleanup for temporal handling: YEAR()	259	* Returns whether the supplied date components are within the
	260	* range of the UNIX epoch.
	261	*
	262	* Times in the range of 1970-01-01T00:00:00 to 2038-01-19T03:14:07
	263	*
	264	* @param Year
	265	* @param Month
	266	* @param Day
	267	* @param Hour
	268	* @param Minute
	269	* @param Second
	270	*/
	271	bool in_unix_epoch_range(uint32_t year
	272	, uint32_t month
	273	, uint32_t day
	274	, uint32_t hour
	275	, uint32_t minute
	276	, uint32_t second);
	277
	278	/**
	279	* Returns the number of the week from a supplied year, month, and
813.1.22 by Jay Pipes default_week_format variable has gone the way of the Dodo, as have the	280	* date in the Gregorian proleptic calendar. We use strftime() and
	281	* the %U, %W, and %V format specifiers depending on the value
	282	* of the sunday_is_first_day_of_week parameter.
813.1.2 by Jay Pipes First function cleanup for temporal handling: YEAR()	283	*
	284	* @param Subject year
	285	* @param Subject month
	286	* @param Subject day
	287	* @param Is sunday the first day of the week?
	288	* @param Pointer to a uint32_t to hold the resulting year, which
	289	* may be incremented or decremented depending on flags
	290	*/
	291	uint32_t week_number_from_gregorian_date(uint32_t year
	292	, uint32_t month
	293	, uint32_t day
813.1.22 by Jay Pipes default_week_format variable has gone the way of the Dodo, as have the	294	, bool sunday_is_first_day_of_week);
813.1.2 by Jay Pipes First function cleanup for temporal handling: YEAR()	295
813.1.22 by Jay Pipes default_week_format variable has gone the way of the Dodo, as have the	296	/**
	297	* Returns the ISO week number of a supplied year, month, and
	298	* date in the Gregorian proleptic calendar. We use strftime() and
	299	* the %V format specifier to do the calculation, which yields a
	300	* correct ISO 8601:1988 week number.
	301	*
	302	* The final year_out parameter is a pointer to an integer which will
	303	* be set to the year in which the week belongs, according to ISO8601:1988,
	304	* which may be different from the Gregorian calendar year.
	305	*
	306	* @see http://en.wikipedia.org/wiki/ISO_8601
	307	*
	308	* @param Subject year
	309	* @param Subject month
	310	* @param Subject day
	311	* @param Pointer to a uint32_t to hold the resulting year, which
	312	* may be incremented or decremented depending on flags
	313	*/
	314	uint32_t iso_week_number_from_gregorian_date(uint32_t year
	315	, uint32_t month
	316	, uint32_t day
	317	, uint32_t *year_out);
907.1.3 by Jay Pipes Merging in old r903 temporal changes	318	/**
	319	* Takes a number in the form [YY]YYMM and converts it into
	320	* a number of months.
	321	*
	322	* @param Period in the form [YY]YYMM
	323	*/
	324	uint32_t year_month_to_months(uint32_t year_month);
	325
	326	/**
	327	* Takes a number of months and converts it to
	328	* a period in the form YYYYMM.
	329	*
	330	* @param Number of months
	331	*/
	332	uint32_t months_to_year_month(uint32_t months);
	333
1280.1.10 by Monty Taylor Put everything in drizzled into drizzled namespace.	334	} /* namespace drizzled */
	335
813.1.2 by Jay Pipes First function cleanup for temporal handling: YEAR()	336	#endif /* DRIZZLED_CALENDAR_H */