@rogolev/value 0.0.3 → 0.0.4

package/src/helpers/array/array_slice.mjs

@@ -0,0 +1,99 @@
+import array from '../array.mjs';
+import is_array from '../is_array.mjs';
+import is_list from '../is_list.mjs';
+import is_null from '../is_null.mjs';
+import is_int from '../is_int.mjs';
+import array_combine from './array_combine.mjs';
+
+/**
+ * Возвращает новый массив, содержащий часть исходного массива.
+ *
+ * ### Описание
+ *
+ * Функция `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" должен быть массивом.
+ *    }
+ *    ```
+ *
+ * @param {object} arr Исходный массив.
+ * @param {number} offset Смещение, с которого начинается извлечение.
+ * @param {number|null} [length=null] Длина извлекаемой части.
+ * @returns {object} Возвращает новый массив, содержащий часть исходного массива.
+ * @throws {TypeError} Если параметры не являются массивом, целым числом или null.
+ */
+export default function array_slice(arr, offset, length = null) {
+    if (!is_array(arr)) {
+        throw new TypeError('Параметр "arr" должен быть массивом.');
+    }
+
+    if (!is_int(offset)) {
+        throw new TypeError('Параметр "offset" должен быть целым числом.');
+    }
+
+    if (!is_int(length) && !is_null(length)) {
+        throw new TypeError('Параметр "length" должен быть целым числом.');
+    }
+
+    let end;
+
+    if (!is_null(length)) {
+        if (length === 0) {
+            return is_list(arr) ? [] : array({});
+        }
+
+        end = length > 0 ? offset + length : Object.keys(arr).length + length;
+    }
+
+    if (is_list(arr)) {
+        return Object.values(arr).slice(offset, end);
+    }
+
+    return array_combine(
+        Object.keys(arr).slice(offset, end),
+        Object.values(arr).slice(offset, end),
+    );
+}

package/src/helpers/array/array_splice.mjs

