ocaml-community / calendar

OCaml library for handling dates and times.

Calendar

A calendar library for OCaml. API documentation

1. Introduction
2. Contents
3. Copyright
4. Installation
5. How to use
6. Documentation
7. Makefile
8. Contact the developers

1- Introduction

The Calendar library provides types and operations over dates and times. This library requires OCaml 4.03.0 or higher. Older OCaml versions are unsupported.

2- Contents

• CHANGES Information about the last changes
• COPYING Information about copyright
• LGPL Information about LGPL
• README.md This file
• calendar_faq.txt FAQ frow which some algorithms come
• doc HTML documentation of the API
• src Source files directory
• _build/default/ Directory containing the built library
• tests Test files directory
• utils Some utilities

3- Copyright

This program is distributed under the GNU LGPL 2.1. See the enclosed file COPYING for more details.

4- Installation

Easiest way is opam install calendar.

To manually install the library, you first need to install dune and re. Then:

$ dune build @install
$ dune install

You can remove files installed with :

dune uninstall

5- How to use

Use the calendar library using ocamlfind. In dune, it means having an entry (libraries calendar).

6- Documentation

The doc directory contains an html documentation of the .mli files. This documentation is available online at http://calendar.forge.ocamlcore.org/doc/

7- Makefile

A description of some Makefile entries follows :

• make test will execute some tests. You'll need alcotest.

  To run only some tests: dune exec ./tests/test.exe test time (for example)

• make doc to produce the documentation of the API. You need odoc

8- Contact the developers

You can report bugs at https://github.com/ocaml-community/calendar/issues

calendar's Issues

migrate test suite?

at a glance it seems to use a custom test module, we could use alcotest+qcheck or something like that?

migration to dune

if you want help with this, I can try to help.

binaries contain build date

PR #6 created a src/dune which calls date(1), see commit 486d180
Storing a random date in binaries was never a good idea, in any project, at any time.

Debian sells a feature called "reproducible build", openSUSE/build-compare just wants to avoid needless republish to reduce load on mirrors.

Please, remove the version.ml:date API. It can not possibly serve any useful purpose...

3.0 Release or just merge 3.0 branch into master and make master the primary development branch?

I haven't been able to spend a lot of time with calendar (and OCaml in general) for the past months.

My initial plan was to stabilise this branch and then merge it in to master and do a 3.0 release, which would be considered backwards incompatible.

What I'm lacking right at the moment is knowledge on how to do Opam releases.

Please, anyone interested, comment on what you prefer with regards of branches and releases.
Probably @pmetzger was right after all - continuing in master might be a good idea.

CalendarPrinter.from_fstring cannot actually parse most formats

The DatePrinter.from_fsrting function appears to work correctly with all possible formats.

utop # CalendarLib.Printer.DatePrinter.from_fstring "%Y-%m-%d %H:%M%z" "1970-01-01 00:00+0000" |> CalendarLib.Printer.DatePrinter.sprint "%d/%m/%Y" ;;
- : string = "01/01/1970"

If you want to handle both date and time, however... The CalendarPrinter.from_fstring function fails with a generic exception for most formats.

utop # CalendarLib.Printer.CalendarPrinter.from_fstring "%Y-%m-%d %H:%M%z" "1970-01-01 00:00+0000" |> CalendarLib.Printer.CalendarPrinter.sprint "%d/%m/%Y" ;;
Exception: Invalid_argument "Cannot create the calendar".

It only seems to works for shortcut format specifiers that include both date and time, like %c.

utop # CalendarLib.Printer.CalendarPrinter.from_fstring "%c" "Thu Sep 18 14:10:51 2003" |> CalendarLib.Printer.CalendarPrinter.sprint "%d/%m/%Y" ;;
- : string = "18/09/2003"

Is the printer slow?

I have some code that needs to output a large number of dates to a clean format, but I noticed that this was quite slow.

With this benchmark:

open Core;
open Core_bench.Std;

let main = () => {
	let date = CalendarLib.Calendar.from_unixfloat(1000329.);
  Command.run(
    Bench.make_command([
      Bench.Test.create(~name="format", () => ignore(CalendarLib.Printer.Calendar.sprint("%iT%T%z", date))),
    ]),
  );
};

let () = main();

I get this output:

┌────────┬──────────┬─────────┬──────────┬──────────┬────────────┐
│ Name   │ Time/Run │ mWd/Run │ mjWd/Run │ Prom/Run │ Percentage │
├────────┼──────────┼─────────┼──────────┼──────────┼────────────┤
│ format │   2.95us │ 721.26w │    1.07w │    1.07w │    100.00% │
└────────┴──────────┴─────────┴──────────┴──────────┴────────────┘

I'm not sure if you are considering this slow, but to me it was totally unexpected that something like this would take up a large amount of time in my code (after benchmarking almost 50% of my time goes to formatting the date).
When using Calendar_Precise it's even a bit slower (about 0,5 microseconds added)

Am I doing something wrong here? Or is this something that is just slow?

API changes: avoid relying on global state?

there are some global mutations in the lib (e.g. Time_zone.change) which make reasoning about the library complicated.

I think it'd be nice to instead have a ?tz:Time_zone.t argument in functions that make use of the global state, to overload it.

