CloudCastle UnitConvertor

UnitRegistry
in package

Application

FinalYes

Реестр единиц измерения с ленивой загрузкой категорий.

Категории загружаются из файлов данных по требованию: конверсия длин не тратит память на электрические величины. Успешно разрешённые коды (включая алиасы и динамические префиксные единицы) кэшируются для O(1)-повторов.

Внешние справочники подключаются тремя способами:

свой каталог данных вместо встроенного (аргумент конструктора);
дополнительные каталоги поверх встроенного (UnitRegistry::attachSource());
программные категории и единицы (UnitRegistry::registerCategory(), UnitRegistry::register()).

Динамические префиксы: код «Gm» отсутствует в данных, но разбирается как «G» (гига) + «m» (метр) — для любой единицы, помеченной как префиксуемая (СИ-префиксы от кветто 10⁻³⁰ до кветта 10³⁰, IEC-префиксы Ki…Yi).

Constants

CYRILLIC_LOWER : mixed = ['А' => 'а', 'Б' => 'б', 'В' => 'в', 'Г' => 'г'...: Таблица приведения кириллицы к нижнему регистру без ext-mbstring.
IEC_PREFIXES : mixed = ['Ki' => '1024', 'Mi' => '1048576', 'Gi' => '10...: IEC-префиксы: символ → точный множитель (2¹⁰ⁿ) десятичной строкой.
MISSING_CACHE_LIMIT : mixed = 1024: Потолок кэша промахов: дальше он сбрасывается целиком.
SI_PREFIXES : mixed = ['Q' => 30, 'R' => 27, 'Y' => 24, 'Z' => 21, 'E...: СИ-префиксы: символ → десятичная экспонента множителя.

Properties

$baseByCategory : array<string, string>
$categoryDimensions : array<string, Dimension>
$categorySi : array<string, float>
$categorySiString : array<string, string>
$categorySources : array<string, DataLoader, 1: string}>
$categoryUnits : array<string, array<int, string>>
$exactBlob : string: Пакованная карта «код/алиас → категория»: строки «\ncode:category\n».
$loadedCategories : array<string, bool>
$loader : DataLoader
$missing : array<string, true>: Ключи с подтверждённым отсутствием: промах стоит перебора префиксов и двух проходов по индексу, а парсер спрашивает одни и те же не-единицы на каждой строке («ft 3 in» в «5 ft 3 in»).
$path : string
$resolved : array<string, Unit>
$signatures : array<string, string>
$units : array<string, Unit>

Methods

__construct() : mixed
attachSource() : void: Подключает дополнительный внешний справочник — каталог данных того же формата, что встроенный (index.php + units/*.php), поверх текущего.
baseUnitForDimension() : Unit|null: Базовая единица категории, закреплённой за размерностью (для размерностного анализа); null, если такой категории нет.
baseUnitOf() : Unit: Базовая единица категории.
categories() : array<int, string>: Список всех категорий (встроенных, внешних и зарегистрированных).
dataPath() : string: Каталог данных реестра.
derivedBaseFor() : Unit: Базовая единица для размерности: существующая категория или синтетическая производная СИ-единица (результаты размерностного анализа).
dimensionOf() : Dimension: Размерность категории.
has() : bool: Известен ли код (без исключения).
register() : void: Регистрирует пользовательскую единицу.
registerCategory() : void: Регистрирует программную категорию — внешний справочник в виде массива того же формата, что файл данных (dimension, si, units).
resolve() : Unit: Разрешает код, алиас или префиксную форму в единицу.
siFactorOf() : float: СИ-множитель категории: отношение её базовой единицы к когерентной СИ-единице той же размерности.
siFactorStringOf() : string: Точный десятичный СИ-множитель категории (для BCMath-пути).
suggest() : array<int, string>: Подсказки похожих кодов («возможно, вы имели в виду»).
unitsOf() : array<int, Unit>: Все единицы категории.
appendIndexEntry() : void: Дописывает запись в пакованный индекс.
deriveIecPrefixed() : Unit: Собирает производную IEC-префиксную единицу (точный множитель — степень 2).
deriveSiPrefixed() : Unit: Собирает производную СИ-префиксную единицу (точный множитель — степень 10).
ensureCategoryBacking() : void: Регистрация в существующую, но ещё не загруженную категорию сначала подгружает её: встроенные единицы не должны пропадать из-за пометки категории загруженной.
ingestCategory() : void: Вливает разобранную категорию в карты реестра.
loadCategory() : void: Загружает категорию из её источника один раз.
lookup() : Unit|null: Медленный путь разрешения: индекс, категория, префиксы, регистр.
lookupExact() : Unit|null: Точное разрешение по индексу с загрузкой категории.
lookupIndex() : string|null: Категория кода по пакованному индексу; null — код неизвестен.
mergeExactBlob() : void: Вливает пакованную карту кодов внешнего справочника.
prefixBase() : Unit|null: Возвращает префиксуемую базовую единицу для кода с данным префиксом.
requireCategory() : void: Требует загруженную категорию (встроенную, внешнюю или программную).
resolvePrefixed() : Unit|null: Пробует разобрать код как «префикс + известная префиксуемая единица».
storePrefixed() : Unit: Регистрирует производную префиксную единицу в картах реестра.
toLower() : string: Нижний регистр для ASCII и кириллицы без ext-mbstring.

CYRILLIC_LOWER

Таблица приведения кириллицы к нижнему регистру без ext-mbstring.


    private
        mixed
    CYRILLIC_LOWER
    = ['А' => 'а', 'Б' => 'б', 'В' => 'в', 'Г' => 'г', 'Д' => 'д', 'Е' => 'е', 'Ё' => 'ё', 'Ж' => 'ж', 'З' => 'з', 'И' => 'и', 'Й' => 'й', 'К' => 'к', 'Л' => 'л', 'М' => 'м', 'Н' => 'н', 'О' => 'о', 'П' => 'п', 'Р' => 'р', 'С' => 'с', 'Т' => 'т', 'У' => 'у', 'Ф' => 'ф', 'Х' => 'х', 'Ц' => 'ц', 'Ч' => 'ч', 'Ш' => 'ш', 'Щ' => 'щ', 'Ъ' => 'ъ', 'Ы' => 'ы', 'Ь' => 'ь', 'Э' => 'э', 'Ю' => 'ю', 'Я' => 'я']

IEC_PREFIXES

IEC-префиксы: символ → точный множитель (2¹⁰ⁿ) десятичной строкой.


    private
        mixed
    IEC_PREFIXES
    = ['Ki' => '1024', 'Mi' => '1048576', 'Gi' => '1073741824', 'Ti' => '1099511627776', 'Pi' => '1125899906842624', 'Ei' => '1152921504606846976', 'Zi' => '1180591620717411303424', 'Yi' => '1208925819614629174706176']

MISSING_CACHE_LIMIT

Потолок кэша промахов: дальше он сбрасывается целиком.


    private
        mixed
    MISSING_CACHE_LIMIT
    = 1024

SI_PREFIXES

СИ-префиксы: символ → десятичная экспонента множителя.


    private
        mixed
    SI_PREFIXES
    = ['Q' => 30, 'R' => 27, 'Y' => 24, 'Z' => 21, 'E' => 18, 'P' => 15, 'T' => 12, 'G' => 9, 'M' => 6, 'k' => 3, 'h' => 2, 'da' => 1, 'd' => -1, 'c' => -2, 'm' => -3, 'µ' => -6, 'u' => -6, 'n' => -9, 'p' => -12, 'f' => -15, 'a' => -18, 'z' => -21, 'y' => -24, 'r' => -27, 'q' => -30]

$baseByCategory


        private
            array<string, string>
    $baseByCategory
     = []

категория → код базовой единицы

$categoryDimensions


        private
            array<string, Dimension>
    $categoryDimensions
     = []

категория → размерность

$categorySi


        private
            array<string, float>
    $categorySi
     = []

категория → СИ-множитель базы

$categorySiString


        private
            array<string, string>
    $categorySiString
     = []

категория → точный СИ-множитель базы

$categorySources


        private
            array<string, DataLoader, 1: string}>
    $categorySources
     = []

категория → источник и файл

$categoryUnits


        private
            array<string, array<int, string>>
    $categoryUnits
     = []

категория → канонические коды её единиц

$exactBlob

Пакованная карта «код/алиас → категория»: строки «\ncode:category\n».


        private
            string
    $exactBlob

На ~тысяче ключей экономит сотни килобайт против хэш-массива; промахи ищутся подстрокой один раз и кэшируются в UnitRegistry::$resolved.

$loadedCategories


        private
            array<string, bool>
    $loadedCategories
     = []

загруженные категории

$loader read-only


        private
            DataLoader
    $loader

$missing

Ключи с подтверждённым отсутствием: промах стоит перебора префиксов и двух проходов по индексу, а парсер спрашивает одни и те же не-единицы на каждой строке («ft 3 in» в «5 ft 3 in»).


        private
            array<string, true>
    $missing
     = []

$path read-only


        private
            string
    $path

$resolved


        private
            array<string, Unit>
    $resolved
     = []

кэш всех успешно разрешённых ключей (hot path)

$signatures


        private
            array<string, string>
    $signatures
     = []

сигнатура размерности → категория

$units


        private
            array<string, Unit>
    $units
     = []

канонический код → единица

__construct()


    public
                    __construct([null|string $dataPath = null ]) : mixed

Parameters

$dataPath : null|string = null: каталог данных; null — встроенные данные пакета. Каталог должен быть доверенным: данные — PHP-код

attachSource()

Подключает дополнительный внешний справочник — каталог данных того же формата, что встроенный (index.php + units/*.php), поверх текущего.


    public
                    attachSource(string $dataPath[, bool $override = false ]) : void

Индекс справочника генерируется IndexBuilder. При $override = true коды справочника перекрывают встроенные (для ещё не разрешённых кодов); иначе конфликтные коды пропускаются.

Parameters

$dataPath : string
$override : bool = false

baseUnitForDimension()

Базовая единица категории, закреплённой за размерностью (для размерностного анализа); null, если такой категории нет.


    public
                    baseUnitForDimension(Dimension $dimension) : Unit|null

Parameters

$dimension : Dimension

Return values

Unit|null

baseUnitOf()

Базовая единица категории.


    public
                    baseUnitOf(string $category) : Unit

Parameters

$category : string

Return values

Unit

categories()

Список всех категорий (встроенных, внешних и зарегистрированных).


    public
                    categories() : array<int, string>

Return values

array<int, string>

dataPath()

Каталог данных реестра.


    public
                    dataPath() : string

Return values

string

derivedBaseFor()

Базовая единица для размерности: существующая категория или синтетическая производная СИ-единица (результаты размерностного анализа).


    public
                    derivedBaseFor(Dimension $dimension) : Unit

Синтетическая единица получает код-нотацию («m*kg/s2»), регистрируется и с этого момента конвертируема наравне со встроенными.

Parameters

$dimension : Dimension

Return values

Unit

dimensionOf()

Размерность категории.


    public
                    dimensionOf(string $category) : Dimension

Parameters

$category : string

Return values

Dimension

has()

Известен ли код (без исключения).


    public
                    has(string $code) : bool

Отрицательный ответ не строит подсказки: перебор всего индекса нужен только для сообщения об ошибке, а не для проверки. Парсер опирается на этот метод в горячем пути составных величин («5 ft 3 in»).

Parameters

$code : string

Return values

bool

register()

Регистрирует пользовательскую единицу.


    public
                    register(Unit $unit[, bool $overwrite = false ]) : void

Первая единица новой категории становится её базовой и закрепляет сигнатуру размерности за категорией (для размерностного анализа).

Parameters

$unit : Unit
$overwrite : bool = false

registerCategory()

Регистрирует программную категорию — внешний справочник в виде массива того же формата, что файл данных (dimension, si, units).


    public
                    registerCategory(string $category, array<string|int, mixed> $definition) : void

Parameters

$category : string
$definition : array<string|int, mixed>

resolve()

Разрешает код, алиас или префиксную форму в единицу.


    public
                    resolve(string $code) : Unit

Parameters

$code : string

Return values

Unit

siFactorOf()

СИ-множитель категории: отношение её базовой единицы к когерентной СИ-единице той же размерности.


    public
                    siFactorOf(string $category) : float

Parameters

$category : string

Return values

float

siFactorStringOf()

Точный десятичный СИ-множитель категории (для BCMath-пути).


    public
                    siFactorStringOf(string $category) : string

Parameters

$category : string

Return values

string

suggest()

Подсказки похожих кодов («возможно, вы имели в виду»).


    public
                    suggest(string $code[, int $limit = 3 ]) : array<int, string>

Parameters

$code : string
$limit : int = 3

Return values

array<int, string>

unitsOf()

Все единицы категории.


    public
                    unitsOf(string $category) : array<int, Unit>

Parameters

$category : string

Return values

array<int, Unit>

appendIndexEntry()

Дописывает запись в пакованный индекс.


    private
                    appendIndexEntry(string $code, string $category) : void

Единая точка пополнения индекса: сбрасывает кэш промахов, иначе зарегистрированная позже единица осталась бы «отсутствующей».

Parameters

$code : string
$category : string

deriveIecPrefixed()

Собирает производную IEC-префиксную единицу (точный множитель — степень 2).


    private
                    deriveIecPrefixed(string $code, Unit $base, string $multiplier) : Unit

Parameters

$code : string
$base : Unit
$multiplier : string

Return values

Unit

deriveSiPrefixed()

Собирает производную СИ-префиксную единицу (точный множитель — степень 10).


    private
                    deriveSiPrefixed(string $code, Unit $base, int $exponent) : Unit

Parameters

$code : string
$base : Unit
$exponent : int

Return values

Unit

ensureCategoryBacking()

Регистрация в существующую, но ещё не загруженную категорию сначала подгружает её: встроенные единицы не должны пропадать из-за пометки категории загруженной.


    private
                    ensureCategoryBacking(string $category) : void

Parameters

$category : string

ingestCategory()

Вливает разобранную категорию в карты реестра.


    private
                    ingestCategory(string $category, Unit>} $data) : void

Parameters

$category : string
$data : Unit>}

loadCategory()

Загружает категорию из её источника один раз.


    private
                    loadCategory(string $category) : void

Parameters

$category : string

lookup()

Медленный путь разрешения: индекс, категория, префиксы, регистр.


    private
                    lookup(string $code) : Unit|null

Возвращает null вместо исключения — построение подсказок остаётся за вызывающим, чтобы проверка существования кода не стоила полного перебора индекса.

Parameters

$code : string

Return values

Unit|null

lookupExact()

Точное разрешение по индексу с загрузкой категории.


    private
                    lookupExact(string $code) : Unit|null

Parameters

$code : string

Return values

Unit|null

lookupIndex()

Категория кода по пакованному индексу; null — код неизвестен.


    private
                    lookupIndex(string $code) : string|null

Parameters

$code : string

Return values

string|null

mergeExactBlob()

Вливает пакованную карту кодов внешнего справочника.


    private
                    mergeExactBlob(string $blob, bool $override) : void

При $override новая привязка дописывается поверх (последняя выигрывает) и сбрасывает кэш ключа; иначе добавляются только незанятые коды.

Parameters

$blob : string
$override : bool

prefixBase()

Возвращает префиксуемую базовую единицу для кода с данным префиксом.


    private
                    prefixBase(string $code, string $prefix, array<int, string> $kinds) : Unit|null

Parameters

$code : string
$prefix : string
$kinds : array<int, string>: допустимые виды префиксуемости

Return values

Unit|null

requireCategory()

Требует загруженную категорию (встроенную, внешнюю или программную).


    private
                    requireCategory(string $category) : void

Parameters

$category : string

resolvePrefixed()

Пробует разобрать код как «префикс + известная префиксуемая единица».


    private
                    resolvePrefixed(string $code) : Unit|null

Parameters

$code : string

Return values

Unit|null

storePrefixed()

Регистрирует производную префиксную единицу в картах реестра.


    private
                    storePrefixed(string $code, Unit $base, string $factorString) : Unit

Parameters

$code : string
$base : Unit
$factorString : string

Return values

Unit

toLower()

Нижний регистр для ASCII и кириллицы без ext-mbstring.


    private
                    toLower(string $value) : string

Parameters

$value : string

Return values

string

UnitRegistry in package Application

Table of Contents

Constants

Properties

Methods

Constants

CYRILLIC_LOWER

IEC_PREFIXES

MISSING_CACHE_LIMIT

SI_PREFIXES

Properties

$baseByCategory

$categoryDimensions

$categorySi

$categorySiString

$categorySources

$categoryUnits

$exactBlob

$loadedCategories

$loader read-only

$missing

$path read-only

$resolved

$signatures

$units

Methods

__construct()

Parameters

attachSource()

Parameters

Tags

baseUnitForDimension()

Parameters

Return values

baseUnitOf()

Parameters

Tags

Return values

categories()

Return values

dataPath()

Return values

derivedBaseFor()

Parameters

Return values

dimensionOf()

Parameters

Tags

Return values

has()

Parameters

Return values

register()

Parameters

Tags

registerCategory()

Parameters

Tags

resolve()

Parameters

Tags

Return values

siFactorOf()

Parameters

Tags

Return values

siFactorStringOf()

Parameters

Tags

Return values

suggest()

Parameters

Return values

unitsOf()

Parameters

Tags

Return values

appendIndexEntry()

Parameters

deriveIecPrefixed()

UnitRegistry
in package

Application