Main Page Compound List File List Compound Members File Members

date.c File Reference

libdate - A C library for manipulating dates. More...

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <math.h>
#include "config.h"
#include "date.h"

Defines

#define modulo(x,y) ((x)%(y)<0?(x)%(y)+(y):(x)%(y))

#define DT_event_is_in_range(d,e)

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)

DT_DATE* DT_copy_date (DT_DATE *date)

void DT_rmdate (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)

void DT_gregorian_date (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_months (DT_DATE *date, long int months)

void DT_add_days (DT_DATE *date, long int days)

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)

void DT_event_calc_adj (DT_DATE *date, DT_EVENT *event)

int DT_event_check_pattern (DT_DATE *start_date, DT_EVENT *event, DT_DATE *target_date)

void DT_event_calc_from_seed (DT_DATE *date, DT_EVENT *event)

void DT_event_closest (DT_DATE *date, DT_EVENT *event)

void DT_event_next_block (DT_DATE *event_date, DT_EVENT *event)

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)

Variables

char* month []

char* dow []

int days_per_month []

Detailed Description

libdate - A C library for manipulating dates.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library 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 Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Define Documentation

#define DT_event_is_in_range( d, e )

Initial value:

\
   ((d)->rata_die >= (e)->start_date->rata_die \
      && ((e)->end_date == NULL \
          || (d)->rata_die <= (e)->end_date->rata_die))

#define modulo( x, y ) ((x)%(y)<0?(x)%(y)+(y):(x)%(y))

Modulo function that works correctly for negative divisors.

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.

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_calc_adj ( DT_DATE * date,

DT_EVENT * event ) [static]

DT_event_calc_adj.

Given a date and an event, adjust the date according to the day and day of week adjustments in the event structure. This assumes the date has already been set to match the event sans adjustment. This function is for internal use only.

Parameters:

date	The date to adjust
event	The event from which the adjustments will be taken

Returns:: void (The date structure will be adjusted)

void DT_event_calc_from_seed ( DT_DATE * date,

DT_EVENT * event ) [static]

DT_event_calc_from_seed.

Given a "seed" date, calculates when the event associated with that seed occurs. Notice that this function is for internal use only.

Parameters:

date	The seed date
event	The event to calculate

Returns:: void (The date is returned in the date structure)

Note This function does not take the start and end dates into consideration except to calculate when the interval starts.

int DT_event_check_pattern ( DT_DATE * start_date,

DT_EVENT * event,

DT_DATE * target_date ) [static]

DT_event_check_pattern.

Given a date which is assumed to be the beginning of an event, an event with a pattern, and a target date, determines if the event occurs on the target date. Notice that this function is for internal use only

Parameters:

start_date	The date when the event begins
event	The event in question
target_date	The target date to test

Returns:: 1 if the target date is an active event day, or 0 if it's not.

void DT_event_closest ( DT_DATE * date,

DT_EVENT * event ) [static]

DT_event_closest.

Find the start of the event on or before a given target date. This function doesn't consider the event's start and end dates. Notice that this function is for internal use only.

Parameters:

date	The target date
event	The event to find

Returns:: void (the date is modified 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_next_block ( DT_DATE * event_date,

DT_EVENT * event ) [static]

DT_event_next_block.

Given a date which is the start of an event block, find the start of the next event block. Notice that this function is for internal use only.

Parameters:

event_date	The start of the event block
event	The event we are looking at

Returns:: void (event_date is modified in place)

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)

void DT_gregorian_date ( DT_DATE * date ) [static]

DT_gregorian_date.

Internally calculates the gregorian date from the rata die. This function is for internal use only.

Parameters:

date

The date structure

Returns:: void (All output is 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

Variable Documentation

int days_per_month[] [static]

Initial value:

{ 31, 28, 31, 30, 31, 30,
                                31, 31, 30, 31, 30, 31 }

The number of days in each month.

char * dow[] [static]

Initial value:

{"Sunday", "Monday", "Tuesday",
                      "Wednesday", "Thursday", "Friday", "Saturday"}

The names of all the days of the week.

char * month[] [static]

Initial value:

{"January", "February", "March", "April", "May",
                        "June", "July", "August", "September", "October",
                        "November", "December"}

The names of the months.

Generated at Fri May 12 15:50:03 2000 for Date Manipulation Library by

Defines
#define	modulo(x,y) ((x)%(y)<0?(x)%(y)+(y):(x)%(y))
#define	DT_event_is_in_range(d,e)
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)
DT_DATE*	DT_copy_date (DT_DATE *date)
void	DT_rmdate (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)
void	DT_gregorian_date (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_months (DT_DATE *date, long int months)
void	DT_add_days (DT_DATE *date, long int days)
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)
void	DT_event_calc_adj (DT_DATE date, DT_EVENT event)
int	DT_event_check_pattern (DT_DATE start_date, DT_EVENT event, DT_DATE *target_date)
void	DT_event_calc_from_seed (DT_DATE date, DT_EVENT event)
void	DT_event_closest (DT_DATE date, DT_EVENT event)
void	DT_event_next_block (DT_DATE event_date, DT_EVENT event)
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)
Variables
char*	month []
char*	dow []
int	days_per_month []