README

Timere

OCaml date time handling and reasoning suite

This repo houses:

• Timedesc - date time handling library

• Timere - date time reasoning library

• Timere-parse - date time and duration natural language parsing library

API documentation

Note: The NLP component is WIP.

Disclaimer: Timere is not designed to handle prehistoric events. For prehistoric planning and booking software, please consultappropriate experts.

Examples

Christmases which fall on Wednesday from now

let () =  let open Timere in  match    resolve (      since (Timedesc.now ())      &&& months [12]      &&& days [25]      &&& weekdays [`Wed]    )  with  | Error msg -> failwith msg  | Ok s ->    Fmt.pr "%a@." (Timedesc.Interval.pp_seq ~sep:(Fmt.any "@.") ()) s

gives

[2024 Dec 25 00:00:00 +00:00:00, 2024 Dec 26 00:00:00 +00:00:00)[2030 Dec 25 00:00:00 +00:00:00, 2030 Dec 26 00:00:00 +00:00:00)[2041 Dec 25 00:00:00 +00:00:00, 2041 Dec 26 00:00:00 +00:00:00)[2047 Dec 25 00:00:00 +00:00:00, 2047 Dec 26 00:00:00 +00:00:00)[2052 Dec 25 00:00:00 +00:00:00, 2052 Dec 26 00:00:00 +00:00:00)[2058 Dec 25 00:00:00 +00:00:00, 2058 Dec 26 00:00:00 +00:00:00)...

Seeexamples/ for more examples

Features

Timedesc

• Timestamp and date time handling with platform independent time zone support

  • Subset of the IANA time zone database is built into this library

• Supports Gregorian calendar date, ISO week date, and ISO ordinal date

• Supports nanosecond precision

• ISO8601 parsing and RFC3339 printing

• RFC9110 (HTTP) date time parsing and printing

  • Parses IMF-fixdate, RFC850, and ANSI's C's asctime() format permissively

  • Prints in IMF-fixdate

Timere

• Reasoning over time intervals viatimere objects/expressions, examples:

  • Pattern matching time and intervals. These work across DST boundaries.

  • Intersection and union

  • Chunking at year or month boundary, or in fixed sizes

  • Evaluate (sub)expressions with a different time zone (e.g. intersection of 9am to 5pm of Sydney and 9am to 5pm of New York)

Basic usage

Includetimedesc (timere andtimere-parse if needed) in thelibraries stanza in your dune file

Tzdb backend

You can optionally pick one of the following concrete implementations of time zone data source

• timedesc-tzdb.full

  • This is the default implementation which embeds the IANA time zone database from year 1970 to year 2040 exclusive

• timedesc-tzdb.none

  • This embeds no database. This is suitable for when you want to retrieve time zone data during run time, for instance, to reduce the built artifact size.

  • The following resources should allow you to implement said approach readily

    • A usable and test suite covered data source is provided undertzdb-json/.

    • List of available time zones is available asgen-artifacts/available-time-zones.txt

    • Timedesc_json.Time_zone.of_string can load files intzdb-json/

Tzlocal backend

You can optionally pick one of the following concrete implementations of local time zone detection

• timedesc-tzlocal.unix-or-utc

  • This is the default implementation which tries to look up info of OS for local time zone name, and resorts to UTC if that fails.

• timedesc-tzlocal.unix

  • This is the implementation which tries to look up info of OS for local time zone name, but relevant calls for returning or using the local time zone will fail if said lookup was unsuccessful. Should work for common Linux distros.

• timedesc-tzlocal.none

  • This simply returns no time zone guesses

• timedesc-tzlocal.utc

  • This simply returns UTC as the only guess

• timedesc-tzlocal-js (requires packagetimedesc-tzlocal-js)

  • This is an implementation forjs_of_ocaml which usesIntl.DateTimeFormat to get the local time zone name. Should work in all modern browsers, as well as node.js.

Note: Whiletzdb-json/ may be useful and usable outside of Timere, we make no guarantees that the JSON format stays unmodified (though changes of the format should be a rare occurrence, if ever occurring)

Advanced usage

Using Timedesc in utop

To use Timedesc in utop, you need to pick the backends explicitly first

For example, to use the default implementations, one can first type the following lines in utop

#require "timedesc-tzdb.full";;#require "timedesc-tzlocal.unix";;#require "timedesc";;

thenTimedesc should be accessible in utop

Building a custom Tzdb backend

Timedesc itself can help build a time zone data source backend

TODO

Changelog

Seehere

License

Code files are licensed under the MIT license as specified in theLICENSE file

Time zone database derived files are licensed under its original terms (public domain)

Acknowledgement

• Time zone information is extracted viazdump command output intogen-artifacts/time_zone_db.sexp, using the IANA database (as time zone files) distributed on Linux

• Time zone data handling code copies approach used bychrono-tz

  • This includes data representation and choices of some algorithms

• Local time zone detection approach fortimedesc.tzlocal.unix backend is copied fromtzlocal

• Some internal calculations/formulas in Timedesc based around Julian day are copied fromPtime

1. result>= "1.5"
2. ptime
3. angstrom>= "0.15.0"
4. seq
5. timedesc-tzlocal= version
6. timedesc-tzdb= version
7. dune>= "2.9"
8. ocaml>= "4.08"

1. odocwith-doc
2. qcheckwith-test
3. qcheck-alcotestwith-test
4. alcotestwith-test
5. crowbarwith-test
6. bisect_ppxdev & >= "2.5.0"

1. docfd>= "2.1.0"
2. sarif
3. timedesc-json>= "3.1.0"
4. timedesc-sexp>= "3.1.0"

None