Crate embedded_semver[−][src]

Compact representation of semantic versions as an i32, u32 i64 or u64

Limitations:

  • Storage format is not standards-conformant (none exists at the time of writing)
  • 32-bit values can represent values in range of major/minor/patch = 0 - 1023 (10 bits)
  • 64-bit values can represent values in range of major/minor/patch = 0 - 65535 (16 bits)
  • Other than major/minor/patch features (e.g pre-release) are not supported

Examples

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]);

Decode an integer into a semver:

let int_semver: i32 = 83886081;

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

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 = 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
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
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:

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:

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));

Modules

prelude

Structs

Semver

Represents a version number conforming to the semantic versioning scheme

Enums

Error

Represents an error that occured during an operation

Magic

Magic number - storage format