---

date.h File Reference

Go to the source code of this file.

Compounds
struct	DT_DATE
struct	DT_EVENT
Defines
#define	DT_INTERVAL_DAY   1
#define	DT_INTERVAL_MONTH   2
#define	DT_INTERVAL_MONTH_DOW   3
#define	DT_FIRST   1
#define	DT_SECOND   2
#define	DT_THIRD   3
#define	DT_FOURTH   4
#define	DT_LAST   5
#define	DT_SUNDAY   0
#define	DT_MONDAY   1
#define	DT_TUESDAY   2
#define	DT_WEDNESDAY   3
#define	DT_THURSDAY   4
#define	DT_FRIDAY   5
#define	DT_SATURDAY   6
#define	DT_DAY   10
#define	DT_JANUARY   1
#define	DT_FEBRUARY   2
#define	DT_MARCH   3
#define	DT_APRIL   4
#define	DT_MAY   5
#define	DT_JUNE   6
#define	DT_JULY   7
#define	DT_AUGUST   8
#define	DT_SEPTEMBER   9
#define	DT_OCTOBER   10
#define	DT_NOVEMBER   11
#define	DT_DECEMBER   12
#define	DT_LUNAR_PERIOD   29.5305882
#define	DT_NEWMOON_OFFSET   17.7800836001
#define	DT_ASCII_BUFFER_SIZE   32
#define	DT_NUMERIC_OUT   0x01
#define	DT_US_FORMAT   0x02
#define	DT_EUROPE_FORMAT   0x04
#define	DT_UNIVERSAL_FORMAT   0x08
#define	DT_FREE_ALL   1
#define	DT_FREE_NONE   2
#define	DT_PREV   -1
#define	DT_NONE   0
#define	DT_NEXT   1
#define	DT_is_leap_year(x)
#define	DT_is_leap_year_q(x)    ((x)%400==0 || ((x)%100!=0 && (x)%4==0))
#define	DT_set_year(date,year)
#define	DT_set_month(date,month)
#define	DT_set_day(date,day)
Functions
DT_DATE*	DT_mkdate (int year, int month, int day)
DT_DATE*	DT_mkdate_dow (int ordinal, int dow, int month, int year)
DT_DATE*	DT_mkdate_rata_die (long int rata_die)
void	DT_rmdate (DT_DATE *date)
DT_DATE*	DT_copy_date (DT_DATE *date)
long int	DT_days_between (DT_DATE *date1, DT_DATE *date2)
long int	DT_months_between (DT_DATE *date1, DT_DATE *date2)
char*	DT_ascii (DT_DATE *date, unsigned long int format)
char*	DT_ascii_r (char *buffer, int buf_size, DT_DATE *date, unsigned long int format)
char*	DT_dow_ascii (DT_DATE *date)
void	DT_set_date (DT_DATE *date, int year, int month, int day)
void	DT_set_rata_die (DT_DATE *date, long int rata_die)
int	DT_dow (DT_DATE *date)
int	DT_year (DT_DATE *date)
int	DT_month (DT_DATE *date)
int	DT_day (DT_DATE *date)
long int	DT_rata_die (DT_DATE *date)
void	DT_add_days (DT_DATE *date, long int days)
void	DT_add_months (DT_DATE *date, long int months)
void	DT_find_dow_date (DT_DATE *date, int ordinal, int dow, int month)
int	DT_days_this_month (DT_DATE *date)
int	DT_days_this_month_q (int year, int month)
void	DT_easter (DT_DATE *date)
DT_EVENT*	DT_mkevent (DT_DATE *start, DT_DATE *end, long int interval)
DT_EVENT*	DT_mkevent_monthly (DT_DATE *start, DT_DATE *end, long int interval, int day)
DT_EVENT*	DT_mkevent_monthly_dow (DT_DATE *start, DT_DATE *end, long int interval, int ordinal, int dow)
void	DT_rmevent (DT_EVENT *event, int freeall)
void	DT_event_adj_rel (DT_EVENT *event, int adj)
void	DT_event_adj_dow (DT_EVENT *event, int sign, int dow)
void	DT_event_multiday (DT_EVENT *event, int len)
void	DT_event_pattern (DT_EVENT *event, char *pattern)
int	DT_is_event_today (DT_DATE *date, DT_EVENT *event)
DT_DATE*	DT_event_next (DT_DATE *date, DT_EVENT *event)
int	DT_cal_rows (DT_DATE *date)
int	DT_cal_day_to_row (DT_DATE *date)
int	DT_cal_day_to_col (DT_DATE *date)
int	DT_cal_row_col_to_day (DT_DATE *date, int row, int col)
double	DT_moon_age (DT_DATE *date, int timezone)

