@rogolev/value 0.0.3 → 0.0.5

package/src/helpers/expect_string.mjs

@@ -0,0 +1,65 @@
+import is_string from './is_string.mjs';
+
+/**
+ * Проверяет, является ли значение строкой, и выбрасывает ошибку с указанным сообщением, если это не так.
+ *
+ * ### Описание
+ *
+ * Функция `expect_string` используется для проверки, является ли переданное значение строкой.
+ * Если значение не является строкой, функция выбрасывает ошибку типа `TypeError` с указанным сообщением.
+ *
+ * ### Параметры
+ *
+ * - `value` (any): Значение для проверки.
+ * - `message` (string): Сообщение об ошибке, если значение не является строкой. По умолчанию пустая строка.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает `true`, если значение является строкой.
+ *
+ * ### Примеры использования
+ *
+ * 1. Проверка значения, являющегося строкой:
+ *
+ *    ```js
+ *    const value = 'Hello, world!';
+ *    const result = expect_string(value);
+ *    console.log(result); // true
+ *    ```
+ *
+ * 2. Проверка значения, не являющегося строкой:
+ *
+ *    ```js
+ *    try {
+ *        const result = expect_string(123, 'Значение должно быть строкой.');
+ *    } catch (e) {
+ *        console.error(e.message); // Значение должно быть строкой.
+ *    }
+ *    ```
+ *
+ * 3. Проверка значения с использованием пользовательского сообщения об ошибке:
+ *
+ *    ```js
+ *    try {
+ *        const result = expect_string({}, 'Ожидалась строка.');
+ *    } catch (e) {
+ *        console.error(e.message); // Ожидалась строка.
+ *    }
+ *    ```
+ *
+ * @param {any} value Значение для проверки.
+ * @param {string} [message=''] Сообщение об ошибке, если значение не является строкой.
+ * @returns {boolean} Возвращает `true`, если значение является строкой.
+ * @throws {TypeError} Если значение не является строкой или если параметр `message` не является строкой.
+ */
+export default function expect_string(value, message = '') {
+    if (!is_string(message)) {
+        throw new TypeError('Параметр "message" должен быть строкой.');
+    }
+
+    if (!is_string(value)) {
+        throw new TypeError(message);
+    }
+
+    return true;
+}

package/src/helpers/expect_symbol.mjs

@@ -0,0 +1,66 @@
+import is_string from './is_string.mjs';
+import is_symbol from './is_symbol.mjs';
+
+/**
+ * Проверяет, является ли значение символом, и выбрасывает ошибку с указанным сообщением, если это не так.
+ *
+ * ### Описание
+ *
+ * Функция `expect_symbol` используется для проверки, является ли переданное значение символом.
+ * Если значение не является символом, функция выбрасывает ошибку типа `TypeError` с указанным сообщением.
+ *
+ * ### Параметры
+ *
+ * - `value` (any): Значение для проверки.
+ * - `message` (string): Сообщение об ошибке, если значение не является символом. По умолчанию пустая строка.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает `true`, если значение является символом.
+ *
+ * ### Примеры использования
+ *
+ * 1. Проверка значения, являющегося символом:
+ *
+ *    ```js
+ *    const value = Symbol('example');
+ *    const result = expect_symbol(value);
+ *    console.log(result); // true
+ *    ```
+ *
+ * 2. Проверка значения, не являющегося символом:
+ *
+ *    ```js
+ *    try {
+ *        const result = expect_symbol('not a symbol', 'Значение должно быть символом.');
+ *    } catch (e) {
+ *        console.error(e.message); // Значение должно быть символом.
+ *    }
+ *    ```
+ *
+ * 3. Проверка значения с использованием пользовательского сообщения об ошибке:
+ *
+ *    ```js
+ *    try {
+ *        const result = expect_symbol(123, 'Ожидался символ.');
+ *    } catch (e) {
+ *        console.error(e.message); // Ожидался символ.
+ *    }
+ *    ```
+ *
+ * @param {any} value Значение для проверки.
+ * @param {string} [message=''] Сообщение об ошибке, если значение не является символом.
+ * @returns {boolean} Возвращает `true`, если значение является символом.
+ * @throws {TypeError} Если значение не является символом или если параметр `message` не является строкой.
+ */
+export default function expect_symbol(value, message = '') {
+    if (!is_string(message)) {
+        throw new TypeError('Параметр "message" должен быть строкой.');
+    }
+
+    if (!is_symbol(value)) {
+        throw new TypeError(message);
+    }
+
+    return true;
+}

package/src/helpers/expect_undefined.mjs

