Функция cot_build_number в Cotonti

Назначение функции:
Функция cot_build_number используется для форматирования числа с учётом локализации (например, использование десятичного разделителя или разделителя тысяч) и опционального округления.

/**
 * Wrapper for number_format() using locale number formatting and optional rounding.
 *
 * @param float $number
 *    Number to format
 * @param int $decimals
 *    Number of decimals to return
 * @param mixed $round
 *    Round up to this number of decimals.
 *    Set false to disable or null to inherit from $decimals.
 * @return string
 */
function cot_build_number($number, $decimals = 0, $round = null)
{
    global $Ln;
    if ($round === null) $round = $decimals;
    if ($round !== false)
    {
        $number = round($number, $round);
    }
    return number_format($number, $decimals, $Ln['decimal_point'], $Ln['thousands_separator']);
}

Параметры:

$number (float): число, которое нужно отформатировать.
$decimals (int): количество знаков после запятой. По умолчанию — 0.
$round (mixed): параметр, который определяет, до какого количества знаков после запятой нужно округлить число. Если значение равно false, округление не выполняется. Если null, округление выполняется с точностью до $decimals.

Алгоритм работы:
Параметры округления:

Если параметр $round не задан (то есть равен null), то значение для округления будет взято из $decimals.
Если параметр $round не равен false, то число будет округлено до $round знаков после запятой.
Форматирование числа:

Функция использует number_format(), который форматирует число в строку с учётом:

$decimals — количества знаков после запятой.
$Ln['decimal_point'] — символ для разделения целой и дробной части числа.
$Ln['thousands_separator'] — символ для разделения тысяч (например, пробел или запятая).

Пример:
Допустим, у нас есть число 1234567.89, и мы хотим его отформатировать с двумя знаками после запятой, используя локализованные разделители для тысяч и десятичных знаков:

$number = 1234567.89;
$formatted_number = cot_build_number($number, 2);

Если локаль настроена таким образом:

Десятичный разделитель: точка (.)
Разделитель тысяч: запятая (,)
Тогда результат будет следующим:

'1,234,567.89'

/**
 * Обёртка для number_format() с использованием локализованного форматирования чисел и опционального округления.
 *
 * @param float $number
 *  Число, которое нужно отформатировать.
 * @param int $decimals
 *  Количество знаков после запятой, которые нужно вернуть.
 * @param mixed $round
 *  Округлить до этого числа знаков после запятой.
 *  Установите false, чтобы отключить округление, или null, чтобы использовать значение из $decimals.
 * @return string
 */

 
 
Логика:
Определение параметра округления:

Если $round === null, то мы принимаем значение $decimals как количество знаков после запятой для округления.
Если $round !== false, то выполняем округление числа с помощью round($number, $round).

Форматирование числа:

Используется встроенная функция number_format, которая принимает три аргумента:
$number — само число.
$decimals — количество знаков после запятой.
$Ln['decimal_point'] — разделитель дробной части числа (например, точка или запятая).
$Ln['thousands_separator'] — разделитель тысяч (например, пробел или запятая).
Это позволяет отформатировать число в зависимости от локализации, что особенно полезно в многоязычных приложениях.

Пример использования:

Предположим, что мы хотим отформатировать число 1234.5678 в зависимости от локали и округлить его до 2 знаков после запятой.

$number = 1234.5678;
$formatted_number = cot_build_number($number, 2);
echo $formatted_number;  // Выведет, например: "1,234.57" в зависимости от локали

Если требуется округление до целого числа, например:

$formatted_number = cot_build_number($number, 0, 0);

echo $formatted_number;  // Выведет: "1,235" (округлено до целого)

Это важная функция для отображения чисел в интерфейсах с учётом локализации и округлений, особенно в приложениях, работающих с денежными суммами, количеством товаров и других подобных данных.