@rogolev/value 0.0.1

package/docs/types/array.md

@@ -0,0 +1,252 @@
+[Главная](../../README.md) / [Типы данных](../types.md) / Массивы
+
+---
+
+# Массивы
+
+## Массивы в JavaScript
+
+**Массив в JavaScript** — объект типа `Array`, позволяющий хранить набор из нескольких
+элементов под одним именем переменной.
+[Подробнее.](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
+
+Для массива `Array` оператор
+[typeof](https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Operators/typeof) возвращает
+`"object"`.
+
+```js
+const array = [1, 2, 3];
+Array.isArray(array); // true
+typeof array; // "object"
+```
+
+Данные массивы являются списками, а значит имеют индексные ключи (`0, 1, 2, ...`). Если вам нужен
+ассоциативный массив (массив пар ключ-значение, где ключи являются строками), то можно использовать
+объекты (`Object`).
+
+```js
+const array = {
+    key1: 'value1',
+    key2: 'value2',
+    key3: 'value3',
+};
+Array.isArray(array); // false
+typeof array; // "object"
+```
+
+Как видно из примера, оператор
+[typeof](https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Operators/typeof) для
+ассоциативного массива также возвращает `"object"`. Это правильно с точки зрения **JavaScript**, но
+нам бы хотелось, как-то различать массивы и объекты. Да, списки мы можем отличить от объекта с
+помощью метода `Array.isArray` или с помощью оператора `instanceof`, а как отличить ассоциативный
+массив от экземпляра класса **ES6**?
+
+### Задача
+
+Отличить ассоциативный массив от экземпляра класса.
+
+#### Решение 1
+
+Можно использовать встроенную коллекцию
+[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)
+добавленную в **ES6**.
+
+```js
+const map = new Map();
+map.set('key1', 'value1');
+map.set('key2', 'value2');
+map.set('key3', 'value3');
+console.log(map); // Map(3) {key1: "value1", key2: "value2", key...}
+```
+
+Передавать ключи и значения в метод `set` не всегда удобно. Можно передавать список ключей и
+значений в конструктор.
+
+```js
+const data = {
+    key1: 'value1',
+    key2: 'value2',
+    key3: 'value3',
+};
+const entries = Object.entries(data);
+const map = new Map(entries);
+console.log(map); // Map(3) {key1: "value1", key2: "value2", key...}
+```
+
+Передать объект `data` напрямую без преобразования в `entries` не получится.
+
+```js
+const data = {
+    key1: 'value1',
+    key2: 'value2',
+    key3: 'value3',
+};
+const map = new Map(data); // TypeError: object is not iterable (cannot read property Symbol(Symbol.iterator))
+```
+
+Отличить экземпляр
+[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) от
+экземпляра класса мы можем с помощью оператора `instanceof`.
+
+```js
+const map = new Map();
+map instanceof Map; // true
+```
+
+#### Решение 2
+
+Отличить ассоциативный массив от экземпляра класса можно проверкой его прототипа.
+
+```js
+const array = {
+    key1: 'value1',
+    key2: 'value2',
+    key3: 'value3',
+};
+Object.getPrototypeOf(array) === Object.prototype; // true
+
+const list = [1, 2, 3];
+Object.getPrototypeOf(list) === Object.prototype; // false
+
+const map = new Map();
+Object.getPrototypeOf(map) === Object.prototype; // false
+```
+
+Если прототипом является `Object.prototype`, значит это ассоциативный массив, иначе это экземпляр
+класса.
+
+#### Итог
+
+Подведем итог из приведенных выше решений:
+
+В качестве ассоциативных массивов в первом решении мы использовали экземпляры встроенной коллекции
+[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map), а во
+втором решении обычные объекты типа `Object`. У обоих подходов есть свои плюсы и минусы. Сравнение
+обоих подходов приведено в
+[этой таблице](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map#objects_vs._maps).
+
+Какой подход лучше? Все зависит от контекста. В одном конкретном случае будет предпочтительно
+использовать коллекцию
+[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map), в
+другом — объект типа `Object`, да и на вкус и цвет, как говорится.
+
+## Массивы в value.js
+
+Итак, когда мы разобрались с массивами в `JavaScript`, введем понятие массива в **value.js**.
+
+**Массив в value.js** — это и объект типа `Object` (ассоциативный массив), прототипом которого
+является `Object.prototype`, и объект типа `Array`, позволяющие хранить набор из нескольких
+элементов под одним именем переменной.
+
+```js
+const list = [1, 2, 3];
+const assoc = {
+    key1: 'value1',
+    key2: 'value2',
+    key3: 'value3',
+};
+
+is_array(list); // true
+is_array(assoc); // true
+
+gettype(list); // "array"
+gettype(assoc); // "array"
+```
+
+Как видно из примера функция [is_array](../helpers/is_array.md) рассматривает оба массива как
+равноценные по типу. Также для обоих массивов функция `gettype` возвращает одинаковые значения.
+
+При этом коллекция
+[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map), как и
+другие коллекции, считается экземпляром класса.
+
+```js
+const map = new Map();
+const set = new Set();
+
+is_array(map); // false
+is_array(set); // false
+
+gettype(map); // "object"
+gettype(set); // "object"
+```
+
+### Проверка типа
+
+Проверить, что переменная является массивом, можно с помощью функции
+[is_array](../helpers/is_array.md).
+
+```js
+const array = { foo: 'bar' };
+
+is_array(array); // true
+```
+
+### Привидение к типу
+
+Привести к массиву можно с помощью функции `to_array`.
+
+```js
+to_array(123); // [123]
+```
+
+### Примеры использования массивов в value.js
+
+#### Создание и использование списков
+
+```js
+const list = [1, 2, 3, 4, 5];
+console.log(list); // [1, 2, 3, 4, 5]
+console.log(list.length); // 5
+console.log(list[0]); // 1
+console.log(list[list.length - 1]); // 5
+```
+
+#### Создание и использование ассоциативных массивов
+
+```js
+const assoc = {
+    name: 'John',
+    age: 30,
+    city: 'New York',
+};
+console.log(assoc); // { name: 'John', age: 30, city: 'New York' }
+console.log(assoc.name); // John
+console.log(assoc['age']); // 30
+```
+
+#### Преобразование массивов в коллекции и обратно
+
+```js
+const array = { a: 1, b: 2, c: 3 };
+const entries = Object.entries(array);
+const map = new Map(entries);
+console.log(map); // Map(3) { 'a' => 1, 'b' => 2, 'c' => 3 }
+
+const newArray = Object.fromEntries(map);
+console.log(newArray); // { a: 1, b: 2, c: 3 }
+```
+
+#### Проверка типа массива
+
+```js
+const list = [1, 2, 3];
+const assoc = { key1: 'value1', key2: 'value2', key3: 'value3' };
+
+console.log(is_array(list)); // true
+console.log(is_array(assoc)); // true
+console.log(is_array(new Map())); // false
+console.log(is_array(new Set())); // false
+```
+
+#### Получение типа переменной
+
+```js
+const list = [1, 2, 3];
+const assoc = { key1: 'value1', key2: 'value2', key3: 'value3' };
+
+console.log(gettype(list)); // "array"
+console.log(gettype(assoc)); // "array"
+console.log(gettype(new Map())); // "object"
+console.log(gettype(new Set())); // "object"
+```

package/docs/types/bigint.md

@@ -0,0 +1,34 @@
+[Главная](../../README.md) / [Типы данных](../types.md) / Большое целое число
+
+# Большое целое число
+
+## Большое целое число в JavaScript
+
+`BigInt` – это специальный числовой тип, который предоставляет возможность работать с целыми числами
+произвольной длины.
+
+[Подробнее...](https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Global_Objects/BigInt)
+
+## Большое целое число в value.js
+
+Библиотека не вносит ни каких изменений в определение большого целого числа.
+
+### Проверка типа
+
+Проверить, является ли значение большим целым числом, можно с помощью функции
+[is_bigint](../helpers/is_bigint.md).
+
+```js
+is_bigint(10n); // true
+is_bigint(10); // false
+
+gettype(10n); // "bigint"
+```
+
+### Привидение к типу
+
+Привести к большому целому числу можно с помощью функции `to_bigint`.
+
+```js
+to_bigint(10); // 10n
+```

package/docs/types/boolean.md

@@ -0,0 +1,47 @@
+[Главная](../../README.md) / [Типы данных](../types.md) / Логическое значение
+
+# Логическое значение
+
+## Логическое значение в JavaScript
+
+**Булево (логическое) значение** — примитивный тип данных в информатике, который может
+принимать два возможных значения, иногда называемых истиной (`true`) и ложью (`false`).
+
+[Подробнее...](https://developer.mozilla.org/ru/docs/Glossary/Boolean)
+
+## Логическое значение в value.js
+
+Библиотека не вносит ни каких изменений в определение логического типа.
+
+### Проверка типа
+
+Проверить, что переменная имеет логический тип можно с помощью функции
+[is_bool](../helpers/is_bool.md) и [is_boolean](../helpers/is_boolean.md).
+
+```js
+is_bool(true); // true
+is_boolean(false); // true
+```
+
+### Привидение к типу
+
+Привести к логическому типу можно с помощью функции `to_bool` и `to_boolean`.
+
+```js
+to_bool(1); // true
+to_boolean(0); // false
+```
+
+### Примеры использования
+
+#### Пример 1
+
+```js
+is_bool(true); // true
+is_boolean(false); // true
+
+gettype(true); // "boolean"
+
+to_bool(1); // true
+to_boolean(0); // false
+```

package/docs/types/class.md

@@ -0,0 +1,36 @@
+[Главная](../../README.md) / [Типы данных](../types.md) / Класс
+
+# Класс
+
+## Класс в JavaScript
+
+Классы в **JavaScript** были введены в **ECMAScript 2015** и представляют собой синтаксический сахар
+над существующим в **JavaScript** механизмом прототипного наследования. Синтаксис классов не вводит
+новую объектно-ориентированную модель, а предоставляет более простой и понятный способ создания
+объектов и организации наследования.
+
+На самом деле <u>**классы**</u> &mdash; это <u>"специальные функции"</u>, поэтому точно также, как
+вы определяете функции, вы можете определять и классы.
+
+[Подробнее...](https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Classes)
+
+## Класс в value.js
+
+Библиотека не вносит ни каких изменений в определение класса, а лишь выделяет его как отдельный тип
+(`class`), отличая его от функции.
+
+### Проверка типа
+
+Проверить, является ли переменная классом, можно с помощью функции
+[is_class](../helpers/is_class.md).
+
+```js
+class stdClass {}
+function Func() {}
+
+is_class(stdClass); // true
+is_class(class {}); // true
+is_class(Func); // false
+
+gettype(stdClass); // "class"
+```

package/docs/types/float.md

@@ -0,0 +1,35 @@
+[Главная](../../README.md) / [Типы данных](../types.md) / Число с плавающей точкой
+
+# Число с плавающей точкой
+
+## Число с плавающей точкой в JavaScript
+
+В **JavaScript** нет отдельного типа для чисел с плавающей точкой. Они являются частью типа
+`number`, включающего как целые числа, так и числа с плавающей точкой.
+
+[Подробнее...](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)
+
+## Число с плавающей точкой в value.js
+
+Библиотека **value.js** упраздняет тип `number` и разбивает его на два новых типа: `integer` и
+`float`.
+
+### Проверка типа
+
+Проверить, является ли значение числом с плавающей точкой, можно с помощью функции
+[is_float](../helpers/is_float.md).
+
+```js
+is_float(3.14); // true
+is_float(3); // false
+
+gettype(3.14); // "float"
+```
+
+### Привидение к типу
+
+Привести значение к числу с плавающей точкой можно с помощью функции `to_float`.
+
+```js
+to_float('3.14'); // 3.14
+```

package/docs/types/function.md

@@ -0,0 +1,121 @@
+[Главная](../../README.md) / [Типы данных](../types.md) / Функция
+
+# Функция
+
+## Функция в JavaScript
+
+В общем случае, **функция** — это "подпрограмма", которую можно вызывать из внешнего (или
+внутреннего, в случае рекурсии) по отношению к функции кода.
+
+В **JavaScript** функции являются объектами первого класса, то есть: они являются объектами и с ними
+можно взаимодействовать и передавать их точно так же как любой другой объект. Если быть точным,
+функции — это объекты `Function`.
+
+[Подробнее...](https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Functions)
+
+### Классы ES6
+
+Классы в **JavaScript** были введены в **ECMAScript 2015** и представляют собой синтаксический сахар
+над существующим в **JavaScript** механизмом прототипного наследования. Синтаксис классов не вводит
+новую объектно-ориентированную модель, а предоставляет более простой и понятный способ создания
+объектов и организации наследования.
+
+На самом деле <u>**классы**</u> &mdash; это <u>"специальные функции"</u>, поэтому точно также, как
+вы определяете функции, вы можете определять и классы.
+
+[Подробнее...](https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Classes)
+
+## Функция в value.js
+
+Библиотека не вносит ни каких изменений в определение функции. Она лишь различает понятие функции и
+класса. Если в JavaScript класс &mdash; это функция по типу, то библиотека вводит новый тип для
+классов: `class`.
+
+### Проверка типа
+
+Проверить, является ли переменная функцией можно с помощью функции
+[is_function](../helpers/is_function.md).
+
+```js
+function func() {}
+
+is_function(func); // true
+is_function(function () {}); // true
+is_function(() => {}); // true
+```
+
+### Примеры использования
+
+#### Пример 1. Функция
+
+```js
+function func() {}
+
+is_function(func); // true
+is_function(function () {}); // true
+is_function(() => {}); // true
+
+gettype(func); // "function"
+```
+
+#### Пример 2. Класс
+
+```js
+class stdClass {}
+
+is_function(stdClass); // false
+is_function(class {}); // false
+
+gettype(stdClass); // "class"
+```
+
+### Дополнительные примеры
+
+#### Пример 3. Асинхронная функция
+
+```js
+async function asyncFunc() {}
+
+is_function(asyncFunc); // true
+gettype(asyncFunc); // "function"
+```
+
+#### Пример 4. Генератор
+
+```js
+function* generatorFunc() {}
+
+is_function(generatorFunc); // true
+gettype(generatorFunc); // "function"
+```
+
+#### Пример 5. Асинхронный генератор
+
+```js
+async function* asyncGeneratorFunc() {}
+
+is_function(asyncGeneratorFunc); // true
+gettype(asyncGeneratorFunc); // "function"
+```
+
+#### Пример 6. Функция без строкового представления
+
+```js
+const func = () => {};
+func.toString = undefined;
+
+is_function(func); // true
+gettype(func); // "function"
+```
+
+### Пример 7. Функция с методом toString
+
+```js
+const func = () => {};
+func.toString = function () {
+    return 'function';
+};
+
+is_function(func); // true
+gettype(func); // "function"
+```

package/docs/types/infinity.md

@@ -0,0 +1,32 @@
+[Главная](../../README.md) / [Типы данных](../types.md) / Бесконечность
+
+# Бесконечность
+
+## Бесконечность в JavaScript
+
+Глобальное свойство `Infinity` является числовым значением, представляющим бесконечность.
+
+Бесконечность имеет тип `number`.
+
+```js
+typeof Infinity; // "number"
+```
+
+[Подробнее...](https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Global_Objects/Infinity)
+
+## Бесконечность в value.js
+
+Библиотека не вносит ни каких изменений в определение бесконечности, а лишь выносит ее в отдельный
+тип `infinity`.
+
+### Проверка типа
+
+Проверить, является ли значение бесконечностью, можно с помощью функции
+[is_infinity](../helpers/is_infinity.md).
+
+```js
+is_infinity(Infinity); // true
+is_infinity(-Infinity); // true
+
+gettype(Infinity); // "infinity"
+```

package/docs/types/integer.md

@@ -0,0 +1,35 @@
+[Главная](../../README.md) / [Типы данных](../types.md) / Целое число
+
+# Целое число
+
+## Целое число в JavaScript
+
+В **JavaScript** нет отдельного типа для целых чисел. Они являются частью типа `number`, включающего
+как целые числа, так и числа с плавающей точкой.
+
+[Подробнее...](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)
+
+## Целое число в value.js
+
+Библиотека **value.js** упраздняет тип `number` и разбивает его на два новых типа: `integer` и
+`float`.
+
+### Проверка типа
+
+Проверить, является ли значение целым числом, можно с помощью функции [is_int](../helpers/is_int.md)
+и [is_integer](../helpers/is_integer.md).
+
+```js
+is_int(3); // true
+is_integer(3.14); // false
+
+gettype(3.14); // "integer"
+```
+
+### Привидение к типу
+
+Привести значение к числу с плавающей точкой можно с помощью функции `to_int`.
+
+```js
+to_int('3'); // 3
+```

package/docs/types/null.md

@@ -0,0 +1,23 @@
+[Главная](../../README.md) / [Типы данных](../types.md) / Нулевое значение
+
+# Нулевое значение
+
+## Нулевое значение в JavaScript
+
+Значение `null` представляет отсутствие какого-либо объектного значения.
+
+[Подробнее...](https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Operators/null)
+
+## Нулевое значение в value.js
+
+Библиотека не вносит ни каких изменений в определение нулевого значения.
+
+### Проверка типа
+
+Проверить, является ли значение нулевым, можно с помощью функции [is_null](../helpers/is_null.md).
+
+```js
+is_null(null); // true
+
+gettype(null); // "null"
+```

package/docs/types/object.md

@@ -0,0 +1,62 @@
+[Главная](../../README.md) / [Типы данных](../types.md) / Объект
+
+# Объект
+
+## Объект в JavaScript
+
+Тип `Object` используется для хранения различных коллекций с ключами и более сложных сущностей.
+
+Пример объекта:
+
+```js
+class stdClass {}
+
+const object1 = { foo: 'key' };
+const object2 = new stdClass();
+```
+
+[Подробнее...](https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Global_Objects/Object)
+
+## Объект в value.js
+
+**Объект** — это экземпляр класса **ES6**.
+
+Пример объекта:
+
+```js
+class stdClass {}
+
+const object = new stdClass();
+```
+
+Пример ассоциативного массива:
+
+```js
+const array = { foo: 'key' };
+```
+
+### Проверка типа
+
+Проверить, является ли значение объектом, можно с помощью функции
+[is_object](../helpers/is_object.md).
+
+```js
+class stdClass {}
+
+const object = new stdClass();
+const array = { foo: 'key' };
+
+is_object(object); // true
+is_object(array); // false
+
+gettype(object); // "object"
+gettype(array); // "array"
+```
+
+### Привидение к типу
+
+Привести значение к объекту можно с помощью функции `to_object`.
+
+```js
+to_object([1, 2, 3]); // { 0: 1, 1: 2, 2: 3 }
+```