@rogolev/value 0.0.3 → 0.0.5

package/docs/helpers/array/array_shift.md

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

package/docs/helpers/array/array_slice.md

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

package/docs/helpers/array/array_splice.md

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

package/docs/helpers/array/array_sum.md

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

package/docs/helpers/array/array_udiff.md

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

package/docs/helpers/array/array_udiff_assoc.md

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

package/docs/helpers/array/array_udiff_uassoc.md

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

package/docs/helpers/array/array_uintersect.md

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