diff --git a/doc/calendar.md b/doc/calendar.md index a2340a6..0b557e3 100644 --- a/doc/calendar.md +++ b/doc/calendar.md @@ -10,6 +10,10 @@ 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 --------------------- @@ -21,7 +25,7 @@ with calendar dates - mostly with month granularity. Module for handling months algebra to be used in period construction and matching. - (make-month y m) + (make-cal-month y m) * ```y``` - a number representing valid year * ```m``` - a number between 1 and 12 inclusive @@ -29,15 +33,27 @@ and matching. Constructs a new month value with ```y``` number as the year component and ```m``` number as the month component. - (month-valid? m) + (cal-month? m) * ```m``` - constructed month value -Checks whether given value is structurally valid month value, the year -is between 1000 and 9999 inclusive and the month is between 1 and 12 +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. - (string->month s) + (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 @@ -45,7 +61,7 @@ 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. - (month->string m) + (cal-month->string m) * ```m``` - valid month value or ```#f``` @@ -55,14 +71,21 @@ If ```#f```, returns a special empty month result ```"____-__"```. Raises an error if ```m``` is not a valid month. - (month=? m n) + (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?```. - (month=? m n) + (cal-month>=? m n) * ```m``` - first valid month value * ```n``` - second valid month value @@ -86,7 +109,7 @@ before ```n``` in the calendar or they are ```equal?```. Returns ```#t``` if both month values are valud and ```m``` comes after ```n``` in the calendar or they are ```equal?```. - (month>? m n) + (cal-month>? m n) * ```m``` - first valid month value * ```n``` - second valid month value @@ -94,7 +117,7 @@ after ```n``` in the calendar or they are ```equal?```. Returns ```#t``` if both month values are valud and ```m``` comes after ```n``` in the calendar. - (month-diff f t) + (cal-month-diff f t) * ```f``` - valid month (from) * ```t``` - valid month (to) @@ -103,7 +126,7 @@ 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. - (month-add m [n]) + (cal-month-add m [n]) * ```m``` - valid month * ```n``` - an integer, defaults to 1 diff --git a/src/cal-month.scm b/src/cal-month.scm index 915dd62..fbccaa2 100644 --- a/src/cal-month.scm +++ b/src/cal-month.scm @@ -37,6 +37,7 @@ string->cal-month cal-month->string + iso-date->cal-month cal-month=? cal-month? cal-month-diff cal-month-add - iso-date->cal-month + cal-month-tests! ) @@ -113,6 +114,24 @@ (error 'string->month "Invalid month" M)) "____-__")) + ;; Converts ISO date YYYY-MM-DD to single month + (define (iso-date->cal-month str) + (let ((lst (string-split str "-"))) + (if (or (not lst) + (null? lst) + (null? (cdr lst)) + (null? (cddr lst)) + (not (null? (cdddr lst)))) + #f + (let ((year (string->number (car lst))) + (mon (string->number (cadr lst)))) + (if (and year mon) + (let ((M (make-cal-month year mon))) + (if (cal-month? M) + M + #f)) + #f))))) + ;; Returns true if both arguments are a valid month and are equal (define (cal-month=? m n) (and (cal-month? m) @@ -163,24 +182,6 @@ (make-cal-month (quotient mi 12) (+ (remainder mi 12) 1)))) - ;; Converts ISO date YYYY-MM-DD to single month - (define (iso-date->cal-month str) - (let ((lst (string-split str "-"))) - (if (or (not lst) - (null? lst) - (null? (cdr lst)) - (null? (cddr lst)) - (not (null? (cdddr lst)))) - #f - (let ((year (string->number (car lst))) - (mon (string->number (cadr lst)))) - (if (and year mon) - (let ((M (make-cal-month year mon))) - (if (cal-month? M) - M - #f)) - #f))))) - ;; Performs self-tests of the month module. (define (cal-month-tests!) (run-tests