在进进程式设计的时候,有时会需要进行文件大小或是数据大小的输入与输出,甚至会需要对其做一些运算。做这件事有什么困难的吗?我们应该都知道,8 个比特是 1 个字节(Byte),1000 个字节是 1KB,而 1000KB 是 1MB。在设计程序的时候,如果要将一个以字节为单位的值,选择适当的单位来输出(例如 1200 字节要输出成 1.20KB、5555555 字节要输出成 5.56MB)的话,就必须要多撰写几进程式来完成。如果是数据输入的时候,假设用户输入的是「3.6MB」,程序也许需要多撰写几进程式,将其转为「3600000」来保存,表示为「3600000 个字节」;输入「25KB」,就要转成「25000」。这些虽然都是简单的事情,且所需要的代码量也不大,但就是由于简单又常用,每次都要在不同项目写一样的程序去处理就会觉得很烦躁,所以干脆将其发展为一个独立的套件,就能不断地重复使用了。

Byte Unit

「Byte Unit」是笔者开发的套件,实现了字节(B)、KB、KiB、MB、MiB、GB、GiB、TB、TiB、PB、PiB、EB、EiB、ZB、ZiB、YB、YiB 的大小单位换算。

KB、MB、GB、TB、PB、EB、ZB、YB 等都是基于 1000 的单位,而 KiB、MiB、GiB、TiB、PiB、EiB、ZiB、YiB 等则是基于 1024 的单位。

1KB  = 1000
1KiB = 1024
1MB  = 1000000
1MiB = 1048576
1GB  = 1000000000
1GiB = 1073741824
1TB  = 1000000000000
1TiB = 1099511627776
1PB  = 1000000000000000
1PiB = 1125899906842624
1EB  = 1000000000000000000
1EiB = 1152921504606846976
1ZB  = 1000000000000000000000
1ZiB = 1180591620717411303424
1YB  = 1000000000000000000000000
1YiB = 1208925819614629174706176

预设保存字节的数值类型是采用 u64,不过也可以激活 u128 特色来改为使用 u128 数值类型,最大支持的单位才会从 EiB 变成 YiB。

Crates.io

Cargo.toml

byte-unit = "*"

使用方法

Unit

Unit 枚举可以表示比特或是字节的单位。

use byte_unit::Unit;

assert_eq!("KB", Unit::KB.as_str());
assert_eq!("MiB", Unit::MiB.as_str());

assert_eq!(Unit::KB, Unit::parse_str("K", true, true).unwrap());
assert_eq!(Unit::Kbit, Unit::parse_str("K", true, false).unwrap());

assert_eq!(Unit::KB, Unit::parse_str("KB", true, true).unwrap());
assert_eq!(Unit::KB, Unit::parse_str("Kb", true, true).unwrap());
assert_eq!(Unit::Kbit, Unit::parse_str("Kbit", true, true).unwrap());

assert_eq!(Unit::KB, Unit::parse_str("KB", false, true).unwrap());
assert_eq!(Unit::Kbit, Unit::parse_str("Kb", false, true).unwrap());
Byte

Byte 结构体可以表示字节的大小。

from_* 关联函数可以被用来从不同的数据类型创建 Byte 实体。as_* 方法能以基本数据类型来取得大小。

use byte_unit::{Byte, Unit};

assert_eq!(15000, Byte::from_u64(15000).as_u64());
assert_eq!(15000, Byte::from_u64_with_unit(15, Unit::KB).unwrap().as_u64());

我们也可以解析一个字符串来产生出一个 Byte 实体。

use byte_unit::Byte;

assert_eq!(50840000, Byte::parse_str("50.84 MB", true).unwrap().as_u64());

一个 Byte 实体可以被精确地格式化成字符串。更多用法请参考 API 文档。

use byte_unit::Byte;

let byte = Byte::from_u64(15500);

assert_eq!("15500", byte.to_string());

assert_eq!("15.5 KB", format!("{byte:#}"));
assert_eq!("15500 B", format!("{byte:#.0}"));
计算

有 add、subtract、multiply 和 divide 方法可以使用。

use byte_unit::Byte;

let a = Byte::from_u64(15500);
let b = Byte::from_u64(500);

assert_eq!(16000, a.add(b).unwrap().as_u64());
assert_eq!(15000, a.subtract(b).unwrap().as_u64());

assert_eq!(31000, a.multiply(2).unwrap().as_u64());
assert_eq!(3100, a.divide(5).unwrap().as_u64());
找出适当的单位

如果我们想要替某个 Byte 实体找出适当的单位,get_exact_unit 和 get_recoverable_unit 方法很有用。

use byte_unit::{Byte, Unit};

let byte = Byte::from_u64(50840000);

assert_eq!((50840, Unit::KB), byte.get_exact_unit(false));
assert_eq!((50.84f64.try_into().unwrap(), Unit::MB), byte.get_recoverable_unit(false, 2));
assert_eq!((50840.into(), Unit::KB), byte.get_recoverable_unit(false, 0));
AdjustedByte

AdjustedByte 结构体可以被用来粗略地表示字节的大小和单位。

我们可以使用 get_adjusted_unit 方法来改变某个 Byte 实体的单位。

一个 AdjustedByte 实体可以被格式化成字符串。更多用法请参考 API 文档。

use byte_unit::{Byte, Unit};

let byte = Byte::parse_str("123KiB", true).unwrap();

let adjusted_byte = byte.get_adjusted_unit(Unit::KB);

assert_eq!("125.952 KB", adjusted_byte.to_string());
assert_eq!("125.95 KB", format!("{adjusted_byte:.2}"));

get_appropriate_unit 方法可以被用来自动地替 Byte 实体找到一个合适的单位来产生 AdjustedByte 实体。

use byte_unit::{Byte, Unit, UnitType};

let byte = Byte::from_u64(1500000);

let adjusted_byte = byte.get_appropriate_unit(UnitType::Binary);

assert_eq!("1.43 MiB", format!("{adjusted_byte:.2}"));
Bit

Bit 结构体可以表示比特的大小。

必须激活 bit 特色。

Bit 结构体的用法和 Byte 结构体非常相似。也有 AdjustedBit 结构体能用。有差异的地方在于 Bit 的 parse_str 方法不能够设置为忽略大小写,它总是不会忽略大小写。

use byte_unit::{Bit, Unit};

let bit = Bit::parse_str("123Kib").unwrap();

let adjusted_bit = bit.get_adjusted_unit(Unit::Kbit);

assert_eq!("125.952 Kb", adjusted_bit.to_string());
assert_eq!("125.95 Kb", format!("{adjusted_bit:.2}"));