@rogolev/value 0.0.3 → 0.0.4

package/src/helpers/array/array_combine.mjs

@@ -0,0 +1,26 @@
+import array from '../array.mjs';
+import is_list from '../is_list.mjs';
+
+export default function array_combine(keys, values) {
+    if (!is_list(keys)) {
+        throw new TypeError('Параметр "keys" должен быть списком.');
+    }
+
+    if (!is_list(values)) {
+        throw new TypeError('Параметр "values" должен быть списком.');
+    }
+
+    if (keys.length !== values.length) {
+        throw new Error(
+            'Количество элементов в списке ключей должно ровняться количеству элементов в списке значений.',
+        );
+    }
+
+    const result = array({});
+
+    for (let i = 0; i < keys.length; i++) {
+        result[keys[i]] = values[i];
+    }
+
+    return result;
+}

package/src/helpers/array/array_count_values.mjs

@@ -0,0 +1,82 @@
+import array from '../array.mjs';
+import is_array from '../is_array.mjs';
+
+/**
+ * Подсчитывает количество значений в массиве.
+ *
+ * ### Описание
+ *
+ * Функция `array_count_values` используется для подсчета количества значений в массиве.
+ * Если переданное значение не является массивом, функция выбрасывает ошибку типа `TypeError`.
+ *
+ * ### Параметры
+ *
+ * - `value` (array): Массив значений, которые необходимо подсчитать.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает объект, где ключи представляют уникальные значения из массива, а значения представляют количество их вхождений.
+ *
+ * ### Примеры использования
+ *
+ * 1. Подсчет количества значений в массиве:
+ *
+ *    ```js
+ *    const array = ['a', 'b', 'a', 'c', 'b', 'a'];
+ *    const result = array_count_values(array);
+ *    console.log(result); // { a: 3, b: 2, c: 1 }
+ *    ```
+ *
+ * 2. Обработка пустого массива:
+ *
+ *    ```js
+ *    const array = [];
+ *    const result = array_count_values(array);
+ *    console.log(result); // {}
+ *    ```
+ *
+ * 3. Обработка значений разных типов:
+ *
+ *    ```js
+ *    const array = [1, '1', true, 'true', null, 'null', undefined, 'undefined'];
+ *    const result = array_count_values(array);
+ *    console.log(result); // { 1: 2, true: 2, null: 2, undefined: 2 }
+ *    ```
+ *
+ * 4. Обработка значения, не являющегося массивом:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_count_values('not an array');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "value" должен быть массивом.
+ *    }
+ *    ```
+ *
+ * 5. Обработка ассоциативных массивов:
+ *
+ *    ```js
+ *    const assoc = { key1: 'a', key2: 'b', key3: 'a', key4: 'c' };
+ *    const result = array_count_values(assoc);
+ *    console.log(result); // { a: 2, b: 1, c: 1 }
+ *    ```
+ *
+ * @param {object} value Массив значений, которые необходимо подсчитать.
+ * @returns {object} Возвращает объект, где ключи представляют уникальные значения из массива, а значения представляют количество их вхождений.
+ * @throws {TypeError} Если переданное значение не является массивом.
+ */
+export default function array_count_values(value) {
+    if (!is_array(value)) {
+        throw new TypeError('Параметр "value" должен быть массивом.');
+    }
+
+    const result = array({});
+
+    for (const k in value) {
+        const v = String(value[k]);
+
+        v in result ? result[v]++ : (result[v] = 1);
+    }
+
+    return result;
+}

package/src/helpers/array/array_diff.mjs