@@ -0,0 +1,66 @@
+import is_string from './is_string.mjs';
+import is_undefined from './is_undefined.mjs';
+
+/**
+ * Проверяет, является ли значение undefined, и выбрасывает ошибку с указанным сообщением, если это не так.
+ *
+ * ### Описание
+ *
+ * Функция `expect_undefined` используется для проверки, является ли переданное значение undefined.
+ * Если значение не является undefined, функция выбрасывает ошибку типа `TypeError` с указанным сообщением.
+ *
+ * ### Параметры
+ *
+ * - `value` (any): Значение для проверки.
+ * - `message` (string): Сообщение об ошибке, если значение не является undefined. По умолчанию пустая строка.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает `true`, если значение является undefined.
+ *
+ * ### Примеры использования
+ *
+ * 1. Проверка значения, являющегося undefined:
+ *
+ *    ```js
+ *    let value;
+ *    const result = expect_undefined(value);
+ *    console.log(result); // true
+ *    ```
+ *
+ * 2. Проверка значения, не являющегося undefined:
+ *
+ *    ```js
+ *    try {
+ *        const result = expect_undefined(123, 'Значение должно быть undefined.');
+ *    } catch (e) {
+ *        console.error(e.message); // Значение должно быть undefined.
+ *    }
+ *    ```
+ *
+ * 3. Проверка значения с использованием пользовательского сообщения об ошибке:
+ *
+ *    ```js
+ *    try {
+ *        const result = expect_undefined('not undefined', 'Ожидалось значение undefined.');
+ *    } catch (e) {
+ *        console.error(e.message); // Ожидалось значение undefined.
+ *    }
+ *    ```
+ *
+ * @param {any} value Значение для проверки.
+ * @param {string} [message=''] Сообщение об ошибке, если значение не является undefined.
+ * @returns {boolean} Возвращает `true`, если значение является undefined.
+ * @throws {TypeError} Если значение не является undefined или если параметр `message` не является строкой.
+ */
+export default function expect_undefined(value, message = '') {
+    if (!is_string(message)) {
+        throw new TypeError('Параметр "message" должен быть строкой.');
+    }
+
+    if (!is_undefined(value)) {
+        throw new TypeError(message);
+    }
+
+    return true;
+}

package/src/helpers/is_char.mjs

@@ -0,0 +1,54 @@
+import is_string from './is_string.mjs';
+
+/**
+ * Проверяет, является ли значение одиночным символом.
+ *
+ * ### Описание
+ *
+ * Функция `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
+ *    ```
+ *
+ * @param {string} value Значение для проверки.
+ * @returns {boolean} Возвращает `true`, если значение является одиночным символом, иначе `false`.
+ */
+export default function is_char(value) {
+    return is_string(value) && value.length === 1;
+}

package/src/helpers/is_equal.mjs

