Data.List.HasLength

This module implements a relation between a natural number and a list.
The relation witnesses the fact the number is the length of the list.

It is meant to be used in a runtime-irrelevant fashion in computations
manipulating data indexed over lists where the computation actually only
depends on the length of said lists.

Instead of writing:
```idris example
f0 : (xs : List a) -> P xs
```

We would write either of:
```idris example
f1 : (n : Nat) -> (0 _ : HasLength xs n) -> P xs
f2 : (n : Subset n (HasLength xs)) -> P xs
```

See `sucR` for an example where the update to the runtime-relevant Nat is O(1)
but the udpate to the list (were we to keep it around) an O(n) traversal.

Definitions

data HasLength : List a -> Nat -> Type

  Ensure that the list's length is the provided natural number

Totality: total
Visibility: public export
Constructors:

Z : HasLength [] 0

S : HasLength xs n -> HasLength (x :: xs) (S n)

hasLengthUnique : HasLength xs m -> HasLength xs n -> m = n

  The length is unique

Totality: total
Visibility: export

hasLength : (xs : List a) -> HasLength xs (length xs)

  This specification corresponds to the length function

Totality: total
Visibility: export

map : (f : (a -> b)) -> HasLength xs n -> HasLength (map f xs) n

Totality: total
Visibility: export

sucR : HasLength xs n -> HasLength (snoc xs x) (S n)

  @sucR demonstrates that snoc only increases the lenght by one
  So performing this operation while carrying the list around would cost O(n)
  but relying on n together with an erased HasLength proof instead is O(1)

Totality: total
Visibility: export

data View : (xs : List a) -> Subset Nat (HasLength xs) -> Type

  We provide this view as a convenient way to perform nested pattern-matching
  on values of type `Subset Nat (HasLength xs)`. Functions using this view will
  be seen as terminating as long as the index list `xs` is left untouched.
  See e.g. listTerminating below for such a function.

Totality: total
Visibility: public export
Constructors:

Z : View [] (Element 0 Z)

S : (p : Subset Nat (HasLength xs)) -> View (x :: xs) (Element (S (fst p)) (S (snd p)))

view : (p : Subset Nat (HasLength xs)) -> View xs p

  Proof that the view covers all possible cases.

Totality: total
Visibility: export

data View : (xs : List a) -> (n : Nat) -> HasLength xs n -> Type

  We provide this view as a convenient way to perform nested pattern-matching
  on pairs of values of type `n : Nat` and `HasLength xs n`. If transformations
  to the list between recursive calls (e.g. mapping over the list) that prevent
  it from being a valid termination metric, it is best to take the Nat argument
  separately from the HasLength proof and the Subset view is not as useful anymore.
  See e.g. natTerminating below for (a contrived example of) such a function.

Totality: total
Visibility: public export
Constructors:

Z : View [] 0 Z

S : (n : Nat) -> (0 p : HasLength xs n) -> View (x :: xs) (S n) (S p)

view : (n : Nat) -> (0 p : HasLength xs n) -> View xs n p

  Proof that the view covers all possible cases.

Totality: total
Visibility: export