@@ -0,0 +1,77 @@
+import array_udiff from './array_udiff.mjs';
+
+/**
+ * Вычисляет расхождение между массивами.
+ *
+ * ### Описание
+ *
+ * Функция `array_diff` используется для вычисления расхождения между массивами. Она возвращает ассоциативный массив, содержащий элементы из первого массива, которые отсутствуют в других массивах.
+ *
+ * ### Параметры
+ *
+ * - `original_array` (object): Исходный массив.
+ * - `...arrays` (object): Массивы для сравнения.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает ассоциативный массив, содержащий элементы из первого массива, которые отсутствуют в других массивах.
+ *
+ * ### Примеры использования
+ *
+ * 1. Сравнение массивов:
+ *
+ *    ```js
+ *    const original_array = [1, 2, 3];
+ *    const array1 = [1, 2];
+ *    const result = array_diff(original_array, array1);
+ *    console.log(result); // { 2: 3 }
+ *    ```
+ *
+ * 2. Обработка пустых массивов:
+ *
+ *    ```js
+ *    const original_array = [];
+ *    const array1 = [];
+ *    const result = array_diff(original_array, array1);
+ *    console.log(result); // {}
+ *    ```
+ *
+ * 3. Сравнение массивов с различными типами данных:
+ *
+ *    ```js
+ *    const original_array = [1, '2', true];
+ *    const array1 = [1, 2, false];
+ *    const result = array_diff(original_array, array1);
+ *    console.log(result); // { 1: '2', 2: true }
+ *    ```
+ *
+ * 4. Сравнение массивов с объектами:
+ *
+ *    ```js
+ *    const original_array = [{ id: 1 }, { id: 2 }, { id: 3 }];
+ *    const array1 = [{ id: 1 }, { id: 2 }];
+ *    const result = array_diff(original_array, array1);
+ *    console.log(result); // { 2: { id: 3 } }
+ *    ```
+ *
+ * 5. Сравнение ассоциативных массивов:
+ *
+ *    ```js
+ *    const original_array = { a: 1, b: 2, c: 3 };
+ *    const array1 = { a: 1, b: 2 };
+ *    const result = array_diff(original_array, array1);
+ *    console.log(result); // { c: 3 }
+ *    ```
+ *
+ * @param {object} original_array Исходный массив.
+ * @param {...object} arrays Массивы для сравнения.
+ * @returns {object} Возвращает ассоциативный массив, содержащий элементы из первого массива, которые отсутствуют в других массивах.
+ * @throws {TypeError} Если параметры не являются массивами.
+ */
+export default function array_diff(original_array, ...arrays) {
+    return array_udiff(
+        (a, b) => JSON.stringify(a) === JSON.stringify(b),
+        original_array,
+        ...arrays,
+    );
+}

package/src/helpers/array/array_diff_assoc.mjs

@@ -0,0 +1,56 @@
+import array_diff_uassoc from './array_diff_uassoc.mjs';
+
+/**
+ * Вычисляет расхождение между массивами с использованием стандартной функции сравнения значений и ключей.
+ *
+ * ### Описание
+ *
+ * Функция `array_diff_assoc` используется для вычисления расхождения между массивами с использованием стандартной функции сравнения значений и ключей.
+ * Она возвращает ассоциативный массив, содержащий элементы из первого массива, которые отсутствуют в других массивах.
+ *
+ * ### Параметры
+ *
+ * - `original_array` (object): Исходный массив.
+ * - `...arrays` (object): Массивы для сравнения.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает ассоциативный массив, содержащий элементы из первого массива, которые отсутствуют в других массивах.
+ *
+ * ### Примеры использования
+ *
+ * 1. Сравнение массивов:
+ *
+ *    ```js
+ *    const original_array = { a: 1, b: 2, c: 3 };
+ *    const array1 = { a: 1, b: 2 };
+ *    const result = array_diff_assoc(original_array, array1);
+ *    console.log(result); // { c: 3 }
+ *    ```
+ *
+ * 2. Обработка пустых массивов:
+ *
+ *    ```js
+ *    const original_array = {};
+ *    const array1 = {};
+ *    const result = array_diff_assoc(original_array, array1);
+ *    console.log(result); // {}
+ *    ```
+ *
+ * 3. Сравнение массивов с различными типами данных:
+ *
+ *    ```js
+ *    const original_array = { a: 1, b: '2', c: true };
+ *    const array1 = { a: 1, b: 2, d: false };
+ *    const result = array_diff_assoc(original_array, array1);
+ *    console.log(result); // { b: '2', c: true }
+ *    ```
+ *
+ * @param {object} original_array Исходный массив.
+ * @param {...object} arrays Массивы для сравнения.
+ * @returns {object} Возвращает ассоциативный массив, содержащий элементы из первого массива, которые отсутствуют в других массивах.
+ * @throws {TypeError} Если параметры не являются массивами.
+ */
+export default function array_diff_assoc(original_array, ...arrays) {
+    return array_diff_uassoc((a, b) => a === b, original_array, ...arrays);
+}

package/src/helpers/array/array_diff_key.mjs

