(*****************************************************************************)
(*                                                                           *)
(* Open Source License                                                       *)
(* Copyright (c) 2022 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.                                                 *)
(*                                                                           *)
(*****************************************************************************)

(** In transaction rollups, some values can be replaced by indexes in
    the messages sent from the layer-1 to the layer-2.

    This module provides various type-safe helpers to manipulate these
    particular values. *)

type value_only = Value_only

type index_only = Index_only

type unknown = Unknown

(** An indexable value is a value which can be replaced by an
    integer. The first type parameter determines whether or not this
    replacement has happened already. *)
type (_, 'a) t = private
  | Value : 'a -> (value_only, 'a) t
  | Hidden_value : 'a -> (unknown, 'a) t
  | Index : int32 -> (index_only, 'a) t
  | Hidden_index : int32 -> (unknown, 'a) t

(** The type of indexable values identified as not being indexes. *)
type 'a value = (value_only, 'a) t

(** The type of indexable values identified as being indexes. *)
type 'a index = (index_only, 'a) t

(** The type of indexable values whose content is still unknown. *)
type 'a either = (unknown, 'a) t

(** [value v] wraps [v] into an indexable value identified as not
    being an index. *)
val value : 'a -> 'a value

(** [from_value v] wraps [v] into an indexable value, but forget about
    the nature of the content of the result. *)
val from_value : 'a -> 'a either

(** [index i] wraps [i] into an indexable value identified as being an
    index.

    Returns the error [Index_cannot_be_negative] iff [i <= 0l]. *)
val index : int32 -> 'a index tzresult

(** [from_index i] wraps [i] into an indexable value, but forget about the
    nature of the content of the result.

    Returns the error [Index_cannot_be_negative] iff [i <= 0l]. *)
val from_index : int32 -> 'a either tzresult

(** [index_exn i] wraps [i] into an indexable value identified as
    being an index.

    @raise Invalid_argument iff [i <= 0l]. *)
val index_exn : int32 -> 'a index

(** [from_index_exn i] wraps [i] into an indexable value, but forget
    about the nature of the content of the result.

    @raise Invalid_argument iff [i <= 0l]. *)
val from_index_exn : int32 -> 'a either

(** [compact val_encoding] is a combinator to derive a compact
    encoding for an indexable value of type ['a] from an encoding for
    ['a]. It uses two bits in the shared tag. [00] is used for indexes
    fitting in one byte, [01] for indexes fitting in two bytes, [10]
    for indexes fitting in four bytes, and [11] for the values of type
    ['a]. *)
val compact : 'a Data_encoding.t -> (unknown, 'a) t Data_encoding.Compact.t

val encoding : 'a Data_encoding.t -> (unknown, 'a) t Data_encoding.t

val pp :
  (Format.formatter -> 'a -> unit) -> Format.formatter -> ('state, 'a) t -> unit

(** [destruct x] returns either the index or the (unwrapped) value
    contained in [x].

    {b Note:} If you want to manipulate a value of type ['a value],
    you can use {!value}. *)
val destruct : ('state, 'a) t -> ('a index, 'a) Either.t

(** [forget x] returns an indexable value whose kind of contents has
    been forgotten. *)
val forget : ('state, 'a) t -> (unknown, 'a) t

(** [to_int32 x] unwraps and returns the integer behind [x]. *)
val to_int32 : 'a index -> int32

(** [to_value x] unwraps and returns the value behind [x]. *)
val to_value : 'a value -> 'a

(** [is_value_e err x] unwraps and returns the value behind [x], and
    throws an [err] if [x] is an index. *)
val is_value_e : error:'trace -> ('state, 'a) t -> ('a, 'trace) result

(** [in_memory_size a] returns the number of bytes allocated in RAM for [a]. *)
val in_memory_size :
  ('a -> Cache_memory_helpers.sint) ->
  ('state, 'a) t ->
  Cache_memory_helpers.sint

(** [size a] returns the number of bytes allocated in an inbox to store [a]. *)
val size : ('a -> int) -> ('state, 'a) t -> int

(** [compare f x y] is a total order on indexable values, which
    proceeds as follows.

    {ul {li If both [x] and [y] are a value, then use [f] to compare them.}
        {li If both [x] and [y] are indexes, then uses the
            [Int32.compare] function to compare them.}
        {li Finally, if [x] and [y] have not the same kind, the logic
            is that indexes are smaller than values.}}

    {b Note:} This can be dangerous, as you may end up comparing two
    things that are equivalent (a value and its index) but declare
    they are not equal. *)
val compare : ('a -> 'a -> int) -> ('state, 'a) t -> ('state', 'a) t -> int

(** [compare_values f x y] compares the value [x] and [y] using [f],
    and relies on the type system of OCaml to ensure that [x] and [y]
    are indeed both values. *)
val compare_values : ('a -> 'a -> int) -> 'a value -> 'a value -> int

(** [compare_indexes x y] compares the indexes [x] and [y], and relies
    on the type system of OCaml to ensure that [x] and [y] are indeed
    both indexes. *)
val compare_indexes : 'a index -> 'a index -> int

module type VALUE = sig
  type t

  val encoding : t Data_encoding.t

  val compare : t -> t -> int

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

module Make (V : VALUE) : sig
  type nonrec 'state t = ('state, V.t) t

  type nonrec index = V.t index

  type nonrec value = V.t value

  type nonrec either = V.t either

  val value : V.t -> value

  val index : int32 -> index tzresult

  val index_exn : int32 -> index

  val compact : either Data_encoding.Compact.t

  val encoding : either Data_encoding.t

  val index_encoding : index Data_encoding.t

  val value_encoding : value Data_encoding.t

  val compare : 'state t -> 'state' t -> int

  val compare_values : value -> value -> int

  val compare_indexes : index -> index -> int

  val pp : Format.formatter -> 'state t -> unit
end

type error += Index_cannot_be_negative of int32