briny 0.4.1

Low-level enforcement of memory layout integrity
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
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

//! Functions, traits, methods, and types to improve memory integrity.

// #![forbid(missing_docs)]
#![forbid(unused_must_use)]
#![deny(clippy::all)]
#![deny(clippy::nursery)]
#![deny(clippy::pedantic)]
#![forbid(clippy::expect_used)]
#![forbid(clippy::unwrap_used)]
#![allow(clippy::inline_always)]
#![no_std]

pub mod raw;
pub mod ub;

pub mod traits;

/// A general error for anything that goes wrong internally.
///
/// # Examples
///
/// Common examples include:
///
/// - Raw data is invalid
/// - Memory is unaligned
/// - Types have incorrect sizes
/// 
/// To find out what specifically happened, match the code with each constant
/// descriptor.
#[repr(transparent)]
#[derive(Debug, Clone, Copy)]
pub struct BrinyError {
    code: u8,
}

impl core::ops::BitOr<Self> for BrinyError {
    type Output = Self;

    fn bitor(self, rhs: Self) -> Self::Output {
        self.add(rhs)
    }
}

impl BrinyError {
    const RESERVED_CODE: u8 = 0b00000000;

    const INVALID_BITPATTERN_CODE: u8 = 0b00000001;

    const SIZE_BOUND_FAILURE_CODE: u8 = 0b00000010;

    const UNALIGNED_ACCESS_CODE: u8 = 0b00000100;

    const BAD_BUFFER_CODE: u8 = 0b00001000;

    /// A reserved code `0` that does not work as a regular error.
    pub const RESERVED: Self = Self::new(Self::RESERVED_CODE);

    /// An error representing that a typed cast has invalid bitpatterns.
    pub const INVALID_BITPATTERN: Self = Self::new(Self::INVALID_BITPATTERN_CODE);

    /// An error indicating that two sizes are incompatible.
    pub const SIZE_BOUND_FAILURE: Self = Self::new(Self::SIZE_BOUND_FAILURE_CODE);

    /// An error indicating that an unaligned access is imminent.
    pub const UNALIGNED_ACCESS: Self = Self::new(Self::UNALIGNED_ACCESS_CODE);

    /// An error indicating that a provided buffer is incorrect for it's use case.
    pub const BAD_BUFFER: Self = Self::new(Self::BAD_BUFFER_CODE);

    /// Constructs a new error from a code.
    #[inline]
    const fn new(code: u8) -> Self {
        Self {
            code
        }
    }

    /// Adds the two errors into a combination of multiple error codes.
    #[inline]
    #[must_use]
    pub const fn add(self, rhs: Self) -> Self {
        Self {
            code: (self.code | rhs.code),
        }
    }

    /// Checks if the error is even an error.
    ///
    /// This returns false if and only if `self` IS [`Self::RESERVED`].
    #[inline]
    pub const fn is_err(self) -> bool {
        self.code != 0
    }

    /// Checks if the error includes an unaligned access code.
    #[inline]
    pub const fn is_unaligned_access(self) -> bool {
        (self.code & Self::UNALIGNED_ACCESS_CODE) != 0
    }

    /// Checks if the error includes an bad buffer code.
    #[inline]
    pub const fn is_bad_buffer(self) -> bool {
        (self.code & Self::BAD_BUFFER_CODE) != 0
    }

    /// Checks if the error includes an invalid bitpattern code.
    #[inline]
    pub const fn is_invalid_bitpattern(self) -> bool {
        (self.code & Self::INVALID_BITPATTERN_CODE) != 0
    }

    /// Checks if the error includes an size bound failure code.
    #[inline]
    pub const fn is_size_bound_failure(self) -> bool {
        (self.code & Self::SIZE_BOUND_FAILURE_CODE) != 0
    }
}

impl core::fmt::Display for BrinyError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> Result<(), core::fmt::Error> {
        write!(f, "BrinyError:code={}", self.code)
    }
}
impl core::error::Error for BrinyError {}

unsafe impl crate::traits::RawConvert for BrinyError {}
unsafe impl crate::traits::StableLayout for BrinyError {}
unsafe impl crate::traits::InteriorImmutable for BrinyError {}
unsafe impl crate::traits::Unaligned for BrinyError {}