tezos-crypto

Tezos: library with all the cryptographic primitives used by Tezos
Legend:
Library
Module
Module type
Parameter
Class
Class type
Library tezos-crypto
include Tezos_stdlib.WeakRingTable.S with type key = t
type 'a t
type key = t
val create : int -> 'a t

create n is a table with at most n elements except when it has more. Specifically, the table may contain up to n _strongly-held_ bindings and an unlimited number of _weakly-held_ bindings.

Strongly-held bindings are not garbage collected. Weakly-held bindings may be garbage collected.

val add : 'a t -> key -> 'a -> unit

add t k v adds a strongly-held binding from key k to value v in the table. If the table is a full capacity for strongly-held bindings (i.e., if there are as many strongly-held bindings as the size specified when the table was created), the oldest strongly-held binding becomes weakly-held.

Note however, that when inserting multiple bindings to the same key in the table, the previous bindings become unavailable immediately, but they may still count towards the strongly-held binding limits until there are more calls to add. In other words, the size limit for the strongly-held bindings may be lowered when inserting bindings from the same key.

Unlike a usual hash-table, hash collisions are severe. Specifically, when inserting two elements that have the same hash, only the second element will be retrieved by find_opt, fold, and iter.

val fold : ( key -> 'a -> 'b -> 'b ) -> 'a t -> 'b -> 'b

fold f t acc folds the function f and value acc through the strongly-held bindings of t. It does not fold over the weakly-held bindings. Consequently, fold never folds over more bindings than the size bound of the table, even if the table temporarily holds more bindings.

val iter : ( key -> 'a -> unit ) -> 'a t -> unit

iter f t iterates the function f through the strongly-held bindings of t. It does not fold over the weakly-held bindings. Consequently, iter never calls f over more bindings than the size bound of the table, even if the table temporarily holds more bindings.

val find_opt : 'a t -> key -> 'a option

find_opt t k is Some v if t holds a binding from k to v and None otherwise. Whether the binding is strongly- or weakly-held does not affect find_opt. As a result:

  • find_opt is able to return values that fold or iter would miss.
  • find_opt may return a value, and then, if the GC decides to collect some weakly-held bindings, may not be able to return the same value even if the table was not used.
val remove : 'a t -> key -> unit

remove t k removes the binding from key to the associated element in t. This works regardless of whether the binding is strongly- or weakly-held.

Note however, that when removing a strongly-held binding, it may still count towards the limit of strongly-held bindings until further bindings are added.

val length : 'a t -> int

length t is the number of bindings currently held by t. This include both strongly- and weakly-held bindings. As a result, length t is greater or equal to fold (+) t 0.

val encoding : 'a Data_encoding.t -> 'a t Data_encoding.t