Module Basic.Span
type underlying
Span.t represents a span of time (e.g. 7 minutes, 3 hours, 12.8 days). The span may be positive or negative.
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 variantt
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
val hash_fold_t : Base.Hash.state -> t -> Base.Hash.state
val hash : t -> Base.Hash.hash_value
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
module Parts : Core_kernel__.Span_intf.Parts
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 tocompare
.descending x y = ascending y x
. These are intended to be mnemonic when used likeList.sort ~compare:ascending
andList.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
meanslow <= t <= high
val clamp_exn : t -> min:t -> max:t -> t
clamp_exn t ~min ~max
returnst'
, the closest value tot
such thatbetween 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.Comparable.With_zero with type t := t
val validate_positive : t Base.Validate.check
val validate_non_negative : t Base.Validate.check
val validate_negative : t Base.Validate.check
val validate_non_positive : t Base.Validate.check
val is_positive : t -> bool
val is_non_negative : t -> bool
val is_negative : t -> bool
val is_non_positive : t -> bool
val sign : t -> Base__.Sign0.t
Returns
Neg
,Zero
, orPos
in a way consistent with the above functions.
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 betweenlower_bound
andupper_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 iflower_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 betweenlower_bound
andupper_bound
, inclusive. Raises iflower_bound > upper_bound
.
val to_string : t -> Core_kernel__.Import.string
Time spans are denominated as a float suffixed by a unit of time; the valid suffixes are listed below:
d - days h - hours m - minutes s - seconds ms - milliseconds us - microseconds ns - nanoseconds
to_string
andsexp_of_t
use a mixed-unit format, which breaks the input span into parts and concatenates them in descending order of unit size. For example, pi days is rendered as "3d3h23m53.60527015815s". If the span is negative, a single "-" precedes the entire string. For extremely large (>10^15 days) or small (<1us) spans, a unit may be repeated to ensure the string conversion round-trips.of_string
andt_of_sexp
accept any combination of (nonnegative float string)(unit of time suffix) in any order, without spaces, and sums up the durations of each of the parts for the magnitude of the span. The input may be prefixed by "-" for negative spans.String and sexp conversions round-trip precisely, that is:
Span.of_string (Span.to_string t) = t
val of_string : Core_kernel__.Import.string -> t
values
val nanosecond : t
val microsecond : t
val millisecond : t
val second : t
val minute : t
val hour : t
val day : t
val robust_comparison_tolerance : t
10^-6 seconds, used in robustly comparable operators (<., >., =., ...) to determine equality
val zero : t
val create : ?sign:Core_kernel.Sign.t -> ?day:Core_kernel__.Import.int -> ?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
?sign
defaults to positive. Setting it to negative is equivalent to negating all the integers.
converters
val of_ns : Core_kernel__.Import.float -> t
val of_us : Core_kernel__.Import.float -> t
val of_ms : Core_kernel__.Import.float -> t
val of_sec : Core_kernel__.Import.float -> t
val of_int_sec : Core_kernel__.Import.int -> t
val of_int32_seconds : Core_kernel.Int32.t -> t
val of_int63_seconds : Core_kernel.Int63.t -> t
val of_min : Core_kernel__.Import.float -> t
val of_hr : Core_kernel__.Import.float -> t
val of_day : Core_kernel__.Import.float -> t
val to_ns : t -> Core_kernel__.Import.float
val to_us : t -> Core_kernel__.Import.float
val to_ms : t -> Core_kernel__.Import.float
val to_sec : t -> Core_kernel__.Import.float
val to_min : t -> Core_kernel__.Import.float
val to_hr : t -> Core_kernel__.Import.float
val to_day : t -> Core_kernel__.Import.float
val to_int63_seconds_round_down_exn : t -> Core_kernel.Int63.t
to_int63_seconds_round_down_exn t
returns the number of seconds represented byt
, rounded down, raising if the result is not representable as anInt63.t
.
val to_proportional_float : t -> Core_kernel__.Import.float
The only condition
to_proportional_float
is supposed to satisfy is that for allt1, t2 : t
:to_proportional_float t1 /. to_proportional_float t2 = t1 // t2
.
Basic operations on spans
The arithmetic operations rely on the behavior of the underlying representation of a span. For example, if addition overflows with float-represented spans, the result is an infinite span; with fixed-width integer-represented spans, the result silently wraps around as in two's-complement arithmetic.
val scale : t -> Core_kernel__.Import.float -> t
val (/) : t -> Core_kernel__.Import.float -> t
val (//) : t -> t -> Core_kernel__.Import.float
val next : t -> t
next t
is the smallest representable span greater thant
(and therefore representation-dependent)
val prev : t -> t
prev t
is the largest representable span less thant
(and therefore representation-dependent)
val to_short_string : t -> Core_kernel__.Import.string
to_short_string t
pretty-prints approximate time span using no more than five characters if the span is positive, and six if the span is negative. Examples"4h"
= 4 hours"5m"
= 5 minutes"4s"
= 4 seconds"10ms"
= 10 milliseconds
only the most significant denomination is shown.
val to_unit_of_time : t -> Core_kernel.Unit_of_time.t
to_unit_of_time t
=Day
ifabs t >= day
,Hour
ifabs t >= hour
, and so on down toMicrosecond
ifabs t >= microsecond
, andNanosecond
otherwise.
val of_unit_of_time : Core_kernel.Unit_of_time.t -> t
of_unit_of_time unit_of_time
produces at
representing the corresponding span.
val to_string_hum : ?delimiter:Core_kernel__.Import.char -> ?decimals:Core_kernel__.Import.int -> ?align_decimal:Core_kernel__.Import.bool -> ?unit_of_time:Core_kernel.Unit_of_time.t -> t -> Core_kernel__.Import.string
to_string_hum t ~delimiter ~decimals ~align_decimal ~unit_of_time
formatst
using the given unit of time, or the largest appropriate units if none is specified, among "d"=day, "h"=hour, "m"=minute, "s"=second, "ms"=millisecond, "us"=microsecond, or "ns"=nanosecond. The magnitude of the time span in the chosen unit is formatted by:Float.to_string_hum ~delimiter ~decimals ~strip_zero:(not align_decimal)
If
align_decimal
is true, the single-character suffixes are padded with an extra space character. In combination with not stripping zeroes, this means that the decimal point will occur a fixed number of characters from the end of the string.
val randomize : t -> percent:Core_kernel.Percent.t -> t
randomize t ~percent
returns a span +/- percent * original span. Percent must be between 0% and 100% inclusive, and must be positive.