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

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

/* - mode: c; c-basic-offset: 2; indent-tabs-mode: nil; -*-
 *  vim:expandtab:shiftwidth=2:tabstop=2:smarttab:
 *
 *  Copyright (C) 2008 Sun Microsystems, Inc.
 * 
 *  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
 */

#pragma once

#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 UNIX_EPOCH_MIN_YEARS 1970
#define UNIX_EPOCH_MAX_YEARS 2038

#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)

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);

/**
 * 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);

inline static bool num_leap_years(uint32_t y, enum calendar c) 
{
  return (c == GREGORIAN                
          ? number_of_leap_years_gregorian(y) 
          : number_of_leap_years_julian(y));
}

/**
 * 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
 */
uint32_t iso_week_number_from_gregorian_date(uint32_t year
                                           , uint32_t month
                                           , uint32_t day);
/**
 * 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);

/**
 * Simple function returning whether the supplied year
 * is a leap year in the supplied calendar.
 *
 * @param Year to evaluate
 * @param Calendar to use
 */
inline static bool is_leap_year(uint32_t y, enum calendar c)
{
  return (days_in_year(y, c) == 366);
}

/**
 * Simple function returning whether the supplied year
 * is a leap year in the Gregorian proleptic calendar.
 */
inline static bool is_gregorian_leap_year(uint32_t y)
{
  return (days_in_year_gregorian(y) == 366);
}

/**
 * Simple function returning whether the supplied year
 * is a leap year in the Julian proleptic calendar.
 */
inline static bool is_julian_leap_year(uint32_t y) 
{
  return (days_in_year_julian(y) == 366);
}

} /* namespace drizzled */


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	*
1999.6.1 by kalebral at gmail update Copyright strings to a more common format to help with creating the master debian copyright file	4	* Copyright (C) 2008 Sun Microsystems, Inc.
813.1.2 by Jay Pipes First function cleanup for temporal handling: YEAR()	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
2234 by Brian Aker Mass removal of ifdef/endif in favor of pragma once.	39	#pragma once
813.1.2 by Jay Pipes First function cleanup for temporal handling: YEAR()	40
1491.6.1 by Monty Taylor Merged Pawel.	41	#define JULIAN_DAY_NUMBER_AT_ABSOLUTE_DAY_ONE INT64_C(1721425)
	42
	43	#define DAYS_IN_NORMAL_YEAR INT32_C(365)
	44	#define DAYS_IN_LEAP_YEAR INT32_C(366)
	45
	46	#define UNIX_EPOCH_MIN_YEARS 1970
2097.1.6 by Brian Aker Place limits on timestamp (unforunatly)	47	#define UNIX_EPOCH_MAX_YEARS 2038
1491.6.1 by Monty Taylor Merged Pawel.	48
	49	#define CALENDAR_YY_PART_YEAR 70
	50
	51	/**
	52	* The following constants define the system of calculating the number
	53	* of days in various periods of time in the Gregorian calendar.
	54	*
	55	* Leap years (years containing 366 days) occur:
	56	*
	57	* - When the year is evenly divisible by 4
	58	* - If the year is evenly divisible by 100, it must also
	59	* be evenly divisible by 400.
	60	*/
	61	#define GREGORIAN_DAYS_IN_400_YEARS UINT32_C(146097)
	62	#define GREGORIAN_DAYS_IN_100_YEARS UINT32_C(36524)
	63	#define GREGORIAN_DAYS_IN_4_YEARS UINT32_C(1461)
	64
