Module Units.Time

Functions for converting and displaying units of time.

This functor needs to be applied to a module of type NUM representing your preferred base time unit resolution.

Example: module Time_int = Time (Int)

This module is intended to provide informal human-readable representations of approximate time durations, converting a value of type t to friendly strings like "3 weeks, 1 day" or "3 hours and 10 minutes".

Accuracy is not the raison d'etre of this module; for example, months are defined as 31 days long, and years are defined as 12 months long! Leap years and leap seconds are completely ignored.

Examples:

N.B. For computing with accurate representations of time durations, see e.g. Daniel Bünzli's excellent modules:

Parameters

module N : NUM

Signature

Types and type conversion

type t = N.t

The type of base time units.

val (!) : int -> N.t

Prefix operator to convert an int to a t.

Arithmetic

val (+) : N.t -> N.t -> N.t

Addition over values of type t.

val (-) : N.t -> N.t -> N.t

Subtraction over values of type t.

val (*) : N.t -> N.t -> N.t

Multiplication over values of type t.

val (/) : N.t -> N.t -> N.t

Division over values of type t.

Units

val factors : (N.t * string * string) list

Multiplicative factors for each unit, in descending order, with the unit's name and the plural form of the name.

For example, (!24, "day", "days") says that one day is 24 of the unit that follows it in the list, which is "hour".

This list may contain units that cannot be represented in a given base number type N; see Units.

factors contains the following units:

  • year
  • month
  • week
  • day
  • hour
  • minute
  • second
  • millisecond
  • microsecond
val units : (N.t * string * string) list

All the units, with their multipliers, in descending order, that are resolvable with base number type N.

For example, with Units.Int base units, units contains (86400000000, "day", "days"), because one day is 86_400_000_000 microseconds, which is the minimum factor or "base unit".

If you use a small base unit, then units may not contain all the units in factors. For example:

module T = Units.Time (struct
  include Int32
  let ( + ), ( - ), ( * ), ( / ), (mod) = add, sub, mul, div, rem
end)
T.(minimum,maximum) = ((1l, "microsecond", "microseconds"), (60000000l, "minute", "minutes"))
val maximum : N.t * string * string

maximum is the maximum resolvable unit with base type t.

val minimum : N.t * string * string

minimum is the minimum resolvable unit with base type t.

val microseconds : N.t -> N.t

(microseconds n) is n microseconds in base units.

val milliseconds : N.t -> N.t

(milliseconds n) is n milliseconds in base units.

val seconds : N.t -> N.t

(seconds n) is n seconds in base units.

val minutes : N.t -> N.t

(minutes n) is n minutes in base units.

val hours : N.t -> N.t

(hours n) is n hours in base units.

val days : N.t -> N.t

(days n) is n days in base units.

val weeks : N.t -> N.t

(weeks n) is n weeks in base units.

val months : N.t -> N.t

(months n) is n months in base units.

val years : N.t -> N.t

(years n) is n years in base units.

val to_units : N.t -> (string * N.t) list
val long : ?zero:string -> ?sep:string -> ?last:string -> N.t -> string

(long ?zero ?sep ?last t) is a long-format string representation of time t.

~zero is returned when (t = N.zero) (default: N.(to_string zero))

~sep is the string that separates all the units of the time description (default: ", "), except that ~last is used as the separator between the last unit and the one preceding it.

Examples:

  • (days !22 + minutes !10 |> long) = ("3 weeks, 1 day and 10 minutes")
  • (days !22 |> long) = ("3 weeks and 1 day")
  • (days !1 |> long) = ("1 day")
  • (days !0 |> long) = ("0")
  • (days !0 |> long ~zero:"no days, baby") = ("no days, baby")
val of_string : ?min:string -> ?sep:string -> string -> N.t

(of_string ?min ?sep str) converts a string in a certain format to a t.

The format of the string that of positive integers (with optional leading zeroes) separated by any of the characters in ~sep (default: ":"). ~min is (singular form of) the name of minimal unit i.e. the unit of the rightmost integer (default: "second").

For example, (of_string 10) is 10 seconds in base units (due to the default ~sep), while (of_string "1:12:04") is 1 hour, 12 minutes and 4 seconds.

module Month : sig ... end

Functions to convert between month names and month numbers.