Skip to main content

Units

Package for converting and formatting units and numerical values.

npm install @dynatrace-sdk/units

Conversion example

Code example
import { convert, units } from "@dynatrace-sdk/units";

convert(1000,
// units.<category>.<unit>
units.length.meter, // FromUnit
units.length.kilometer, // ToUnit
); // 1

Interfaces

AdjustFractionDigitsOptions

Properties

NameTypeDescription
localestring | Array<string>The locale according to which the number will be adjusted.
maximumFractionDigitsnumberMaximum number of decimal digits.
maximumSignificantDigitsnumberMaximum number of significant digits. Default is 21
minimumFractionDigitsnumberMinimum number of decimal digits.
minimumSignificantDigitsnumberMinimum number of significant digits. Default is 1
useGroupingbooleanWhether to use grouping separators, such as thousands separators or thousand/lakh/crore separators.

FormatDateOptions

Interface that extends Intl.DateTimeFormatOptions to pass an optional property to overwrite the default locale. See MDN.

Properties

NameTypeDescription
calendarstring
dateStyle"long" | "short" | "full" | "medium"
day"numeric" | "2-digit"
dayPeriod"long" | "short" | "narrow"
era"long" | "short" | "narrow"
formatMatcher"best fit" | "basic"
fractionalSecondDigits1 | 2 | 3
hour"numeric" | "2-digit"
hour12boolean
hourCycle"h11" | "h12" | "h23" | "h24"
localestring | Array<string>The locale according to which the number will be formatted.
localeMatcher"best fit" | "lookup"
minute"numeric" | "2-digit"
month"long" | "short" | "narrow" | "numeric" | "2-digit"
numberingSystemstring
second"numeric" | "2-digit"
timeStyle"long" | "short" | "full" | "medium"
timeZonestring
timeZoneName"long" | "short" | "shortOffset" | "longOffset" | "shortGeneric" | "longGeneric"
weekday"long" | "short" | "narrow"
year"numeric" | "2-digit"

FormatOptions

Properties

NameTypeDescription
abbreviateboolean

It will shorten the number to a shorter format. (e.g. input: 1500, output: 1.5k).

cascadenumber

Will search for the biggest unit within its group and cascade it down the the specified dept. The last number will get rounded to maximumFractionDigits. (e.g. format(1500, { input: units.length.meter, cascade: 2}), output: "1 km 500 m")).

inputFromUnit

If input unit is defined, it will convert it to the best fitting unit. (e.g. format(1500, { input: units.length.meter }), output: "1.5 km")).

localestring | Array<string>

The locale that will be used to format the number. By default it will use the platform locale specified by the user.

maximumFractionDigitsnumber

The amount of maximumFractionDigits points. See MDN. If minimumFractionDigits is passed, set to minimumFractionDigits by default. Otherwise set to 0 by default.

maximumSignificantDigitsnumberMaximum number of significant digits. Default is 21
minimumFractionDigitsnumber

The amount of minimumFractionDigits points. See MDN.

minimumSignificantDigitsnumberMinimum number of significant digits. Default is 1
outputOutputUnit<UndefinedCoalescing<FromUnit | > | ToUnit>

If not specified, the conversion is disabled (e.g. format(1500), output: 1.5K).

suffixstringA custom suffix that overwrites the unit symbol.
useGroupingboolean

Whether to use grouping separators, such as thousands separators or thousand/lakh/crore separators See MDN

Variables

ExponentialDecimalLevels: Object

Abbreviation levels for decimal metric prefixes from kilo to quecto, 10^3, 10^6, ...

ExponentialOctalBitLevels: Object

Abbreviation levels for bit binary prefixes from kilobit to quebibit, 2^10, 2^20, ...

ExponentialOctalByteLevels: Object

Abbreviation levels for byte binary prefixes from kibibyte to quebibyte, 2^10, 2^20, ...

units: Object

Grouped collection of all the supported units

Functions

_cascade

_cascade(number,unit,depth,list?,fractionDigits?): ValueUnitList

Cascades the input to the best fitting unit, depth/precision can be adjusted Supported base units units.electricity.ampere, units.electricity.volt, units.electricity.ohm, units.electricity.watt, units.electricity.coulomb, units.electricity.farad, units.electricity.weber, units.electricity.tesla, units.electricity.henry, units.electricity.siemens, units.force.newton, units.frequency.hertz, units.length.meter, units.mass.gram, units.physics.gray, units.physics.sievert, units.physics.candela, units.physics.lumen, units.physics.lux, units.physics.steradian, units.pressure.pascal, units.time.second, units.length.meter, units.data.byte, units.data.bit, units.unspecified.pixel units.angle.degree

Parameters

