# Module `Time.Ofday`

`type underlying`

Time of day.

`t`

represents a clock-face time of day. Usually this is equivalent to a time-offset from midnight, and each`t`

occurs exactly once in each calendar day. However, when daylight saving time begins or ends, some clock face times (and therefore`t`

's) can occur more than once per day or not at all, and e.g. 04:00 can occur three or five hours after midnight, so knowing your current offset from midnight is *not* in general equivalent to knowing the current`t`

.(See

`Zone`

for tools to help you cope with DST.)There is one nonstandard representable value,

`start_of_next_day`

, which can be thought of as "24:00:00" in 24-hour time. It is essentially "00:00:00" on the next day. By having this value, we allow comparisons against a strict upper bound on`t`

values. However, it has some odd properties; for example,`Time.of_date_ofday ~zone date start_of_next_day |> Time.to_date ~zone`

yields a different date.Any

`ofday`

will satisfy`start_of_day <= ofday <= start_of_next_day`

.

`type t`

`= private underlying`

`include Bin_prot.Binable.S with type t := t`

`include Bin_prot.Binable.S_only_functions with type t := t`

`val bin_size_t : t Bin_prot.Size.sizer`

`val bin_write_t : t Bin_prot.Write.writer`

`val bin_read_t : t Bin_prot.Read.reader`

`val __bin_read_t__ : (int -> t) Bin_prot.Read.reader`

This function only needs implementation if

`t`

exposed to be a polymorphic variant. Despite what the type reads, this does *not* produce a function after reading; instead it takes the constructor tag (int) before reading and reads the rest of the variant`t`

afterwards.

`val bin_shape_t : Bin_prot.Shape.t`

`val bin_writer_t : t Bin_prot.Type_class.writer`

`val bin_reader_t : t Bin_prot.Type_class.reader`

`val bin_t : t Bin_prot.Type_class.t`

`include Ppx_sexp_conv_lib.Sexpable.S with type t := t`

`val t_of_sexp : Sexplib0.Sexp.t -> t`

`val sexp_of_t : t -> Sexplib0.Sexp.t`

`include Typerep_lib.Typerepable.S with type t := t`

`val typerep_of_t : t Typerep_lib.Std_internal.Typerep.t`

`val typename_of_t : t Typerep_lib.Typename.t`

`include Core_kernel__.Std_internal.Comparable_binable with type t := t`

`include Core_kernel__.Comparable_intf.S_common`

`include Base.Comparable.S`

`include Base__.Comparable_intf.Polymorphic_compare`

`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`

`val comparator : (t, comparator_witness) Base.Comparator.comparator`

`include Base__.Comparable_intf.Validate with type t := t`

`val validate_lbound : min:t Base.Maybe_bound.t -> t Base.Validate.check`

`val validate_ubound : max:t Base.Maybe_bound.t -> t Base.Validate.check`

`val validate_bound : min:t Base.Maybe_bound.t -> max:t Base.Maybe_bound.t -> t Base.Validate.check`

`module Replace_polymorphic_compare : Core_kernel__.Comparable_intf.Polymorphic_compare with type t := t`

`include Core_kernel__.Comparable_intf.Map_and_set_binable with type t := t with type comparator_witness := comparator_witness`

`include Core_kernel.Comparator.S with type t := t`

`val comparator : (t, comparator_witness) Core_kernel.Comparator.comparator`

`module Map : Core_kernel.Map.S_binable with type Key.t = t with type Key.comparator_witness = comparator_witness`

`module Set : Core_kernel.Set.S_binable with type Elt.t = t with type Elt.comparator_witness = comparator_witness`

`include Core_kernel__.Std_internal.Hashable_binable with type t := t`

`val hash_fold_t : Base.Hash.state -> t -> Base.Hash.state`

`val hash : t -> Base.Hash.hash_value`

`val hashable : t Core_kernel.Hashtbl.Hashable.t`

`module Table : Core_kernel.Hashtbl.S_binable with type key = t`

`module Hash_set : Core_kernel.Hash_set.S_binable with type elt = t`

`module Hash_queue : Core_kernel.Hash_queue.S with type key = t`

`include Core_kernel__.Import.Pretty_printer.S with type t := t`

`val pp : Base.Formatter.t -> t -> unit`

`include Core_kernel.Quickcheck.S_range with type t := t`

`include Core_kernel.Quickcheck_intf.S`

`val quickcheck_generator : t Base_quickcheck.Generator.t`

`val quickcheck_observer : t Base_quickcheck.Observer.t`

`val quickcheck_shrinker : t Base_quickcheck.Shrinker.t`

`val gen_incl : t -> t -> t Base_quickcheck.Generator.t`

`gen_incl lower_bound upper_bound`

produces values between`lower_bound`

and`upper_bound`

, inclusive. It uses an ad hoc distribution that stresses boundary conditions more often than a uniform distribution, while still able to produce any value in the range. Raises if`lower_bound > upper_bound`

.

`val gen_uniform_incl : t -> t -> t Base_quickcheck.Generator.t`

`gen_uniform_incl lower_bound upper_bound`

produces a generator for values uniformly distributed between`lower_bound`

and`upper_bound`

, inclusive. Raises if`lower_bound > upper_bound`

.

`module Span : Core_kernel__.Span_intf.S`

`of_string`

supports and correctly interprets 12h strings with the following suffixes:

"A", "AM", "A.M.", "A.M" "P", "PM", "P.M.", "P.M"

as well as the lowercase and space-prefixed versions of these suffixes.

`of_string`

also fully supports 24h wall-clock times.

`to_string`

only produces the 24h format.

`include Core_kernel__.Std_internal.Stringable with type t := t`

`val create : ?hr:Core_kernel__.Import.int -> ?min:Core_kernel__.Import.int -> ?sec:Core_kernel__.Import.int -> ?ms:Core_kernel__.Import.int -> ?us:Core_kernel__.Import.int -> ?ns:Core_kernel__.Import.int -> Core_kernel__.Import.unit -> t`

`val to_parts : t -> Span.Parts.t`

`val start_of_day : t`

Smallest valid ofday.

`val start_of_next_day : t`

Largest representable ofday; see notes above on how

`start_of_next_day`

behaves differently from other ofday values.

`val approximate_end_of_day : t`

A time very close to the end of a day. Not necessarily the largest representable value before

`start_of_next_day`

, but as close as possible such that using this ofday with`Time.of_date_ofday`

and`Time.to_date`

should round-trip to the same date. With floating-point representations of time, this may not be possible for dates extremely far from epoch.The clock-face time represented by

`approximate_end_of_day`

may vary with different time and ofday representations, depending on their precision.

`val to_span_since_start_of_day : t -> Span.t`

Note that these names are only really accurate on days without DST transitions. When clocks move forward or back,

`of_span_since_start_of_day_exn s`

will not necessarily occur`s`

after that day's midnight.

`val of_span_since_start_of_day_exn : Span.t -> t`

`val of_span_since_start_of_day : Span.t -> t`

`val span_since_start_of_day_is_valid : Span.t -> Core_kernel__.Import.bool`

Reports whether a span represents a valid time since the start of the day, i.e. whether

`of_span_since_start_of_day_exn span`

would succeed.

`val of_span_since_start_of_day_unchecked : Span.t -> t`

`of_span_since_start_of_day_unchecked`

does not validate that the`Span`

represents a valid`Ofday`

.Behavior of other

`Ofday`

accessors is unspecified, but still safe (e.g., won't segfault), if the input does not satisfy`span_since_start_of_day_is_valid`

.

`val add : t -> Span.t -> t Core_kernel__.Import.option`

`add t s`

shifts the time of day`t`

by the span`s`

. It returns`None`

if the result is not in the same 24-hour day.

`val sub : t -> Span.t -> t Core_kernel__.Import.option`

`val next : t -> t Core_kernel__.Import.option`

`next t`

return the next`t`

(next t > t) or None if`t`

= end of day.

`val prev : t -> t Core_kernel__.Import.option`

`prev t`

return the previous`t`

(prev t < t) or None if`t`

= start of day.

`val diff : t -> t -> Span.t`

`diff t1 t2`

returns the difference in time between two ofdays, as if they occurred on the same 24-hour day.

`val small_diff : t -> t -> Span.t`

Returns the time-span separating the two of-days, ignoring the hour information, and assuming that the of-days represent times that are within a half-hour of each other. This is useful for comparing two ofdays in unknown time-zones.

`val to_string_trimmed : t -> Core_kernel__.Import.string`

Trailing groups of zeroes are trimmed such that the output is printed in terms of the smallest non-zero units among nanoseconds, microseconds, milliseconds, or seconds; or minutes if all of the above are zero.

`val to_sec_string : t -> Core_kernel__.Import.string`

HH:MM:SS, without any subsecond components. Seconds appear even if they are zero.

`val of_string_iso8601_extended : ?pos:Core_kernel__.Import.int -> ?len:Core_kernel__.Import.int -> Core_kernel__.Import.string -> t`

24-hour times according to the ISO 8601 standard. This function can raise.

`val to_millisecond_string : t -> Core_kernel__.Import.string`

with milliseconds

`val to_millisec_string : t -> Core_kernel__.Import.string`