@@ -0,0 +1,218 @@
+import array from '../array.mjs';
+import empty from '../empty.mjs';
+import is_array from '../is_array.mjs';
+import is_assoc from '../is_assoc.mjs';
+import is_int from '../is_int.mjs';
+import is_list from '../is_list.mjs';
+import is_null from '../is_null.mjs';
+import array_push from './array_push.mjs';
+
+/**
+ * Удаляет элементы из массива и, при необходимости, добавляет новые элементы на их место.
+ *
+ * ### Описание
+ *
+ * Функция `array_splice` используется для удаления элементов из массива и добавления новых элементов на их место.
+ * Она поддерживает как обычные массивы, так и ассоциативные массивы (объекты с ключами и значениями).
+ *
+ * ### Параметры
+ *
+ * - `arr` (object): Исходный массив.
+ * - `offset` (number): Смещение, с которого начинается удаление.
+ * - `length` (number|null): Количество удаляемых элементов. Если не указано, удаляются все элементы до конца массива.
+ * - `replacements` (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" должен быть массивом.
+ *    }
+ *    ```
+ *
+ * @param {object} arr Исходный массив.
+ * @param {number} offset Смещение, с которого начинается удаление.
+ * @param {number|null} [length=null] Количество удаляемых элементов.
+ * @param {object} [replacements=[]] Элементы для добавления на место удаленных.
+ * @returns {object} Возвращает массив удаленных элементов.
+ * @throws {TypeError} Если параметры не являются массивом, целым числом или null.
+ */
+export default function array_splice(arr, offset, length = null, ...replacements) {
+    if (!is_array(arr)) {
+        throw new TypeError('Параметр "arr" должен быть массивом.');
+    }
+
+    if (!is_int(offset)) {
+        throw new TypeError('Параметр "offset" должен быть целым числом.');
+    }
+
+    if (!is_int(length) && !is_null(length)) {
+        throw new TypeError('Параметр "length" должен быть целым числом.');
+    }
+
+    if (empty(replacements) && !is_null(length) && length === 0) {
+        return is_list(arr) ? [] : array({});
+    }
+
+    const count = Object.keys(arr).length;
+
+    if (offset < 0) {
+        offset = count + offset;
+    }
+
+    // if (is_list(arr)) {
+    //     if (is_null(length)) {
+    //         length = count;
+    //     } else if (length < 0) {
+    //         length = count + length - offset;
+    //     }
+
+    //     return arr.splice(offset, length, ...replacements);
+    // }
+
+    let end = count;
+
+    if (!is_null(length)) {
+        if (length > 0) {
+            end = offset + length;
+        } else if (length < 0) {
+            end = count + length;
+        } else {
+            end = offset;
+        }
+    }
+
+    // Удаленные пары ключ-значение исходного массива.
+    const result = {};
+
+    // Временный массив.
+    // Нужен для того, чтобы элементы исходного массива имели ожидаемые позиции.
+    const tmp = {};
+
+    // Текущая позиция в исходном массиве.
+    let index = 0;
+
+    //
+    // Исходный массив рассматривается как список пар ключ-значение,
+    // где ключами являются не индексы, а позиция пары в массиве.
+    //
+    // Например, список будет иметь вид:
+    //
+    //  0  1  2 - это не индексы, а позиция в массиве.
+    // [1, 2, 3]
+    //
+    // или
+    //
+    // -3 -2 -1 - позиция в массиве c обратной стороны.
+    // [1, 2, 3]
+    //
+    // Ассоциативный массив:
+    //
+    //      0            1           2       -  позиция в массиве.
+    // { foo: 'bar', baz: 'bax', ban: 'bam' }
+    //
+    for (const [k, v] of Object.entries(arr)) {
+        // Если текущая позиция совпадает с начальной позицией для удаления
+        // и если переданы элементы для вставки, добавляем их в конец временного массива.
+        if (index === offset && !empty(replacements)) {
+            for (const replacement of replacements) {
+                if (is_assoc(replacement)) {
+                    Object.assign(tmp, replacement);
+                } else if (is_list(replacement)) {
+                    array_push(tmp, ...replacement);
+                } else {
+                    array_push(tmp, replacement);
+                }
+            }
+        }
+
+        // Если текущая позиция входит в диапазон элементов для удаления,
+        // записывает пару ключ-значение в результирующий массив.
+        // Иначе записываем пару ключ-значение во временный массив.
+        if (index >= offset && index < end) {
+            result[k] = v;
+        } else {
+            is_int(Number(k)) ? array_push(tmp, v) : (tmp[k] = v);
+        }
+
+        index++;
+    }
+
+    // Очищаем исходный массив.
+    for (const k in arr) {
+        delete arr[k];
+    }
+
+    // Копируем все свойства из временного массива в исходный.
+    for (const [k, v] of Object.entries(tmp)) {
+        arr[k] = v;
+    }
+
+    if (is_list(arr)) {
+        return Object.values(result);
+    }
+
+    return result;
+}

package/src/helpers/array/array_sum.mjs

@@ -0,0 +1,60 @@
+import is_array from '../is_array.mjs';
+import to_float from '../to_float.mjs';
+import array_reduce from './array_reduce.mjs';
+
+/**
+ * Вычисляет сумму значений массива.
+ *
+ * ### Описание
+ *
+ * Функция `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" должен быть массивом.
+ *    }
+ *    ```
+ *
+ * @param {object} arr Исходный массив.
+ * @returns {number} Возвращает сумму всех значений в массиве.
+ * @throws {TypeError} Если параметр не является массивом.
+ */
+export default function array_sum(arr) {
+    if (!is_array(arr)) {
+        throw new TypeError('Параметр "arr" должен быть массивом.');
+    }
+
+    return array_reduce(arr, (carry, item) => (carry += to_float(item)), 0);
+}

package/src/helpers/array/array_udiff.mjs

