@cute-dw/core/assets/COLLECTIONS.md

This TypeScript library is the main part of a more powerfull package designed for the fast WEB software development. The cornerstone of the library is the **DataStore** class, which might be useful when you need a full control of the data, but do not need

## Cute Collections Framework

**Collections Framework** is a group of classes and interfaces denoted to work with an ordered set of the different data structures. The declared interfaces are in many ways similar to the well-known interfaces of the [Java Collections Framework](https://en.wikipedia.org/wiki/Java_collections_framework). But they are NOT completely identical and reflect the specifics of the JavaScript/TypeScript languages.

### Differences from Arrays ###
> Collections and arrays are similar in that they both hold references to objects and they can be managed as a group. However, unlike arrays, collections do not need to be assigned a certain capacity when instantiated. Collections can also grow and shrink in size automatically when objects are added or removed. (Wikipedia)

>Unlike `Java`, `Cute Collections` can hold basic data type elements (primitive types) such as `number`, `string`, `boolean` and `null`.

### Architecture ###
Almost all collections are derived from the `Collection` interface. `Collection` defines the basic parts of all collections. The interface states the _add_ and _remove_ methods for adding to and removing from a collection respectively. Also required is the _toArray_ method, which converts the collection into a simple array of all the elements in the collection. Finally, the _contains_ method checks if a specified element is in the collection. The `Collection` interface is a subinterface of `Iterable`, so any `Collection` may be the target of a `for-of` statement. All collections have an `iterable iterator` that goes through all of the elements in the collection. Additionally, `Collection` is a generic. Any collection can be written to store any class. For example, `Collection<string>` can hold strings, and the elements from the collection can be used as strings without any casting required. Note that the angled brackets < > can hold a type argument that specifies which type the collection holds.

### Three Types of Collection ###
There are three generic types of collection: ordered lists, dictionaries/maps, and sets.

_Ordered lists_ allows the programmer to insert items in a certain order and retrieve those items in the same order. An example is a waiting list. The base interfaces for ordered lists are called `List` and `Queue`.

_Dictionaries/Maps_ store references to objects with a lookup key to access the object's values. One example of a key is an identification card. The base interface for dictionaries/maps is the JavaScript's `Map` interface.

_Sets_ are unordered collections that can be iterated and contain each element at most once. The base interface for sets is derived from JavaScript's `Set` interface.

### List interface ###
Lists are implemented in the collections framework via the `List` interface. It defines a list as essentially a more flexible version of an array. Elements have a specific order, and duplicate elements are allowed. Elements can be placed in a specific position. They can also be searched for within the list. Two examples for concrete classes that implement `List` are:

- `ArrayList`, which implements the list as an array. Whenever functions specific to a list are required, the class moves the elements around within the array in order to do it.
- `LinkedList`. This class stores the elements in nodes that each have a pointer to the previous and next nodes in the list. The list can be traversed by following the pointers, and elements can be added or removed simply by changing the pointers around to place the node in its proper place.

### Stack class ###
Stacks are created using `Stack` class. The stack offers methods to put a new object on the stack (method _push_) and to get objects from the stack (method _pop_). A stack returns the object according to last-in-first-out (LIFO), e.g. the object which was placed latest on the stack is returned first. The `Stack` class extends class `Vector` with operations that allow a vector to be treated as a stack. The usual _push_ and _pop_ operations are provided, as well as a method to _peek_ at the top item on the stack, a method to test for whether the stack _is empty_, and a method to _search_ the stack for an item and discover how far it is from the top. When a stack is first created, it contains no items.

### Queue interfaces ###
The `Queue` interface defines the queue data structure, which stores elements in the order in which they are inserted. New additions go to the end of the line, and elements are removed from the front. It creates a first-in first-out system. This interface is implemented by `LinkedList` and `PriorityQueue`. `LinkedList`, of course, also implements the `List` interface and can also be used as one. But it also has the `Queue` methods. `LinkedList` also implements the `Deque` interface, giving it more flexibility.

`PriorityQueue` implements `Queue`, but also alters it. Instead of elements being ordered in the order in which they are inserted, they are ordered by priority. The method used to determine priority is a method given in the constructor. The class creates this by using a [heap](https://en.wikipedia.org/wiki/Heap_(data_structure)) to keep the items sorted.

### Double-ended queue (deque) interfaces ###
The `Queue` interface is expanded by the `Deque` subinterface. `Deque` creates a double-ended queue. While a regular queue only allows insertions at the rear and removals at the front, the deque allows insertions or removals to take place both at the front and the back. A deque is like a queue that can be used forwards or backwards, or both at once. Additionally, both a forwards and a backwards iterator can be generated. The `Deque` interface is implemented by `LinkedList`.

### Set interfaces ###
JavaScript's `Set` interface defines the set. A set can't have any duplicate elements in it. Additionally, the set has no set order. As such, elements can't be found by index. Set is implemented by native JavaScript's [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) object, `HashSet` and `TreeSet` classes. `TreeSet` uses a AVL tree implemented by a `TreeMap` class. The [AVL tree](https://en.wikipedia.org/wiki/AVL_tree) makes sure that there are no duplicates. Additionally, it allows `TreeSet` to implement `SortedSet`.

The `Set` interface is extended by the `SortedSet` interface. Unlike a regular set, the elements in a sorted set are sorted by a method provided to the constructor of the sorted set. The first and last elements of the sorted set can be retrieved, and subsets can be created via minimum and maximum values, as well as beginning or ending at the beginning or ending of the sorted set. The `SortedSet` interface is implemented by `TreeSet`.

`SortedSet` is extended further via the `NavigableSet` interface. It's similar to `SortedSet`, but there are a few additional methods. The _floor_, _ceiling_, _lower_, and _higher_ methods find an element in the set that's close to the parameter. As with `SortedSet`, `TreeSet` implements `NavigableSet`.

>Unlike JavaScript's [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) object, keys in the set-classes of the `Collections Framework` CAN NOT have _undefined_ values.    

### Map interfaces ###
Maps are defined by the JavaScript's `Map` interface. Maps are simple data structures that associate a key with an element. This lets the map be very flexible. If the key is the hash code of the element, the map is essentially a set. If it's just an increasing number, it becomes a list. Maps are implemented by the native JavaScript's [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object, `HashMap` and `TreeMap` classes. `TreeMap` uses a [AVL tree](https://en.wikipedia.org/wiki/AVL_tree) inside. The keys are used as the values for the nodes in the tree, and the nodes point to the elements in the map.

The JavaScript's `Map` interface is extended by its subinterface, `SortedMap`. This interface defines a map that's sorted by the keys provided. Using a method provided in the constructor to the sorted map, the key-element pairs are sorted by the keys. The first and last keys in the map can be called. `SortedMap` is implemented by `TreeMap`.

The `NavigableMap` interface extends `SortedMap` in various ways. Methods can be called that find the key or map entry that's closest to the given key in either direction. It's implemented by `TreeMap`.

>Unlike JavaScript's [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object, keys in the map-classes of the `Collections Framework` CAN NOT have _undefined_ values.    

### Immutability ###
Every object created from this framework has an Immutable interface that is safe to pass around confident that the object cannot be changed via the methods exposed by the Immutable interface. In fact, the root mutable interface `Collection` inherits from `ImmutableCollection`, which defines the immutable part of the former interface. Similarly, all mutable Lists inherit from `ImmutableList`, all Sets inherit from `ImmutableSet` and all Maps implement `ImmutableMap` interface.