package tezos-base

  1. Overview
  2. Docs
package tezos-base
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.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.