Skip to main content

API reference

This page lists the public members of the base classes. All types are in the Renfordt\UnitLib namespace.

PhysicalQuantity​

Abstract base class implementing JsonSerializable and Stringable. Every quantity type extends it.

Properties​

public readonly float $originalValue;
public readonly UnitOfMeasurement $originalUnit;
public readonly float $nativeValue;
public readonly UnitOfMeasurement $nativeUnit;

Constructor​

public function __construct(float $originalValue, string|UnitOfMeasurement $unit)

Throws InvalidArgumentException if the unit cannot be resolved.

Conversion​

public function toUnit(string|UnitOfMeasurement $unit): float
public function toNativeUnit(): PhysicalQuantity

toUnit() returns the value in the requested unit. toNativeUnit() returns a new instance expressed in the native unit.

Arithmetic​

public function add(PhysicalQuantity $quantity): PhysicalQuantity
public function subtract(PhysicalQuantity $quantity): PhysicalQuantity
public function multiply(PhysicalQuantity $quantity, ?string $resultType = null): PhysicalQuantity
public function divide(PhysicalQuantity $quantity): PhysicalQuantity
public function power(int $exponent): PhysicalQuantity

add() and subtract() return a new instance of the same type in the native unit. multiply(), divide(), and power() return derived quantity types and throw InvalidArgumentException for unsupported combinations. The $resultType argument on multiply() disambiguates Force × Length between Energy and Torque. divide() throws if the divisor's native value is zero. See Derived units.

Comparison​

public function compareTo(PhysicalQuantity $quantity): int           // -1, 0, or 1
public function greaterThan(PhysicalQuantity $quantity): bool
public function lessThan(PhysicalQuantity $quantity): bool
public function greaterThanOrEqualTo(PhysicalQuantity $quantity): bool
public function lessThanOrEqualTo(PhysicalQuantity $quantity): bool
public function equals(PhysicalQuantity $quantity, float $epsilon = 1e-10): bool

All comparison methods throw InvalidArgumentException if the operand is a different quantity type. See Comparison.

Parsing and serialization​

public static function parse(string $input, ?string $expectedClass = null): PhysicalQuantity
public function jsonSerialize(): array
public static function fromJson(array $data): PhysicalQuantity

See Parsing strings and Serialization.

String conversion​

public function __toString(): string

Returns "{originalValue} {originalUnit->name}".

Methods for subclasses​

abstract protected function initialise(): void;
protected function addUnit(UnitOfMeasurement $unit): void;
protected function findUnit(string $unitName): UnitOfMeasurement;
protected function convert(UnitOfMeasurement $unit): PhysicalQuantity;

initialise() must be implemented by every subclass to register its units. The first unit registered becomes the native unit. Subclasses with offset-based scales may also define convertToNativeUnit(float $value, string $unitName): float; the constructor calls it when present. See Adding new quantities.

UnitOfMeasurement​

Value object for a single unit.

Constructor​

public function __construct(string $name, float $conversionFactor)

The name is registered as the first alias. The conversion factor is relative to the native unit.

Properties​

public readonly string $name;
public float $conversionFactor;   // read-only via property hook
public array $aliases;            // read-only via property hook

Methods​

public function addAlias(string $alias): void
public function isAlias(string $alias): bool

conversionFactor and aliases are accessed as properties, not methods. See UnitOfMeasurement.

HasSIUnits​

Trait adding metric prefix conversion.

public function convertSIUnit(float $value, string $fromUnit, string $toUnit): float
protected function getSIBaseUnit(): string   // override per quantity; defaults to 'm'

A quantity uses the trait and overrides getSIBaseUnit() to declare its base unit symbol. convertSIUnit() throws InvalidArgumentException for invalid units or for a conversion between units of different powers. See SI units.