@rogolev/value 0.0.3 → 0.0.4

package/docs/helpers/array/in_array.md

@@ -0,0 +1,65 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / in_array
+
+[Исходный код](../../../src/helpers/array/in_array.mjs)
+
+# in_array
+
+`in_array` — Проверяет, существует ли значение в массиве.
+
+## Сигнатура функции
+
+```ts
+function in_array(arr: object, value: any, strict: boolean = false): boolean;
+```
+
+## Описание
+
+Функция `in_array` используется для проверки, существует ли значение в массиве. Она поддерживает как
+обычные массивы, так и ассоциативные массивы (объекты с ключами и значениями). Функция может
+работать в строгом режиме, сравнивая значения с учетом типа.
+
+## Параметры
+
+- `arr` (object): Исходный массив.
+- `value` (any): Значение для поиска.
+- `strict` (boolean): Флаг строгого сравнения. По умолчанию `false`.
+
+## Возвращаемое значение
+
+Возвращает `true`, если значение существует в массиве, иначе `false`.
+
+## Примеры использования
+
+1. Проверка значения в обычном массиве:
+
+    ```js
+    const array = [1, 2, 3, 4, 5];
+    const result = in_array(array, 3);
+    console.log(result); // true
+    ```
+
+2. Проверка значения в ассоциативном массиве:
+
+    ```js
+    const array = { a: 1, b: 2, c: 3 };
+    const result = in_array(array, 2);
+    console.log(result); // true
+    ```
+
+3. Проверка значения с использованием строгого сравнения:
+
+    ```js
+    const array = [1, '2', 3];
+    const result = in_array(array, 2, true);
+    console.log(result); // false
+    ```
+
+4. Обработка значений, не являющихся массивами:
+
+    ```js
+    try {
+        const result = in_array('not an array', 1);
+    } catch (e) {
+        console.error(e.message); // Параметр "arr" должен быть массивом.
+    }
+    ```

package/docs/helpers/array/natsort.md

@@ -0,0 +1,60 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / natsort
+
+[Исходный код](../../../src/helpers/array/natsort.mjs)
+
+# natsort
+
+`natsort` — Сортирует массив в естественном порядке.
+
+## Сигнатура функции
+
+```ts
+function natsort(arr: object, getter: function = (entry) => entry[1]): array;
+```
+
+## Описание
+
+Функция `natsort` используется для сортировки массива в естественном порядке. Она поддерживает как
+обычные массивы, так и ассоциативные массивы (объекты с ключами и значениями). Функция принимает
+необязательный параметр `getter`, который используется для получения значения для сравнения.
+
+## Параметры
+
+- `arr` (object): Исходный массив.
+- `getter` (function): Функция для получения значения для сравнения. По умолчанию
+  `(entry) => entry[1]`.
+
+## Возвращаемое значение
+
+Возвращает новый массив, отсортированный в естественном порядке.
+
+## Примеры использования
+
+1. Сортировка обычного массива:
+
+    ```js
+    const array = [10, 2, 30, 4];
+    const result = natsort(array);
+    console.log(result); // [2, 4, 10, 30]
+    ```
+
+2. Сортировка ассоциативного массива:
+
+    ```js
+    const array = { a: 10, b: 2, c: 30, d: 4 };
+    const result = natsort(array);
+    console.log(result); // [['b', 2], ['d', 4], ['a', 10], ['c', 30]]
+    ```
+
+3. Сортировка массива с использованием функции `getter`:
+
+    ```js
+    const array = [{ value: 10 }, { value: 2 }, { value: 30 }, { value: 4 }];
+    const result = natsort(array, (entry) => entry[1].value);
+    console.log(result); // [{ value: 2 }, { value: 4 }, { value: 10 }, { value: 30 }]
+    ```
+
+## Исключения
+
+- `TypeError`: Если параметр `arr` не является массивом.
+- `TypeError`: Если параметр `getter` не является функцией.

package/docs/helpers/array/range.md