---

Define Documentation

#define DT_APRIL   4

#define DT_ASCII_BUFFER_SIZE   32

#define DT_AUGUST   8

#define DT_DAY   10

#define DT_DECEMBER   12

#define DT_EUROPE_FORMAT   0x04

#define DT_FEBRUARY   2

#define DT_FIRST   1

#define DT_FOURTH   4

#define DT_FREE_ALL   1

#define DT_FREE_NONE   2

#define DT_FRIDAY   5

#define DT_INTERVAL_DAY   1

#define DT_INTERVAL_MONTH   2

#define DT_INTERVAL_MONTH_DOW   3

#define DT_JANUARY   1

#define DT_JULY   7

#define DT_JUNE   6

#define DT_LAST   5

#define DT_LUNAR_PERIOD   29.5305882

#define DT_MARCH   3

#define DT_MAY   5

#define DT_MONDAY   1

#define DT_NEWMOON_OFFSET   17.7800836001

#define DT_NEXT   1

#define DT_NONE   0

#define DT_NOVEMBER   11

#define DT_NUMERIC_OUT   0x01

#define DT_OCTOBER   10

#define DT_PREV   -1

#define DT_SATURDAY   6

#define DT_SECOND   2

#define DT_SEPTEMBER   9

#define DT_SUNDAY   0

#define DT_THIRD   3

#define DT_THURSDAY   4

#define DT_TUESDAY   2

#define DT_UNIVERSAL_FORMAT   0x08

#define DT_US_FORMAT   0x02

#define DT_WEDNESDAY   3

#define DT_is_leap_year( x )

Initial value:

(DT_year(x)%400==0 \
                             || (DT_year(x)%100!=0 && DT_year(x)%4==0))

Determines if a date is in a leap year.

#define DT_is_leap_year_q( x )   ((x)%400==0 || ((x)%100!=0 && (x)%4==0))

Determines if a year is a leap year.

#define DT_set_day( date, day )

Initial value:

DT_set_date((date),DT_year(date), \
                              DT_month(date), (day))

Sets just the day part of a date.

#define DT_set_month( date, month )

Initial value:

DT_set_date((date),DT_year(date), \
                                  (month), DT_day(date))

Sets just the month part of a date.

#define DT_set_year( date, year )

Initial value:

DT_set_date((date),(year),DT_month(date), \
                                DT_day(date))

Sets just the year part of a date.

---

Function Documentation

void DT_add_days ( DT_DATE * date, long int days )

DT_add_days.

Adds some number of days to the date.

Parameters:

date	The date to adjust.
days	The number of days to add.

Returns:

void (All calculations are done inside date)

Note If you want to subtract days, pass a negative value in for days.

void DT_add_months ( DT_DATE * date, long int months )

DT_add_months.

Adds some number of months to the date.

Parameters:

date	The date to adjust.
months	The number of months to add.

Returns:

void (All calculations are done inside date)

Note If you want to subtract months, pass a negative value in for months. Also, beware of adding months when the day of the month is at the end of the month. For example, March 31 + 1 month = April 31, but since April only has 30 days, the it rolls back to April 30.

char * DT_ascii ( DT_DATE * date, unsigned long int format )

DT_ascii.

Converts a date into ascii format suitable for displaying to the user. The format can be in one of several formats, which are DT_US_FORMAT, DT_EUROPE_FORMAT, or DT_UNIVERSAL_FORMAT. This symbol can be ORed with DT_NUMERIC_OUT if you want the output to be strictly numeric. The result will be stored in a statically declared buffer.

Parameters:

date	The date to convert
format	The desired output format, as described above

Returns:

A pointer to a string containing the ASCII version of the date

Note This version is not thread-safe

char * DT_ascii_r ( char * buffer, int buf_size, DT_DATE * date, unsigned long int format )

DT_ascii_r.

Converts a date into ascii format suitable for displaying to the user. The format can be in one of several formats, which are DT_US_FORMAT, DT_EUROPE_FORMAT, or DT_UNIVERSAL_FORMAT. This symbol can be ORed with DT_NUMERIC_OUT if you want the output to be strictly numeric. The result will be stored in a statically declared buffer.

Parameters:

