New cal-month documentation.

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
+Checks whether given value is valid cal-month, the year is between
-is between 1000 and 9999 inclusive and the month is between 1 and 12
+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
@@ -70,7 +93,7 @@ Returns ```#t``` if both month values are valid and ```equal?```.
 Returns ```#t``` if both month values are valud and ```m``` comes
 before ```n``` in the calendar.
 
-    (month<=? m n)
+    (cal-month<=? m n)
 
 * ```m``` - first valid month value
 * ```n``` - second valid month value
@@ -78,7 +101,7 @@ before ```n``` in the calendar.
 Returns ```#t``` if both month values are valud and ```m``` comes
 before ```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
@@ -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

src/cal-month.scm

@@ -37,6 +37,7 @@
   
   string->cal-month
   cal-month->string
+  iso-date->cal-month
   
   cal-month=?
   cal-month<?
@@ -45,7 +46,7 @@
   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