time-hourglass

A simple and efficient time library

https://github.com/mpilgrem/time-hourglass

Stackage Nightly 2025-11-04:0.3.0
Latest on Hackage:0.3.0

See all snapshots time-hourglass appears in

BSD-3-Clause licensed by Vincent Hanquez
Maintained by Mike Pilgrem
This version can be pinned in stack with:time-hourglass-0.3.0@sha256:ee02356fe24919ec43ae17fc0007398c2fd0bbe822833b2d7a9c849537b90580,3114

Module documentation for 0.3.0

Depends on 2 packages(full list with versions):
base, deepseq
Used by 2 packages in nightly-2025-11-04(full list with versions):
crypton-asn1-encoding, crypton-asn1-types

time-hourglass

Build Status License Haskell

Originally forked from hourglass-0.2.12.

time-hourglass (originally hourglass) is a simple and efficient time library.

Documentation

See the Haddock documentation on Hackage.

Design

A key part of the design is the Timeable and Time type classes. Types representing time values that are instances of these classes allow easy conversion between values of one time type and another.

For example:

let dateTime0 =
      DateTime
        { dtDate = Date
            { dateYear = 1970
            , dateMonth = January
            , dateDay = 1
            }
        , dtTime = TimeOfDay
            { todHour = 0
            , todMin = 0
            , todSec = 0
            , todNSec = 0
            }
        }
    elapsed0 = Elasped 0

> timeGetElapsed elapsed0 == timeGetElapsed dateTime0
True
> timeGetDate elapsed0 == timeGetDate dateTime0
True
> timePrint "YYYY-MM" elapsed0
"1970-01"
> timePrint "YYYY-MM" dateTime0
"1970-01"

The library has the same limitations as your operating system, namely:

  • on 32-bit Linux, you can’t get a date after the year 2038; and
  • on Windows, you can’t get a date before the year 1601.

Comparaison with the time package

  • Getting the elapsed time since 1970-01-01 00:00:00 UTC (POSIX time) from the system clock:

    -- With time:
import Data.Time.Clock.POSIX ( getPOSIXTime )

ptime <- getPOSIXTime

-- With time-hourglass:
import System.Hourglass ( timeCurrent )

ptime <- timeCurrent

  • Getting the current year:

    -- With time:
import Data.Time.Clock ( UTCTime (..) )
import Data.Time.Clock.POSIX ( getCurrentTime )
import Data.Time.Calendar ( toGregorian )

currentYear <- (\(y, _, _) -> y) . toGregorian . utcDay <$> getCurrentTime

-- With time-hourglass:
import System.Hourglass ( timeCurrent )
import Data.Hourglass ( Date (..), timeGetDate )

currentYear <- dateYear . timeGetDate <$> timeCurrent

  • Representating “4th May 1970 15:12:24”

    -- With time:
import Data.Time.Clock ( UTCTime (..), secondsToDiffTime )
import Date.Time.Calendar ( fromGregorian )

let day = fromGregorian 1970 5 4
    diffTime = secondsToDiffTime (15 * 3600 + 12 * 60 + 24)
in  UTCTime day diffTime

-- With time-hourglass:
import Date.Time ( Date (..), DateTime (..), TimeOfDay (..) )

DateTime (Date 1970 May 4) (TimeOfDay 15 12 24 0)

History

The hourglass package was originated and then maintained by Vincent Hanquez. For published reasons, he does not intend to develop the package further after version 0.2.12 but he also does not want to introduce other maintainers.

Changes

Change log for time-hourglass

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to the Haskell Package Versioning Policy.

0.3.0 - 2025-08-01

  • Drop support for GHC < 8.6.
  • Add Real instance for ElapsedSinceP.
  • Add Read instances for TimezoneOffset and Read t => LocalTime t.
  • Export fromRationalSecondsP, mkElapsedP, and fromRationalElapsedP, to facilitate creation of ElapsedP values from precise amounts of seconds or numbers of seconds and nanoseconds.
  • Test added to test suite for toRational :: ElapsedSinceP -> Rational and fromRationalElapsedP.
  • Add Format_DayYear3 for a day of the year padded to 3 characters, represented by @“JJJ”@.
  • Change the types of fields of TimeFormatFct: the parser and printer are in terms of DateTime and TimezoneOffset (rather than just DateTime).
  • In localTimePrint etc, implement Format_TimezoneName and Format_Fct.
  • In localTimeParseE etc, implement Format_Month, Format_DayYear, Format_Day, Format_TimezoneName, Format_Tz_Offset and Format_Fct.
  • Test added to test suite for Format_Fct parsing and printing.
  • In localTimeParseE etc, Format_Spaces now parses one or more space-like characters (as previously documented), rather than one space character (as previously implemented).
  • Export MJDEpoch, representing the Modified Julian Date (MJD) epoch.
  • Drop deprecated modules Data.Hourglass.Compat, Data.Hourglass.Epoch, Data.Hourglass.Types and System.Hourglass. Use modules Time.Compat, Time.Epoch and Time.Types.
  • Drop deprecated function dateFromPOSIXEpoch. Use dataFromUnixEpoch.
  • Drop deprecated function dateFromTAIEpoch. Use dateFromMJDEpoch.
  • Fix Haddock documentaton for Format_Hours, Format_Minutes and Format_Seconds; they all pad to 2 characters.
  • Fix Haddock documentaton for Format_Millisecond, Format_MicroSecond and Format_NanoSecond; they parse and print components only, and all pad to 3 characters.
  • Fix error message if a Format_Text parse fails.
  • Add Haddock documentation for the String instance of TimeFormat.

0.2.14 - 2025-07-24

  • In test-suite and benchmark, depend on main library, drop dependency on package hourglass.

0.2.13 - 2025-07-23

  • Drop support for GHC < 8.4.
  • Move library modules to directory src and benchmark module to directory benchmarks.
  • Move module Example.Time.Compat to directory examples.
  • Expose module Time.Epoch and deprecate equivalent module Data.Hourglass.Epoch.
  • Renamed non-exposed library modules under the Time.* hierarchy.
  • Use LANGUAGE PackageImports in module Example.Time.Compat, allowing stack ghci examples/Example/Time/Compat.hs.
  • Eliminate the use of CPP to vary source code for different operating systems.
  • Fix other-modules of bench-hourglass benchmark.
  • bench-hourglass benchmark depends on tasty-bench, drop dependency on gauge.
  • Improve Haddock and other documentation.
  • Export new dateFromUnixEpoch and deprecate identical dateFromPOSIXEpoch to name epoch consistently.
  • Export new dateFromMJDEpoch and deprecate identical dateFromTAIEpoch to fix the latter being a misnomer.

0.2.12 - 2025-07-21

  • Rename hourglass-0.2.12 package as time-hourglass-0.2.12.
  • Cabal file specifies cabal-version: 1.12 (not >= 1.10).
  • Change maintainer field to Mike Pilgrem <[email protected]>.
  • Add bug-reports field to Cabal file.
  • Reset CHANGELOG.md.
  • Update README.md badges.
  • In test-suite test-hourglass replace use of parseTime (removed from package time-1.10) with parseTimeM True.