buffer	The buffer where the output will be held
buf_size	The size of the buffer
date	The date to convert
format	The desired output format, as described above

Returns:

A pointer to a string containing the ASCII version of the date

Note This version is thread-safe

int DT_cal_day_to_col ( DT_DATE * date )

DT_cal_day_to_col.

Given a date, return the column in which it would appear in the calendar.

Parameters:

date	The date the convert

Returns:

The column in which the date appears.

Note The first column is column 0.

int DT_cal_day_to_row ( DT_DATE * date )

DT_cal_day_to_row.

Given a date, return the row in which it would appear in the calendar.

Parameters:

date	The date the convert

Returns:

The row in which the date appears.

Note The first row is row 0.

int DT_cal_row_col_to_day ( DT_DATE * date, int row, int col )

DT_cal_row_col_to_day.

Given a month, row, and column, determine which day of the month should fill that location.

Parameters:

date	The DT_DATE structure containing the month and year.
row	The row of the calendar (0-5)
col	The column of the calendar (0-6)

Returns:

The day of the month to fill into the given row and column.

Note If this function returns a 0, it means the row and column are for another month. A -1 means there was an error of some kind.

int DT_cal_rows ( DT_DATE * date )

DT_cal_rows.

Determines how many rows would be in a rendered calendar for a given month.

Parameters:

date	The DT_DATE structure holding the year and month to check

Returns:

The number of rows in a rendered calendar for the month.

DT_DATE * DT_copy_date ( DT_DATE * date )

DT_copy_date.

Creates a new date structure by copying the elements from an existing one.

Parameters:

date	The date to copy

Returns:

A pointer to a new date which is equivalent to the input date, or NULL if there is an error.

int DT_day ( DT_DATE * date )

DT_day.

Returns the day part of the date.

Parameters:

date	The date to extract the day from

Returns:

The day

long int DT_days_between ( DT_DATE * date1, DT_DATE * date2 )

DT_days_between.

Determines how many days are between two dates. It subtracts the second from the first, so if the second date is more recent than the first, the result will be negative.

Parameters:

date1	The first date
date2	The second date

Returns:

The number of days between the two dates, with a negative value if the second is more recent than the first.

int DT_days_this_month ( DT_DATE * date )

DT_days_this_month.

Given a date structure set to some month, return the number of days in the month.

Parameters:

date	The date whose month we want to check.

Returns:

The number of days in the month

int DT_days_this_month_q ( int year, int month )

DT_days_this_month_q.

Given a date structure set to some month, return the number of days in the month. This version is meant to make a quick calculation without the need to create a date structure.

Parameters:

year	The year for the month we're interested in
month	The month we're interested in (1-12)

Returns:

The number of days in the month

int DT_dow ( DT_DATE * date )

DT_dow.

Returns the day of week for the time stored in a DT_DATE structure.

Parameters:

date	The date structure to use

Returns:

The day of week (0=Sunday, 1=Monday, ... , 5=Friday, 6=Saturday)

char * DT_dow_ascii ( DT_DATE * date )

DT_dow_ascii.

Given a date, returns a pointer to an ascii version of the day of the week for that date.

Parameters:

date	The date to convert

Returns:

A pointer to the ascii version of the day of the week

void DT_easter ( DT_DATE * date )

DT_easter.

Calculate easter for a given year. The date calculated will be for the year contained in the date.

Parameters:

date	The DT_DATE structure

Returns:

void (date will be updated with easter)

void DT_event_adj_dow ( DT_EVENT * event, int sign, int dow )

DT_event_adj_dow.

Given an event, this allows one to adjust to a particular day of the week. The adjustment can be made either in the forward or reverse direction, will never exceed one week, and is guaranteed to change the date. As an example, if you wanted the first Monday after April 15, and April 15 is on a Friday, this would cause the event to be pushed 3 days forward. If April 15 is on a Monday, the event will be pushed 7 days forward. If you want to disable this feature from an event, use DT_NONE for the event, and anything you want for the dow.

Parameters:

event	The event to adjust
sign	DT_NEXT, DT_PREV, or DT_NONE
dow:	The day of the week DT_SUNDAY, DT_MONDAY, etc.

Returns:

void (the event is updated in place)

void DT_event_adj_rel ( DT_EVENT * event, int adj )

DT_event_adj_rel.

Give an event a relative adjustment. What this means is that after calculating the day an event occurs on, add this many days to it. That way, you can, for example, calculate election day as the first Tuesday after the first Monday of November every fourth year. Just calculate the first Monday in November, then add 1 to it. That's what this function is for. Notice, however, that the days you add or subtract must not be greater than the interval for the event.

