cstd/README.md

CoffeeScript Standart Library

# Библиотека стандартных классов для кофескрипта/яваскрипта
[![Build Status](https://travis-ci.org/E-geek/cstd.svg?branch=master)](https://travis-ci.org/E-geek/cstd)
[![Coverage Status](https://coveralls.io/repos/github/E-geek/cstd/badge.svg)](https://coveralls.io/github/E-geek/cstd)

## Оглавление

1. [Оглавление](#Оглавление)
1. [Введение](#Введение)
1. [Общее описание классов](#Общее-описание-классов)
    2. [Легенда](#Легенда)
    2. [Атомы](#Атомы)
    2. [Контейнеры](#Контейнеры)
    2. [Даты](#Даты)
    2. [События](#События)
    2. [Кэш](#Кэш)
    2. [Ошибки](#Ошибки)

## Введение
Библиотека реализует набор примитивов, которые могут быть полезны. 
Примитивы создаются аналогично библиотеке STL для C++, 
но аналогичность не означает идиентичность.

Некоторые контейнеры могут уступать по скорости нативному массиву (например 
`Stack`), но гарантируют отсутствие утечек и странных скачков потребления 
памяти (в отличии от `Array`). Так же следует понимать зачем какой 
тип вы используете т.к. в противном случае получить просадку по 
скорости и памяти проще простого.
Методы, использование которых не желательно, зачастую имеют 
простор для оптимизации, но она отложена. О нежелательном использовании 
можно узнать из документации.

В библиотеке предусматриватся обратная совместимость поведения, 
без обратной совместимости отбрасывания ошибок. Это значит, 
что если метод в одной версии может обрабатывать 2 аргумента, 
а в следущей 3, то в первой версии он бросит исключение при 
работе с 3 аргументами, а во второй версии -- нет.
 
Библиотека полностью покрывается тестами, которые так же будут 
учавствовать в тестах на обратную совместимость. Естественно 
тесты исключений в обратной совместимости будут пропущены.

## Общее описание классов:
### Легенда:
* '<-' = extends (означает что класс слева унаследован от класса справа)
* '(abstract)' = класс абстрактный, если создавать объект на его основе,
то будет брошено исключение
* '(inner)' = класс не доступен через мостик `cstd`, для доступа надо подключать
самостоятельно
* '(native)' = уточнение, что речь идёт от встроенном классе, чтобы не путать

### Атомы
Атомами являются классы, котрые не наследуют никакой другой класс 
и не имплементируют в себе никакой класс вовсе.
Типичными атомами являются:

* `CSObject` (abstract) <- `Object`
* `Node` <- `CSObject`

### Контейнеры
Контейнерами являются классы, объекты которых хранят, обрабатывают, 
представляют и удаляют другие сущности (примитивы и объекты) 
по определённым для данного класса правилам. Контейнеры оперируют 
с узлами (`Node`) и обычно класс контейнера имеет метод (`fromArray`) создания 
кобъекта на основе представления массива. Реализованны:

* `Container` (abstract) <- `CSObject`
* `Stack` <- `Container`
* `Queue` <- `Container`
* `Deque` <- `Container`
* `List` <- `CSObject`
* `CircularList` <- `CSObject`
* `NodeQueue` (inner) <- `CSObject`

### Даты
Для возможности наследовать класс `Date` был создан промежуточный 
класс `CSDate`. В нём все методы дублируют оригинальный `Date` 
и есть гарантия наличия некоторых методов (напрмер `now`).

* `CSDate` <- `Date` (native)

### События
Для событий существует абстрактный класс `CSEmitter` объекта, 
создающего события и сам класс события `CSEvent`.

* `CSEmitter` <- `CSObject`
* `CSEvent` <- `CSObject`

### Кэш
Для кеширования по количеству объектов существует абстрактный класс `BaseCache`,
работающий на `NodeQueue` представлениях с примитивнейшим механизмом вытеснения.
Реализован полноценный LRU кэш (`LRUCache`) с алгоритмической сложностью 
доступа, посика, вставки О(1). Для всех кэшей публичны методы `get`, `set`, 
`clear`, а так же read-only свойства `length` и `maxSize`

* `BaseCache` (abstract) <- `CSObject`
* `LRUCache` <- `BaseCache`

### Ошибки
Для создания "своих" классов ошибок есть `CSError`, который сам так же может 
быть использован для бросания исключения. 

* `CSError` <- `Error` (native)