[commit: packages/time] master, wip/travis: more haddock comments, timezone conversion functions (3ad0923)

[git at git.haskell.org]

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

On branches: master,wip/travis
Link       : http://git.haskell.org/packages/time.git/commitdiff/3ad0923af5407c1bb45d6ca6ce8ba8d6614598a8

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

commit 3ad0923af5407c1bb45d6ca6ce8ba8d6614598a8
Author: Ashley Yakeley <ashley at semantic.org>
Date:   Wed Mar 2 02:53:53 2005 -0800

    more haddock comments, timezone conversion functions
    
    darcs-hash:20050302105353-ac6dd-7e0a4765b0845ddc199bfb01fd74cb35c77fbe47


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

3ad0923af5407c1bb45d6ca6ce8ba8d6614598a8
 System/Time/Calendar.hs | 22 +++++++++++++++++-----
 System/Time/Clock.hs    | 11 +++++++++--
 2 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/System/Time/Calendar.hs b/System/Time/Calendar.hs
index 725398c..fa55f5a 100644
--- a/System/Time/Calendar.hs
+++ b/System/Time/Calendar.hs
@@ -1,7 +1,7 @@
 module System.Time.Calendar
 (
 	-- time zones
-	TimeZone,
+	TimeZone,timezoneToMinutes,minutesToTimezone,
 
 	-- getting the locale time zone
 
@@ -19,9 +19,14 @@ import System.Time.Clock
 import Data.Char
 
 -- | count of minutes
-newtype TimeZone = MkTimeZone Int deriving (Eq,Ord)
+newtype TimeZone = MkTimeZone {
+	timezoneToMinutes :: Int
+} deriving (Eq,Ord)
 
+minutesToTimezone :: Int -> TimeZone
+minutesToTimezone = MkTimeZone
 
+-- | time of day as represented in hour, minute and second (with picoseconds), typically used to express local time of day
 data TimeOfDay = TimeOfDay {
 	todHour    :: Int,
 	todMin     :: Int,
@@ -47,6 +52,7 @@ showpicodecimal i = '.':(showFraction 100000000000 i)
 instance Show TimeOfDay where
 	show (TimeOfDay h m s ps) = (show2 h) ++ ":" ++ (show2 m) ++ ":" ++ (show2 s) ++ (showpicodecimal ps)
 
+-- | a year, month and day aggregate, suitable for the Gregorian calendar
 data CalendarDay = CalendarDay {
 	cdYear    :: Integer,
 	cdMonth   :: Int,
@@ -56,6 +62,7 @@ data CalendarDay = CalendarDay {
 instance Show CalendarDay where
 	show (CalendarDay y m d) = (if y > 0 then show y else (show (1 - y) ++ "BCE")) ++ "-" ++ (show2 m) ++ "-" ++ (show2 d)
 
+-- | straightforward date and time aggregate
 data CalendarTime = CalendarTime {
 	ctDay    :: CalendarDay,
 	ctTime   :: TimeOfDay
@@ -83,12 +90,17 @@ findMonthDay :: [Int] -> Int -> (Int,Int)
 findMonthDay (n:ns) yd | yd > n = (\(m,d) -> (m + 1,d)) (findMonthDay ns (yd - n))
 findMonthDay _ yd = (1,yd)
 
+
+months :: Bool -> [Int]
+months isleap = 
+	[31,if isleap then 29 else 28,31,30,31,30,31,31,30,31,30,31]
+	--J        F                   M  A  M  J  J  A  S  O  N  D
+
+-- | name the given day according to the Gregorian calendar
 dayToCalendar :: ModJulianDay -> CalendarDay
 dayToCalendar mjd = CalendarDay year month day where
 	(year,yd,isleap) = dayToYearDay mjd
-	(month,day) = findMonthDay
-		[31,if isleap then 29 else 28,31,30,31,30,31,31,30,31,30,31] yd
-		--J       F                   M  A  M  J  J  A  S  O  N  D
+	(month,day) = findMonthDay (months isleap) yd
 
 
 utcToCalendar :: TimeZone -> UTCTime -> CalendarTime
diff --git a/System/Time/Clock.hs b/System/Time/Clock.hs
index 9f59a8c..5a4825f 100644
--- a/System/Time/Clock.hs
+++ b/System/Time/Clock.hs
@@ -19,15 +19,17 @@ module System.Time.Clock
 import Foreign
 import Foreign.C
 
--- | standard Julian count of Earth days
+-- | standard Modified Julian Day, a count of Earth days
 type ModJulianDay = Integer
 
--- | standard Julian dates for UT1, 1 = 1 day
+-- | standard Modified Julian Date to represent UT1, 1 = 1 day
 type ModJulianDate = Rational
 
+-- | the number of picoseconds in a second
 secondPicoseconds :: (Num a) => a
 secondPicoseconds = 1000000000000
 
+-- | a length of time
 newtype DiffTime = MkDiffTime Integer deriving (Eq,Ord,Num,Enum,Real,Integral)
 
 instance Show DiffTime where
@@ -39,11 +41,15 @@ timeToSISeconds t = fromRational ((toRational t) / (toRational secondPicoseconds
 siSecondsToTime :: (Real a) => a -> DiffTime
 siSecondsToTime t = fromInteger (round ((toRational t) * secondPicoseconds))
 
+-- | time in UTC
 data UTCTime = UTCTime {
+	-- | the day
 	utctDay :: ModJulianDay,
+	-- | the time from midnight, 0 <= t < 61s (because of leap-seconds)
 	utctDayTime :: DiffTime
 }
 
+-- | a length of time for UTC, ignoring leap-seconds
 newtype UTCDiffTime = MkUTCDiffTime Integer deriving (Eq,Ord,Num,Enum,Real,Integral)
 
 instance Show UTCDiffTime where
@@ -100,6 +106,7 @@ instance Storable CTimeval where
 
 foreign import ccall unsafe "sys/time.h gettimeofday" gettimeofday :: Ptr CTimeval -> Ptr () -> IO CInt
 
+-- | get the current time
 getCurrentTime :: IO UTCTime
 getCurrentTime = with (MkCTimeval 0 0) (\ptval -> do
 	result <- gettimeofday ptval nullPtr