Off-by-one in precise_sub

Originally reported here by Stephen Dolan

I expected that if I use CalendarLib.Calendar.Precise.precise_sub to compute the difference between two dates, then I could add this difference to the earlier and get the later.

However, if I attempt this on [2025-03-31 17:53:04; 2026-07-19 12:15:23], then the result of add is 2026-07-20 12:15:23, not 2026-07-19 12:15:23.

Add print functions that can be installed in the toplevel

Time zone limitations

**Originally reported here by Jérôme Vouillon @vouillon **

New Zealand is at UTC+12:00, which is not accepted by Calendar. Indeed, we have this code in time_Zone.ml:
let out_of_bounds x = x < - 12 || x > 11

This is affected by commit but needs to be verified by a test and maybe we need to come up with new, reasonable limitations

Cleanup the float/int distinction

There is currently Calendar, Calendar.Precise, FCalendar and FCalendar.Precise, all with various float/int combination. The tradeoffs are absolutely not explained in the documentation, and I'm quite sure they don't apply anymore, in these times of ubiquitous 64bit systems. We should be able to clean all that up.

New release for OCaml 5.0 support

Hi, currently no release of calendar work on OCaml 5.0 (see ocaml/opam-repository#22208) but master compiles just fine.

Any chance someone could do a release of calendar to add support for OCaml 5.0 ?

bs?

I note the name bs-calendar. Can this be used in the browser with ReasonML/Bucklescript/ReScript?

Thank you!

Date.make 2018 1 32 should probably not be allowed?

The current behavior is this:

utop # Date.make 2017 1 32 |> Printer.Date.to_string;;
- : string = "2017-02-01"

Calendar does not support non-integral time zone offsets

**Originally repoted here by Jérôme Vouillon @vouillon **

Calendar does not support non-integral time zone offsets (for instance, India is at UTC+05:30).

Calendar: off by one in week-of-year ( week_first_last ) ( calendar 2.04 )

Originally reported here by Oliver Bandel

Week one in 2017 starts at 2017-01-02 and ends at 2017-01-08.

But
week_first_last 1 2017
gives 2016-12-26 ... 2017-01-01

So the result is off by one.

This is affected by this commit

opam release?

I may have missed it, but I couldn't find this new version of Calendar on opam. Is there any plan to release it in the foreseeable future? I'm particularly interested in the switch from Str to Re...

Travis CI status

@pmetzger @Drup - I added the Travis CI status banner but I don't seem to have any actual control over Travis CI itself, as I am not listed as ocaml-community member. Because of this in the Travis CI admin panel I don't see the calendar project.

Please have a look if you can run a new CI build and if the build will light up green.

missing release tags

Is there a chance to get git tags for binaries on opam and ocamlcore, like 7f7ba91 == 2.04?

Fix documentation generation

This probably depends on #6

Currently the default opam installation doesn't generate any documentation via odoc

Date.is_leap_day seems wrong

utop [21]: Date.is_leap_year 2000;;
- : bool = true
utop [22]: Date.is_leap_day (Date.make 2000 2 29);;
- : bool = false

calendar/src/date.ml

Line 212 in a447a88

is_leap_year (year d) && month d = Feb && day_of_month d = 24

This seems to just be defined incorrectly.

add OPAM files

Right now, I believe the CI is failing because of the lack of an OPAM file. One should be added. It won't take much effort once the dune migration @c-cube is doing is done.

short_name_of_{day/month} not compatible with UTF8 chars

short_name_of_day and short_name_of_month use:

String.sub s 0 3

This will only work with languages using ASCII chars only, but it doesn't work with UTF-8 characters.

In addition to the functions refs month_name and day_name we should also create month_short_name and day_short_name.

Host `odoc` documentation on gh-pages branch

Not sure that #15 is still relevant. Using currently release odoc i'm able to generate documentation using dune build @doc. It might be nice to have that output hosted on the gh-pages branch so it can be viewed online.

How to install? ./configure is not present

Hi,
I just tried to download & install this library, but the first step of the documentation is already not direct:

$ ./configure
bash: ./configure: Aucun fichier ou dossier de ce type

Thanks in advance!
(I could probably find on my own how to proceed, but the documentation should be improved, if possible!)

Documentation no longer includes format specifiers (as a bonus, old doc links are all dead)

The old docs used to have useful information on the formats: https://web.archive.org/web/20160415075101/http://calendar.forge.ocamlcore.org/doc/Printer.html

It's no longer the case. The original documentation links don't work anymore, and the new docs leave the user to guess what the available specifiers are.

I can help fix it, but I need to know where you think this info should be in the docs.

Wrong DST application

Originally reported here by Petter Urkedal

The calendar library seems to apply DST of the current date rather than the date to be converted. From a locale time zone with DST, the following should show the problem:

Printer.Calendar.to_string (on (fun () -> Calendar.make 2015 1 1 10 00 00) UTC ());;
- : bytes = "2015-01-01 12:00:00"
Printer.Calendar.to_string (on (fun () -> Calendar.make 2015 7 1 10 00 00) UTC ());;
- : bytes = "2015-07-01 12:00:00"

As I'm in a CET with DST time zone I would expect the first to return 11:00:00.

Calendar version 2.03.2.