@@ -0,0 +1,76 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / range
+
+[Исходный код](../../../src/helpers/array/range.mjs)
+
+# range
+
+`range` — Генерирует массив значений от start до end с шагом step.
+
+## Сигнатура функции
+
+```ts
+function range(start: string | number, end: string | number, step: number = 1): Array<any>;
+```
+
+## Описание
+
+Функция `range` используется для генерации массива значений от начального значения до конечного с
+заданным шагом. Она поддерживает как числовые значения, так и строки. Шаг не может быть равен нулю.
+
+## Параметры
+
+- `start` (string | number): Начальное значение (строка или число).
+- `end` (string | number): Конечное значение (строка или число).
+- `step` (number): Шаг между значениями. По умолчанию `1`.
+
+## Возвращаемое значение
+
+Возвращает массив значений от start до end с шагом step.
+
+## Примеры использования
+
+1. Генерация числового диапазона:
+
+    ```js
+    const result = range(1, 5);
+    console.log(result); // [1, 2, 3, 4, 5]
+    ```
+
+2. Генерация диапазона с отрицательным шагом:
+
+    ```js
+    const result = range(5, 1, -1);
+    console.log(result); // [5, 4, 3, 2, 1]
+    ```
+
+3. Генерация диапазона строк:
+
+    ```js
+    const result = range('a', 'e');
+    console.log(result); // ['a', 'b', 'c', 'd', 'e']
+    ```
+
+4. Обработка значений с преобразованием типов:
+
+    ```js
+    const result = range('1', 5);
+    console.log(result); // [1, 2, 3, 4, 5]
+    ```
+
+5. Обработка пустых строк:
+
+    ```js
+    const result = range('', 3);
+    console.log(result); // [0, 1, 2, 3]
+    ```
+
+6. Обработка строк и чисел:
+
+    ```js
+    const result = range('1', '5');
+    console.log(result); // [1, 2, 3, 4, 5]
+    ```
+
+## Исключения
+
+- `TypeError`: Если параметры имеют неверный тип или значение.

package/docs/helpers/array/shuffle.md

@@ -0,0 +1,74 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / shuffle
+
+[Исходный код](../../../src/helpers/array/shuffle.mjs)
+
+# shuffle
+
+`shuffle` — Перемешивает элементы массива в случайном порядке.
+
+## Сигнатура функции
+
+```ts
+function shuffle(arr: object): Array<any>;
+```
+
+## Описание
+
+Функция `shuffle` используется для перемешивания элементов массива в случайном порядке. Она
+поддерживает как обычные массивы, так и ассоциативные массивы (объекты с ключами и значениями).
+
+## Параметры
+
+- `arr` (object): Исходный массив.
+
+## Возвращаемое значение
+
+Возвращает новый массив с элементами в случайном порядке.
+
+## Примеры использования
+
+1. Перемешивание обычного массива:
+
+    ```js
+    const array = [1, 2, 3, 4, 5];
+    const result = shuffle(array);
+    console.log(result); // [3, 1, 5, 2, 4] (пример)
+    ```
+
+2. Перемешивание ассоциативного массива:
+
+    ```js
+    const array = { a: 1, b: 2, c: 3 };
+    const result = shuffle(array);
+    console.log(result); // [['b', 2], ['a', 1], ['c', 3]] (пример)
+    ```
+
+3. Обработка пустого массива:
+
+    ```js
+    const array = [];
+    const result = shuffle(array);
+    console.log(result); // []
+    ```
+
+4. Обработка массива с одним элементом:
+
+    ```js
+    const array = [1];
+    const result = shuffle(array);
+    console.log(result); // [1]
+    ```
+
+5. Обработка значений, не являющихся массивами:
+
+    ```js
+    try {
+        const result = shuffle('not an array');
+    } catch (e) {
+        console.error(e.message); // Параметр "arr" должен быть массивом.
+    }
+    ```
+
+## Исключения
+
+- `TypeError`: Если параметр не является массивом.

package/docs/helpers/array/sort.md

