Calendar

Calendar — functions for working with dates

Functions

Object Hierarchy


Includes

#include <libgretl.h>

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

Functions

FOUR_DIGIT_YEAR()

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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.

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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

Parameters

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 .

Parameters

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

Parameters

dset

dataset information.

 

Returns

best quess at data frequency.


easterdate ()

double
easterdate (int year);

Algorithm taken from Wikipedia page "https://en.wikipedia.org/wiki/Computus" under the heading "Anonymous Gregorian algorithm".

Parameters

year

year for which we want Easter date (Gregorian).

 

Returns

the date of Easter in the Gregorian calendar as (month + day/100). Note that April the 10th, is, under this convention, 4.1; hence, 4.2 is April the 20th, not April the 2nd (which would be 4.02).

Types and Values