Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Convertible

A convertible combines a number with a unit. It offers several methods to convert itself into different units and therefore is the key concept behind converting in simple-units.

Hierarchy

  • Convertible

Index

Constructors

Properties

Methods

Constructors

constructor

  • Creates a convertible with the passed value and unit. It is not recommended to create a convertible this way. Instead use the collection's .from(value: number, unit: string) or .Convertible(value: number, unit: string) method.

    Recommended way to create a convertible:

    example
    import units from "simple-units";

const convertible = units.Convertible(12, "m");
console.log(convertible.value); // Output: 12
console.log(convertible.unit.toString()); // Output: m

    Parameters

    • value: number

      the convertible's value

    • unit: Unit

      the convertible's unit

    Returns Convertible

Properties

unit

unit: Unit

The convertible's unit. Changes through converting.

value

value: number

The convertible's value. Changes through converting.

Methods

as

  • Converts the convertible to the passed unit and returns the convertible itself.

    example
    const convertible = units.from(12, "°C").as("K");

console.log(convertible.value);
// Output: 261.15

console.log(convertible.unit.toString());
// Output: K

    Parameters

    • unit: Unit | UnitString

      the target unit

    Returns Convertible

    the convertible itself

asBest

  • Converts the convertible to the best possible unit. In this case the best means having as few digits as possible before the decimal point. Returns the convertible itself.

    example
    const convertible = units.Convertible(1000, "m").asBest();

console.log(convertible.value);
// Output: 1

console.log(convertible.unit.toString());
// Output: km

    By default the convertible remains in the same unit system. If false is passed, this behaviour is disabled.

    Parameters

    • remainInUnitSystem: boolean = true

      whether to remain in the same unit system (default is true)

    Returns Convertible

    the convertible itself

compare

  • Compares this convertible semantically to another. Returns -1, 0, or 1 as this convertible is less than, equal to, or greater than the passed convertible.

    Parameters

    Returns 0 | 1 | -1

    -1, 0, or 1 as this convertible is less than, equal to, or greater than the passed convertible

copy

eq

  • Returns whether this convertible is semantically equal to the passed convertible.

    Parameters

    Returns boolean

    whether this convertible is semantically equal to the passed convertible

format

  • format(format: string, formatOptions?: FormatOptions): string

  • Returns the convertible as formatted string.

    The first argument specifies the string's format (see example), the second one additional format options.

    Currently there is only the format option length. Setting this to "long" will result in a long unit symbol (e.g. "meter" or "meters"), "short" will result in a short unit symbol (e.g. "m").

    example
    const convertible = units.Convertible(12.2323123, "kt");

console.log(convertible.format("%.2f %s", { length: "long" }));
// Output: 12.23 knots

    Parameters

    • format: string

      the string's format

    • Optional formatOptions: FormatOptions

      additional format options

    Returns string

    the convertible as formatted string

gt

  • Returns whether this convertible is semantically greater than the passed convertible.

    Parameters

    Returns boolean

    whether this convertible is semantically greater than the passed convertible

gte

  • Returns whether this convertible is semantically greater than or equal to the passed convertible.

    Parameters

    Returns boolean

    whether this convertible is semantically greater than or equal to the passed convertible

lt

  • Returns whether this convertible is semantically less than the passed convertible.

    Parameters

    Returns boolean

    whether this convertible is semantically less than the passed convertible

lte

  • Returns whether this convertible is semantically less than or equal to the passed convertible.

    Parameters

    Returns boolean

    whether this convertible is semantically less than or equal to the passed convertible

possibilities

  • possibilities(): UnitString[]

  • Returns an array of units to which the convertible can be converted.

    example
    const convertible = units.Convertible(12, "kt");

for(const unit of convertible.possibilities()){
   console.log(unit); // Output: Ym/a, Zm/a, Em/a, Pm/a, ...
}

    Returns UnitString[]

    an array of units to which the convertible can be converted

to

  • to(unit: Unit | UnitString): number

  • Converts the convertible to the passed unit and returns the conversion's result.

    example
    const convertible = units.Convertible(12, "°C");

console.log(convertible.to("K"));
// Output: 261.15

console.log(convertible.value);
// Output: 261.15

console.log(convertible.unit.toString());
// Output: K

    Parameters

    • unit: Unit | UnitString

      the target unit

    Returns number

    the conversion's result

toString

  • toString(): string

  • Returns the convertible as short string.

    example
    const convertible = units.Convertible(1000, "meter");

console.log(convertible.toString());
// Output: 1000m

console.log(convertible);
// Output: 1000m (but in blue :D)

    Returns string

Generated using TypeDoc