_{Official ZPE/YASS documentation}Converter

Introduction

The Converter object provides a set of unit converters that can be used to convert between common measurement systems (metric, imperial/US customary, and scientific units where appropriate).

The design is intentionally modular: the Converter object is a container, and each converter is accessed as a sub-object (for example, $converter->distance()).

Each converter follows the same pattern:

• Call set_value(number value, string type) to set the input value and unit.
• Call to_*() to convert into your desired unit.
• The conversion functions return a number (ZPENumber).

Note that this object was updated and expanded on 22/02/2026 using AI to add more conversion tools rapidly. This documentation was subsequently updated using AI also.

Usage

The Converter object is used by selecting a converter and then performing a conversion:

$converter = new Converter()

// Convert 5 miles to kilometres
$km = $converter->distance()->set_value(5, "mi")->to_kilometres()
print($km)

// Convert 10 stone to kilograms
$kg = $converter->mass()->set_value(10, "st")->to_kilograms()
print($kg)

Converter object functions

The following is a list of internal functions the Converter object exposes. All functions are ZPEObjectNativeFunctions unless specified therefore run in native code.

distance() ⇒ DistanceConverter

Returns the distance/length converter (metres, kilometres, miles, yards, feet, inches, nautical miles, and more).

mass() ⇒ MassConverter

Returns the mass/weight converter (kilograms, grams, pounds, ounces, stone, tonnes, and more).

temperature() ⇒ TemperatureConverter

Returns the temperature converter (Celsius, Fahrenheit, Kelvin).

area() ⇒ AreaConverter

Returns the area converter (m², km², hectares, acres, ft², and more).

volume() ⇒ VolumeConverter

Returns the volume converter (litres, millilitres, cubic metres, gallons, pints, and more).

energy() ⇒ EnergyConverter

Returns the energy converter (joules, kilojoules, watt-hours, kilowatt-hours, calories, and more).

time() ⇒ TimeConverter

Returns the time converter (seconds, minutes, hours, days, weeks, and more).

speed() ⇒ SpeedConverter

Returns the speed converter (m/s, km/h, mph, knots, and more).

frequency() ⇒ FrequencyConverter

Returns the frequency converter (Hz, kHz, MHz, GHz, THz).

fuel_economy() ⇒ FuelEconomyConverter

Returns the fuel economy converter (mpg UK, mpg US, L/100km, km/L).

Converter objects

Each converter object provides set_value and a set of to_* methods. Converter objects store the last value and unit you provided.

DistanceConverter

Converts between common distance/length units using metres as an internal base unit.

set_value(number value, string type) ⇒ DistanceConverter

Sets the input value and unit. The unit may be provided in short form (km, mi, ft) or common names ("kilometres", "miles", "feet").

to_metres() ⇒ number

to_kilometres() ⇒ number

to_centimetres() ⇒ number

to_millimetres() ⇒ number

to_micrometres() ⇒ number

to_nanometres() ⇒ number

to_picometers() ⇒ number

to_miles() ⇒ number

to_yards() ⇒ number

to_feet() ⇒ number

to_inches() ⇒ number

to_nautical_miles() ⇒ number

Converts the currently configured value into the chosen output unit.

Supported input units include: m, km, cm, mm, um/µm, nm, pm, mi, yd/yr, ft, in, nmi.

MassConverter

Converts between mass/weight units using kilograms as an internal base unit.

set_value(number value, string type) ⇒ MassConverter

Sets the input value and unit. Accepts common aliases such as "kg", "grams", "lb", "stone", "tonne", etc.

to_kilograms() ⇒ number

to_grams() ⇒ number

to_milligrams() ⇒ number

to_micrograms() ⇒ number

to_pounds() ⇒ number

to_ounces() ⇒ number

to_stone() ⇒ number

to_tonnes() ⇒ number

to_us_tons() ⇒ number

to_uk_tons() ⇒ number

Converts the currently configured value into the chosen output unit.

Supported input units include: kg, g, mg, ug/µg, lb/lbs, oz, st, t, ton_us, ton_uk.

TemperatureConverter

Converts between temperatures using Kelvin as an internal base unit.

set_value(number value, string type) ⇒ TemperatureConverter

Sets the input temperature and unit. Accepts "c", "f", "k", and common names such as "celsius", "fahrenheit", "kelvin". The degree symbol is accepted and ignored (for example "°c").

to_celsius() ⇒ number

to_fahrenheit() ⇒ number

to_kelvin() ⇒ number

AreaConverter

Converts between area units using square metres (m²) as an internal base unit.

set_value(number value, string type) ⇒ AreaConverter

Sets the input area and unit. Units may be entered as m2, m^2, or m², and the converter will normalise these.