@@ -0,0 +1,91 @@
+import array_udiff_uassoc from './array_udiff_uassoc.mjs';
+
+/**
+ * Вычисляет расхождение между массивами с использованием пользовательской функции сравнения для значений.
+ *
+ * ### Описание
+ *
+ * Функция `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 }
+ *    ```
+ *
+ * @param {function} value_compare_func Функция для сравнения значений.
+ * @param {object} original_array Исходный массив.
+ * @param {...object} arrays Массивы для сравнения.
+ * @returns {object} Возвращает ассоциативный массив, содержащий элементы из первого массива, которые отсутствуют в других массивах.
+ * @throws {TypeError} Если параметры не являются функциями или массивами.
+ */
+export default function array_udiff(value_compare_func, original_array, ...arrays) {
+    return array_udiff_uassoc(value_compare_func, () => true, original_array, ...arrays);
+}

package/src/helpers/array/array_udiff_assoc.mjs

@@ -0,0 +1,71 @@
+import array_udiff_uassoc from './array_udiff_uassoc.mjs';
+
+/**
+ * Вычисляет расхождение между массивами с использованием пользовательской функции сравнения для значений и ассоциативного сравнения ключей.
+ *
+ * ### Описание
+ *
+ * Функция `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 }
+ *    ```
+ *
+ * @param {function} value_compare_func Функция для сравнения значений.
+ * @param {object} original_array Исходный массив.
+ * @param {...object} arrays Массивы для сравнения.
+ * @returns {object} Возвращает ассоциативный массив, содержащий элементы из первого массива, которые отсутствуют в других массивах.
+ * @throws {TypeError} Если параметры не являются функциями или массивами.
+ */
+export default function array_udiff_assoc(value_compare_func, original_array, ...arrays) {
+    return array_udiff_uassoc(value_compare_func, (a, b) => a === b, original_array, ...arrays);
+}

package/src/helpers/array/array_udiff_uassoc.mjs

@@ -0,0 +1,124 @@
+import is_array from '../is_array.mjs';
+import is_function from '../is_function.mjs';
+
+/**
+ * Вычисляет расхождение между массивами с использованием пользовательских функций сравнения для значений и ключей.
+ *
+ * ### Описание
+ *
+ * Функция `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 }
+ *    ```
+ *
+ * @param {function} value_compare_func Функция для сравнения значений.
+ * @param {function} key_compare_func Функция для сравнения ключей.
+ * @param {object} original_array Исходный массив.
+ * @param {...object} arrays Массивы для сравнения.
+ * @returns {object} Возвращает массив, содержащий элементы из первого массива, которые отсутствуют в других массивах.
+ * @throws {TypeError} Если параметры не являются функциями или массивами.
+ */
+export default function array_udiff_uassoc(
+    value_compare_func,
+    key_compare_func,
+    original_array,
+    ...arrays
+) {
+    if (!is_function(value_compare_func)) {
+        throw new TypeError('Параметр "value_compare_func" должен быть функцией.');
+    }
+
+    if (!is_function(key_compare_func)) {
+        throw new TypeError('Параметр "key_compare_func" должен быть функцией.');
+    }
+
+    if (!is_array(original_array)) {
+        throw new TypeError('Параметр "original_array" должен быть массивом.');
+    }
+
+    if (!arrays.every((array) => is_array(array))) {
+        throw new TypeError('Параметр "arrays" должен быть массивом.');
+    }
+
+    const result = {};
+
+    // Перебираем исходный массив
+    original: for (const original_key in original_array) {
+        const original_value = original_array[original_key];
+
+        // Каждую пару ключ-значение из исходного массива мы сравниваем с парами из исходных массивов.
+        // Если совпадение найдено, переходим к следующей паре ключ-значение из исходного массива.
+        for (const array of arrays) {
+            for (const key in array) {
+                const value = array[key];
+
+                if (
+                    key_compare_func(original_key, key) &&
+                    value_compare_func(original_value, value)
+                ) {
+                    continue original;
+                }
+            }
+        }
+
+        // Если совпадений не найдено, записываем пару ключ-значение из исходного массива в расхождение.
+        result[original_key] = original_value;
+    }
+
+    return result;
+}