Matreshka.Array.jsdoc.js

/**
@class Seemple.Array
@module seemple/array
@inherits Seemple
@importance 1
@classdesc Класс ``Seemple.Array`` служит коллекцией во фреймворке Seemple.js. Он наследуется от класса {@link Seemple} и включает все его свойства и методы. Кроме этого, ``Seemple.Array`` имеет все методы, которые есть у обычного массива, тем самым упрощая изучение его возможностей.

#### Все методы, позаимствованные у встроенного Array работают аналогично их оригиналам

Программист, знакомый с методами нативного ``Array`` сразу может понять, каким методом можно добавить элемент (``push``, ``unshift``, ``splice``), каким удалить (``pop``, ``shift``, ``splice``), каким отсортировать (``sort``, ``reverse``) и т. д.

По причине того, что методы работают так же, как и оригинальные (с небольшими исключениями), они не приведены в этой документации по отдельности, а выведены в раздел {@link Seemple.Array#METHOD}.
```js
this.push(1, 2, 3);
this.pop();
```

#### Все методы, позаимствованные у встроенного Array, которые модифицируют массив могут быть вызваны с передачей объекта события

Для этого используется синтаксис ``метод_``, где нижнее подчеркивание в конце имени метода означает, что последним аргументом является объект события. Такие методы не приведены в этой документации, так как требуется запомнить только их синтаксис. См.  {@link Seemple.Array#METHOD_}.
```js
this.push_(1, 2, 3, {
	silent: true
});

this.pop_({
	foo: 'bar'
});
```

#### Разработчик имеет возможность отлавливать любые модификации данных

__При использовании методов, позаимствованных у встроенного ``Array`` генерируются события с соответствующим именем.__ Вызывая метод ``push``, генерируется событие ``push``, вызывая метод ``shift`` генерируется событие ``shift``, вызывая метод ``sort``, генерируется событие ``sort`` и так далее.
```js
this.on('push', evt => {
	console.log('push is called');
});

this.push(1, 2, 3);
```

__При добавлении элементов генерируются события ``add`` и ``addone``.__ Первое генерируется один раз на добавление (например, вы добавили несколько элементов с помощью ``push``, событие вызвалось только один раз), второе генерируется один раз на каждый добавленный элемент.

При срабатывании события ``add``, значением свойства  ``added`` объекта события передается массив добавленных элементов, а при срабатывании ``addone``, значением свойства ``addedItem`` - каждый отдельный добавленный элемент.

```js
this.on('add', evt => {
	console.log(evt.added); // [1,2,3]
});

this.push(1, 2, 3);
```
```js
// обработчик запустится трижды,
// так как в массив добавили три новых элемента
this.on('addone', evt {
	console.log(evt.addedItem); // 1 ... 2 ... 3
});

this.push(1, 2, 3);
```


__При удалении элементов действует та же логика__: ``remove`` срабатывает один раз, даже если удалено несколько элементов, а событие ``removeone`` срабатывает для каждого удаленного элемента индивидуально. При генерации события ``remove`` удаленные элементы содержатся в свойстве ``removed`` объекта события, а при генерации события ``removeone`` - каждый удаленный элемент содержится в свойстве ``removedItem``.

```js
this.push(1, 2, 3, 4, 5);

this.on('remove', evt => {
	console.log(evt.removed); // [2, 3, 4]
});

this.splice(1, 3);
```
```js
this.push(1, 2, 3, 4, 5);

// обработчик запустится трижды,
// так как из массива удалили три элемента
this.on('removeone', evt => {
	console.log(evt.removedItem); // 2 ... 3 ... 4
});

this.splice(1, 3);
```

__При каждой модификации массива генерируется событие ``modify``__, позволяя отловить все без исключения изменения в массиве (добавление, удаление, пересортировку).
```js
this.on('modify', evt => {
	console.log(evt.added);
	console.log(evt.removed);
});
```

__``length`` - это обычное свойство__ которое можно связывать с HTML элементом или отлавливать изменения с помощью события ``change:length``.

> Например, при добавлении трех элементов с помощью метода ``push`` с тремя аргументами, генерируются следующие события: ``push``, ``add``, ``addone`` (трижды), ``modify``, ``change:length``.

#### Model
Свойство {@link Seemple.Array#Model} определяет класс элементов, которые будет содержать коллекция. Рекомендуется наследовать ``Model`` от класса {@link Seemple.Object} или {@link Seemple.Array} (на случай, если требуется получить коллекцию коллекций), чтобы получить возможность конвертации массива в обычный массив рекурсивно методом {@link Seemple.Array#toJSON}.

#### Автоматический рендеринг
``Seemple.Array`` умеет автоматически отрисовывать элементы на странице при любых модификациях массива. За подробностями обратитесь к документации {@link Seemple.Array#itemRenderer}.

@see {@link Seemple.Array#itemRenderer}
@see {@link Seemple.Array#Model}

@example <caption>Создание экземпляра с нулевой длиной</caption>
new Seemple.Array();
@example <caption>Создание экземпляра с указанием длины</caption>
new Seemple.Array(42);
@example <caption>Передача элементов при создании</caption>
new Seemple.Array('Hi', { a: 'b' });
@example <caption>Наследование</caption>
class MyClass extends Seemple.Array {
	constructor(items) {
		super(...items).sayHello();
	}
	sayHello() {
		alert("Hello World!");
	}
}

@example <caption>Наследование, используя функцию {@link Seemple.Class}</caption>
const MyClass = Seemple.Class({
	extends: Seemple.Array,
	constructor(items) {
		this.recreate(items).sayHello();
	},
	sayHello() {
		alert("Hello World!");
	}
});
*/