Module `Feat.Enum`

This module offers a concrete data type `'a enum` of enumerations of elements of type `'a`. Suppose that every element of type `'a` is implicitly assigned a certain size. Then, an enumeration is a function of an integer `s` to the (implicit, finite) sequence of all elements whose size is `s`.

`include FeatCore.EnumSig.ENUM with module IFSeq = IFSeq`
`module IFSeq = IFSeq`

This implementation of implicit finite sequences is used as a building block in the definition of the type `enum`, which follows.

`type 'a enum = int -> 'a IFSeq.seq`

An enumeration of type `'a enum` can be loosely thought of as a set of values of type `'a`, equipped with a notion of size. More precisely, it is a function of a size `s` to a subset of inhabitants of size `s`, presented as a sequence.

We expose the fact that enumerations are functions, instead of making `enum` an abstract type, because this allows the user to make recursive definitions. It is up to the user to ensure that recursion is well-founded; as a rule of thumb, every recursive call must appear under `pay`. It is also up to the user to take precautions so that these functions have constant time complexity (beyond the cost of an initialization phase). This is typically achieved by using a memoizing fixed point combinator instead of an ordinary recursive definition.

`val empty : 'a enum`

`empty` is the empty enumeration.

`val zero : 'a enum`

`zero` is a synonym for `empty`.

`val just : 'a -> 'a enum`

The enumeration `just x` contains just the element `x`, with size zero. `just x` is equivalent to `finite [x]`.

`val enum : 'a IFSeq.seq -> 'a enum`

The enumeration `enum x` contains the elements in the sequence `xs`, with size zero.

`val pay : 'a enum -> 'a enum`

The enumeration `pay e` contains the same elements as `e`, with a size that is increased by one with respect to `e`.

`val sum : 'a enum -> 'a enum -> 'a enum`

`sum e1 e2` is the union of the enumerations `e1` and `e2`. It is up to the user to ensure that the sets `e1` and `e2` are disjoint.

`val (++) : 'a enum -> 'a enum -> 'a enum`

`(++)` is a synonym for `sum`.

`val exists : 'a list -> ('a -> 'b enum) -> 'b enum`

`exists xs e` is the union of all enumerations of the form `e x`, where `x` is drawn from the list `xs`. (This is an indexed sum.) It is up to the user to ensure that the sets `e1` and `e2` are disjoint.

`val product : 'a enum -> 'b enum -> ('a * 'b) enum`

`product e1 e2` is the Cartesian product of the enumerations `e1` and `e2`.

`val (**) : 'a enum -> 'b enum -> ('a * 'b) enum`

`( ** )` is a synonym for `product`.

`val balanced_product : 'a enum -> 'b enum -> ('a * 'b) enum`

`balanced_product e1 e2` is a subset of the Cartesian product ```product e1 e2``` where the sizes of the left-hand and right-hand pair components must differ by at most one.

`val (*-*) : 'a enum -> 'b enum -> ('a * 'b) enum`

`( *-* )` is a synonym for `balanced_product`.

`val map : ('a -> 'b) -> 'a enum -> 'b enum`

`map phi e` is the image of the enumeration `e` through the function `phi`. It is up to the user to ensure that `phi` is injective.

`val finite : 'a list -> 'a enum`

The enumeration `finite xs` contains the elements in the list `xs`, with size zero.

`val bool : bool enum`

`bool` is equivalent to `finite [false; true]`.

`val list : 'a enum -> 'a list enum`

If `elem` is an enumeration of the type `'a`, then `list elem` is an enumeration of the type `'a list`. It is worth noting that every call to `list elem` produces a fresh memoizing function, so (if possible) one should avoid applying `list` twice to the same argument; that would be a waste of time and space.

`val dlist : ('env -> 'a list enum) Fix.fix -> ('env -> ('a * 'env) list) -> 'env -> 'a list enum`

Suppose we wish to enumerate lists of elements, where the validity of an element depends on which elements have appeared earlier in the list. For instance, we might wish to enumerate lists of instructions, where the set of permitted instructions at some point depends on the environment at this point, and each instruction produces an updated environment. If `fix` is a suitable fixed point combinator and if the function `elem` describes how elements depend on environments and how elements affect environments, then `dlist fix elem` is such an enumeration. Each list node is considered to have size 1. Because the function `elem` produces a list (as opposed to an enumeration), an element does not have a size.

The fixed point combinator `fix` is typically of the form `curried fix`, where `fix` is a fixed point combinator for keys of type `'env * int`. Memoization takes place at keys that are pairs of an environment and a size.

The function `elem` receives an environment and must return a list of pairs of an element and an updated environment.

`val sample : int -> 'a enum -> int -> int -> 'a Stdlib.Seq.t -> 'a Stdlib.Seq.t`

`sample m e i j k` is a sequence of at most `m` elements of every size comprised between `i` (included) and `j` (excluded) extracted out of the enumeration `e`, prepended in front of the existing sequence `k`. At every size, if there are at most `m` elements of this size, then all elements of this size are produced; otherwise, a random sample of `m` elements of this size is produced.