3 releases (breaking)
0.3.0 | Aug 26, 2022 |
---|---|
0.2.0 | Oct 24, 2021 |
0.1.0 | Apr 19, 2021 |
#2184 in Parser implementations
Used in 2 crates
(via citadel_proto)
23KB
308 lines
embedded-semver
Compact representation of semantic versions as an i32, u32 i64 or u64
Because the integer formats have limited space, there are limits for semver field
(major, minor, patch) sizes depending on type (0 - 1023
for 32 bits, 0 - 65535
for 64 bits).
Examples
Encoding
Encode a semver to an integer
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
]);
Decoding
Decode an integer into a 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));
Feature flags
For no-std support, add as a dependency without default features:
embedded-semver = { version = "...", default-features = false }
Binary format
- Fields are packed with the most significant bit first (see Msb0)
- Format contains a 2-bit (on 32-bit values) and 4-bit (on 64-bit values) api version, which allows for extensibility and/or api changes in future
32 bits
The binary format for i32
and u32
is represented below. Fields:
version
: First two bits represent the API version (packed data format). Currenly 0 = V0major
: Next 10 bits represent major in range of 0-1023minor
: Next 10 bits represent minor in range of 0-1023patch
: Next 10 bits represent patch in range of 0-1023
0 2 12 22 32
├────┴────┼┴┴┴┴┴┴┴┴┴┼┴┴┴┴┴┴┴┴┴┼┴┴┴┴┴┴┴┴┴┤
│ API ver │ Major │ Minor │ Patch │
│ u2 │ u10 │ u10 │ u10 │
└─────────┴─────────┴─────────┴─────────┘
64 bits
The binary format for i64
and u64
is represented below. Fields:
version
: First four bits represent the API version (packed data format). Currenly 0 = V0major
: Next 16 bits represent major in range of 0-65535minor
: Next 16 bits represent minor in range of 0-65535patch
: Next 16 bits represent patch in range of 0-65535- 12 remaining bits are unused
0 4 20 36 52 64
├─┴──┴─┴──┼┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┼┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┼┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┼┴┴┴┴┴┴┴┴┴┴┴┤
│ API ver │ Major │ Minor │ Patch | (unused) │
│ u4 │ u16 │ u16 │ u16 | u12 │
└─────────┴───────────────┴─────────────────┴─────────────────┴───────────┘
Notes about conversions
Note that the binary representations in i32 and i64 are not the same:
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)
);
However, the underlying bits in u32 and i32 represent the same values:
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));
Performance
No need to worry :)
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 Version Support
The minimum supported Rust version is 1.51
Future plans
None currently
License
Compact semantic version representation
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the software by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Dependencies
~1MB
~23K SLoC