sergiobenitez/ubyte

A simple, complete, const-everything, saturating, human-friendly, no_std Rust library for byte units.

ubyte  

A simple, complete, const-everything, saturating, human-friendly, #![no_std] Rust library for byte units.

use ubyte::{ByteUnit, ToByteUnit};

// Constructors and associated units for all SI units up to exbibyte.
let half_mb = 500.kilobytes();
let half_mb = ByteUnit::Kilobyte(500);
let half_mb = 500 * ByteUnit::kB;

// All arithmetic and conversions are saturating.
let exbibyte_too_large_a = 1024 * ByteUnit::EiB;
let exbibyte_too_large_b = ByteUnit::Exbibyte(1024);
let exbibyte_too_large_c = 1024.exbibytes();
assert_eq!(exbibyte_too_large_a, ByteUnit::max_value());
assert_eq!(exbibyte_too_large_b, ByteUnit::max_value());
assert_eq!(exbibyte_too_large_c, ByteUnit::max_value());

// Printing is human-friendly and customizeable.
assert_eq!(323.kilobytes().to_string(), "323kB");
assert_eq!(3.mebibytes().to_string(), "3MiB");
assert_eq!((7.gigabytes() + 58.mebibytes() + 3.kilobytes()).to_string(), "7.06GB");
assert_eq!(format!("{:.0}", 7.gibibytes() + 920.mebibytes()), "8GiB");
assert_eq!(format!("{:.3}", 7.gibibytes() + 920.mebibytes()), "7.898GiB");
assert_eq!(format!("{:04.2}", 999.kilobytes() + 990.bytes()), "0976.55KiB");
assert_eq!(format!("{:02.0}", 999.kilobytes() + 990.bytes()), "01MB");

// Parsing is intuitive.
assert_eq!("10 KiB".parse().unwrap(), 10.kibibytes());
assert_eq!("10kb".parse().unwrap(), 10.kilobytes());
assert_eq!("512Kb".parse().unwrap(), 512.kilobytes());
assert_eq!("0.2MB".parse().unwrap(), 200.kilobytes());
assert_eq!("1.5 MiB".parse().unwrap(), 1.mebibytes() + 512.kibibytes());
assert_eq!("7.25 gb".parse().unwrap(), 7.gigabytes() + 250.megabytes());

See the documentation for detailed usage information.

Usage

Add the following to your Cargo.toml:

[dependencies]
ubyte = "0.10"

For serde (de)serialization support, enable the serde feature, which is disabled by default:

[dependencies]
ubyte = { version = "0.10", features = ["serde"] }

License

ubyte is licensed under either of the following, at your option:

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in ubyte by you shall be dual licensed as above without any additional terms or conditions.

ubyte's Issues

Panic when parsing byte unit with very long fractional part

assert_parses! {
    "9.00000000000000000000MB" => 9.megabytes(),
}

This test should pass, but instead you get

thread 'parse::parse_tests::accept' panicked at 'attempt to multiply with overflow', /rustc/8b09ba6a5d5c644fe0f1c27c7f9c80b334241707/library/core/src/num/mod.rs:843:5
stack backtrace:
   0: rust_begin_unwind
             at /rustc/8b09ba6a5d5c644fe0f1c27c7f9c80b334241707/library/std/src/panicking.rs:498:5
   1: core::panicking::panic_fmt
             at /rustc/8b09ba6a5d5c644fe0f1c27c7f9c80b334241707/library/core/src/panicking.rs:106:14
   2: core::panicking::panic
             at /rustc/8b09ba6a5d5c644fe0f1c27c7f9c80b334241707/library/core/src/panicking.rs:47:5
   3: core::num::<impl u64>::pow
             at /rustc/8b09ba6a5d5c644fe0f1c27c7f9c80b334241707/library/core/src/num/uint_macros.rs:1955:13
   4: ubyte::parse::<impl core::str::traits::FromStr for ubyte::byte_unit::ByteUnit>::from_str
             at ./src/parse.rs:77:47
   5: ubyte::parse::parse_tests::accept
             at ./src/parse.rs:183:9
   6: ubyte::parse::parse_tests::accept::{{closure}}
             at ./src/parse.rs:134:5
   7: core::ops::function::FnOnce::call_once
             at /rustc/8b09ba6a5d5c644fe0f1c27c7f9c80b334241707/library/core/src/ops/function.rs:227:5
   8: core::ops::function::FnOnce::call_once
             at /rustc/8b09ba6a5d5c644fe0f1c27c7f9c80b334241707/library/core/src/ops/function.rs:227:5
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

The problem is the .pow in

ubyte/src/parse.rs

Line 77 in c3cfe51

let frac_part = frac as f64 / 10u64.pow(frac_str.len() as u32) as f64;

I think this probably should be parsed successfully (as opposed to giving an error).

I'll have a look at trying to fix the arithmetic, but this kind of code is kinda hard to reason about for me.

FromStr Err type don't implement std::error::Error trait

Err of FromStr is defined as Option<(usize,char)> and it's not possible to handle it with generic error handling code.

I've encountered a problem when tried to use your crate in conjunction with structopt.

Deserialization of strings fails

Can't use serde deserialize feature because in ser_de.rs deserialization expects a u64:

impl<'de> Deserialize<'de> for ByteUnit {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
        where D: serde::Deserializer<'de>
    {
        deserializer.deserialize_u64(Visitor)
    }
}

Even though Visitor declares visit_str, it is not called because serde expects u64 and returns error when string is used.

How to add space between the number and the unit?

The linguistically correct way of formatting values with units (at least in English and in Polish) is to put a space between the number and the unit: "2 MB" not "2MB". Is there an option to do this?