Calendar

Calendar — functions for working with dates

Synopsis

#include <libgretl.h>

#define             FOUR_DIGIT_YEAR                     (y)
long                epoch_day_from_ymd                  (int y,
                                                         int m,
                                                         int d);
char *              ymd_extended_from_epoch_day         (long ed Param1,
                                                         int *err);
double              ymd_basic_from_epoch_day            (long ed Param1,
                                                         int *err);
int                 iso_basic_to_extended               (const double *b,
                                                         double *y,
                                                         double *m,
                                                         double *d,
                                                         int n);
long                get_epoch_day                       (const char *date);
int                 weekday_from_date                   (const char *date);
int                 weekday_from_epoch_day              (long ed Param1);
int                 day_starts_month                    (int d,
                                                         int m,
                                                         int y,
                                                         int wkdays,
                                                         int *pad);
int                 day_ends_month                      (int d,
                                                         int m,
                                                         int y,
                                                         int wkdays);
int                 get_days_in_month                   (int mon,
                                                         int yr,
                                                         int wkdays);
int                 days_in_month_before                (int yr,
                                                         int mon,
                                                         int day,
                                                         int wkdays);
int                 days_in_month_after                 (int yr,
                                                         int mon,
                                                         int day,
                                                         int wkdays);
int                 calendar_obs_number                 (const char *date,
                                                         const DATASET *dset);
int                 calendar_date_string                (char *str,
                                                         int t,
                                                         const DATASET *dset);
int                 MS_excel_date_string                (char *date,
                                                         int mst,
                                                         int pd,
                                                         int d1904);
double              get_dec_date                        (const char *date);
double              day_of_week                         (int yr,
                                                         int mo,
                                                         int day,
                                                         int *err);
int                 n_hidden_missing_obs                (const DATASET *dset);
int                 guess_daily_pd                      (const DATASET *dset);

Description

Here we have various functions dealing with calendar dates; for the most part these are designed for handling daily time-series data. Most of the basic code is derived from the unix "cal" program which is released under the BSD license (reproduced in the libgretl source file calendar.c).

Details

FOUR_DIGIT_YEAR()

#define FOUR_DIGIT_YEAR(y) ((y < 50)? y + 2000 : y + 1900)

y :

year given to only two digits.

Returns :

a guess at the 4-digit year intended when two digits were provided. But really, who knows?

epoch_day_from_ymd ()

long                epoch_day_from_ymd                  (int y,
                                                         int m,
                                                         int d);

y :

year (1 <= y <= 9999).

m :

month (1 <= m <= 12).

d :

day of month (1 <= d <= 31).

Returns :

the epoch day number, which equals 1 for the first of January in the year 1 AD, or -1 on error.

ymd_extended_from_epoch_day ()

char *              ymd_extended_from_epoch_day         (long ed Param1,
                                                         int *err);

err :

location to receive error code.

Returns :

a string on the pattern YYYY-MM-DD (ISO 8601 extended date format) given the epoch day number, which equals 1 for the first of January in the year 1 AD, or NULL on error.

ymd_basic_from_epoch_day ()

double              ymd_basic_from_epoch_day            (long ed Param1,
                                                         int *err);

err :

location to receive error code.

Returns :

an 8-digit number on the pattern YYYYMMDD (ISO 8601 basic date format) given the epoch day number, which equals 1 for the first of January in the year 1 AD, or NADBL on error.

iso_basic_to_extended ()

int                 iso_basic_to_extended               (const double *b,
                                                         double *y,
                                                         double *m,
                                                         double *d,
                                                         int n);

Given the array b of ISO 8601 "basic" daily dates (YYYYMMDD as doubles), fill out the arrays y, m and d with year, month and day.

b :

source array of YYYYMMDD values.

y :

array to hold year values.

m :

array to hold month values.

d :

array to hold day-of-week values.

n :

length of all the above arrays.

Returns :

0.

get_epoch_day ()

long                get_epoch_day                       (const char *date);

date :

string representation of calendar date, in form YY[YY]-MM-DD.

Returns :

the epoch day number, or -1 on failure.

weekday_from_date ()

int                 weekday_from_date                   (const char *date);

date :

calendar representation of date, [YY]YY/MM/DD

Returns :

day of week as integer, Sunday = 0.

weekday_from_epoch_day ()

int                 weekday_from_epoch_day              (long ed Param1);

Returns :

the weekday (Sunday = 0) corrsponding to ed.

day_starts_month ()