@@ -0,0 +1,79 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / sort
+
+[Исходный код](../../../src/helpers/array/sort.mjs)
+
+# sort
+
+`sort` — Сортирует элементы массива с использованием функции сравнения.
+
+## Сигнатура функции
+
+```ts
+function sort(arr: object, compare_func: function = (a, b) => a[1] - b[1]): Array<any>;
+```
+
+## Описание
+
+Функция `sort` используется для сортировки элементов массива с использованием функции сравнения. Она
+поддерживает как обычные массивы, так и ассоциативные массивы (объекты с ключами и значениями).
+
+## Параметры
+
+- `arr` (object): Исходный массив.
+- `compare_func` (function): Функция сравнения, используемая для сортировки. По умолчанию
+  `(a, b) => a[1] - b[1]`.
+
+## Возвращаемое значение
+
+Возвращает новый массив с отсортированными элементами.
+
+## Примеры использования
+
+1. Сортировка обычного массива:
+
+    ```js
+    const array = [5, 3, 1, 4, 2];
+    const result = sort(array);
+    console.log(result); // [1, 2, 3, 4, 5]
+    ```
+
+2. Сортировка ассоциативного массива:
+
+    ```js
+    const array = { a: 3, b: 1, c: 2 };
+    const result = sort(array);
+    console.log(result); // [['b', 1], ['c', 2], ['a', 3]]
+    ```
+
+3. Сортировка с использованием пользовательской функции сравнения:
+
+    ```js
+    const array = [5, 3, 1, 4, 2];
+    const result = sort(array, (a, b) => b[1] - a[1]);
+    console.log(result); // [5, 4, 3, 2, 1]
+    ```
+
+4. Обработка значений, не являющихся массивами:
+
+    ```js
+    try {
+        const result = sort('not an array');
+    } catch (e) {
+        console.error(e.message); // Параметр "arr" должен быть массивом.
+    }
+    ```
+
+5. Обработка значений параметра compare_func, не являющихся функцией:
+
+    ```js
+    try {
+        const result = sort([1, 2, 3], 'not a function');
+    } catch (e) {
+        console.error(e.message); // Параметр "compare_func" должен быть функцией.
+    }
+    ```
+
+## Исключения
+
+- `TypeError`: Если параметр не является массивом или если параметр compare_func не является
+  функцией.

package/docs/helpers/is_char.md

@@ -0,0 +1,84 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / is_char
+
+[Исходный код](../../src/helpers/is_char.mjs)
+
+# is_char
+
+`is_char` — Проверяет, является ли значение одиночным символом.
+
+## Сигнатура функции
+
+```ts
+function is_char(value: string): boolean;
+```
+
+## Описание
+
+Функция `is_char` используется для проверки, является ли переданное значение одиночным символом.
+Значение считается одиночным символом, если оно является строкой длиной в один символ.
+
+## Параметры
+
+- `value` (string): Значение для проверки.
+
+## Возвращаемое значение
+
+Возвращает `true`, если значение является одиночным символом, иначе `false`.
+
+## Примеры использования
+
+1. Проверка одиночного символа:
+
+    ```js
+    const result = is_char('a');
+    console.log(result); // true
+    ```
+
+2. Проверка строки из нескольких символов:
+
+    ```js
+    const result = is_char('abc');
+    console.log(result); // false
+    ```
+
+3. Проверка пустой строки:
+
+    ```js
+    const result = is_char('');
+    console.log(result); // false
+    ```
+
+4. Проверка значения, не являющегося строкой:
+
+    ```js
+    const result = is_char(1);
+    console.log(result); // false
+    ```
+
+5. Проверка пробельного символа:
+
+    ```js
+    const result = is_char(' ');
+    console.log(result); // true
+    ```
+
+6. Проверка строки с пробелами:
+
+    ```js
+    const result = is_char(' a ');
+    console.log(result); // false
+    ```
+
+7. Проверка строки с числовыми значениями:
+
+    ```js
+    const result = is_char('123');
+    console.log(result); // false
+    ```
+
+8. Проверка одиночного числового символа:
+
+    ```js
+    const result = is_char('1');
+    console.log(result); // true
+    ```

package/docs/helpers/string/is_digit_char.md

