[commit: packages/time] format-widths, improve-leapseconds, master, posix-perf, tasty, wip/travis: conversion documentation (c2ff391)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/time

On branches: format-widths,improve-leapseconds,master,posix-perf,tasty,wip/travis
Link       : http://git.haskell.org/packages/time.git/commitdiff/c2ff391a8786ebeba2e6574634ddc7d70e039822

>---------------------------------------------------------------

commit c2ff391a8786ebeba2e6574634ddc7d70e039822
Author: Ashley Yakeley <ashley at semantic.org>
Date:   Sat Aug 6 13:42:34 2005 -0700

    conversion documentation
    
    darcs-hash:20050806204234-ac6dd-6b698b3ab0328723f4da2ca9f22000b8792cbee8


>---------------------------------------------------------------

c2ff391a8786ebeba2e6574634ddc7d70e039822
 Data/Time/Calendar/Gregorian.hs  | 4 ++++
 Data/Time/Calendar/ISOWeekDay.hs | 7 ++++++-
 Data/Time/Calendar/YearDay.hs    | 7 ++++++-
 3 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/Data/Time/Calendar/Gregorian.hs b/Data/Time/Calendar/Gregorian.hs
index 9e83440..3312b29 100644
--- a/Data/Time/Calendar/Gregorian.hs
+++ b/Data/Time/Calendar/Gregorian.hs
@@ -14,11 +14,14 @@ import Data.Time.Calendar.YearDay
 import Data.Time.Calendar.Days
 import Data.Time.Calendar.Private
 
+-- | convert to proleptic Gregorian calendar. First element of result is year, second month number (1-12), third day (1-31).
 gregorian :: Date -> (Integer,Int,Int)
 gregorian date = (year,month,day) where
 	(year,yd) = yearAndDay date
 	(month,day) = findMonthDay (monthLengths (isLeapYear year)) yd
 
+-- | convert from proleptic Gregorian calendar. First argument is year, second month number (1-12), third day (1-31).
+-- Invalid values will be clipped to the correct range, month first, then day.
 fromGregorian :: Integer -> Int -> Int -> Date
 -- formula from <http://en.wikipedia.org/wiki/Julian_Day>
 fromGregorian year month day = ModJulianDay
@@ -30,6 +33,7 @@ fromGregorian year month day = ModJulianDay
 	m = month'' + (12 * a) - 3
 	day' = fromIntegral (clip 1 (gregorianMonthLength' year month') day)
 
+-- | show in ISO 8601 format (yyyy-mm-dd)
 showGregorian :: Date -> String
 showGregorian date = (show4 y) ++ "-" ++ (show2 m) ++ "-" ++ (show2 d) where
 	(y,m,d) = gregorian date
diff --git a/Data/Time/Calendar/ISOWeekDay.hs b/Data/Time/Calendar/ISOWeekDay.hs
index 2dbd7e9..0c23495 100644
--- a/Data/Time/Calendar/ISOWeekDay.hs
+++ b/Data/Time/Calendar/ISOWeekDay.hs
@@ -3,7 +3,7 @@
 -- #hide
 module Data.Time.Calendar.ISOWeekDay
 	(
-	-- * ISO Week calendar
+	-- * ISO 8601 Week calendar
 	module Data.Time.Calendar.ISOWeekDay
 	) where
 
@@ -11,6 +11,9 @@ import Data.Time.Calendar.YearDay
 import Data.Time.Calendar.Days
 import Data.Time.Calendar.Private
 
+-- | convert to ISO 8601 Week format. First element of result is year, second week number (1-53), third day of week (1 for Monday to 7 for Sunday).
+-- Note that "Week" years are not quite the same as Gregorian years, as the first day of the year is always a Monday.
+-- The first week of a year is the first week to contain at least four days in the corresponding Gregorian year.
 isoWeekDay :: Date -> (Integer,Int,Int)
 isoWeekDay date@(ModJulianDay mjd) = (y1,fromInteger (w1 + 1),fromInteger (mod d 7) + 1) where
 	(y0,yd) = yearAndDay date
@@ -27,6 +30,7 @@ isoWeekDay date@(ModJulianDay mjd) = (y1,fromInteger (w1 + 1),fromInteger (mod d
 			else (y0,w0)
 		else (y0,w0)
 
+-- | convert from ISO 8601 Week format. First argument is year, second week number (1-53), third day of week (1 for Monday to 7 for Sunday).
 fromISOWeekDay :: Integer -> Int -> Int -> Date
 fromISOWeekDay y w d = ModJulianDay (k - (mod k 7) + (toInteger (((clip 1 (if longYear then 53 else 52) w) * 7) + (clip 1 7 d))) - 10) where
 		k = getModJulianDay (fromYearAndDay y 6)
@@ -34,6 +38,7 @@ fromISOWeekDay y w d = ModJulianDay (k - (mod k 7) + (toInteger (((clip 1 (if lo
 			(_,53,_) -> True
 			_ -> False
 
+-- | show in ISO 8601 Week format as yyyy-Www-dd (e.g. 
 showISOWeekDay :: Date -> String
 showISOWeekDay date = (show4 y) ++ "-W" ++ (show2 w) ++ "-" ++ (show d) where
 	(y,w,d) = isoWeekDay date
diff --git a/Data/Time/Calendar/YearDay.hs b/Data/Time/Calendar/YearDay.hs
index 6b8790a..68fe0da 100644
--- a/Data/Time/Calendar/YearDay.hs
+++ b/Data/Time/Calendar/YearDay.hs
@@ -10,6 +10,8 @@ module Data.Time.Calendar.YearDay
 import Data.Time.Calendar.Days
 import Data.Time.Calendar.Private
 
+-- | convert to ISO 8601 Ordinal Date format. First element of result is year (proleptic Gregoran calendar),
+-- second is the day of the year, with 1 for Jan 1, and 365 (or 366 in leap years) for Dec 31.
 yearAndDay :: Date -> (Integer,Int)
 yearAndDay (ModJulianDay mjd) = (year,yd) where
 	a = mjd + 678575
@@ -23,16 +25,19 @@ yearAndDay (ModJulianDay mjd) = (year,yd) where
 	yd = fromInteger (d - (y * 365) + 1)
 	year = quadcent * 400 + cent * 100 + quad * 4 + y + 1
 
+-- | convert from ISO 8601 Ordinal Date format.
+-- Invalid day numbers will be clipped to the correct range (1 to 365 or 366).
 fromYearAndDay :: Integer -> Int -> Date
 fromYearAndDay year day = ModJulianDay mjd where
 	y = year - 1
 	mjd = (fromIntegral (clip 1 (if isLeapYear year then 366 else 365) day)) + (div (1532) 5) + (365 * y) + (div y 4) - (div y 100) + (div y 400) - 678882
 
--- | ISO 8601 Ordinal Date
+-- | show in ISO 8601 Ordinal Date format (yyyy-ddd)
 showYearAndDay :: Date -> String
 showYearAndDay date = (show4 y) ++ "-" ++ (show3 d) where
 	(y,d) = yearAndDay date
 
+-- | Is this year a leap year according to the propleptic Gregorian calendar?
 isLeapYear :: Integer -> Bool
 isLeapYear year = (mod year 4 == 0) && ((mod year 400 == 0) || not (mod year 100 == 0))