to_square_metres() ⇒ number

to_square_kilometres() ⇒ number

to_square_centimetres() ⇒ number

to_square_millimetres() ⇒ number

to_hectares() ⇒ number

to_ares() ⇒ number

to_square_inches() ⇒ number

to_square_feet() ⇒ number

to_square_yards() ⇒ number

to_acres() ⇒ number

to_square_miles() ⇒ number

Supported input units include: m2, cm2, mm2, km2, ha, a, in2, ft2, yd2, acre, mi2.

VolumeConverter

Converts between common volume units using litres as an internal base unit.

set_value(number value, string type) ⇒ VolumeConverter

Sets the input value and unit. Accepts common aliases such as l, ml, m3, cm3, gal, qt, pt, floz, etc (depending on implementation).

to_litres() ⇒ number

to_millilitres() ⇒ number

to_cubic_metres() ⇒ number

to_cubic_centimetres() ⇒ number

to_us_gallons() ⇒ number

to_us_quarts() ⇒ number

to_us_pints() ⇒ number

to_us_fluid_ounces() ⇒ number

to_uk_gallons() ⇒ number

to_uk_quarts() ⇒ number

to_uk_pints() ⇒ number

to_uk_fluid_ounces() ⇒ number

Converts the currently configured value into the chosen output unit.

Supported input units (typical): l, ml, m3, cm3, us_gal, uk_gal, qt, pt, floz.

EnergyConverter

Converts between energy units using joules as an internal base unit.

set_value(number value, string type) ⇒ EnergyConverter

Sets the input value and unit. Accepts common aliases such as j, kj, wh, kwh, cal, kcal, btu (depending on implementation).

to_joules() ⇒ number

to_kilojoules() ⇒ number

to_watt_hours() ⇒ number

to_kilowatt_hours() ⇒ number

to_calories() ⇒ number

to_kilocalories() ⇒ number

to_btu() ⇒ number

Converts the currently configured value into the chosen output unit.

Supported input units (typical): j, kj, wh, kwh, cal, kcal, btu.

TimeConverter

Converts between time units using seconds as an internal base unit.

set_value(number value, string type) ⇒ TimeConverter

Sets the input value and unit. Accepts common aliases such as s, sec, min, h, day, etc.

to_seconds() ⇒ number

to_minutes() ⇒ number

to_hours() ⇒ number

to_days() ⇒ number

to_weeks() ⇒ number

to_months() ⇒ number

to_years() ⇒ number

Converts the currently configured value into the chosen output unit.

Supported input units (typical): s, min, h, day, week, month, year.

SpeedConverter

Converts between speed units using metres per second (m/s) as an internal base unit.

set_value(number value, string type) ⇒ SpeedConverter

Sets the input value and unit. Accepts common aliases such as m/s, km/h, mph, knot.

to_metres_per_second() ⇒ number

to_kilometres_per_hour() ⇒ number

to_miles_per_hour() ⇒ number

to_knots() ⇒ number

Converts the currently configured value into the chosen output unit.

Supported input units (typical): m/s, km/h, mph, kt/knot.

FrequencyConverter

Converts between frequency units using Hertz (Hz) as an internal base unit.

set_value(number value, string type) ⇒ FrequencyConverter

Sets the input value and unit. Accepts aliases such as hz, khz, mhz, ghz, thz.

to_hz() ⇒ number

to_khz() ⇒ number

to_mhz() ⇒ number

to_ghz() ⇒ number

to_thz() ⇒ number

Converts the currently configured value into the chosen output unit.

Supported input units (typical): hz, khz, mhz, ghz, thz.

FuelEconomyConverter

Converts between fuel economy units. This converter is useful because UK mpg and US mpg are not the same.

set_value(number value, string type) ⇒ FuelEconomyConverter

Sets the input value and unit. Typical unit identifiers: mpg_uk, mpg_us, l_per_100km, km_per_l.

to_mpg_uk() ⇒ number

to_mpg_us() ⇒ number

to_l_per_100km() ⇒ number

to_km_per_l() ⇒ number

Converts the currently configured value into the chosen output unit.

Supported input units (typical): mpg_uk, mpg_us, l/100km, l_per_100km, km/l, km_per_l.

Notes and caveats

• Converter objects are designed to be chained. set_value returns the converter instance so you can call a to_* method immediately afterwards.
• Units are normalised internally. For example, the area converter accepts m², m^2, and m2.
• If an unknown unit type is provided to set_value, conversions may return 0 depending on the converter implementation.
• Data rate: if you previously had a data rate converter and removed it due to stability issues, it is intentionally not documented here.
• Remember: to create a Map in YASS you should use [=>], not new Map().