chronos

A high-performance time library

https://github.com/byteverse/chronos

LTS Haskell 23.23:1.1.6.2@rev:1
Stackage Nightly 2025-05-23:1.1.6.2@rev:1
Latest on Hackage:1.1.6.2@rev:1

See all snapshots chronos appears in

BSD-3-Clause licensed by Andrew Martin
Maintained by [email protected], [email protected]
This version can be pinned in stack with:chronos-1.1.6.2@sha256:bc7d675a0b955a8a5b81eccde9393250e3f4494e4517637c2c698d10610d2911,4234

Module documentation for 1.1.6.2

Chronos

Chronos is a performance-oriented time library for Haskell, with a straightforward API. The main differences between this and the time library are:

  • Chronos uses machine integers where possible. This means that time-related arithmetic should be faster, with the drawback that the types are incapable of representing times that are very far in the future or the past (because Chronos provides nanosecond, rather than picosecond, resolution). For most users, this is not a hindrance and the tradeoff is worthwhile.
  • Chronos provides ‘ToJSON’/‘FromJSON’ instances for serialisation.
  • Chronos provides ‘Unbox’ instances for working with unboxed vectors.
  • Chronos provides ‘Prim’ instances for working with byte arrays/primitive arrays.
  • Chronos uses normal non-overloaded haskell functions for encoding and decoding time. It provides attoparsec parsers for both ‘Text’ and ‘ByteString’. Additionally, Chronos provides functions for encoding time to ‘Text’ or ‘ByteString’. The time library accomplishes these with the Data.Time.Format module, which uses UNIX-style datetime format strings. The approach taken by Chronos is faster and catches more mistakes at compile time, at the cost of being less expressive.

Jacob Stanley has written a blog post comparing the features and performance of time, thyme, and chronos. It has a good bulleted breakdown of why you may want to use each library along with some benchmarks.

Benchmarks

Benchmarks of chronos against time and thyme.

Parsing

Benchmark name Time
Time.parseTimeM 9.679 μs
Thyme.parseTime 1.743 μs
Thyme.timeParser 1.113 μs
Chronos.parserUtf8_YmdHMS 301.4 ns
Chronos.zeptoUtf8_YmdHMS 173.6 ns

Pretty-printing

Benchmark name Time
dmy/Time.formatTime 4.404 μs
dmy/Thyme.formatTime 663.0 ns
dmy/Chronos.builder_Dmy 340.9 ns
HMS/Time.formatTime 1.987 μs
HMS/Thyme.formatTime 879.1 ns
HMS/Chronos.builder_HMS 481.3 ns

Doctest

Doctest used to be provided as a test suite, but doctest-0.20 and higher do not require this to be run. To run the doctests, make sure you have doctest on your path (i.e. run cabal install doctest), and then run:

cabal build
cabal repl --build-depends=QuickCheck --with-ghc=doctest --repl-options='-fno-warn-orphans'

This runs incredibly slowly, but it works for now. Doctest is not run by CI, so if you make a change that adds more doctests, it needs to be run by hand by someone. (The maintainer is happy to do this if you’re on a platform where doctest is finicky.)

Changes

Revision history for chronos

1.1.6.2 – 2024-12-11

  • Support GHC 9.10

1.1.6.1 – 2024-02-15

  • Update package metadata.

1.1.6.0 – 2024-01-29

  • Add sinceEpoch and asSeconds functions

1.1.5.1 – 2023-08-24

  • Allow newer natural-arithmetic, primitive, and vector.
  • Allow base 4.18.
  • Add units to offset docs.

1.1.5 – 2022-11-03

  • Add decodeShortTextIso8601Zulu.
  • Add decodeUtf8BytesIso8601ZonelessSpaced.

1.1.4 – 2022-02-21

  • Fix February length in normalYearMonthLength. Fixes GitHub issue #67.
  • Support aeson-2.x, with backward compatibility for aeson-1.x.
  • Add helper dateToDayOfWeek
  • Add helpers encode_Ymd and encode_Dmy to more easily pretty-print dates
  • Add various lenses for core data type fields and isos
  • Drop support for GHC 8.8 and earlier.

1.1.3 – 2021-09-07

  • Dropped support for GHC < 8.6.
  • Integrated with byteverse libraries and text-short, adding efficient builders and parsers targeting UT8-encoded unpinned byte arrays. The new functions are: boundedBuilderUtf8BytesIso8601Zoneless, encodeShortTextIso8601Zulu, encodeShortTextIso8601Zoneless, parserUtf8BytesIso8601, boundedBuilderUtf8BytesIso8601, decodeUtf8BytesIso8601, decodeShortTextIso8601, decodeShortTextIso8601Zoneless, decodeUtf8BytesIso8601Zoneless, encodeShortTextIso8601.
  • Corrected an implementation mistake that had caused many parsers to incorrectly identifier a subseconds part of 0 (i.e. 23:59:17.000).
  • Improved layout of cabal file.

1.1.2 – 2021-02-08

  • Adds NFData typeclass instances for all data types.
  • Add encodeIso8601 and builderIso8601.
  • Soft deprecate builderW3C in favor of builderIso8601.
  • Fix formatting in cabal file.

1.1.1 – 2020-04-17

  • Add timeToDayOfWeek, datetimeToDayOfWeek, todayDayOfWeek, yesterdayDayOfWeek, and tomorrowDayOfWeek.
  • Remove stopwatchWith(_) on GHC 8.6+.
  • Fix build on 32-bit POSIX systems.

1.1 – 2019-11-28

  • Drop dependency of clock on GHC 8.6+.
  • Remove stopwatchWith(_) on GHC 8.6+.
  • Deprecate stopwatchWith(_) on GHC <8.6.
  • Fix build on Windows. Thanks @SpaceKitteh for reporting this.

1.0.9 – 2019-11-09

  • Add TimeParts for custom formatting.

1.0.8 – 2019-11-07

  • Allow newer semigroups.

1.0.7 – 2019-08-16

  • Fix build on windows. Chronos now builds on windows, macos, and linux. Thanks to @nprindle for the fix/testing and @ShrykerWindgrace for reporting it!

1.0.6 – 2019-07-19

  • Add ‘TimeInterval’ type and related functions.

1.0.5 – 2019-05-01

  • Allow newer version of clock (==0.7.* ===> >=0.7 && < 0.9)
  • Build with -Wall
  • Build with -O2

1.0.4 – 2018-08-14

  • Initial version, w.r.t. CHANGELOG (i.e. there was no changelog before).