hackerbase/doc/calendar.md

Calendar Support Modules

This file contains the documentation of calendar handling routines.

Rationale

As all the processes within the organization have monthly granularity, it is an intentional design decision to have unified approach for working with months, month periods and relations between them.

For certain operations, daily granularity is required, however deterministic conversion from exact date (day) to month is implemented with respect to different requirements of period starts and ends.

Modules Documentation

All the functions documented below should be used for all manipulation with calendar dates - mostly with month granularity.

Month

Module for handling months algebra to be used in period construction and matching.

(make-cal-month y m)

• y - a number representing valid year
• m - a number between 1 and 12 inclusive

Constructs a new month value with y number as the year component and m number as the month component.

(cal-month? m)

• m - constructed month value

Checks whether given value is valid cal-month, the year is between 1000 and 9999 inclusive and the month is between 1 and 12 inclusive. Returns boolean value.

(cal-month-year m)

• m - a valid cal-month? value

Returns the year component from given month value.

(cal-month-month m)

• m - a valid cal-month? value

Returns the month component from given month value.

(string->cal-month s)

• s - a string in "YYYY-MM" format

Parses given string s as month and constructs a month value from the YYYY and MM components parsed. The resulting month value is returned only if it is valid. Otherwise #f is returned.

(cal-month->string m)

• m - valid month value or #f

Converts given month value to a string in "YYYY-MM" format.

If #f, returns a special empty month result "____-__".

Raises an error if m is not a valid month.

(iso-date->cal-month s)

• s - a string in "YYYY-MM-DD" format

Parses given ISO date and returns a cal-monh from the year and month given.

(cal-month=? m n)

• m - first valid month value
• n - second valid month value

Returns #t if both month values are valid and equal?.

(cal-month<? m n)

• m - first valid month value
• n - second valid month value

Returns #t if both month values are valud and m comes before n in the calendar.

(cal-month<=? m n)

• m - first valid month value
• n - second valid month value

Returns #t if both month values are valud and m comes before n in the calendar or they are equal?.

(cal-month>=? m n)

• m - first valid month value
• n - second valid month value

Returns #t if both month values are valud and m comes after n in the calendar or they are equal?.

(cal-month>? m n)

• m - first valid month value
• n - second valid month value

Returns #t if both month values are valud and m comes after n in the calendar.

(cal-month-diff f t)

• f - valid month (from)
• t - valid month (to)

Returns the difference in months from month f to month t. If both months are the same, the result is zero. If t is before f, the result is negative.

(cal-month-add m [n])

• m - valid month
• n - an integer, defaults to 1

Returns a new valid month that comes n months after m. If n is negative, it correctly subtracts the months.

Period

This module implements simple calendar period handling with month granularity. The period contains fields since which is the first month of the period and before which is the first month just after the period.

(*current-month* [month])

• month - valid month structure as specified in the month module

Configuration parameter specifying the current month. Defaults to the current month derived from the current system time.

(period-since p)

• p - valid period

Returns the since part of given period.

(period-before p)

Returns the since part of given period.

Returns the before part of given period.

(period-markers->periods l)

• l - list of sorted (list tag month)

Converts a list of period markers l into actual periods where each period is represented by (list start-month end-month).

The end-month may be #f in which case it is an open-ended period which has not ended yet.

(periods-duration l)

• l - list of periods

Returns the total duration in months of the periods given in the list l. Each period is represented as (list start-month end-month).

(month-in-periods p [m (*current-month*)])

• p - a periods
• m - a valid month - defaults to (*current-month*)

Returns #t if given month m lies within the period p.

(month-in-periods? ps [m (*current-month*)])

• ps - a list of periods
• m - a valid month - defaults to (*current-month*)

Returns #t if given month m lies within any of the periods given in the list of periods ps.

(periods->string ps)

• ps - a list of periods

Returns a string representing all the periods given in the list of periods ps. The periods are represented as ````"YYYY-MM..YYYY-MM"and an open end is substituded with"____-__"```.

(periods-match ps [m (*current-month*)])

• ps - a list of periods

Returns the period from the list of periods ps the given month m falls into. If no period matches, returns #f.

(make-period-lookup-table source)

• source a list of specifications

Creates a lookup table containing periods where each specification starts with a month and the rest of the list is value to be stored in the lookup table. The resulting lookup table contains periods with the last period being open-ended without ending month.

(lookup-by-period table)

• table - period lookup table

Looks up the value(s) as specified by the table created by make-period-lookup-table for current month from parameter (*current-month*).