@@ -0,0 +1,94 @@
+/**
+ * Проверяет, являются ли два значения равными.
+ *
+ * ### Описание
+ *
+ * Функция `is_equal` используется для проверки равенства двух значений. Она поддерживает сравнение
+ * примитивных типов данных, а также объектов и массивов. Для объектов и массивов функция рекурсивно
+ * сравнивает их ключи и значения. Функция также поддерживает строгий режим сравнения, который учитывает типы значений.
+ *
+ * ### Параметры
+ *
+ * - `actual` (any): Первое значение для сравнения.
+ * - `expected` (any): Второе значение для сравнения.
+ * - `strict` (boolean): Флаг строгого сравнения. По умолчанию `false`.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает `true`, если значения равны, иначе `false`.
+ *
+ * ### Примеры использования
+ *
+ * 1. Проверка равенства чисел:
+ *
+ *    ```js
+ *    const result = is_equal(1, 1);
+ *    console.log(result); // true
+ *    ```
+ *
+ * 2. Проверка равенства строк:
+ *
+ *    ```js
+ *    const result = is_equal('hello', 'hello');
+ *    console.log(result); // true
+ *    ```
+ *
+ * 3. Проверка равенства объектов:
+ *
+ *    ```js
+ *    const obj1 = { a: 1, b: 2 };
+ *    const obj2 = { a: 1, b: 2 };
+ *    const result = is_equal(obj1, obj2);
+ *    console.log(result); // true
+ *    ```
+ *
+ * 4. Проверка равенства массивов:
+ *
+ *    ```js
+ *    const arr1 = [1, 2, 3];
+ *    const arr2 = [1, 2, 3];
+ *    const result = is_equal(arr1, arr2);
+ *    console.log(result); // true
+ *    ```
+ *
+ * 5. Проверка равенства с использованием строгого сравнения:
+ *
+ *    ```js
+ *    const result = is_equal(1, '1', true);
+ *    console.log(result); // false
+ *    ```
+ *
+ * @param {any} actual Первое значение для сравнения.
+ * @param {any} expected Второе значение для сравнения.
+ * @param {boolean} [strict=false] Флаг строгого сравнения.
+ * @returns {boolean} Возвращает `true`, если значения равны, иначе `false`.
+ */
+export default function is_equal(actual, expected, strict = false) {
+    if (
+        typeof actual === 'object' &&
+        typeof expected === 'object' &&
+        actual !== null &&
+        expected !== null
+    ) {
+        const entriesA = Object.entries(actual);
+        const entriesB = Object.entries(expected);
+
+        if (entriesA.length !== entriesB.length) {
+            return false;
+        }
+
+        for (let i = 0; i < entriesA.length; i++) {
+            if (entriesA[i][0] !== entriesB[i][0] || !is_equal(entriesA[i][1], entriesB[i][1])) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    if (strict) {
+        return Object.is(actual, expected);
+    }
+
+    return actual == expected;
+}

package/src/helpers/string/is_digit_char.mjs

@@ -0,0 +1,60 @@
+import is_char from '../is_char.mjs';
+
+/**
+ * Проверяет, является ли символ цифрой.
+ *
+ * ### Описание
+ *
+ * Функция `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
+ *    ```
+ *
+ * @param {any} value Символ для проверки.
+ * @returns {boolean} Возвращает `true`, если символ является цифрой, иначе `false`.
+ */
+export default function is_digit_char(value) {
+    if (!is_char(value)) {
+        return false;
+    }
+
+    const char_code = value.charCodeAt(0);
+
+    return char_code >= 48 && char_code <= 57;
+}

package/src/helpers/string/is_whitespace_char.mjs

@@ -0,0 +1,54 @@
+import is_char from '../is_char.mjs';
+
+/**
+ * Проверяет, является ли символ пробельным.
+ *
+ * ### Описание
+ *
+ * Функция `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
+ *    ```
+ *
+ * @param {any} value Символ для проверки.
+ * @returns {boolean} Возвращает `true`, если символ является пробельным, иначе `false`.
+ */
+export default function is_whitespace_char(value) {
+    return is_char(value) && value.charCodeAt(0) <= 32;
+}

package/src/helpers/string/natcompare.mjs

@@ -0,0 +1,107 @@
+import is_string from '../is_string.mjs';
+import is_digit_char from './is_digit_char.mjs';
+import is_whitespace_char from './is_whitespace_char.mjs';
+import natcompare_numeric from './natcompare_numeric.mjs';
+
+/**
+ * Сравнивает две строки в естественном порядке.
+ *
+ * ### Описание
+ *
+ * Функция `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
+ *    ```
+ *
+ * @param {string} a Первая строка для сравнения.
+ * @param {string} b Вторая строка для сравнения.
+ * @returns {number} Возвращает отрицательное значение, если `a` меньше `b`, ноль, если `a` равно `b`, и положительное значение, если `a` больше `b`.
+ * @throws {TypeError} Если параметры не являются строками.
+ */
+export default function natcompare(a, b) {
+    if (!is_string(a)) {
+        throw new TypeError('Параметр "a" должен быть строкой.');
+    }
+
+    if (!is_string(b)) {
+        throw new TypeError('Параметр "b" должен быть строкой.');
+    }
+
+    a = a.trim();
+    b = b.trim();
+
+    let ia = 0;
+    let ib = 0;
+    let nza = 0;
+    let nzb = 0;
+
+    while (true) {
+        nza = 0;
+        nzb = 0;
+
+        let ca = a.charAt(ia);
+        let cb = b.charAt(ib);
+
+        while (is_whitespace_char(ca) || ca === '0') {
+            if (ca === '0') {
+                nza++;
+            } else {
+                nza = 0;
+            }
+            ca = a.charAt(++ia);
+        }
+
+        while (is_whitespace_char(cb) || cb === '0') {
+            if (cb === '0') {
+                nzb++;
+            } else {
+                nzb = 0;
+            }
+            cb = b.charAt(++ib);
+        }
+
+        if (is_digit_char(ca) && is_digit_char(cb)) {
+            const result = natcompare_numeric(a.slice(ia), b.slice(ib));
+
+            if (result !== 0) {
+                return result;
+            }
+        }
+
+        if (ca === '' && cb === '') {
+            return nza - nzb;
+        }
+
+        if (ca < cb) {
+            return -1;
+        } else if (ca > cb) {
+            return 1;
+        }
+
+        ia++;
+        ib++;
+    }
+}