Utility Modules
===============

To ensure there are no external dependencies (including chicken eggs),
these modules re-implement any basic procedures which are required for
any algorithms used. And some advanced yet generic functionality as
well.

The modules are listed in alphabetical order.

### Dictionary

    (import util-dict-list)

This module implements a simple key/value dictionary using lists as
backend. All operations are O(n) with respect to time.

    (make-ldict [equality?/pairs [pairs]])

* ```equality?/pairs``` - procedure or list of pairs
* ```pairs``` - list of pairs

Creates a new ldict with configurable equality procedure, optionally
populating it with initial data.

If only one argument is given, the procedure checks whether it is a
list of equality procedure and acts accordingly.

    (ldict? v)

* ```v``` - any value

Returns ```#t``` if given value is a ldict.

    (ldict-empty? ld)

* ```ld``` - a ldict instance

Returns ```#t``` if given dictionary contains no keys.

    (ldict-contains? ld k)

* ```ld``` - a ldict instance
* ```k``` - a key compatible with given ldict

Returns ```#t``` if given ```ld``` contains given key ```k```.

    (ldict-ref ld k [default])

* ```ld``` - a ldict instance
* ```k``` - a compatible key
* ```default``` - optional fallback value

Retrieves the value associated with given key in given dictionary. If
the dictionary does not contain it and no default is given, an
exception is raised. Otherwise the default value is returned in case
of missing key.

    (ldict-remove ld k)

* ```ld``` - a ldict instance
* ```k``` - a compatible key

Returns a new dictionary with the record under given key removed. If
the dictionary does not contain the key ```k```, an error is raised.

    (ldict-set ld k v)

* ```ld``` - a ldict instance
* ```k``` - a compatible key
* ```v``` - a value to insert

Sets existing key ```k``` to the new value ```v``` or inserts it if it
is not already present in the dictionary ```ld```.

    (ldict-keys ld)

* ```ld``` - a ldict instance

Returns the list of keys stored in given dictionary.

    (ldict-map proc ld)

* ```proc``` - procedure accepting 1, 2 or 3 arguments
* ```ld``` - a ldict instance

Returns a new dictionary of the same type with all values processed by
given procedure.

If it accepts one argument, only the value is passed to it. If it
accepts two values, the key and the value is passed to it. And lastly
if it accepts three arguments, the key, value and numeric index
(starting from 0) are passed to it.

In all cases the value the procedure returns is taken as the new value
for given key.

    (ldict-filter pred? ld)

* ```pred?``` - predicate procedure
* ```ld``` -a ldict instance

Returns a new dictionary containing only key/value pairs matching the
given predicate. The procedure ```pred?``` must accept two arguments -
the key and the value.

    (ldict-reduce init proc ld)

* ```init``` - initial accumulator value
* ```proc``` - accumulating procedure
* ```ld``` - a ldict instance

Performs a reduce operation on the pairs of given dictionary using
```init``` as initial accumulator. The accumulating procedure must
accept three arguments: the value accumulated so far, the key and the
value.

    (ldict-equal? d1 d2 [equality?])

* ```d1``` - a ldict instance
* ```d2``` - a ldict instance
* ```equality?``` - optional equality? predicate for values

Returns ```#t``` if both dictionaries contain the same keys and their
values are equal according to the provided ```equality?``` predicate
which defaults to ```equal?```.

### Set (List)

    (import util-set-list)

This module implements linear-time set with custom comparator.

    (make-lset [comparator])

* ```comparator``` - comparison procedure, defaults to ```equal?```

Creates new lset with given comparator.

    (lset? v)

* ```v``` - any value

Returns ```#t``` if given value is a lset.

    (lset-empty? ls)

* ```ls``` - lset instance

Returns ```#t``` if given lset contains no elements.

    (lset-member? ls el)

* ```ls``` - lset instance
* ```el``` - element to check

Returns ```#t``` if given element ```el``` is contained in the lset
```ls``` using its equality comparator.

    (lset-count ls)

* ```ls``` - lset instance

Returns the number of elements in given lset.
  
    (lset-add ls [el ...])

* ```ls``` - lset instance
* ```el``` - element(s) to add

Adds given element(s) ```el``` to the lset instance ```ls``` returning
a new lset instance.

    (lset-remove ls el)

* ```ls``` - lset instance
* ```el``` - element to remove

If given lset instance ```ls``` contains the element ```el```
provided, it is removed and the new lset is returned. If the element
is not contained in ```ls```, it is returned intact.

    (list->lset lst [comparator])

* ```lst``` - list to convert
* ```comparator``` - equality comparison procedure, defaults to ```equal?```

Returns a new lset with the comparator provided containing all
elements in given list.

    (lset->list ls)

* ```ls``` - lset instance

Returns the list of elements in given lset.

    (lset-merge ls1 ls2)

* ```ls1``` - lset instance
* ```ls2``` - lset instance

Returns a new lset instance with all elements in both lset instances given.

    (lset-intersect ls1 ls2)

* ```ls1``` - lset instance
* ```ls2``` - lset instance

Returns a new lset instance containing elements present both in
```ls1``` and ```ls2```.

    (lset-subtract ls1 ls2)

Returns a new lset instance from ```ls1``` with all elements in
```ls2``` removed from it.

    (lset=? ls1 ls2)

* ```ls1``` - lset instance
* ```ls2``` - lset instance

Returns true if the sets contain exactly the same values.