(*****************************************************************************)
(*                                                                           *)
(* Open Source License                                                       *)
(* Copyright (c) 2021 Nomadic Labs <contact@nomadic-labs.com>                *)
(*                                                                           *)
(* Permission is hereby granted, free of charge, to any person obtaining a   *)
(* copy of this software and associated documentation files (the "Software"),*)
(* to deal in the Software without restriction, including without limitation *)
(* the rights to use, copy, modify, merge, publish, distribute, sublicense,  *)
(* and/or sell copies of the Software, and to permit persons to whom the     *)
(* Software is furnished to do so, subject to the following conditions:      *)
(*                                                                           *)
(* The above copyright notice and this permission notice shall be included   *)
(* in all copies or substantial portions of the Software.                    *)
(*                                                                           *)
(* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR*)
(* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  *)
(* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL   *)
(* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER*)
(* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING   *)
(* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER       *)
(* DEALINGS IN THE SOFTWARE.                                                 *)
(*                                                                           *)
(*****************************************************************************)

(** Slot index representation *)

(** {1 Abstract type} *)

(** A slot index is in essence a bounded whole number. That is, it is not
   allowed to overflow [max_value], nor does it wrap when calling [succ
   max_value]. In this case it returns an [Invalid_slot] error.*)
type t

type slot = t

val encoding : t Data_encoding.t

(** {1 Constructors }*)

val zero : t

(** Upper bound on the value a slot index can take *)
val max_value : t

(** [of_int i] creates a slot index from integer [i].

    @return [Error (Invalid_slot i)] if [i < 0 || i > max_value], and
            [Ok slot] otherwise
 *)
val of_int : int -> t tzresult

(** [of_int_do_not_use_except_for_parameters i] is an unchecked construction
   function.

   It may be used in cases where one knows [0 <= i <= max_value], e.g., when
   creating protocol parameters.

   When in doubt, use [of_int] or [of_int_exn].
 *)
val of_int_do_not_use_except_for_parameters : int -> t

(** {1 Operator and pretty-printer} *)

(** [succ n] either returns an [Invalid_slot] error if [n] is [max_value] or [ok
    value] otherwise. *)
val succ : t -> t tzresult

(** {1 Conversion/Printing} *)

(** [to_int slot] returns the integral representation of a slot index. This
    value is always a whole number. *)
val to_int : t -> int

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

(** {1 Submodules} *)

module Map : Map.S with type key = t

module Set : Set.S with type elt = t

include Compare.S with type t := t

(** {2 Slot ranges} *)
module Range : sig
  (** An ordered range of slots, in increasing order. *)
  type t

  (** {3 Constructor} *)

  (** [create ~min ~count] creates a full slot range starting at [min], of size
      [count], i.e, [min, min + count - 1].

      [create] errors if
      - [min < 0]
      - [count < 1]
      - [min + count - 1 > max_value]
   *)
  val create : min:int -> count:int -> t tzresult

  (** {3 Iterators} *)

  (** [fold f acc range] folds [f] over the values of [range], in increasing
      order. *)
  val fold : ('a -> slot -> 'a) -> 'a -> t -> 'a

  (** [fold_es f acc range] folds [f] over the values of [range], in increasing
      order. *)
  val fold_es :
    ('a -> slot -> 'a tzresult Lwt.t) -> 'a -> t -> 'a tzresult Lwt.t

  (** [rev_fold_es f acc range] folds [f] over the values of [range], in decreasing
      order. *)
  val rev_fold_es :
    ('a -> slot -> 'a tzresult Lwt.t) -> 'a -> t -> 'a tzresult Lwt.t
end

module Internal_for_tests : sig
  val of_int : int -> t tzresult
end