package timmy

  1. Overview
  2. Docs

Module Timmy.Date

A day of a month of a year.

A day of a month of a year.

Type

type t = {
  1. day : int;
    (*

    The day of the month.

    *)
  2. month : Month.t;
    (*

    The month of the year.

    *)
  3. year : int;
    (*

    The year.

    *)
}

A date.

Construction

val make : year:int -> month:Month.t -> day:int -> (t, string) Result.t

make ~year ~month ~day is { day; month; year } if it represents a valid date or a relevant error message otherwise.

val make_overflow : ?day_truncate:bool -> year:int -> month:int -> day:int -> unit -> t

make_overflow is make except out of range components will readjust the next component until the date becomes valid. This enables to perform simple arithmetics over dates like adding or substracting days and months without worrying about month and year boundaries and readjust the final results.

Month below 1 will underflow to previous years and month above 12 will overflow to the next years, eg. make ~year:2021 ~month:-1 ~day:1 () is {year = 2020; month = 11; day = 1} and make ~year:2021 ~month:25 ~day:1 () is {year = 2023; month = 1; day = 1}.

Unless truncate_day is true, days below 1 will underflow to the previous months and days past the last day of the month will overflow to the next months, eg. make_overflow ~year:1985 ~month:2 ~day:29 () is {year = 1985; month = 3; day = 1}.

If truncate_day is true, the day is clipped to the valid range for the current month. This is useful to do arithmetics on months without risking the day overflowing to the next months if the new month is shorter, eg. make_overflow ~day_truncate:true ~year:1985 ~month:(1 + 1) ~day:31 () is {year = 1985; month = 2; day = 28}.

Time manipulations

val add_days : t -> int -> t

add_days date n is the date occuring n days after date.

val max_month_day : int -> int -> int

max_month_day year month is the last day of the given month of year. It can be 31, 30, 29 or 28.

val weekday : t -> Weekday.t

weekday date is the day of the week on date.

Time conversions

val of_time : timezone:Timezone.t -> Time.t -> t

of_time ~timezone date is the date on date in timezone.

val to_time : timezone:Timezone.t -> t -> Time.t

to_time ~timezone date is the time at midnight on date in timezone.

Comparison

include Base.Comparable.S with type t := t
include Base.Comparisons.S with type t := t
include Base.Comparisons.Infix with type t := t
val equal : t -> t -> bool
val compare : t -> t -> int

compare t1 t2 returns 0 if t1 is equal to t2, a negative integer if t1 is less than t2, and a positive integer if t1 is greater than t2.

val min : t -> t -> t
val max : t -> t -> t
val ascending : t -> t -> int

ascending is identical to compare. descending x y = ascending y x. These are intended to be mnemonic when used like List.sort ~compare:ascending and List.sort ~cmp:descending, since they cause the list to be sorted in ascending or descending order, respectively.

val descending : t -> t -> int
val between : t -> low:t -> high:t -> bool

between t ~low ~high means low <= t <= high

val clamp_exn : t -> min:t -> max:t -> t

clamp_exn t ~min ~max returns t', the closest value to t such that between t' ~low:min ~high:max is true.

Raises if not (min <= max).

val clamp : t -> min:t -> max:t -> t Base.Or_error.t
include Base.Comparator.S with type t := t
type comparator_witness

Operators

module O : sig ... end

Convenience module to only pull operators.

include module type of O
include Base.Comparable.Infix with type t := t
val (>=) : t -> t -> bool
val (<=) : t -> t -> bool
val (=) : t -> t -> bool
val (>) : t -> t -> bool
val (<) : t -> t -> bool
val (<>) : t -> t -> bool
val (+) : t -> int -> t

date + n is add_days date n.

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

end - start is the duration elapsed from start to end.

Scalar conversions

Pretty-print

val pp : t Fmt.t

pp f date prints date to f in RFC3339 format, eg. 2021-10-04.

val pp_human : t Fmt.t

pp_human f date prints date to f in an unspecified human readable english format, eg. "August 1st 2022".

val pp_relative : ?default:t Fmt.t -> reference:t -> t Fmt.t

pp_relative ?default ~reference f date prints date to f in an unspecified human readable english format relative to reference, eg. "today", "last Sunday", "Tuesday".

If no relevant relative format is found, default is used. It defaults to pp_human.

String

val to_string : t -> string

to_string date is the RCF3339 representation of date, eg. 2021-10-04.

val of_string : string -> (t, string) Result.t

of_string s is the date represented by s as per RCF3339 or a relevant error message if it is invalid.

Tuple

val to_tuple : t -> int * int * int

to_tuple { year; month; day} is (year, Month.to_int month, day).

val of_tuple : (int * int * int) -> (t, string) Result.t

of_tuple (year, month, day) is the corresponding date if it is valid or a relevant error message otherwise.

val of_tuple_exn : ?here:Base.Source_code_position.t -> (int * int * int) -> t

of_tuple (year, month, day) is the corresponding date.

  • raises Failure

    if the date is invalid.

S-expression

val to_sexp : t -> Base.Sexp.t

to_sexp date is a s-expression representing date.

Integer

val to_int : t -> int

to_int date is the Julian day of date.

val of_int : int -> t

of_int jd is the date of the Julian day jd.