# `si-scale`
[](https://crates.io/crates/si-scale)
[](https://docs.rs/si-scale)
[](https://rust-lang.github.io/rfcs/2495-min-rust-version.html)
[](https://github.com/graelo/si-scale/actions/workflows/essentials.yml)
Format value with units according to SI ([système international d’unités](https://en.wikipedia.org/wiki/International_System_of_Units)).
Version requirement: _rustc 1.78+_
```toml
[dependencies]
si-scale = "0.2"
```
## Overview
This crate formats numbers using the
[SI Scales](https://en.wikipedia.org/wiki/International_System_of_Units):
from 1 y (yocto, i.e. 1e-24) to 1 Y (Yotta, i.e. 1e24).
It has the same purpose as the great
[human-repr](https://docs.rs/human-repr), but strikes a different balance:
- this crate yields more terse code at the call sites
- it gives you more control over the output. As shown later in this page,
you can extend it pretty easily to handle throughput, etc. (seriously, see
below)
- but it only operates on numbers, so it does not prevent you from using a
function to print meters on a duration value (which human-repr does
brilliantly).
## Getting started
To use this crate, either use one of the few pre-defined helper functions,
or build your own.
Basic example:
```rust
use si_scale::helpers::{seconds, seconds3};
let actual = format!("{}", seconds(1.3e-5));
let expected = "13 µs";
assert_eq!(actual, expected);
let actual = format!("{}", seconds3(1.3e-5));
let expected = "13.000 µs";
assert_eq!(actual, expected);
```
## Features
- **`lossy-conversions`**: enables support for `u64`, `i64`, `usize`, and
`isize`. These conversions may lose precision for values > 2^53.
```toml
[dependencies]
si-scale = { version = "0.2", features = ["lossy-conversions"] }
```
## Pre-defined helper functions
The helper functions use the following naming convention:
- the name indicates the units to use
- a number suffix indicates the decimal digits for floating points
- a `_` suffix indicates the digits use "thousands grouping"
But that's up to you to depart from that when writing your own functions.
Currently the helper functions are:
| `number_()` | `1.234567`, `1515` | `1.234_567`, `1_515` |
| --- | --- | --- |
| `seconds()` | `1.234567e-6`, `16e-3` | `1.234567 µs`, `16 ms` |
| `seconds3()` | `1.234567e-6`, `16e-3` | `1.235 µs`, `16.000 ms`|
| --- | --- | --- |
| `bytes()` | `1234567` | `1.234567 MB` |
| `bytes_()` | `1234567` | `1_234_567 B` |
| `bytes1()` | `2.3 * 1e12` | `2.3 TB` |
| `bytes2()` | `2.3 * 1e12` | `2.30 TB` |
| --- | --- | --- |
| `bibytes()` | `1024 * 1024 * 1.25` | `1.25 MiB` |
| `bibytes1()` | `1024 * 1024 * 1.25` | `1.3 MiB` |
| `bibytes2()` | `1024 * 1024 * 1.25` | `1.25 MiB` |
## Custom helper functions - BYOU (bring your own unit)
To define your own format function, use the
[`scale_fn!()`](`crate::scale_fn!\(\)`) macro. All pre-defined helper
functions from this crate are defined using this macro.
| `number_()` | `"{}"` | `UnitOnly` | B1000 | `_` | `1.234567`, `1515` | `1.234_567`, `1_515` |
| --- | -- | --- | --- | --- | --- | --- |
| `seconds()` | `"{}"` | `UnitAndBelow` | B1000 | none | `1.234567e-6`, `16e-3` | `1.234567 µs`, `16 ms` |
| `seconds3()` | `"{:.3}"` | `UnitAndBelow` | B1000 | none | `1.234567e-6`, `16e-3` | `1.235 µs`, `16.000 ms`|
| --- | -- | --- | --- | --- | --- | --- |
| `bytes()` | `"{}"` | `UnitAndAbove` | B1000 | none | `1234567` | `1.234567 MB` |
| `bytes_()` | `"{}"` | `UnitOnly` | B1000 | `_` | `1234567` | `1_234_567 B` |
| `bytes1()` | `"{:.1}"` | `UnitAndAbove` | B1000 | none | `2.3 * 1e12` | `2.3 TB` |
| `bytes2()` | `"{:.2}"` | `UnitAndAbove` | B1000 | none | `2.3 * 1e12` | `2.30 TB` |
| --- | -- | --- | --- | --- | --- | --- |
| `bibytes()` | `"{}"` | `UnitAndAbove` | B1024 | none | `1024 * 1024 * 1.25` | `1.25 MiB` |
| `bibytes1()` | `"{:.1}"` | `UnitAndAbove` | B1024 | none | `1024 * 1024 * 1.25` | `1.3 MiB` |
| `bibytes2()` | `"{:.2}"` | `UnitAndAbove` | B1024 | none | `1024 * 1024 * 1.25` | `1.25 MiB` |
The additional table columns show the underlying controls.
### The "mantissa" column
It is a format string which only acts on the mantissa after scaling. For
instance, `"{}"` will display the value with all its digits or no digits if
it is round, and `"{:.1}"` for instance will always display one decimal.
### The "prefix constraint" column
In a nutshell, this allows values to be represented in unsurprising scales:
for instance, you would never write `1.2 ksec`, but always `1200 sec` or
`1.2e3 sec`. In the same vein, you would never write `2 mB`, but always
`0.002 B` or `2e-3 B`.
So, here the term "unit" refers to the unit scale (`1`), and has nothing to
do with units of measurements. It constrains the possible scales for a
value:
- `UnitOnly` means the provided value won't be scaled: if you provide a
value larger than 1000, say 1234, it will be printed as 1234.
- `UnitAndAbove` means the provided value can only use higher scales, for
instance `16 GB` but never `4.3 µB`.
- `UnitAndBelow` means the provided value can only use lower scales, for
instance `1.3 µsec` but not `16 Gsec`.
### The "base" column
Base B1000 means 1k = 1000, the base B1024 means 1k = 1024. This is defined
in an [IEC document](https://www.iec.ch/prefixes-binary-multiples). If you
set the base to `B1024`, the mantissa will be scaled appropriately, but in
most cases, you will be using `B1000`.
### The "groupings" column
Groupings refer to "thousands groupings"; the provided char will be
used (for instance 1234 is displayed as 1\_234), if none, the value is
displayed 1234.
### Example - how to define a helper for kibits/s
For instance, let's define a formatting function for bits per sec which
prints the mantissa with 2 decimals, and also uses base 1024 (where 1 ki =
1024). Note that although we define the function in a separate module,
this is not a requirement.
```rust
mod unit_fmt {
use si_scale::scale_fn;
use si_scale::prelude::Value;
// defines the `bits_per_sec()` function
scale_fn!(bits_per_sec,
base: B1024,
constraint: UnitAndAbove,
mantissa_fmt: "{:.2}",
groupings: '_',
unit: "bit/s",
doc: "Return a string with the value and its si-scaled unit of bit/s.");
}
use unit_fmt::bits_per_sec;
fn main() {
let x = 2.1 * 1024 as f32;
let actual = format!("throughput: {:>15}", bits_per_sec(x));
let expected = "throughput: 2.10 kibit/s";
assert_eq!(actual, expected);
let x = 2;
let actual = format!("throughput: {}", bits_per_sec(x));
let expected = "throughput: 2.00 bit/s";
assert_eq!(actual, expected);
}
```
You can omit the `groupings` argument of the macro to not separate
thousands.
## SI Scales - Developer doc
With base = 1000, 1k = 1000, 1M = 1\_000\_000, 1m = 0.001, 1µ = 0.000\_001,
etc.
| .. | .. | -24 | `Prefix::Yocto` |
| .. | .. | -21 | `Prefix::Zepto` |
| .. | .. | -18 | `Prefix::Atto` |
| .. | .. | -15 | `Prefix::Femto` |
| .. | .. | -12 | `Prefix::Pico` |
| .. | .. | -9 | `Prefix::Nano` |
| 0.000\_001 | 0.001 | -6 | `Prefix::Micro` |
| 0.001 | 1 | -3 | `Prefix::Milli` |
| 1 | 1_000 | 0 | `Prefix::Unit` |
| 1000 | 1\_000\_000 | 3 | `Prefix::Kilo` |
| 1\_000\_000 | 1\_000\_000\_000 | 6 | `Prefix::Mega` |
| .. | .. | 9 | `Prefix::Giga` |
| .. | .. | 12 | `Prefix::Tera` |
| .. | .. | 15 | `Prefix::Peta` |
| .. | .. | 18 | `Prefix::Exa` |
| .. | .. | 21 | `Prefix::Zetta` |
| .. | .. | 24 | `Prefix::Yotta` |
The base is usually 1000, but can also be 1024 (bibytes).
With base = 1024, 1ki = 1024, 1Mi = 1024 * 1024, etc.
### API overview
The central representation is the [`Value`](`crate::value::Value`) type,
which holds
- the mantissa,
- the SI unit prefix (such as "kilo", "Mega", etc),
- and the base which represents the cases where "1 k" means 1000 (most
common) and the cases where "1 k" means 1024 (for kiB, MiB, etc).
This crate provides 2 APIs: a low-level API, and a high-level API for
convenience.
For the low-level API, the typical use case is
- first parse a number into a [`Value`](`crate::value::Value`). For doing
this, you have to specify the base, and maybe some constraint on the SI
scales. See [`Value::new()`](`crate::value::Value::new\(\)`) and
[`Value::new_with()`](`crate::value::Value::new_with\(\)`)
- then display the `Value` either by yourself formatting the mantissa
and prefix (implements the `fmt::Display` trait), or using the provided
Formatter.
For the high-level API, the typical use cases are
1. parse and display a number using the provided functions such as
`bibytes()`, `bytes()` or `seconds()`, they will choose for each number
the most appropriate SI scale.
2. In case you want the same control granularity as the low-level API
(e.g. constraining the scale in some way, using some base, specific
mantissa formatting), then you can build a custom function using the
provided macro `scale_fn!()`. The existing functions such as
`bibytes()`, `bytes()`, `seconds()` are all built using this same
macro.
### The high-level API
The `seconds3()` function parses a number into a `Value` and displays it
using 3 decimals and the appropriate scale for seconds (`UnitAndBelow`),
so that non-sensical scales such as kilo-seconds can't be output. The
`seconds()` function does the same but formats the mantissa with the
default `"{}"`, so no decimals are printed for integer mantissa.
```rust
use si_scale::helpers::{seconds, seconds3};
let actual = format!("result is {:>15}", seconds(1234.5678));
let expected = "result is 1234.5678 s";
assert_eq!(actual, expected);
let actual = format!("result is {:>10}", seconds3(12.3e-7));
let expected = "result is 1.230 µs";
assert_eq!(actual, expected);
```
The `bytes()` function parses a number into a `Value` _using base 1000_
and displays it using 1 decimal and the appropriate scale for bytes
(`UnitAndAbove`), so that non-sensical scales such as milli-bytes may not
appear.
```rust
use si_scale::helpers::{bytes, bytes1};
let actual = format!("result is {}", bytes1(12_345_678));
let expected = "result is 12.3 MB";
assert_eq!(actual, expected);
let actual = format!("result is {:>10}", bytes(16));
let expected = "result is 16 B";
assert_eq!(actual, expected);
let actual = format!("result is {}", bytes(0.12));
let expected = "result is 0.12 B";
assert_eq!(actual, expected);
```
The `bibytes1()` function parses a number into a `Value` _using base 1024_
and displays it using 1 decimal and the appropriate scale for bytes
(`UnitAndAbove`), so that non-sensical scales such as milli-bytes may not
appear.
```rust
use si_scale::helpers::{bibytes, bibytes1};
let actual = format!("result is {}", bibytes1(12_345_678));
let expected = "result is 11.8 MiB";
assert_eq!(actual, expected);
let actual = format!("result is {}", bibytes(16 * 1024));
let expected = "result is 16 kiB";
assert_eq!(actual, expected);
let actual = format!("result is {:>10}", bibytes1(16));
let expected = "result is 16.0 B";
assert_eq!(actual, expected);
let actual = format!("result is {}", bibytes(0.12));
let expected = "result is 0.12 B";
assert_eq!(actual, expected);
```
### The low-level API
#### Creating a `Value` with `Value::new()`
The low-level function [`Value::new()`](`crate::value::Value::new\(\)`)
converts any number convertible to f64 into a `Value` using base 1000. The
`Value` struct implements `From` for common numbers and delegates to
`Value::new()`, so they are equivalent in practice. Here are a few
examples.
```rust
use std::convert::From;
use si_scale::prelude::*;
let actual = Value::from(0.123);
let expected = Value {
mantissa: 123f64,
prefix: Prefix::Milli,
base: Base::B1000,
};
assert_eq!(actual, expected);
assert_eq!(Value::new(0.123), expected);
let actual: Value = 0.123.into();
assert_eq!(actual, expected);
let actual: Value = 1300i32.into();
let expected = Value {
mantissa: 1.3f64,
prefix: Prefix::Kilo,
base: Base::B1000,
};
assert_eq!(actual, expected);
let actual: Vec<Value> = vec![0.123f64, -1.5e28]
.iter().map(|n| n.into()).collect();
let expected = vec![
Value {
mantissa: 123f64,
prefix: Prefix::Milli,
base: Base::B1000,
},
Value {
mantissa: -1.5e4f64,
prefix: Prefix::Yotta,
base: Base::B1000,
},
];
assert_eq!(actual, expected);
```
As you can see in the last example, values which scale are outside of the
SI prefixes are represented using the closest SI prefix.
#### Creating a `Value` with `Value::new_with()`
The low-level [`Value::new_with()`](`crate::value::Value::new_with\(\)`)
operates similarly to [`Value::new()`](`crate::value::Value::new\(\)`) but
also expects a base and a constraint on the scales you want to use. In
comparison with the simple `Value::new()`, this allows base 1024 scaling
(for kiB, MiB, etc) and preventing upper scales for seconds or lower
scales for integral units such as bytes (e.g. avoid writing 1300 sec as
1.3 ks or 0.415 B as 415 mB).
```rust
use si_scale::prelude::*;
// Assume this is seconds, no kilo-seconds make sense.
let actual = Value::new_with(1234, Base::B1000, Constraint::UnitAndBelow);
let expected = Value {
mantissa: 1234f64,
prefix: Prefix::Unit,
base: Base::B1000,
};
assert_eq!(actual, expected);
```
Don't worry yet about the verbosity, the following parser helps with this.
#### Formatting values
In this example, the number `x` is converted into a value and displayed
using the most appropriate SI prefix. The user chose to constrain the
prefix to be anything lower than `Unit` (1) because kilo-seconds make
no sense.
```rust
use si_scale::format_value;
use si_scale::{value::Value, base::Base, prefix::Constraint};
let x = 1234.5678;
let v = Value::new_with(x, Base::B1000, Constraint::UnitAndBelow);
let unit = "s";
let actual = format!(
"result is {}{u}",
format_value!(v, "{:.5}", groupings: '_'),
u = unit
);
let expected = "result is 1_234.567_80 s";
assert_eq!(actual, expected);
```
## Run code-coverage
Install the llvm-tools-preview component and grcov
```sh
rustup component add llvm-tools-preview
cargo install grcov
```
Install nightly
```sh
rustup toolchain install nightly
```
The following make invocation will switch to nigthly run the tests using
Cargo, and output coverage HTML report in `./coverage/`
```sh
make coverage
```
The coverage report is located in `./coverage/index.html`
## License
Licensed under either of
- [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
- [MIT license](http://opensource.org/licenses/MIT)
at your option.
### Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.