package octez-libs

  1. Overview
  2. Docs
package octez-libs
Legend:
Library
Module
Module type
Parameter
Class
Class type

Protocol time

The out-of-protocol view of in-protocol timestamps. The precision of in-protocol timestamps are only precise to the second.

Note that the out-of-protocol view does not necessarily match the in-protocol representation.

type t

The type of protocol times

val epoch : t

Unix epoch is 1970-01-01 00:00:00 +0000 (UTC).

val min_rfc3339 : t

The first instant supported by RFC 3339, corresponds to 0000-01-01 00:00:00 +0000 (UTC).

val max_rfc3339 : t

The last instant supported by RFC 3339, corresponds to 9999-12-31 23:59:59 +0000 (UTC).

include Tezos_stdlib.Compare.S with type t := t
val (=) : t -> t -> bool

x = y iff compare x y = 0

val (<>) : t -> t -> bool

x <> y iff compare x y <> 0

val (<) : t -> t -> bool

x < y iff compare x y < 0

val (<=) : t -> t -> bool

x <= y iff compare x y <= 0

val (>=) : t -> t -> bool

x >= y iff compare x y >= 0

val (>) : t -> t -> bool

x > y iff compare x y > 0

val compare : t -> t -> int

compare an alias for the functor parameter's compare function

val equal : t -> t -> bool

equal x y iff compare x y = 0

val max : t -> t -> t

max x y is x if x >= y otherwise it is y

val min : t -> t -> t

min x y is x if x <= y otherwise it is y

val add : t -> int64 -> t

add t s is s seconds later than t

val diff : t -> t -> int64

diff a b is the number of seconds between a and b. It is negative if b is later than a.

Conversions to and from string representations

val of_notation : string -> t option

Convert a string in the RFC3339 format (e.g., "1970-01-01T00:00:00Z") into a protocol time. Invalid RFC3339 notations will return None.

Note that years outside the 0000-9999 range are invalid RFC3339-wise.

val of_notation_exn : string -> t

Convert a string in the RFC3339 format (e.g., "1970-01-01T00:00:00Z") into a protocol time. Invalid RFC3339 notations will raise Invalid_argument.

Note that years outside the 0000-9999 range are invalid RFC3339-wise.

val to_notation : t -> string

Convert a protocol time into an RFC3339 notation (e.g., "1970-01-01T00:00:00Z").

Note that years outside the 0000-9999 range will raise Invalid_argument as they are invalid RFC3339-wise.

Conversion to and from "number of seconds since epoch" representation.

val of_seconds : int64 -> t

Make a Protocol time from a number of seconds since the epoch.

val to_seconds : t -> int64

Convert a Protocol time into a number of seconds since the epoch.

Serialization functions

val encoding : t Data_encoding.t

Binary and JSON encoding.

Binary is always encoding/decoding as int64.

JSON is more complex (for backward compatibility and user-friendliness):

  • encoding uses the RFC3339 format (e.g., "1970-01-01T00:00:00Z") if the year is between 0000 and 9999 (RFC3339-compatible); otherwise it uses the int64 format
  • decoding tries to decode as an RFC3339 notation, and if it fails, it decodes as int64.
val rfc_encoding : t Data_encoding.t

Note: the RFC has a different range than the internal representation. Specifically, the RFC can only represent times between 0000-00-00 and 9999-12-31 (inclusive). The RFC-encoding fails for dates outside of this range.

For this reason, it is preferable to use encoding and only resort to rfc_encoding for human-readable format.

val rpc_arg : t Tezos_rpc.Arg.t

Pretty-printing functions

val pp : Format.formatter -> t -> unit

Pretty print as a number of seconds after epoch.

val pp_hum : Format.formatter -> t -> unit

Note: pretty-printing uses the RFC3339 for human-readability. As mentioned in the comment on rfc_encoding, this representation fails when given dates too far in the future (after 9999-12-31) or the past (before 0000-00-00).

For reliable, generic pretty-printing use pp.

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