@@ -0,0 +1,56 @@
+import array_diff_ukey from './array_diff_ukey.mjs';
+
+/**
+ * Вычисляет расхождение между массивами с использованием стандартной функции сравнения ключей.
+ *
+ * ### Описание
+ *
+ * Функция `array_diff_key` используется для вычисления расхождения между массивами с использованием стандартной функции сравнения ключей.
+ * Она возвращает ассоциативный массив, содержащий элементы из первого массива, которые отсутствуют в других массивах.
+ *
+ * ### Параметры
+ *
+ * - `original_array` (object): Исходный массив.
+ * - `...arrays` (object): Массивы для сравнения.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает ассоциативный массив, содержащий элементы из первого массива, которые отсутствуют в других массивах.
+ *
+ * ### Примеры использования
+ *
+ * 1. Сравнение массивов:
+ *
+ *    ```js
+ *    const original_array = { a: 1, b: 2, c: 3 };
+ *    const array1 = { a: 1, b: 2 };
+ *    const result = array_diff_key(original_array, array1);
+ *    console.log(result); // { c: 3 }
+ *    ```
+ *
+ * 2. Обработка пустых массивов:
+ *
+ *    ```js
+ *    const original_array = {};
+ *    const array1 = {};
+ *    const result = array_diff_key(original_array, array1);
+ *    console.log(result); // {}
+ *    ```
+ *
+ * 3. Сравнение массивов с различными типами данных:
+ *
+ *    ```js
+ *    const original_array = { a: 1, b: '2', c: true };
+ *    const array1 = { a: 1, b: 2, d: false };
+ *    const result = array_diff_key(original_array, array1);
+ *    console.log(result); // { c: true }
+ *    ```
+ *
+ * @param {object} original_array Исходный массив.
+ * @param {...object} arrays Массивы для сравнения.
+ * @returns {object} Возвращает ассоциативный массив, содержащий элементы из первого массива, которые отсутствуют в других массивах.
+ * @throws {TypeError} Если параметры не являются массивами.
+ */
+export default function array_diff_key(original_array, ...arrays) {
+    return array_diff_ukey((a, b) => a === b, original_array, ...arrays);
+}

package/src/helpers/array/array_diff_uassoc.mjs

@@ -0,0 +1,76 @@
+import array_udiff_uassoc from './array_udiff_uassoc.mjs';
+
+/**
+ * Вычисляет расхождение между массивами с использованием пользовательской функции сравнения ключей.
+ *
+ * ### Описание
+ *
+ * Функция `array_diff_uassoc` используется для вычисления расхождения между массивами с использованием пользовательской функции сравнения ключей.
+ * Она возвращает ассоциативный массив, содержащий элементы из первого массива, которые отсутствуют в других массивах.
+ *
+ * ### Параметры
+ *
+ * - `key_compare_func` (function): Функция для сравнения ключей.
+ * - `original_array` (object): Исходный массив.
+ * - `...arrays` (object): Массивы для сравнения.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает ассоциативный массив, содержащий элементы из первого массива, которые отсутствуют в других массивах.
+ *
+ * ### Примеры использования
+ *
+ * 1. Сравнение массивов с использованием пользовательской функции сравнения:
+ *
+ *    ```js
+ *    const key_compare_func = (a, b) => a === b;
+ *    const original_array = { a: 1, b: 2, c: 3 };
+ *    const array1 = { a: 1, b: 2 };
+ *    const result = array_diff_uassoc(key_compare_func, original_array, array1);
+ *    console.log(result); // { c: 3 }
+ *    ```
+ *
+ * 2. Обработка пустых массивов:
+ *
+ *    ```js
+ *    const key_compare_func = (a, b) => a === b;
+ *    const original_array = {};
+ *    const array1 = {};
+ *    const result = array_diff_uassoc(key_compare_func, original_array, array1);
+ *    console.log(result); // {}
+ *    ```
+ *
+ * 3. Обработка значений, не являющихся массивами:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_diff_uassoc('not a function', 'not an array');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "key_compare_func" должен быть функцией.
+ *    }
+ *    ```
+ *
+ * 4. Сравнение массивов с различными типами данных:
+ *
+ *    ```js
+ *    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_diff_uassoc(key_compare_func, original_array, array1);
+ *    console.log(result); // { c: true }
+ *    ```
+ *
+ * @param {function} key_compare_func Функция для сравнения ключей.
+ * @param {object} original_array Исходный массив.
+ * @param {...object} arrays Массивы для сравнения.
+ * @returns {object} Возвращает ассоциативный массив, содержащий элементы из первого массива, которые отсутствуют в других массивах.
+ * @throws {TypeError} Если параметры не являются функциями или массивами.
+ */
+export default function array_diff_uassoc(key_compare_func, original_array, ...arrays) {
+    return array_udiff_uassoc(
+        (a, b) => JSON.stringify(a) === JSON.stringify(b),
+        key_compare_func,
+        original_array,
+        ...arrays,
+    );
+}

package/src/helpers/array/array_diff_ukey.mjs