Parameters:

event	The event to adjust
adj	The number of days to add to an event day

Returns:

void (the event is updated in place)

void DT_event_multiday ( DT_EVENT * event, int len )

DT_event_multiday.

Sets an event to last more than a single day. Using this function, every day of an event will be considered part of the event. For more complex patterns, use the DT_event_pattern function instead.

Parameters:

event	The event to adjust
len	How long to make the event.

Returns:

void (the event is updated in place)

Note The length should not be longer than the interval between one event and the next.

DT_DATE * DT_event_next ( DT_DATE * date, DT_EVENT * event )

DT_event_next.

Given a date and an event, find the next occurance of the event. Notice that if an event occurs on the date supplied, that date will not be returned.

Parameters:

date	The date to check around
event	The event to locate

Returns:

A pointer to date if a next date was found, or NULL if nothing was found.

Note date will be modified in place, and the return value, if successful, will be nothing more than a pointer to it.

void DT_event_pattern ( DT_EVENT * event, char * pattern )

DT_event_pattern.

Sets a complex pattern for a multiday event. The input contains a string of 0's and 1's, with each character representing a single day. A 0 means the event does not take place on that day, while a 1 means it does.

Parameters:

event	The event to adjust
pattern	The pattern for the event

Returns:

void (the event is updated in place)

void DT_find_dow_date ( DT_DATE * date, int ordinal, int dow, int month )

DT_find_dow_date.

