package core_kernel

  1. Overview
  2. Docs
package core_kernel
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Source file span_intf.ml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
open! Import
open Std_internal

(** Parts represents the individual parts of a Span as if it were written out (it is the
    counterpart to [Span.create]). For example, 90 seconds is represented by:

    {[
      {sign = Pos; hr = 0; min = 1; sec = 30; ms = 0; ns = 0}
    ]}

    The fields will always be non-negative, and will never be large enough to form the
    next larger unit (e.g., [min < 60]). *)
module type Parts = sig
  type t = private
    { sign : Sign.t
    ; hr : int
    ; min : int
    ; sec : int
    ; ms : int
    ; us : int
    ; ns : int
    }
  [@@deriving compare, sexp]
end

module type S = sig
  (** Span.t represents a span of time (e.g. 7 minutes, 3 hours, 12.8 days).  The span
      may be positive or negative. *)
  type underlying

  type t = private underlying [@@deriving bin_io, hash, sexp, typerep]

  module Parts : Parts
  include Comparable_binable with type t := t
  include Comparable.With_zero with type t := t
  include Hashable_binable with type t := t
  include Pretty_printer.S with type t := t
  include Robustly_comparable with type t := t
  include Quickcheck.S_range with type t := t

  (** 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] and [sexp_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] and [t_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 to_string : t -> string

  val of_string : string -> t

  (** {6 values} *)

  val nanosecond : t
  val microsecond : t
  val millisecond : t
  val second : t
  val minute : t
  val hour : t
  val day : t

  (** 10^-6 seconds, used in robustly comparable operators (<., >., =., ...) to determine
      equality *)
  val robust_comparison_tolerance : t

  val zero : t

  (** [?sign] defaults to positive. Setting it to negative is equivalent to negating all
      the integers. *)
  val create
    :  ?sign:Sign.t
    -> ?day:int
    -> ?hr:int
    -> ?min:int
    -> ?sec:int
    -> ?ms:int
    -> ?us:int
    -> ?ns:int
    -> unit
    -> t

  val to_parts : t -> Parts.t

  (** {6 converters} *)

  val of_ns : float -> t
  val of_us : float -> t
  val of_ms : float -> t
  val of_sec : float -> t
  val of_int_sec : int -> t
  val of_int32_seconds : Int32.t -> t
  val of_int63_seconds : Int63.t -> t
  val of_min : float -> t
  val of_hr : float -> t
  val of_day : float -> t
  val to_ns : t -> float
  val to_us : t -> float
  val to_ms : t -> float
  val to_sec : t -> float
  val to_min : t -> float
  val to_hr : t -> float
  val to_day : t -> float

  (** [to_int63_seconds_round_down_exn t] returns the number of seconds represented by
      [t], rounded down, raising if the result is not representable as an [Int63.t]. *)
  val to_int63_seconds_round_down_exn : t -> Int63.t

  (** The only condition [to_proportional_float] is supposed to satisfy is that for all
      [t1, t2 : t]: [to_proportional_float t1 /. to_proportional_float t2 = t1 // t2]. *)
  val to_proportional_float : t -> float

  (** {6 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 ( + ) : t -> t -> t
  val ( - ) : t -> t -> t

  (** absolute value *)
  val abs : t -> t

  (** negation *)
  val neg : t -> t

  val scale : t -> float -> t
  val ( / ) : t -> float -> t
  val ( // ) : t -> t -> float

  (** [next t] is the smallest representable span greater than [t] (and therefore
      representation-dependent) *)
  val next : t -> t

  (** [prev t] is the largest representable span less than [t] (and therefore
      representation-dependent) *)
  val prev : t -> t

  (** [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
      {ul
      {li ["4h"] = 4 hours}
      {li ["5m"] = 5 minutes}
      {li ["4s"] = 4 seconds}
      {li ["10ms"] = 10 milliseconds}
      }

      only the most significant denomination is shown.
  *)
  val to_short_string : t -> string

  (** [to_unit_of_time t] = [Day] if [abs t >= day], [Hour] if [abs t >= hour], and so on
      down to [Microsecond] if [abs t >= microsecond], and [Nanosecond] otherwise. *)
  val to_unit_of_time : t -> Unit_of_time.t

  (** [of_unit_of_time unit_of_time] produces a [t] representing the corresponding span. *)
  val of_unit_of_time : Unit_of_time.t -> t

  (** [to_string_hum t ~delimiter ~decimals ~align_decimal ~unit_of_time] formats [t] 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 to_string_hum
    :  ?delimiter:char (** defaults to ['_'] *)
    -> ?decimals:int (** defaults to 3 *)
    -> ?align_decimal:bool (** defaults to [false] *)
    -> ?unit_of_time:Unit_of_time.t (** defaults to [to_unit_of_time t] *)
    -> t
    -> string

  (** [randomize t ~percent] returns a span +/- percent * original span.  Percent must be
      between 0% and 100% inclusive, and must be positive. *)
  val randomize : t -> percent:Percent.t -> t
end
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct