Convert values between different units. Such as,
514 ms
to
0.514
or
sizeInKiB=4
to
size=4096
.
Parameter | Type | Required | Default Value | Description |
---|---|---|---|---|
as | string | optional[a] | The output name of the field to set (defaults to the same as the input field). | |
binary | boolean | optional[a] | false | If specified, unit prefixes kMGTPEZY will be treated as powers of 1024 instead of 1000. |
field [b] | string | required | The name of the input field. | |
from | string | optional[a] | If the field contains unitless values, specify this parameter to tell which unit the value should be normalized from. | |
keepUnit | boolean | optional[a] | false | If specified, the output field will have the normalized unit appended. |
to | string | optional[a] | The output field should have the value converted to this unit. | |
unit | string | optional[a] | If specified, the field must end with this unit. | |
[a] Optional parameters use their default value unless explicitly set. |
Hide omitted argument names for this function
Omitted Argument NamesThe argument name for
field
can be omitted; the following forms of this function are equivalent:logscaleunit:convert("field")
and:
logscaleunit:convert(field="field")
These examples show basic structure only.
Tip
If the unit begins with a reserved prefix character, try manually setting the unit parameter.
Any unit is supported and the following unit prefixes are converted:
Prefix | Decimal Factor | Binary Factor | Prefix | Typical Value |
---|---|---|---|---|
Y | 1024 | 10248 (280) | Yotta- (Yobi-) | Bytes |
Z | 1021 | 10247 (270) | Zetta- (Zebi-) | Bytes |
E | 1018 | 10246 (260) | Exa- (Exbi-) | Bytes |
P | 1015 | 10245 (250) | Peta- (Pebi-) | Bytes |
T | 1012 | 10244 (240) | Tera- (Tebi-) | Bytes |
G | 109 | 10243 (230) | Giga- (Gibi-) | Bytes |
M | 106 | 10242 (220) | Mega- (Mebi-) | Bytes |
k | 103 | 1024 (210) | Kilo- (Kibi-) | Metric, Bytes |
h | 102 | Hect- | Metric | |
da | 10 | Deca- | Metric | |
d | 10-1 | Deci- | Metric | |
c | 10-2 | Centi- | Metric | |
m | 10-3 | Milli- | Metric, Seconds | |
u, µ | 10-6 | Micro- | Metric, Seconds | |
n | 10-9 | Nano | Metric, Seconds | |
p | 10-12 | Pico | Metric, Seconds | |
f | 10-15 | Femto | Metric, Seconds | |
a | 10-18 | Atto | Metric, Seconds | |
z | 10-21 | Zepto | Metric, Seconds | |
y | 10-24 | Yocto | Metric, Seconds | |
Yi | 10248 (280) | Yobi- | Bytes | |
Zi | 10247 (270) | Zebi- | Bytes | |
Ei | 10246 (260) | Exbi- | Bytes | |
Pi | 10245 (250) | Pebi- | Bytes | |
Ti | 10244 (240) | Tebi- | Bytes | |
Gi | 10243 (230) | Gibi- | Bytes | |
Mi | 10242 (220) | Mebi- | Bytes | |
Ki | 1024 (210) | Kibi- | Metric, Bytes |
Tip
Units can be expressed as SI units or binary units. An example of a base
unit is 2Gi bytes
. We use the standard
SI-units K, M, G, and P to denote 1000-based kilo, mega, giga and peta;
whereas Ki, Mi, Gi, and Pi designate the binary multiple
1024n style. See the National Institute of
Standards & Technology's
Reference on
Prefixes for Binary Multiples for a detailed explanation.
If a field contains a value such as 5 kB that should be treated as 5 KiB, set the binary flag.
When the unit is a rate, such as MB/min the rate will be normalized to per second, e.g. B/s.
The following rate conversions are supported:
s
, sec
,
m
, min
,
h
, hour
,
d
, day
,
w
, week
.
unit:convert()
Examples
Parses a value into a number by removing the unit. An input event with
the field size with the value 5 MB results in the field size having the
value 5000000
.
unit:convert(size)
Parses a value into a number by removing the unit. An input event with
the field size with the value 5 MiB results in the field size having the
value 5242880
.
unit:convert(size)
Parses a value into a number by removing the unit. An input event with
the field size with the value 5 MB results in the field size having the
value 5242880
.
unit:convert(size, binary=true)
Parses a value into a number by removing the unit. An input event with
the field duration with the value 514
us
results in the field duration having the value
0.000514
.
unit:convert(duration)
Parses a unit less value into a number by manually specifying the input
unit. An input event with the field size with the value
234.567
results in the field size having
the value 234567
.
Internally the value is parsed as {size}
{from}
, just as if the field had contained the value
234.567 k
.
unit:convert(size, from="k")
Parses a value into a number by removing the unit. An input event with
the field rate with the value 120
hits/min
results in the field rate having the value
2
.
Note
Since the unit in this case starts with a letter
h
from the supported prefixes, it
will be interpreted as the prefix
h
(102) and unit
hits
. To enforce that the unit is
actually hits, specify the unit parameter.
unit:convert(rate, as="rate", unit="hits")
Converts a number into a value with a unit. An input event with the
field size with the value 19886168
results in the field rate having the value
19.886168
.
unit:convert(rate, as="rate", to="M")