@@ -0,0 +1,70 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / is_digit_char
+
+[Исходный код](../../../src/helpers/string/is_digit_char.mjs)
+
+# is_digit_char
+
+`is_digit_char` — Проверяет, является ли символ цифрой.
+
+## Сигнатура функции
+
+```ts
+function is_digit_char(value: any): boolean;
+```
+
+## Описание
+
+Функция `is_digit_char` используется для проверки, является ли переданный символ цифрой. Цифровыми
+символами считаются символы с кодами от 48 до 57 включительно.
+
+## Параметры
+
+- `value` (any): Символ для проверки.
+
+## Возвращаемое значение
+
+Возвращает `true`, если символ является цифрой, иначе `false`.
+
+## Примеры использования
+
+1. Проверка цифрового символа:
+
+    ```js
+    const result = is_digit_char('5');
+    console.log(result); // true
+    ```
+
+2. Проверка непробельного символа:
+
+    ```js
+    const result = is_digit_char('a');
+    console.log(result); // false
+    ```
+
+3. Проверка пустой строки:
+
+    ```js
+    const result = is_digit_char('');
+    console.log(result); // false
+    ```
+
+4. Проверка строки из нескольких символов:
+
+    ```js
+    const result = is_digit_char('123');
+    console.log(result); // false
+    ```
+
+5. Проверка символа табуляции:
+
+    ```js
+    const result = is_digit_char('\t');
+    console.log(result); // false
+    ```
+
+6. Проверка символа новой строки:
+
+    ```js
+    const result = is_digit_char('\n');
+    console.log(result); // false
+    ```

package/docs/helpers/string/is_whitespace_char.md

@@ -0,0 +1,70 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / is_whitespace_char
+
+[Исходный код](../../../src/helpers/string/is_whitespace_char.mjs)
+
+# is_whitespace_char
+
+`is_whitespace_char` — Проверяет, является ли символ пробельным.
+
+## Сигнатура функции
+
+```ts
+function is_whitespace_char(value: any): boolean;
+```
+
+## Описание
+
+Функция `is_whitespace_char` используется для проверки, является ли переданный символ пробельным.
+Пробельными символами считаются символы с кодами от 0 до 32 включительно.
+
+## Параметры
+
+- `value` (any): Символ для проверки.
+
+## Возвращаемое значение
+
+Возвращает `true`, если символ является пробельным, иначе `false`.
+
+## Примеры использования
+
+1. Проверка пробельного символа:
+
+    ```js
+    const result = is_whitespace_char(' ');
+    console.log(result); // true
+    ```
+
+2. Проверка непробельного символа:
+
+    ```js
+    const result = is_whitespace_char('a');
+    console.log(result); // false
+    ```
+
+3. Проверка пустой строки:
+
+    ```js
+    const result = is_whitespace_char('');
+    console.log(result); // false
+    ```
+
+4. Проверка строки из нескольких символов:
+
+    ```js
+    const result = is_whitespace_char('abc');
+    console.log(result); // false
+    ```
+
+5. Проверка символа табуляции:
+
+    ```js
+    const result = is_whitespace_char('\t');
+    console.log(result); // true
+    ```
+
+6. Проверка символа новой строки:
+
+    ```js
+    const result = is_whitespace_char('\n');
+    console.log(result); // true
+    ```

package/docs/helpers/string/natcompare.md

@@ -0,0 +1,69 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / natcompare
+
+[Исходный код](../../../src/helpers/string/natcompare.mjs)
+
+# natcompare
+
+`natcompare` — Сравнивает две строки в естественном порядке.
+
+## Сигнатура функции
+
+```ts
+function natcompare(a: string, b: string): number;
+```
+
+## Описание
+
+Функция `natcompare` используется для сравнения двух строк в естественном порядке. Она поддерживает
+строки с ведущими нулями и пробелами и игнорирует их при сравнении.
+
+## Параметры
+
+- `a` (string): Первая строка для сравнения.
+- `b` (string): Вторая строка для сравнения.
+
+## Возвращаемое значение
+
+Возвращает отрицательное значение, если `a` меньше `b`, ноль, если `a` равно `b`, и положительное
+значение, если `a` больше `b`.
+
+## Примеры использования
+
+1. Сравнение строк с числовыми значениями:
+
+    ```js
+    const result = natcompare('10', '2');
+    console.log(result); // 1
+    ```
+
+2. Сравнение строк с ведущими нулями:
+
+    ```js
+    const result = natcompare('0010', '10');
+    console.log(result); // 0
+    ```
+
+3. Сравнение строк с пробелами:
+
+    ```js
+    const result = natcompare(' 10', '10');
+    console.log(result); // 0
+    ```
+
+4. Сравнение строк с буквами и числами:
+
+    ```js
+    const result = natcompare('a10', 'a2');
+    console.log(result); // 1
+    ```
+
+5. Сравнение строк с разными символами:
+
+    ```js
+    const result = natcompare('10-', '10+');
+    console.log(result); // 1
+    ```
+
+## Исключения
+
+- `TypeError`: Если параметры не являются строками.