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


-- | Converting time to and from IS0 8601 text. Specifically the
--   <a>RFC3339</a> profile.
@package text-iso8601
@version 0.1.1


-- | The <a>RFC3339 grammar</a> is below
--   
--   <pre>
--   date-fullyear   = 4DIGIT
--   date-month      = 2DIGIT  ; 01-12
--   date-mday       = 2DIGIT  ; 01-28, 01-29, 01-30, 01-31 based on month/year
--   time-hour       = 2DIGIT  ; 00-23
--   time-minute     = 2DIGIT  ; 00-59
--   time-second     = 2DIGIT  ; 00-58, 00-59, 00-60 based on leap second rules
--   time-secfrac    = "." 1*DIGIT
--   time-numoffset  = ("+" / "-") time-hour ":" time-minute
--   time-offset     = "Z" / time-numoffset
--   
--   partial-time    = time-hour ":" time-minute ":" time-second [time-secfrac]
--   full-date       = date-fullyear "-" date-month "-" date-mday
--   full-time       = partial-time time-offset
--   
--   date-time       = full-date "T" full-time
--   </pre>
--   
--   The parsers are a bit more lenient:
--   
--   <ul>
--   <li>We also accept space instead of <tt>T</tt> date-time separator.
--   (Allowed by RFC3339, forbidden by ISO8601)</li>
--   <li>Seconds are optional (allowed by ISO8601)</li>
--   <li>numerical timezone offset can be just <tt>("+" / "-")
--   time-hour</tt> or without a colon: <tt>("+" / "-") time-hour
--   time-minute</tt> (allowed by ISO8601). However we require colons in
--   between hours, minutes and seconds in the time (<tt>partial-time</tt>)
--   production, and dashes in <tt>full-date</tt> production.</li>
--   <li>We allow over 4 digits in the year part (and that is a reason to
--   require dashes).</li>
--   <li>We allow <tt>-00:00</tt> time offset. (Allowed by RFC3339,
--   forbidden by ISO8601)</li>
--   <li>We always allow time with 60 seconds, we don't consult any leap
--   second database.</li>
--   </ul>
module Data.Time.FromText

-- | Parse a date of the form <tt>[+-]YYYY-MM-DD</tt>.
--   
--   The year must contain at least 4 digits, to avoid the Y2K problem: a
--   two-digit year <tt>YY</tt> may mean <tt>YY</tt>, <tt>19YY</tt>, or
--   <tt>20YY</tt>, and we make it an error to prevent the ambiguity. Years
--   from <tt>0000</tt> to <tt>0999</tt> must thus be zero-padded. The year
--   may have more than 4 digits.
parseDay :: Text -> Either String Day

-- | Parse a date and time, of the form <tt>YYYY-MM-DD
--   HH:MM[:SS[.SSS]]</tt>. The space may be replaced with a <tt>T</tt>.
--   The number of seconds is optional and may be followed by a fractional
--   component.
parseLocalTime :: Text -> Either String LocalTime

-- | Parse a time of the form <tt>HH:MM[:SS[.SSS]]</tt>.
parseTimeOfDay :: Text -> Either String TimeOfDay

-- | Parse a time zone.
--   
--   The accepted formats are <tt>Z</tt>, <tt>+HH</tt>, <tt>+HHMM</tt>, or
--   <tt>+HH:MM</tt>. (<tt>+</tt> can be <tt>-</tt>).
--   
--   Accepts <tt>-23:59..23:59</tt> range, i.e. <tt>HH &lt; 24</tt> and
--   <tt>MM &lt; 59</tt>. (This is consistent with grammar, and with what
--   Python, Clojure, joda-time do).
parseTimeZone :: Text -> Either String TimeZone

-- | Behaves as <tt>zonedTime</tt>, but converts any time zone offset into
--   a UTC time.
parseUTCTime :: Text -> Either String UTCTime

-- | Parse a date with time zone info. Acceptable formats:
--   
--   <pre>
--   YYYY-MM-DD HH:MMZ
--   YYYY-MM-DD HH:MM:SSZ
--   YYYY-MM-DD HH:MM:SS.SSSZ
--   </pre>
--   
--   The first space may instead be a <tt>T</tt>, and the second space is
--   optional. The <tt>Z</tt> represents UTC. The <tt>Z</tt> may be
--   replaced with a time zone offset of the form <tt>+0000</tt> or
--   <tt>-08:00</tt>, where the first two digits are hours, the <tt>:</tt>
--   is optional and the second two digits (also optional) are minutes.
parseZonedTime :: Text -> Either String ZonedTime

-- | Parse a year <tt>[+-]YYYY</tt>, with at least 4 digits. Can include a
--   sign.
--   
--   See also <a>parseDay</a> for details about the year format.
--   
--   Note: <a>Year</a> is a type synonym for <a>Integer</a>.
parseYear :: Text -> Either String Year

-- | Parse a month of the form <tt>[+-]YYYY-MM</tt>.
--   
--   See also <a>parseDay</a> for details about the year format.
parseMonth :: Text -> Either String Month

-- | Parse a quarter of the form <tt>[+-]YYYY-QN</tt>.
--   
--   See also <a>parseDay</a> for details about the year format.
parseQuarter :: Text -> Either String Quarter

-- | Parse a quarter of year of the form <tt>QN</tt> or <tt>qN</tt>.
parseQuarterOfYear :: Text -> Either String QuarterOfYear

module Data.Time.ToText
buildDay :: Day -> Builder
buildLocalTime :: LocalTime -> Builder
buildTimeOfDay :: TimeOfDay -> Builder
buildTimeZone :: TimeZone -> Builder
buildUTCTime :: UTCTime -> Builder
buildZonedTime :: ZonedTime -> Builder

-- | Used in encoding day, month, quarter
buildYear :: Year -> Builder
buildMonth :: Month -> Builder
buildQuarter :: Quarter -> Builder
buildQuarterOfYear :: QuarterOfYear -> Builder
