libraryDocs / unit

unit

libraryclientsource

Static unit conversion library (convert-units style, no object allocation).

Units belong to a measure and a system. Conversion scales through each system's anchor, applies optional anchor_shift (temperature), then bridges systems when needed.

lua

unit.convert( 1, "l", "ml" )   -- 1000
unit.convert( 1, "lb", "kg" )  -- ~0.4536
unit.convert( 100, "C", "F" )  -- 212

local value, abbr = unit.parse( "10cm" ) -- 10, "cm"

unit.measures()               -- { "length", "mass", ... }, count
unit.possibilities( "mass" )  -- { "mcg", "mg", ... }, count

Classes & types

type

unit.Definition

Internal definition of one registered unit abbreviation.

Functions

`unit.convert`	Converts value from from_unit into to_unit within one measure.
`unit.measures`	Returns a copy of the configured measure names in registration order.
`unit.parse`	Parses a quantity string such as "10cm", "1.5ft-us", or "100C".
`unit.possibilities`	Lists unit abbreviations available for conversion.

#unit.convert

clientnodiscardsource

function unit.convert(value: number, from_unit: unit.Type | string, to_unit: unit.Type | string): number

Converts value from from_unit into to_unit within one measure.

Raises ValueError when either abbreviation is unknown, the measures differ, or no system bridge exists between the two systems.

lua

unit.convert( 1, "l", "ml" )  -- 1000
unit.convert( 100, "C", "F" ) -- 212
unit.convert( 1, "lb", "kg" ) -- ~0.4536

Parameters

Name	Type	Description
`value`	`number`	The numeric magnitude expressed in `from_unit`.
`from_unit`	`unit.Type \| string`	The source unit abbreviation.
`to_unit`	`unit.Type \| string`	The destination unit abbreviation.

Returns

Type	Name	Description
`number`	`converted`	The value expressed in `to_unit`.

#unit.measures

clientnodiscardsource

function unit.measures(): unit.Measure[], integer

Returns a copy of the configured measure names in registration order.

lua

local measures, count = unit.measures()
-- measures = { "length", "mass", "volume", ... }

Returns

Type	Name	Description
`unit.Measure[]`	`measures`	A new list of configured measure names (1-based, no `[0]` length slot).
`integer`	`measure_count`	The number of measure names in the returned list.

#unit.parse

clientnodiscardsource

function unit.parse(descriptor: string): number, unit.Type

Parses a quantity string such as "10cm", "1.5ft-us", or "100C".

Raises ValueError with "missing magnitude", "missing unit type", or "unsupported unit" when the descriptor cannot be parsed.

lua

local value, abbr = unit.parse( "10cm" ) -- 10, "cm"

Parameters

Name	Type	Description
`descriptor`	`string`	The quantity string to parse (`"<number><unit>"`).

Returns

Type	Name	Description
`number`	`magnitude`	The numeric part of the descriptor.
`unit.Type`	`unit_type`	The unit abbreviation.

#unit.possibilities

clientnodiscardsource

function unit.possibilities(measure?: unit.Measure): unit.Type[], integer

Lists unit abbreviations available for conversion.

When measure is set, only that measure's units are returned. When omitted, every configured unit across all measures is returned. An unknown measure raises ValueError.

lua

local mass_units, count = unit.possibilities( "mass" ) -- { "mcg", "mg", "g", ... }, count
local all_units = unit.possibilities()                 -- every configured unit

Parameters

Name	Type	Description
`measure`optional	`unit.Measure`	Optional measure filter.

Returns

Type	Name	Description
`unit.Type[]`	`unit_types`	A new list of matching unit abbreviations (1-based, no `[0]` length slot).
`integer`	`unit_count`	The number of matching unit abbreviations.