bitrepr 0.1.1

Traits and derives for packing/unpacking values into bits
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

#![doc = include_str!("../README.md")]
#![cfg_attr(not(test), no_std)]
#![warn(missing_docs)]

extern crate self as bitrepr;

#[doc(hidden)]
pub mod bits;

mod impls;

pub use bitrepr_macros::{BitPack, TryBitPack, UnsafeBitPack};

/// Types which can be represented as bits use this trait to specify the type of the underlying bit representation.
///
/// For example, a `f32` would use `u32` as its bit representation, because `f34` needs *at least* 32 bits to properly
/// represent its value.
///
/// Although any type may be accepted, only unsigned integer types are useful as representation types.
pub trait BitRepr {
    /// The bit representation type of `Self`.
    ///
    /// This will be some unsigned integer in any sane implementation of this trait.
    type Repr;
}

/// Types which are representable as bits may use this trait to convert into or from their bit representation.
/// For more information, look at the crate root documentation.
///
/// This trait is generally not intended to be manually implemented, and most of the time the derive macro `#[derive(BitPack)]`
/// should be used. To see examples of using the macro look at the crate documentation.
pub trait BitPack: BitRepr {
    /// Packs a value of `Self` into its bits representable format.
    fn pack(&self) -> Self::Repr;

    /// Convert a bit representation of `Self` into an instance of `Self`.
    fn unpack(repr: Self::Repr) -> Self;
}

/// Types which are representable as bits may use this trait to convert into or from their bit representation.
/// This trait is different from [`BitPack`] in that the conversion from the bit representation may fail.
/// For more information, look at the crate root documentation.
///
/// This trait is generally not intended to be manually implemented, and most of the time the derive macro `#[derive(TryBitPack)]`
/// should be used. To see examples of using the macro look at the crate documentation.
pub trait TryBitPack: BitRepr + Sized {
    /// Packs a value of `Self` into its bits representable format.
    fn pack(&self) -> Self::Repr;

    /// Attempts to convert a bit representation of `Self` into an instance of `Self`. Returns [None] on failure.
    fn try_unpack(repr: Self::Repr) -> Option<Self>;
}

/// Types which are representable as bits may use this trait to convert into or from their bit representation.
/// This trait is different from [`BitPack`] in that the conversion is unsafe and may cause undefined behaviour.
/// For more information, look at the crate root documentation.
///
/// This trait is generally not intended to be manually implemented, and most of the time the derive macro `#[derive(UnsafeBitPack)]`
/// should be used. To see examples of using the macro look at the crate documentation.
pub trait UnsafeBitPack: BitRepr {
    /// Packs a value of `Self` into its bits representable format.
    fn pack(&self) -> Self::Repr;

    /// Convert a bit representation of `Self` into an instance of `Self`. Does not guarantee `repr` is a valid bit representation of
    /// `Self` and may potentially cause UB if `repr` is an invalid representation of `Self`. For a safe alternative, use [TryBitPack].
    ///
    /// # Safety
    ///
    /// The contract of this function has to guarantee `repr` is a valid bit representation of `Self`. This guarantee depends on `Self`'s
    /// implementation of this trait.
    unsafe fn unsafe_unpack(repr: Self::Repr) -> Self;
}

#[cfg(test)]
mod test;