----------------------------------
| ToolBox collection information |
----------------------------------

This is a short guide to use the right collection type for a particular
problem. A collection type is a class or internal type that is able to
store one or more data items and that provides functionality to quickly get,
store, remove and modify items. There is no best storage type. The types
differ in access and storage time and space, so it is important to choose the
right one.

The following collection types are available:
- Standard C array,
- ArrayList class,
- Graph class,
- HashMap and HashSet class,
- LinkedList classes (ContainingList and PointeredList),
- Stack classes (ContainingStack and PointeredStack).

The points the types differ in are:
- Ability to change the length of the collection (length),
- time to add or remove items and one of both ends (append),
- time to insert or remove items in the middle (insert),
- time to iterate through the collection (iterate),
- time to search for an item (search),
- additional memory for the collection structure (space).

There is a fundamental difference between the List, Stack and array types,
and the Hashtable class. HashMaps store key/value pairs and have no order.
HashSets store keys only, but work similar as hash maps.
All other types don't have named values, but they are ordered.

The Graph class is a special collection class. It stores data that is
linked not only like a chain (List collections), but like a mathematical
graph. It has similar features to the List collections.

If neither the HashMap, nor the Graph class suits, you should consider
which points interest you, and then choose the right type.
Here is the comparison table for all the classes:

            length    append      insert      iterate     search        space
C array     fixed     impossible  impossible  fastest     slow          best
ArrayList   variable  fast        fast        fast        slow          average
Graph       variable  fast        average     fast        slow          good
HashSet     variable  fast        fast        slow        fast          bad
HashMap     variable  fast        fast        slow        fast by key   bad
LinkedList  variable  fastest     average     fast        slow          good
Stack       variable  fastest     impossible  impossible  impossible    good

The Containing and Pointered collections differ in the following way:
The Containing collection is a bit faster than the Pointered, but
the Pointered is able to store the same item in several collections and
multiple times in the collection. The Containing collections are not able
to do that and you must derive your data from the containing item class
provided by the ToolBox.