1280.1.10 by Monty Taylor Put everything in drizzled into drizzled namespace.	65	namespace drizzled
	66	{
	67
813.1.2 by Jay Pipes First function cleanup for temporal handling: YEAR()	68	/**
	69	* Different calendars supported by the temporal library
	70	*/
	71	enum calendar
	72	{
1892.5.2 by Gustaf Thorslund Replaced macros with functions/templates. Part of blueprint:	73	GREGORIAN= 1,
	74	JULIAN= 2,
	75	HEBREW= 3,
	76	ISLAM= 4
813.1.2 by Jay Pipes First function cleanup for temporal handling: YEAR()	77	};
	78
1892.5.2 by Gustaf Thorslund Replaced macros with functions/templates. Part of blueprint:	79
813.1.2 by Jay Pipes First function cleanup for temporal handling: YEAR()	80	/**
	81	* Calculates the Julian Day Number from the year, month
	82	* and day supplied for a Gregorian Proleptic calendar date.
	83	*
	84	* @note
	85	*
	86	* Year month and day values are assumed to be valid. This
	87	* method does no bounds checking or validation.
	88	*
	89	* @param Year of date
	90	* @param Month of date
	91	* @param Day of date
	92	*/
	93	int64_t julian_day_number_from_gregorian_date(uint32_t year, uint32_t month, uint32_t day);
	94
1491.6.1 by Monty Taylor Merged Pawel.	95	/**
	96	* Translates an absolute day number to a
	97	* Julian day number.
	98	*
	99	* @param The absolute day number
	100	*/
	101	int64_t absolute_day_number_to_julian_day_number(int64_t absolute_day);
	102
	103	/**
	104	* Translates a Julian day number to an
	105	* absolute day number.
	106	*
	107	* @param The Julian day number
	108	*/
	109	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()	110
	111	/**
	112	* Given a supplied Julian Day Number, populates a year, month, and day
	113	* with the date in the Gregorian Proleptic calendar which corresponds to
	114	* the given Julian Day Number.
	115	*
	116	* @param Julian Day Number
	117	* @param Pointer to year to populate
	118	* @param Pointer to month to populate
	119	* @param Pointer to the day to populate
	120	*/
	121	void gregorian_date_from_julian_day_number(int64_t julian_day
	122	, uint32_t *year_out
	123	, uint32_t *month_out
	124	, uint32_t *day_out);
	125
1491.6.1 by Monty Taylor Merged Pawel.	126	/**
	127	* Given a supplied Absolute Day Number, populates a year, month, and day
	128	* with the date in the Gregorian Proleptic calendar which corresponds to
	129	* the given Absolute Day Number.
	130	*
	131	* @param Absolute Day Number
	132	* @param Pointer to year to populate
	133	* @param Pointer to month to populate
	134	* @param Pointer to the day to populate
	135	*/
	136	void gregorian_date_from_absolute_day_number(int64_t absolute_day
	137	, uint32_t *year_out
	138	, uint32_t *month_out
	139	, uint32_t *day_out);
	140
	141	/**
	142	* Returns the number of days in a particular year.
	143	*
	144	* @param year to evaluate
	145	* @param calendar to use
	146	*/
	147	uint32_t days_in_year(uint32_t year, enum calendar calendar);
	148
	149	/**
	150	* Returns the number of days in a particular Gregorian Proleptic calendar year.
	151	*
	152	* @param year to evaluate
	153	*/
	154	uint32_t days_in_year_gregorian(uint32_t year);
	155
	156	/**
	157	* Returns the number of days in a particular Julian Proleptic calendar year.
	158	*
	159	* @param year to evaluate
	160	*/
	161	uint32_t days_in_year_julian(uint32_t year);
	162
	163	/**
	164	* Returns the number of leap years that have
	165	* occurred in the Julian Proleptic calendar
	166	* up to the supplied year.
	167	*
	168	* @param year to evaluate (1 - 9999)
	169	*/
	170	int32_t number_of_leap_years_julian(uint32_t year);
	171
	172	/**
	173	* Returns the number of leap years that have
	174	* occurred in the Gregorian Proleptic calendar
	175	* up to the supplied year.
	176	*
	177	* @param year to evaluate (1 - 9999)
	178	*/
	179	int32_t number_of_leap_years_gregorian(uint32_t year);
813.1.2 by Jay Pipes First function cleanup for temporal handling: YEAR()	180
	181	/**
	182	* Returns the number of days in a month, given
	183	* a year and a month in the Gregorian calendar.
	184	*
	185	* @param Year in Gregorian Proleptic calendar
	186	* @param Month in date
	187	*/
	188	uint32_t days_in_gregorian_year_month(uint32_t year, uint32_t month);
	189
1892.5.2 by Gustaf Thorslund Replaced macros with functions/templates. Part of blueprint:	190	inline static bool num_leap_years(uint32_t y, enum calendar c)
	191	{
	192	return (c == GREGORIAN
	193	? number_of_leap_years_gregorian(y)
	194	: number_of_leap_years_julian(y));
	195	}
	196
813.1.2 by Jay Pipes First function cleanup for temporal handling: YEAR()	197	/**
	198	* Returns the number of the day in a week.
	199	*
	200	* @see temporal_to_number_days()
	201	*
	202	* Return values:
	203	*
	204	* Day Day Number Sunday first day?
	205	* -------------- ----------- -----------------
	206	* Sunday 0 true
	207	* Monday 1 true
	208	* Tuesday 2 true
	209	* Wednesday 3 true
	210	* Thursday 4 true
	211	* Friday 5 true
	212	* Saturday 6 true
	213	* Sunday 6 false
	214	* Monday 0 false
	215	* Tuesday 1 false
	216	* Wednesday 2 false
	217	* Thursday 3 false
	218	* Friday 4 false
	219	* Saturday 5 false
	220	*
	221	* @param Number of days since start of Gregorian calendar.
	222	* @param Consider Sunday the first day of the week?
	223	*/
	224	uint32_t day_of_week(int64_t day_number, bool sunday_is_first_day_of_week);
	225
	226	/**
1491.6.1 by Monty Taylor Merged Pawel.	227	* Given a year, month, and day, returns whether the date is
	228	* valid for the Gregorian proleptic calendar.
	229	*
	230	* @param The year
	231	* @param The month
	232	* @param The day
	233	*/
	234	bool is_valid_gregorian_date(uint32_t year, uint32_t month, uint32_t day);
	235
	236	/**
813.1.2 by Jay Pipes First function cleanup for temporal handling: YEAR()	237	* Returns whether the supplied date components are within the
	238	* range of the UNIX epoch.
	239	*
	240	* Times in the range of 1970-01-01T00:00:00 to 2038-01-19T03:14:07
	241	*
	242	* @param Year
	243	* @param Month
	244	* @param Day
	245	* @param Hour
	246	* @param Minute
	247	* @param Second
	248	*/
	249	bool in_unix_epoch_range(uint32_t year
	250	, uint32_t month
	251	, uint32_t day
	252	, uint32_t hour
	253	, uint32_t minute
	254	, uint32_t second);
	255
	256	/**
	257	* 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	258	* date in the Gregorian proleptic calendar. We use strftime() and
	259	* the %U, %W, and %V format specifiers depending on the value
	260	* of the sunday_is_first_day_of_week parameter.
813.1.2 by Jay Pipes First function cleanup for temporal handling: YEAR()	261	*
	262	* @param Subject year
	263	* @param Subject month
	264	* @param Subject day
	265	* @param Is sunday the first day of the week?
	266	* @param Pointer to a uint32_t to hold the resulting year, which
	267	* may be incremented or decremented depending on flags
	268	*/
	269	uint32_t week_number_from_gregorian_date(uint32_t year
	270	, uint32_t month
	271	, uint32_t day
813.1.22 by Jay Pipes default_week_format variable has gone the way of the Dodo, as have the	272	, bool sunday_is_first_day_of_week);
813.1.2 by Jay Pipes First function cleanup for temporal handling: YEAR()	273
813.1.22 by Jay Pipes default_week_format variable has gone the way of the Dodo, as have the	274	/**
	275	* Returns the ISO week number of a supplied year, month, and
	276	* date in the Gregorian proleptic calendar. We use strftime() and
	277	* the %V format specifier to do the calculation, which yields a
	278	* correct ISO 8601:1988 week number.
	279	*
	280	* The final year_out parameter is a pointer to an integer which will
	281	* be set to the year in which the week belongs, according to ISO8601:1988,
	282	* which may be different from the Gregorian calendar year.
	283	*
	284	* @see http://en.wikipedia.org/wiki/ISO_8601
	285	*
	286	* @param Subject year
	287	* @param Subject month
	288	* @param Subject day
	289	*/
	290	uint32_t iso_week_number_from_gregorian_date(uint32_t year
	291	, uint32_t month
1831.1.1 by Andrew Hutchings Fix new warnings in GCC 4.5	292	, uint32_t day);
907.1.3 by Jay Pipes Merging in old r903 temporal changes	293	/**
	294	* Takes a number in the form [YY]YYMM and converts it into
	295	* a number of months.
	296	*
	297	* @param Period in the form [YY]YYMM
	298	*/
	299	uint32_t year_month_to_months(uint32_t year_month);
	300
	301	/**
	302	* Takes a number of months and converts it to
	303	* a period in the form YYYYMM.
	304	*
	305	* @param Number of months
	306	*/
	307	uint32_t months_to_year_month(uint32_t months);
	308
1892.5.2 by Gustaf Thorslund Replaced macros with functions/templates. Part of blueprint:	309	/**
	310	* Simple function returning whether the supplied year
	311	* is a leap year in the supplied calendar.
	312	*
	313	* @param Year to evaluate
	314	* @param Calendar to use
	315	*/
	316	inline static bool is_leap_year(uint32_t y, enum calendar c)
	317	{
	318	return (days_in_year(y, c) == 366);
	319	}
	320
	321	/**
	322	* Simple function returning whether the supplied year
	323	* is a leap year in the Gregorian proleptic calendar.
	324	*/
	325	inline static bool is_gregorian_leap_year(uint32_t y)
	326	{
	327	return (days_in_year_gregorian(y) == 366);
	328	}
	329
	330	/**
	331	* Simple function returning whether the supplied year
	332	* is a leap year in the Julian proleptic calendar.
	333	*/
	334	inline static bool is_julian_leap_year(uint32_t y)
	335	{
	336	return (days_in_year_julian(y) == 366);
	337	}
	338
1280.1.10 by Monty Taylor Put everything in drizzled into drizzled namespace.	339	} /* namespace drizzled */
	340