castflip 0.1.15

Library for encoding/decoding numeric variables, arrays and structures in little-endian and big-endian
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
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159

//
// This file defines three traits: `Cast`, `Flip` and `NopFlip`.
// They act as trait bounds in the generic type programming.
//

use crate::{Endian, include_doc};
use core::{
    mem::{self, MaybeUninit},
    ptr,
};

#[cfg(doc)]
use crate::{BE, EncastMem, LE};


//
// Trait `Cast`
//
#[doc = include_doc!("bound_cast.md")]
pub trait Cast: Sized {}

impl Cast for i8 {}
impl Cast for i16 {}
impl Cast for i32 {}
impl Cast for i64 {}
impl Cast for i128 {}
impl Cast for isize {}

impl Cast for u8 {}
impl Cast for u16 {}
impl Cast for u32 {}
impl Cast for u64 {}
impl Cast for u128 {}
impl Cast for usize {}

impl Cast for f32 {}
impl Cast for f64 {}

impl<T: Cast, const N: usize> Cast for [T; N] {}


//
// Trait `Flip`
//
#[doc = include_doc!("bound_flip.md")]
pub trait Flip: Sized {
    ///
    /// Returns the value of `self` with its endianness reversed.
    ///
    fn flip_val_swapped(&self) -> Self;

    ///
    /// Reads the value of `self`, flips the endianness of the value
    /// if `endian` is not equivalent to the endianness of the target
    /// system, then returns the resulting value.
    ///
    #[inline]
    fn flip_val(&self, endian: Endian) -> Self {
        if !endian.need_swap() {
            unsafe {
                // SAFETY: The following function call to `ptr::read` is safe
                // because those types that implement trait Flip can be
                // duplicated simply by copying bits by the definition of
                // trait Flip.
                ptr::read(self)
            }
        } else {
            self.flip_val_swapped()
        }
    }

    ///
    /// Reverses the endianness of the value in `self`.
    ///
    #[inline]
    fn flip_var_swapped(&mut self) {
        *self = self.flip_val_swapped();
    }

    ///
    /// Flips the endianness of the value in `self` if `endian` is not
    /// equivalent to the endianness of the target system.
    ///
    #[inline]
    fn flip_var(&mut self, endian: Endian) {
        if endian.need_swap() {
            self.flip_var_swapped();
        }
    }
}


macro_rules! impl_flip_for_int {
    ( $( $ty:ty ),* ) => { $(
        impl Flip for $ty {
            #[inline]
            fn flip_val_swapped(&self) -> Self {
                self.swap_bytes()
            }
        }
    )* }
}

macro_rules! impl_flip_for_float {
    ( $( $ty:ty ),* ) => { $(
        impl Flip for $ty {
            #[inline]
            fn flip_val_swapped(&self) -> Self {
                <$ty>::from_bits(self.to_bits().swap_bytes())
            }
        }
    )* }
}

impl_flip_for_int!(i8, i16, i32, i64, i128, isize);
impl_flip_for_int!(u8, u16, u32, u64, u128, usize);
impl_flip_for_float!(f32, f64);


impl<T: Flip, const N: usize> Flip for [T; N] {
    #[inline]
    fn flip_val_swapped(&self) -> Self {
        let mut array = MaybeUninit::<[T; N]>::uninit();

        if mem::size_of_val(&array) > 0 {
            unsafe {
                // SAFETY: The following function call to `mem::transmute`
                // is safe because the memory layouts of [T; N] and
                // MaybeUninit::<[T; N]> are exactly the same.
                let array2: &mut [T; N] = mem::transmute(&mut array);

                // NOTE: All elements in `array2` (=`array`) is initialized.
                for i in 0 .. N {
                    array2[i] = self[i].flip_val_swapped();
                }
            }
        }

        unsafe {
            // SAFETY: The following method call to `MaybeUninit::assume_init`
            // is safe because all elements in `array` have been initialized.
            array.assume_init()
        }
    }

    #[inline]
    fn flip_var_swapped(&mut self) {
        for elem in self {
            elem.flip_var_swapped();
        }
    }
}


//
// Trait `NopFlip`
//
#[doc = include_doc!("bound_nop_flip.md")]
pub trait NopFlip: Flip {}