Crate signifix

Number Formatter of Fixed Significance with Metric Unit Prefix

Signifix guarantees a fixed number of significant figures and a fixed number of resulting characters by automatically choosing the metric unit prefix and appropriately adjusting the decimal point position.

Usage

This crate is on crates.io and can be used by adding signifix to the dependencies in your project's Cargo.toml:

[dependencies]
signifix = "0.3.0"

and this to your crate root:

#![feature(try_from)] // Until stabilized.

extern crate signifix;

Examples

The fixed number of significant figures and resulting characters prevent the digits and prefixed units from jumping to the left or right:

use std::convert::TryFrom; // Until stabilized.

use signifix::{Signifix, Result};

let format = |number| -> Result<String> {
    Ok(format!("{}", Signifix::try_from(number)?))
};

assert_eq!(format(1e-04).ok(), Some("100.0 µ".into()));
assert_eq!(format(1e-03).ok(), Some("1.000 m".into()));
assert_eq!(format(1e-02).ok(), Some("10.00 m".into()));
assert_eq!(format(1e-01).ok(), Some("100.0 m".into()));
assert_eq!(format(1e+00).ok(), Some("1.000  ".into()));
assert_eq!(format(1e+01).ok(), Some("10.00  ".into()));
assert_eq!(format(1e+02).ok(), Some("100.0  ".into()));
assert_eq!(format(1e+03).ok(), Some("1.000 k".into()));
assert_eq!(format(1e+04).ok(), Some("10.00 k".into()));
assert_eq!(format(1e+05).ok(), Some("100.0 k".into()));
assert_eq!(format(1e+06).ok(), Some("1.000 M".into()));

This is useful to smoothly refresh a transfer rate inside a terminal:

use std::convert::TryFrom; // Until stabilized.

use signifix::{Signifix, Result};

let format_rate = |bytes, seconds| -> Result<String> {
    Ok(format!("{}B/s", Signifix::try_from(bytes as f64 / seconds as f64)?))
};

assert_eq!(format_rate(42_667, 300).ok(), Some("142.2  B/s".into()));
assert_eq!(format_rate(42_667, 030).ok(), Some("1.422 kB/s".into()));
assert_eq!(format_rate(42_667, 003).ok(), Some("14.22 kB/s".into()));

Or to monitor a measured quantity like an electrical current including its direction with an optional space placeholder to align with negative values.

use std::convert::TryFrom; // Until stabilized.

use signifix::{Signifix, Result};

let format_load = |current| -> Result<String> {
    Ok(format!("{:#}A", Signifix::try_from(current)?))
};

assert_eq!(format_load( 1.476e-06).ok(), Some(" 1.476 µA".into()));
assert_eq!(format_load(-2.927e-06).ok(), Some("-2.927 µA".into()));

In case of displaying a file size difference after modification, a plus sign might be preferred for positive values:

use std::convert::TryFrom; // Until stabilized.

use signifix::{Signifix, Result};

let format_diff = |curr, prev| -> Result<String> {
    Ok(format!("{:+}B", Signifix::try_from(curr - prev)?))
};

assert_eq!(format_diff(78_346, 57_393).ok(), Some("+20.95 kB".into()));
assert_eq!(format_diff(27_473, 46_839).ok(), Some("-19.37 kB".into()));

Structs

Signifix

Intermediate implementor type of this crate's TryFrom and Display trait implementations. Former tries to convert a number to this type by automatically choosing the metric unit prefix and appropriately adjusting the decimal point position while latter uses this type's fields to format the number to a string of a fixed number of significant figures and a fixed number of resulting characters. The format parameter {} prefixes negative numbers with a minus sign. The variant {:+} additionally prefixes positive numbers with a plus sign while the variant {:#} uses a whitespace instead to align with negative numbers.

Enums

Error

An error arising from this crate's TryFrom trait implementation for its Signifix type.

Constants

FACTOR	Metric unit prefix factors from 1e-24 to 1e+24 indexed from 0 to 16.
MAX_LEN	Number of resulting characters when a sign or whitespace is prefixed.
MIN_LEN	Number of resulting characters when no sign or whitespace is prefixed.
SYMBOL	Metric unit prefix symbols from y to Y indexed from 0 to 16.

Type Definitions

Result

The canonical Result type using this crate's Error type.