@@ -0,0 +1,71 @@
+import array_udiff_uassoc from './array_udiff_uassoc.mjs';
+
+/**
+ * Вычисляет расхождение между массивами с использованием пользовательской функции сравнения для ключей.
+ *
+ * ### Описание
+ *
+ * Функция `array_diff_ukey` используется для вычисления расхождения между массивами с использованием пользовательской функции сравнения для ключей.
+ * Она возвращает ассоциативный массив, содержащий элементы из первого массива, которые отсутствуют в других массивах.
+ *
+ * ### Параметры
+ *
+ * - `key_compare_func` (function): Функция для сравнения ключей.
+ * - `original_array` (object): Исходный массив.
+ * - `...arrays` (object): Массивы для сравнения.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает ассоциативный массив, содержащий элементы из первого массива, которые отсутствуют в других массивах.
+ *
+ * ### Примеры использования
+ *
+ * 1. Сравнение массивов с использованием пользовательской функции сравнения ключей:
+ *
+ *    ```js
+ *    const key_compare_func = (a, b) => a === b;
+ *    const original_array = { a: 1, b: 2, c: 3 };
+ *    const array1 = { a: 1, b: 2 };
+ *    const result = array_diff_ukey(key_compare_func, original_array, array1);
+ *    console.log(result); // { c: 3 }
+ *    ```
+ *
+ * 2. Обработка пустых массивов:
+ *
+ *    ```js
+ *    const key_compare_func = (a, b) => a === b;
+ *    const original_array = {};
+ *    const array1 = {};
+ *    const result = array_diff_ukey(key_compare_func, original_array, array1);
+ *    console.log(result); // {}
+ *    ```
+ *
+ * 3. Обработка значений, не являющихся массивами:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_diff_ukey('not a function', 'not an array');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "key_compare_func" должен быть функцией.
+ *    }
+ *    ```
+ *
+ * 4. Сравнение массивов с различными типами данных:
+ *
+ *    ```js
+ *    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_diff_ukey(key_compare_func, original_array, array1);
+ *    console.log(result); // { c: true }
+ *    ```
+ *
+ * @param {function} key_compare_func Функция для сравнения ключей.
+ * @param {object} original_array Исходный массив.
+ * @param {...object} arrays Массивы для сравнения.
+ * @returns {object} Возвращает ассоциативный массив, содержащий элементы из первого массива, которые отсутствуют в других массивах.
+ * @throws {TypeError} Если параметры не являются функциями или массивами.
+ */
+export default function array_diff_ukey(key_compare_func, original_array, ...arrays) {
+    return array_udiff_uassoc(() => true, key_compare_func, original_array, ...arrays);
+}

package/src/helpers/array/array_fill.mjs

@@ -0,0 +1,108 @@
+import array from '../array.mjs';
+import is_array from '../is_array.mjs';
+import is_int from '../is_int.mjs';
+import is_list from '../is_list.mjs';
+
+/**
+ * Заполняет массив значениями, начиная с указанного индекса.
+ *
+ * ### Описание
+ *
+ * Функция `array_fill` используется для заполнения массива значениями, начиная с указанного индекса.
+ * Она возвращает массив, содержащий заданное количество элементов, заполненных указанным значением.
+ *
+ * ### Параметры
+ *
+ * - `arr` (object): Исходный массив.
+ * - `start_index` (number): Индекс, с которого начинается заполнение массива.
+ * - `count` (number): Количество элементов для заполнения.
+ * - `value` (any): Значение, которым будет заполнен массив.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает массив, содержащий заданное количество элементов, заполненных указанным значением.
+ *
+ * ### Примеры использования
+ *
+ * 1. Заполнение пустого массива значениями:
+ *
+ *    ```js
+ *    const result = array_fill([], 0, 3, 'a');
+ *    console.log(result); // ['a', 'a', 'a']
+ *    ```
+ *
+ * 2. Заполнение массива значениями с указанного индекса:
+ *
+ *    ```js
+ *    const result = array_fill([], 2, 3, 'b');
+ *    console.log(result); // [undefined, undefined, 'b', 'b', 'b']
+ *    ```
+ *
+ * 3. Заполнение существующего массива значениями:
+ *
+ *    ```js
+ *    const existingArray = [1, 2, 3];
+ *    const result = array_fill(existingArray, 1, 2, 'c');
+ *    console.log(result); // [1, 'c', 'c']
+ *    ```
+ *
+ * 4. Обработка отрицательных значений для `count`:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_fill([], 0, -1, 'd');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "count" должен быть равен или больше нуля.
+ *    }
+ *    ```
+ *
+ * 5. Обработка значений, не являющихся целыми числами:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_fill([], 0.5, 3, 'e');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "start_index" должен быть целым числом.
+ *    }
+ *    ```
+ *
+ * 6. Заполнение ассоциативного массива значениями:
+ *
+ *    ```js
+ *    const assocArray = { a: 1, b: 2 };
+ *    const result = array_fill(assocArray, 2, 3, 'f');
+ *    console.log(result); // { a: 1, b: 2, 2: 'f', 3: 'f', 4: 'f' }
+ *    ```
+ *
+ * @param {object} arr Исходный массив.
+ * @param {number} start_index Индекс, с которого начинается заполнение массива.
+ * @param {number} count Количество элементов для заполнения.
+ * @param {any} value Значение, которым будет заполнен массив.
+ * @returns {object} Возвращает массив, содержащий заданное количество элементов, заполненных указанным значением.
+ * @throws {TypeError} Если параметры не являются массивами или целыми числами, или если `count` меньше нуля.
+ */
+export default function array_fill(arr, start_index, count, value) {
+    if (!is_array(arr)) {
+        throw new TypeError('Параметр "arr" должен быть массивом.');
+    }
+
+    if (!is_int(start_index)) {
+        throw new TypeError('Параметр "start_index" должен быть целым числом.');
+    }
+
+    if (!is_int(count)) {
+        throw new TypeError('Параметр "count" должен быть целым числом.');
+    }
+
+    if (count < 0) {
+        throw new TypeError('Параметр "count" должен быть равен или больше нуля.');
+    }
+
+    const result = is_list(arr) ? Array.from(arr) : array(arr);
+
+    for (let index = start_index; index < start_index + count; index++) {
+        result[index] = value;
+    }
+
+    return result;
+}