NameType
number*requirednumber
unit*requiredConvertibleUnit
depth*requirednumber
listCascadeUnit
fractionDigitsnumber

_convertTemperature

_convertTemperature(input,from,to): number

Parameters

NameType
input*requirednumber
from*requiredFromUnit
to*requiredConvertibleTarget<FromUnit | ToUnit>

abbreviateNumber

abbreviateNumber(input,scale,options): Object

Abbreviate large numbers to a shorter format. Example:

import { abbreviateNumber } from '@dynatrace-sdk/units';
abbreviateNumber(1500) // {"formattedValue": "2", "postfix": "k"}

Parameters

NameTypeDescription
input*requirednumberNumber to be abbreviated.
scale*requiredScale

Scale to use for the abbreviation. Default is the decimal scale:

  • abbreviateNumber(1_000) // {"formattedValue": "1", "postfix": "k"}
  • abbreviateNumber(1_000_000, ExponentialOctalByteLevels) // {"formattedValue": "977", "postfix": "KiB"}
options*requiredAdjustFractionDigitsOptions

adjustFractionDigits

adjustFractionDigits(input,options?): string

Adjust number of fractional digits.

Parameters

NameTypeDescription
input*requirednumberThe number to be formatted.
optionsAdjustFractionDigitsOptions

Returns

Description
The formatted number as a string.

convert

convert(input,from,to): number

Converts a given number to the specified unit. Example:

import { convert, units } from "@dynatrace-sdk/units";
convert(1500, units.length.meter, units.length.kilometer) // 1.5

Parameters

NameTypeDescription
input*requirednumberThe number that will get converted.
from*requiredFromUnitThe unit of the input (e.g. units.length.meter).
to*requiredConvertibleTarget<FromUnit | ToUnit>The unit of the output (e.g. units.length.kilometer).

Returns

Description
The result of the conversion (e.g. 1.5).

format

format(number,options?): string

Converts and formats the provided number.

Parameters

NameTypeDescription
number*requirednumberThe number that will get formatted.
optionsFormatOptions<FromUnit | ToUnit>Formatting options.

Returns

Description
A string containing the formatted number.

formatDate

formatDate(input,options?): string

Formats a date according to locale.

Parameters

NameTypeDescription
input*requirednumber | DateNumber of milliseconds since UNIX epoch or a Javascript Date.
optionsFormatDateOptionsAn object that contains one or more properties that specify comparison options.

Returns

Description
Date string

formatUnit

formatUnit(unit): string

Formats a unit to a string.

Parameters

NameType
unit*requiredFormattableUnit

getFormatting

getFormatting(number,options?): Formatting

Converts and formats the provided number, but returns the formatting as parts.

Parameters

NameTypeDescription
number*requirednumberThe number that will get formatted.
optionsFormatOptions<FromUnit | ToUnit>Formatting options.

Returns

Description
An Array of parts containing the formatting result object.

parseTime

parseTime(candidate?,relativeDate): null | TimeDetails

You can use the parseTime utility function to convert a string into TimeDetails, giving you a normalized version of the input string (trimmed string), a Date object created from the given input, and the type of input. The type can be either an expression or iso8601 string. If it is not possible to convert the input, the function will return null.

Parameters

NameType
candidateDEPRECATEDnull | string
relativeDate*requiredDEPRECATEDnumber

parseTimeAsTimeValue

parseTimeAsTimeValue(candidate?,relativeDate): TimeValue | null

You can use the parseTime utility function to convert a string into TimeValue, giving you a normalized version of the input string (trimmed string), a Date object created from the given input, and the type of input. The type can be either an expression or iso8601 string. If it is not possible to convert the input, the function will return null.

Parameters

NameType
candidatenull | string
relativeDate*requirednumber

variantNames

variantNames(unit): VariantNames<U>

Returns the names of all units to which the provided unit can be converted to.

Parameters

NameType
unit*requiredU

variantUnits

variantUnits(unit): VariantUnits<U>

Returns all units to which the provided unit can be converted to.

Parameters

NameType
unit*requiredU

ConvertibleUnit

All supported convertible units. For more details see a conversion example.

import { units } from '@dynatrace-sdk/units';
units.length.meter // extends ConvertibleUnit

FromUnit

A type for every convertible unit. For more details see a conversion example.

ToUnit

All units to which the FromUnit can be converted. For more details see a conversion example.

FormattableUnit

A unit that can be formatted. Example:

import { units } from '@dynatrace-sdk/units';
units.currency.eur // extends FormattableUnit

Unit

A ConvertibleUnit or a FormattableUnit or both.

ConvertibleTarget

TypeScript helper that returns all the possible convertible targets, where the first generic is FromUnit, and second is ToUnit.

Still have questions?
Find answers in the Dynatrace Community