int                 day_starts_month                    (int d,
                                                         int m,
                                                         int y,
                                                         int wkdays,
                                                         int *pad);

d :

day of month, 1-based

m :

month number, 1-based

y :

4-digit year

wkdays :

number of days in week (7, 6 or 5)

pad :

location to receive 1 if the first day of the month can reasonably be padded by a missing value (Jan 1), or NULL.

Returns :

1 if the day is the "first day of the month", allowance made for the possibility of a 5- or 6-day week, else 0.

day_ends_month ()

int                 day_ends_month                      (int d,
                                                         int m,
                                                         int y,
                                                         int wkdays);

d :

day of month, 1-based

m :

month number, 1-based

y :

4-digit year

wkdays :

number of days in week (7, 6 or 5)

Returns :

1 if the day is the "last day of the month", allowance made for the possibility of a 5- or 6-day week, else 0.

get_days_in_month ()

int                 get_days_in_month                   (int mon,
                                                         int yr,
                                                         int wkdays);

mon :

month number, 1-based

yr :

4-digit year

wkdays :

number of days in week (7, 6 or 5)

Returns :

the number of days in the month, allowance made for the possibility of a 5- or 6-day week.

days_in_month_before ()

int                 days_in_month_before                (int yr,
                                                         int mon,
                                                         int day,
                                                         int wkdays);

yr :

4-digit year

mon :

month number, 1-based

day :

day in month.

wkdays :

number of days in week (7, 6 or 5)

Returns :

the number of relevant days in the month prior to the supplied date, allowing for the possibility of a 5- or 6-day week.

days_in_month_after ()

int                 days_in_month_after                 (int yr,
                                                         int mon,
                                                         int day,
                                                         int wkdays);

yr :

4-digit year

mon :

month number, 1-based

day :

day in month.

wkdays :

number of days in week (7, 6 or 5)

Returns :

the number of relevant days in the month after the supplied date, allowing for the possibility of a 5- or 6-day week.

calendar_obs_number ()

int                 calendar_obs_number                 (const char *date,
                                                         const DATASET *dset);

date :

string representation of calendar date, in form YY[YY]/MM/DD.

dset :

pointer to dataset information.

Returns :

The zero-based observation number for the given date within the current data set.

calendar_date_string ()

int                 calendar_date_string                (char *str,
                                                         int t,
                                                         const DATASET *dset);

Writes to str the calendar representation of the date of observation t, in the form YY[YY]/MM/DD.

str :

string to be filled out.

t :

zero-based index of observation.

dset :

pointer to dataset information.

Returns :

0 on success, non-zero on error.

MS_excel_date_string ()

int                 MS_excel_date_string                (char *date,
                                                         int mst,
                                                         int pd,
                                                         int d1904);

Writes to date the calendar representation of the date of observation mst, in the form YYYY-MM-DD if pd is 0, 5, 6, 7 or 52 (unknown, daily, or weekly frequency), otherwise in the appropriate format for annual, quarterly or monthly data.

date :

date string to be filled out.

mst :

MS Excel-type date code: days since base.

pd :

periodicity of data (or 0 if unknown).

d1904 :

set to 1 if the base is 1904/01/01; otherwise the base is assumed to be 1899/12/31.

Returns :

0.

get_dec_date ()

double              get_dec_date                        (const char *date);

date :

calendar representation of date: YYYY-MM-DD.

Returns :

representation of date as year plus fraction of year.

day_of_week ()

double              day_of_week                         (int yr,
                                                         int mo,
                                                         int day,
                                                         int *err);

yr :

year, preferably 4-digit.

mo :

month, 1 to 12.

day :

day in month, 1 to 31.

err :

location to receive error code.

Returns :

the day of the week for the supplied date (Sunday = 0, Monday = 1, ...) or NADBL on failure (the date is invalid).

n_hidden_missing_obs ()

int                 n_hidden_missing_obs                (const DATASET *dset);

For daily data with user-supplied data strings, determine the number of "hidden" missing observations, i.e. the difference between the actual number of observations and the number that should be there, according to the calendar. Allowance is made for 5- or 6-day data, via the data frequency given in dset.

dset :

dataset information.

Returns :

number of hidden observations.

guess_daily_pd ()

int                 guess_daily_pd                      (const DATASET *dset);

Based on user-supplied daily date strings recorded in dset, try to guess whether the number of observations per week is 5, 6 or 7 (given that some observations may be missing).

dset :

dataset information.

Returns :

best quess at data frequency.