嵌入式-SemVer —

将语义版本作为i32、u32、i64或u64的紧凑表示

由于整数格式空间有限，根据类型（32位为0-1023，64位为0-65535）对SemVer字段（主要版本、次要版本、补丁版本）大小有限制。

示例

编码

将semver编码为整数

use embedded_semver::Semver;

let version = Semver::new(1, 0, 20);
let int_semver = version.to_i32().unwrap();

assert_eq!(int_semver, 83886081);
assert_eq!(&int_semver.to_le_bytes(), &[
  0b0000_0001,
  0b0000_0000,
  0b0000_0000,
  0b0000_0101
]);

解码

将整数解码为semver

use embedded_semver::Semver;

let int_semver: i32 = 83886081;

let version = Semver::from_i32(int_semver).unwrap();
assert_eq!(version, Semver::new(1, 0, 20));

功能标志

对于无std支持，作为依赖项添加而不启用默认功能

embedded-semver = { version = "...", default-features = false }

二进制格式

• 字段按最高有效位优先打包（参见Msb0）
• 格式包含一个2位（32位值上）和4位（64位值上）的API版本，这允许在未来进行扩展和/或API更改

32位

i32和u32的二进制格式表示如下。字段

• version：前两个位表示API版本（打包数据格式）。当前0 = V0
• major：接下来的10位表示范围在0-1023之间的主要版本
• minor：接下来的10位表示范围在0-1023之间的次要版本
• patch：接下来的10位表示范围在0-1023之间的补丁版本

0         2        12        22        32
├────┴────┼┴┴┴┴┴┴┴┴┴┼┴┴┴┴┴┴┴┴┴┼┴┴┴┴┴┴┴┴┴┤
│ API ver │ Major   │ Minor   │ Patch   │
│ u2      │ u10     │ u10     │ u10     │
└─────────┴─────────┴─────────┴─────────┘

64位

i64 和 u64 的二进制格式表示如下。字段

• version：前四个位表示 API 版本（打包数据格式）。当前 0 = V0
• major：接下来的 16 位表示范围在 0-65535 之间的主要版本
• minor：接下来的 16 位表示范围在 0-65535 之间的次要版本
• patch：接下来的 16 位表示范围在 0-65535 之间的修补版本
• 剩余的 12 位未使用

0         4              20                36                52          64
├─┴──┴─┴──┼┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┼┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┼┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┼┴┴┴┴┴┴┴┴┴┴┴┤
│ API ver │ Major         │ Minor           │ Patch           | (unused)  │
│ u4      │ u16           │ u16             │ u16             | u12       │
└─────────┴───────────────┴─────────────────┴─────────────────┴───────────┘

关于转换的说明

注意 i32 和 i64 中的二进制表示不相同

use embedded_semver::{Semver, Error, Magic};

let value: i32 = 16904511;
assert_eq!(Semver::from_i32(value).unwrap(), Semver::new(1023, 1, 5));
assert_eq!(
    Semver::from_i64(value as i64).unwrap_err(),
    Error::UnsupportedMagic(Magic::V3)
);

然而，u32 和 i32 的底层位表示相同的值

use embedded_semver::{Semver, Error};

let value: i32 = 16843009;
let bytes = value.to_le_bytes();
let i32_value = i32::from_le_bytes(bytes.clone());
let u32_value = u32::from_le_bytes(bytes);
assert_eq!(Semver::from_i32(i32_value).unwrap(), Semver::new(1, 1, 5));
assert_eq!(Semver::from_u32(u32_value).unwrap(), Semver::new(1, 1, 5));

性能

无需担心 :)

test bench_from_i32 ... bench:          51 ns/iter (+/- 1)
test bench_from_i64 ... bench:          54 ns/iter (+/- 1)
test bench_to_i32   ... bench:          75 ns/iter (+/- 1)
test bench_to_i64   ... bench:          84 ns/iter (+/- 2)

Rust 版本支持

最低支持的 Rust 版本是 1.51

未来计划

目前没有

许可

紧凑语义版本表示

• Apache 许可协议，版本 2.0 或
• MIT 许可协议

由您选择。

贡献

除非您明确表示，否则任何有意提交以包含在软件中的贡献，根据 Apache-2.0 许可协议定义，将如上双许可，不附加任何额外条款或条件。