Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/blaind/embedded-semver
Compact representation of semantic versions as an i32, u32 i64 or u64
https://github.com/blaind/embedded-semver
embedded rust semver
Last synced: 20 days ago
JSON representation
Compact representation of semantic versions as an i32, u32 i64 or u64
- Host: GitHub
- URL: https://github.com/blaind/embedded-semver
- Owner: blaind
- License: apache-2.0
- Created: 2021-04-19T14:39:10.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2022-08-26T17:24:09.000Z (over 2 years ago)
- Last Synced: 2024-11-27T18:56:57.499Z (about 1 month ago)
- Topics: embedded, rust, semver
- Language: Rust
- Homepage:
- Size: 15.6 KB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# embedded-semver [![Build Status]][actions] [![Latest Version]][crates.io] [![Docs Version]][docs] [![Lines of Code]][github]
[Build Status]: https://img.shields.io/github/workflow/status/blaind/embedded-semver/test
[actions]: https://github.com/blaind/embedded-semver/actions?query=branch%3Amain
[Latest Version]: https://img.shields.io/crates/v/embedded-semver.svg
[crates.io]: https://crates.io/crates/embedded-semver
[Lines of Code]: https://tokei.rs/b1/github/blaind/embedded-semver?category=code
[github]: https://github.com/blaind/embedded-semver
[Docs Version]: https://docs.rs/embedded-semver/badge.svg
[docs]: https://docs.rs/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
```rust
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:
```rust
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:
```text
embedded-semver = { version = "...", default-features = false }
```
## Binary format
* Fields are packed with the most significant bit first (see [Msb0](https://docs.rs/bitvec/0.22.3/bitvec/order/struct.Msb0.html))
* 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 = V0
* `major`: Next 10 bits represent major in range of 0-1023
* `minor`: Next 10 bits represent minor in range of 0-1023
* `patch`: Next 10 bits represent patch in range of 0-1023
```text
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 = V0
* `major`: Next 16 bits represent major in range of 0-65535
* `minor`: Next 16 bits represent minor in range of 0-65535
* `patch`: Next 16 bits represent patch in range of 0-65535
* 12 remaining bits are unused
```text
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:
```rust
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:
```rust
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 :)
```text
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
* Apache License, Version 2.0 or
* MIT license
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.