Finds a date based on a day of week expression. For example, to find Thanksgiving, one would say the 4th Thursday in November. The year is taken from the current value in date. It is also possible, using DT_DAY for the day of week, to find the last day of the month (or the first, second, third, or fourth day of the month, but what's the use in that?)

Parameters:

date	The DT_DATE structure to modify
ordinal	DT_FIRST, DT_SECOND, DT_THIRD, DT_FOURTH, or DT_LAST.
dow	Day of week (0-6), or DT_DAY
month	The month (1-12)

Returns:

void (All results are stored in date)

int DT_is_event_today ( DT_DATE * date, DT_EVENT * event )

DT_is_event_today.

Determine if an event occurs on a particular day. Given an event and a date, determines if the event occurs on that day.

Parameters:

date	The DT_DATE structure containing the day
event	The DT_EVENT structure containing the event

Returns:

1 if the event occurs on the given date, or 0 if it doesn't

DT_DATE * DT_mkdate ( int year, int month, int day )

DT_mkdate.

Create a DT_DATE structure from a given year, month, and date

Parameters:

year	The full year (not just the last two digits)
month	The month (1=Jan, 2=Feb, ... , 11=Nov, 12=Dec)
date	The day of the month

Returns:

A DT_DATE structure with the given date, or NULL if there is an error.

Note This function does no sanity checking on the supplied date. So if you enter 40 for the day, or 20 for the month, it will be accepted.

DT_DATE * DT_mkdate_dow ( int ordinal, int dow, int month, int year )

DT_mkdate_dow.

Sets the date according to a particular occurance of a day of the week in some month and year. This can be used to, for example, find the first Sunday in April of 2000, or the last day in October of 2000.

Parameters:

ordinal	DT_FIRST, DT_SECOND, DT_THIRD, DT_FOURTH, or DT_LAST.
dow	Day of week (0-6), or DT_DAY
month	The month (1-12)
year	The year

Returns:

A DT_DATE structure with the given date, or NULL if there is an error.

DT_DATE * DT_mkdate_rata_die ( long int rata_die )

DT_mkdate_rata_die.

Given a date in rata die format, it returns a DT_DATE structure for it.

Parameters:

rata_die

The date in rata die format

Returns:

A DT_DATE structure with the given date, or NULL if there is an error.

DT_EVENT * DT_mkevent ( DT_DATE * start, DT_DATE * end, long int interval )

DT_mkevent.

Create a basic, no frills event. The event will recur at regular intervals, such as a weekly event (but not a monthly one - see DT_mkevent_monthly for that), and have bracketing dates between which the event will occur (so you can create an event that will only occur for one year, for example).

Parameters:

start	The date on which the event first occurs.
end	The date after which the event will no longer occur. If you want the event to continue indefinitely, set this to NULL.
interval	How long between one event and the next (in days)?

Returns:

A DT_EVENT structure with your event, or NULL on an error.

DT_EVENT * DT_mkevent_monthly ( DT_DATE * start, DT_DATE * end, long int interval, int day )

DT_mkevent_monthly.

Create an event that will recur on a certain day of the month every "interval" months. You can create a yearly event by setting the interval to 12. The event will first occur on the start day, and occur no further than the end date, thus allowing one to bracket the dates in which the event will occur. Set the end date to NULL if you want to event to recur indefinetely.

Parameters:

start	The date on which the event first occurs.
end	The date after which the event will no longer occur. If you want the event to continue indefinitely, set this to NULL.
interval	How long between one event and the next (in months)?
day	The day of the month for the event.

Returns:

A DT_EVENT structure with your event, or NULL on an error.

DT_EVENT * DT_mkevent_monthly_dow ( DT_DATE * start, DT_DATE * end, long int interval, int ordinal, int dow )

DT_mkevent_monthly_dow.

Create an event that will recur on a particular day of the week at some point in a given month. This can be used for events which occur, for example, on the third Wednesday of every month (or every other month, or whatever). You need to pass a date for the first occurance of the event, and optionally a date for the last occurance. This last occurance can be NULL if the event to recur indefinitely. You must also specify how many months between events. If you want the event to occur every third month, set interval to 3. The ordinal and dow arguments work the same as the ones in DT_find_dow_date.

Parameters:

start	The date on which the event first occurs.
end	The date after which the event will no longer occur. If you want the event to continue indefinitely, set this to NULL.
interval	How long between one event and the next (in months)?
ordinal	DT_FIRST, DT_SECOND, DT_THIRD, DT_FOURTH, or DT_LAST
dow	A day of the week, or DT_DAY

Returns:

A DT_EVENT structure with your event, or NULL on an error.

int DT_month ( DT_DATE * date )

DT_month.

Returns the month part of the date.

Parameters:

date	The date to extract the month from

Returns:

The month (1=Jan ... 12=Dec)

long int DT_months_between ( DT_DATE * date1, DT_DATE * date2 )

DT_months_between.

Determines how many months are between two dates. It subtracts the second from the first, so if the second date is more recent than the first, the result will be negative. Also, this function completely ignores the day of the month, so consecutive days in different months, like Jan 31 and Feb 1 will have a difference of 1.

Parameters:

date1	The first date
date2	The second date

Returns:

The number of months between the two dates, with a negative value if the second is more recent than the first.

double DT_moon_age ( DT_DATE * date, int timezone )

DT_moon_age.

Calculate the age of the moon in its synodic month. A synodic month Is the time the moon takes to go though all its phases, from one new moon to the next. Once we know the age, we can infer the phase of the moon from it.

Parameters:

date	A DT_DATE structure for the date to calculate for.
timezone	The timezone, represented as the number of hours relative to GMT

Returns:

The age of the moon at midnight on the specified date.

Note To find the age of the moon at times other than midnight, just add the fraction of a day corresponding to the time. In other words, each hour represents 1/24 days, and each minute represents 1/1440 days. If you want 2 30pm (14 30), add 14/24 + 30/1440, (0.604166667).

long int DT_rata_die ( DT_DATE * date )

DT_rata_die.

Returns the date in rata die format

Parameters:

date	The date to extract the year from

Returns:

The date in rata die format.

void DT_rmdate ( DT_DATE * date )

DT_rmdate.

Frees a DT_DATE structure. Call this when you are finished using one.

Parameters:

date	The DT_DATE structure to free

Returns:

void

void DT_rmevent ( DT_EVENT * event, int freeall )

DT_rmevent.

Frees the memory associated with an event. It can optionally free the memory associated with the two date structures inside as well.

Parameters:

event	The event to free.
freeall	Either DT_FREE_ALL or DT_FREE_NONE, referring to whether or not to free the internal date structures.

Returns:

void

void DT_set_date ( DT_DATE * date, int year, int month, int day )

DT_set_date.

Sets the date in a date structure.

Parameters:

date	The DT_DATE structure
year	The year
month	The month
day	The day of the month

Returns:

void

void DT_set_rata_die ( DT_DATE * date, long int rata_die )

DT_set_rata_die.

Sets the date in a date structure using the rata die format.

Parameters:

date	The DT_DATE structure
rata_die	The date in rata die format

Returns:

void

int DT_year ( DT_DATE * date )

DT_year.

Returns the year part of the date.

Parameters:

date	The date to extract the year from

Returns:

The year

---