@rogolev/value 0.0.3 → 0.0.5

package/docs/helpers/array/array_pop.md

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

package/docs/helpers/array/array_product.md

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

package/docs/helpers/array/array_push.md

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

package/docs/helpers/array/array_rand.md

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

package/docs/helpers/array/array_reduce.md

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

package/docs/helpers/array/array_replace.md

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

package/docs/helpers/array/array_replace_recursive.md

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

package/docs/helpers/array/array_reverse.md

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

package/docs/helpers/array/array_search.md

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