Calendar

Calendar — functions for working with dates

Functions

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.

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

guint32
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 AD 1 on the proleptic Gregorian calendar, or 0 on error.


epoch_day_from_julian_ymd ()

guint32
epoch_day_from_julian_ymd (int y,
                           int m,
                           int d);

The y , m and d arguments are assumed to refer to a date on the Julian calendar. The conversion algorithm is taken from https://en.wikipedia.org/wiki/Julian_day, where it appears to be credited to the Department of Computer Science at UT, Austin.

Parameters

y

year (y >= 1).

 

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 AD 1 on the proleptic Gregorian calendar, or 0 on error.


ymd_extended_from_epoch_day ()

char *
ymd_extended_from_epoch_day (guint32 ed,
                             int julian,
                             int *err);

Parameters

ed

epoch day (ed >= 1).

 

julian

non-zero to use Julian calendar, otherwise Gregorian.

 

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 (guint32 ed,
                          int julian,
                          int *err);

Parameters

ed

epoch day (ed >= 1).

 

julian

non-zero to use Julian calendar, otherwise Gregorian.

 

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.


ymd_bits_from_epoch_day ()

int
ymd_bits_from_epoch_day (guint32 ed,
                         int *y,
                         int *m,
                         int *d);

Parameters

ed

epoch day (ed >= 1).

 

y

location to receive year.

 

m

location to receive month.

 

Returns

0 on success, non-zero on error.


julian_ymd_bits_from_epoch_day ()

int
julian_ymd_bits_from_epoch_day (guint32 ed,
                                int *y,
                                int *m,
                                int *d);

Follows the algorithm of E.G. Richards (2013), "Calendars," In S.E. Urban & P.K. Seidelmann, eds. Explanatory Supplement to the Astronomical Almanac, 3rd ed. (pp. 585-624), Mill Valley, CA: University Science Books (as set out on https://en.wikipedia.org/wiki/Julian_day).

There are other algorithms for this purpose on the internet but they are mostly wrong (at least, not right for all dates); many of them fail the round-trip test (date -> epoch day -> date) for some dates.

Parameters

ed

epoch day (ed >= 1).

 

y

location to receive year.

 

m

location to receive month.

 

Returns

0 on success, non-zero 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 ()

guint32
get_epoch_day (const char *datestr);

Parameters

datestr

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

 

Returns

the epoch day number, or -1 on failure.


epoch_day_from_t ()

guint32
epoch_day_from_t (int t,
                  const DATASET *dset);

Parameters

t

0-based observation index.

 

dset

pointer to dataset.

 

Returns

the epoch day based on calendrical information in dset . In case of error 0 is returned.


weekday_from_date ()

int
weekday_from_date (const char *datestr);

Parameters

datestr

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 (guint32 ed);

Parameters

ed

epoch day (ed >= 1).

 

Returns

the weekday (Sunday = 0) corrsponding to ed , or -1 on error.


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 m,
                   int y,
                   int wkdays,
                   int julian);

Parameters

m

month number, 1-based

 

y

4-digit year

 

wkdays

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

 

julian

non-zero for Julian calendar, otherwise Gregorian.

 

Returns

the number of (relevant) 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 y,
                      int m,
                      int d,
                      int wkdays);

Parameters

y

4-digit year

 

m

month number, 1-based

 

d

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 y,
                     int m,
                     int d,
                     int wkdays);

Parameters

y

4-digit year

 

m

month number, 1-based

 

d

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.


date_to_daily_index ()

int
date_to_daily_index (const char *datestr,
                     int wkdays);

Parameters

datestr

date in format YYYY-MM-DD.

 

wkdays

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

 

Returns

the zero-based index of the specified day within the specified month and year. In the case of 5- or 6-day data index zero does not necessarily correspond to the first day of the month but rather to the first relevant day.


daily_index_to_date ()

int
daily_index_to_date (char *targ,
                     int y,
                     int m,
                     int idx,
                     int wkdays);

Fills out targ with the calendar data implied by the specification of y , m , seq and wkdays , provided this specification corresponds to an actual calendar date.

Parameters

targ

location to receive the date (YYYY-MM-DD).

 

y

year.

 

m

month.

 

idx

zero-based index of day within month.

 

wkdays

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

 

Returns

0 on successful completion, non-zero if there is no such calendar date.


calendar_obs_number ()

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

Parameters

datestr

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 *targ,
                      int t,
                      const DATASET *dset);

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

Parameters

targ

string to be filled out.

 

t

zero-based index of observation.

 

dset

pointer to dataset.

 

Returns

0 on success, non-zero on error.


MS_excel_date_string ()

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

Writes to targ 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 according to pd .

Parameters

targ

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

Parameters

datestr

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 y,
             int m,
             int d,
             int julian,
             int *err);

Parameters

y

year.

 

m

month, 1 to 12.

 

d

day in month, 1 to 31.

 

julian

non-zero to use Julian calendar, otherwise Gregorian.

 

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


day_span ()

int
day_span (guint32 ed1,
          guint32 ed2,
          int wkdays,
          int *err);

Types and Values