-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Lenses for Data.Time.* types
--   
--   The <tt>lens-datetime</tt> library provides a unified lens based
--   accessors to the various types in <tt>Data.Time.Clock</tt>,
--   <tt>Data.Time.Calendar</tt> and <tt>Data.Time.LocalTime</tt>. This
--   library only tries to make some of the common use-cases convenient, it
--   doesn't aim for completeness. If you want completeness and/or
--   efficiency try the <tt>thyme</tt> package instead
--   (<a>http://hackage.haskell.org/package/thyme</a>).
--   
--   Demonstration of basic uses.
--   
--   <pre>
--   import Control.Lens
--   import Data.Time
--   import Data.Time.Lens
--   
--   aDay :: Day
--   aDay = fromGregorian 2013 08 22
--   
--   aLocal :: LocalTime
--   aLocal = LocalTime aDay (TimeOfDay 13 45 28)
--   
--   aUTC :: UTCTime
--   aUTC = UTCTime aDay 7458.9
--   </pre>
--   
--   You can then do the following:
--   
--   <pre>
--   &gt; aLocal ^. years
--   2013
--   &gt; aUTC ^. months
--   8
--   &gt; aLocal &amp; time .~ midnight
--   2013-08-22 00:00:00
--   &gt; aUTC &amp; days .~ 1 &amp; months .~ 1
--   2013-01-01 02:04:18.9 UTC
--   </pre>
--   
--   You can manipulate the date-time values with proper roll-over behavior
--   via the <tt>FlexibleDateTime</tt> mechanism:
--   
--   <pre>
--   &gt; aLocal &amp; flexDT.months +~ 12
--   2014-08-22 13:45:28
--   &gt; aUTC &amp; flexDT.days +~ 100
--   2013-11-30 02:04:18.9 UTC
--   &gt; aLocal &amp; flexDT.minutes +~ 120
--   2013-08-22 15:45:28
--   &gt; aLocal &amp; flexDT %~ ((days +~ 7) . (hours +~ 2))
--   2013-08-22 13:45:28
--   </pre>
@package lens-datetime
@version 0.3


-- | <i>Usage:</i>
--   
--   Basic interface consists of the following six lenses: <a>years</a>,
--   <a>months</a>, <a>days</a>, <a>hours</a>, <a>minutes</a> and
--   <a>seconds</a> with which you can access the corresponding "fields" of
--   <a>LocalTime</a> and <a>UTCTime</a> in a unified way. Also, use
--   <a>date</a> and <a>time</a> if you want to access the <a>Day</a> and
--   <a>TimeOfDay</a> parts as a whole.
--   
--   Let's assume the following definitions:
--   
--   <pre>
--   import Control.Lens
--   import Data.Time
--   import Data.Time.Lens
--   
--   aDay :: Day
--   aDay = fromGregorian 2013 08 22
--   
--   aLocal :: LocalTime
--   aLocal = LocalTime aDay (TimeOfDay 13 45 28)
--   
--   aUTC :: UTCTime
--   aUTC = UTCTime aDay 7458.9
--   </pre>
--   
--   Then you can use the above lenses as follows:
--   
--   <pre>
--   &gt;&gt;&gt; aLocal ^. years
--   2013
--   
--   &gt;&gt;&gt; aUTC ^. months
--   8
--   
--   &gt;&gt;&gt; aDay ^. days
--   22
--   
--   &gt;&gt;&gt; aLocal &amp; time .~ midnight
--   2013-08-22 00:00:00
--   
--   &gt;&gt;&gt; aUTC &amp; days .~ 1 &amp; months .~ 1
--   2013-01-01 02:04:18.9 UTC
--   
--   &gt;&gt;&gt; aLocal &amp; hours +~ 1            -- But see the note below!
--   2013-08-22 14:45:28
--   </pre>
--   
--   <i>A note about invalid values and lens laws.</i>
--   
--   For <a>LocalTime</a> and <a>UTCTime</a> these lenses provide the most
--   straightforward implementation: via 'toGregorian'/'fromGregorian' in
--   the case of <a>years</a>, <a>months</a> and <a>days</a>; and directly
--   to the fields of <a>TimeOfDay</a> in the case of <a>hours</a>,
--   <a>minutes</a> and <a>seconds</a>.
--   
--   Which means, on one hand, that the date "parts" will be clipped to
--   valid values:
--   
--   <pre>
--   &gt;&gt;&gt; aLocal &amp; months +~ 12
--   2013-12-22 13:45:28        -- instead of: 2014-08-22 13:45:28
--   
--   &gt;&gt;&gt; aUTC &amp; days +~ 100
--   2013-08-31 02:04:18.9 UTC  -- instead of: 2013-11-30 02:04:18.9 UTC
--   </pre>
--   
--   And on the other hand, that the time "parts" will not roll over and
--   produce invalid values:
--   
--   <pre>
--   &gt;&gt;&gt; aLocal &amp; minutes +~ 120
--   2013-08-22 13:165:28       -- instead of: 2013-08-22 15:45:28
--   </pre>
--   
--   Also, this means that the date lenses are not proper lenses: they only
--   satisfy the lens laws when used with valid values for the given
--   fields.
--   
--   Basically, avoid setting/modifying the date-time values directly via
--   these lenses if you cannot be sure that the result is a valid value.
--   Instead use the <a>FlexibleDateTime</a> mechanism and the
--   <a>flexDT</a> isomorphism, which correctly rolls over:
--   
--   <pre>
--   &gt;&gt;&gt; aLocal &amp; flexDT.months +~ 12
--   2014-08-22 13:45:28
--   
--   &gt;&gt;&gt; aUTC &amp; flexDT.days +~ 100
--   2013-11-30 02:04:18.9 UTC
--   
--   &gt;&gt;&gt; aLocal &amp; flexDT.minutes +~ 120
--   2013-08-22 15:45:28
--   </pre>
--   
--   If you need to set multiple fields try to make only one round-trip via
--   flexDT:
--   
--   <pre>
--   &gt;&gt;&gt; aLocal &amp; flexDT %~ ((days +~ 7) . (hours +~ 2))
--   2013-08-22 13:45:28
--   </pre>
--   
--   Note that even with <a>flexDT</a> we completely ignore all the issues
--   around daylight saving time and leap seconds. If your code has to be
--   correct wrt. DST, do all the computations in <a>UTCTime</a> and
--   convert to local time only for output. If you need to be correct wrt.
--   leap seconds, then... Well, then I don't know. :)
--   
--   And while this doesn't strictly belong to this package, here's a
--   complete example of working with daylight saving time:
--   
--   <pre>
--   dstExample :: IO ()
--   dstExample = do
--     let baseT = UTCTime (fromGregorian 2013 10 26) 0
--   
--         printInLocal :: UTCTime -&gt; IO ()
--         printInLocal t = do
--           tz &lt;- getTimeZone t
--           print (tz, t ^. utcInTZ tz)
--   
--     printInLocal baseT
--     printInLocal $ baseT &amp; flexDT %~ ((days +~ 1) . (hours +~ 0) . (minutes +~ 5))
--     printInLocal $ baseT &amp; flexDT %~ ((days +~ 1) . (hours +~ 1) . (minutes +~ 5))
--     printInLocal $ baseT &amp; flexDT %~ ((days +~ 1) . (hours +~ 2) . (minutes +~ 5))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; dstExample
--   (CEST,2013-10-26 02:00:00)
--   (CEST,2013-10-27 02:05:00)
--   (CET,2013-10-27 02:05:00)
--   (CET,2013-10-27 03:05:00)
--   </pre>
module Data.Time.Lens

-- | Type class that defines access to the "date" part of a type.
--   
--   You can implement either of the two methods.
class Dateable a
date :: Dateable a => Lens' a Day
_dateFlex :: Dateable a => Lens' a FlexDate

-- | Lens into the year value of a <a>Dateable</a>.
--   
--   Warning: this is not a proper lens for <a>LocalTime</a> and
--   <a>UTCTime</a>: it only obeys the lens laws if used with valid values.
--   When the year value in a date is modified the month and day values
--   might also change. This happens when the original date was a February
--   29th and we change to a non-leap year.
years :: Dateable d => Lens' d Integer

-- | Lens into the month value of a <a>Dateable</a>.
--   
--   Warning: this is not a proper lens for <a>LocalTime</a> and
--   <a>UTCTime</a>: it only obeys the lens laws if used with valid values.
--   The updated month value will be clipped to a valid month value. Also
--   note that the day value might also be modified (clipped to a valid day
--   in that month).
months :: Dateable d => Lens' d Int

-- | Lens into the day value of a <a>Dateable</a>.
--   
--   Warning: this is not a proper lens for <a>LocalTime</a> and
--   <a>UTCTime</a>: it only obeys the lens laws if used with valid values.
--   The updated day value will be clipped to a valid day value in the
--   given year-month.
days :: Dateable d => Lens' d Int

-- | Type class that defines access to the "time" part of a type.
--   
--   You only need to define one of the two methods, whichever is more
--   natural.
class Timeable a
time :: Timeable a => Lens' a TimeOfDay
timeAsDiff :: Timeable a => Lens' a DiffTime

-- | Lens into the hour value of a <a>Timeable</a>.
--   
--   Warning: this is not a proper lens for <a>UTCTime</a>: it only obeys
--   the lens laws if used with valid values.
hours :: Timeable t => Lens' t Int

-- | Lens into the minute value of a <a>Timeable</a>.
--   
--   Warning: this is not a proper lens for <a>UTCTime</a>: it only obeys
--   the lens laws if used with valid values.
minutes :: Timeable t => Lens' t Int

-- | Lens into the second value of a <a>Timeable</a>.
--   
--   Warning: this is not a proper lens for <a>UTCTime</a>: it only obeys
--   the lens laws if used with valid values.
seconds :: Timeable t => Lens' t Pico
data FlexDateTime
FlexDateTime :: FlexDate -> TimeOfDay -> FlexDateTime
[flexDate] :: FlexDateTime -> FlexDate
[flexTOD] :: FlexDateTime -> TimeOfDay
data FlexDate
FlexDate :: Integer -> Int -> Int -> FlexDate
[flexYear] :: FlexDate -> Integer
[flexMonth] :: FlexDate -> Int
[flexDay] :: FlexDate -> Int
newtype FlexTime
FlexTime :: TimeOfDay -> FlexTime

-- | Type class to provide correct roll-over behavior for date-time lenses.
--   
--   See examples in the general overview part.
class FlexibleDateTime a
flexDT :: FlexibleDateTime a => Lens' a FlexDateTime

-- | Type class to provide correct roll-over behavior for date lenses.
--   
--   Used exactly as <a>flexDT</a>, but for values that have only "date"
--   and no "time" part.
class FlexibleDate a
flexD :: FlexibleDate a => Lens' a FlexDate

-- | Type class to provide correct roll-over behavior for time lenses.
--   
--   Used exactly as <a>flexDT</a>, but for values that have only "time"
--   and no "date" part.
--   
--   If the time rolls-over more than 24 hours the day carry is discarded.
--   Ex.:
--   
--   <pre>
--   &gt;&gt;&gt; let t = TimeOfDay 1 12 3
--   
--   &gt;&gt;&gt; t
--   01:12:03
--   
--   &gt;&gt;&gt; t &amp; flexT.seconds +~ (-7200)
--   23:12:03
--   </pre>
class FlexibleTime a
flexT :: FlexibleTime a => Lens' a FlexTime

-- | Isomorphism between <a>UTCTime</a> and <a>LocalTime</a> for the given
--   <a>TimeZone</a>.
utcInTZ :: TimeZone -> Iso' UTCTime LocalTime

-- | Trivial isomorphism between <a>UTCTime</a> and <a>LocalTime</a>.
--   
--   We view <a>LocalTime</a> values as being in the UTC time zone. This is
--   <a>utcInTZ</a> applied to <a>utc</a>.
utcAsLocal :: Iso' UTCTime LocalTime

-- | Lens into the <a>LocalTime</a> part of <a>ZonedTime</a>.
zonedAsLocal :: Lens' ZonedTime LocalTime

-- | View <a>Day</a> as an <a>Integer</a> day number in the Julian
--   calendar.
--   
--   See the description at the definition of <a>Day</a>.
julianDay :: Iso' Day Integer

-- | View <a>LocalTime</a> as a fractional day in the modified Julian
--   calendar.
--   
--   See the description of <a>ModifiedJulianDay</a> and
--   <a>timeOfDayToDayFraction</a>.
julianDT :: Iso' LocalTime Rational

-- | View <a>Day</a> as a triple of (year,month,day) in Gregorian calendar.
--   
--   See the description at the definition of <a>fromGregorian</a> /
--   <a>toGregorian</a>.
gregorianDate :: Iso' Day (Integer, Int, Int)
instance GHC.Show.Show Data.Time.Lens.FlexTime
instance GHC.Show.Show Data.Time.Lens.FlexDateTime
instance GHC.Show.Show Data.Time.Lens.FlexDate
instance Data.Time.Lens.Timeable Data.Time.Clock.Internal.UTCTime.UTCTime
instance Data.Time.Lens.Timeable Data.Time.LocalTime.Internal.LocalTime.LocalTime
instance Data.Time.Lens.Timeable Data.Time.LocalTime.Internal.ZonedTime.ZonedTime
instance Data.Time.Lens.Timeable Data.Time.LocalTime.Internal.TimeOfDay.TimeOfDay
instance Data.Time.Lens.Timeable Data.Time.Lens.FlexDateTime
instance Data.Time.Lens.Timeable Data.Time.Lens.FlexTime
instance Data.Time.Lens.Dateable Data.Time.Clock.Internal.UTCTime.UTCTime
instance Data.Time.Lens.Dateable Data.Time.LocalTime.Internal.LocalTime.LocalTime
instance Data.Time.Lens.Dateable Data.Time.LocalTime.Internal.ZonedTime.ZonedTime
instance Data.Time.Lens.Dateable Data.Time.Calendar.Days.Day
instance Data.Time.Lens.Dateable Data.Time.Lens.FlexDate
instance Data.Time.Lens.Dateable Data.Time.Lens.FlexDateTime
instance Data.Time.Lens.FlexibleTime Data.Time.LocalTime.Internal.TimeOfDay.TimeOfDay
instance Data.Time.Lens.FlexibleDate Data.Time.Calendar.Days.Day
instance Data.Time.Lens.FlexibleDateTime Data.Time.LocalTime.Internal.LocalTime.LocalTime
instance Data.Time.Lens.FlexibleDateTime Data.Time.Clock.Internal.UTCTime.UTCTime
instance Data.Time.Lens.FlexibleDateTime Data.Time.LocalTime.Internal.ZonedTime.ZonedTime
instance Control.Lens.Tuple.Field1 Data.Time.Lens.FlexDate Data.Time.Lens.FlexDate GHC.Integer.Type.Integer GHC.Integer.Type.Integer
instance Control.Lens.Tuple.Field2 Data.Time.Lens.FlexDate Data.Time.Lens.FlexDate GHC.Types.Int GHC.Types.Int
instance Control.Lens.Tuple.Field3 Data.Time.Lens.FlexDate Data.Time.Lens.FlexDate GHC.Types.Int GHC.Types.Int