package/src/helpers/array/array_fill_keys.mjs

@@ -0,0 +1,90 @@
+import array from '../array.mjs';
+import is_array from '../is_array.mjs';
+import is_list from '../is_list.mjs';
+
+/**
+ * Заполняет массив значениями по указанным ключам.
+ *
+ * ### Описание
+ *
+ * Функция `array_fill_keys` используется для заполнения массива значениями по указанным ключам.
+ * Она возвращает массив, содержащий элементы, заполненные указанным значением по указанным ключам.
+ *
+ * ### Параметры
+ *
+ * - `arr` (array): Исходный массив.
+ * - `keys` (array): Массив ключей, по которым будет происходить заполнение.
+ * - `value` (any): Значение, которым будет заполнен массив.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает массив, содержащий элементы, заполненные указанным значением по указанным ключам.
+ *
+ * ### Примеры использования
+ *
+ * 1. Заполнение пустого массива значениями по ключам:
+ *
+ *    ```js
+ *    const result = array_fill_keys([], [0, 1, 2], 'a');
+ *    console.log(result); // ['a', 'a', 'a']
+ *    ```
+ *
+ * 2. Заполнение существующего массива значениями по ключам:
+ *
+ *    ```js
+ *    const existingArray = [1, 2, 3];
+ *    const result = array_fill_keys(existingArray, [1, 2], 'b');
+ *    console.log(result); // [1, 'b', 'b']
+ *    ```
+ *
+ * 3. Заполнение ассоциативного массива значениями по ключам:
+ *
+ *    ```js
+ *    const assocArray = { a: 1, b: 2 };
+ *    const result = array_fill_keys(assocArray, ['c', 'd'], 'c');
+ *    console.log(result); // { a: 1, b: 2, c: 'c', d: 'c' }
+ *    ```
+ *
+ * 4. Обработка значений, не являющихся массивами:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_fill_keys('not an array', [0, 1, 2], 'd');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "arr" должен быть массивом.
+ *    }
+ *    ```
+ *
+ * 5. Обработка значений, не являющихся списками:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_fill_keys([], 'not a list', 'e');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "keys" должен быть списком.
+ *    }
+ *    ```
+ *
+ * @param {object} arr Исходный массив.
+ * @param {array} keys Массив ключей, по которым будет происходить заполнение.
+ * @param {any} value Значение, которым будет заполнен массив.
+ * @returns {object} Возвращает массив, содержащий элементы, заполненные указанным значением по указанным ключам.
+ * @throws {TypeError} Если параметры не являются массивами или списками.
+ */
+export default function array_fill_keys(arr, keys, value) {
+    if (!is_array(arr)) {
+        throw new TypeError('Параметр "arr" должен быть массивом.');
+    }
+
+    if (!is_list(keys)) {
+        throw new TypeError('Параметр "keys" должен быть списком.');
+    }
+
+    const result = is_list(arr) ? Array.from(arr) : array(arr);
+
+    for (const key of keys) {
+        result[key] = value;
+    }
+
+    return result;
+}