devela 0.28.0

A development substrate of coherence.
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

// devela::num::grain::cast::traits::join
//
//! construct an unsigned primitive by joining an array of smaller unsigned primitives.
//
// TOC
// - trait PrimJoin
// - macro _num_grain_cast_trait_join_impl_from!

use crate::Cast;

#[doc = crate::_tags!(num primitive)]
/// Offers methods to construct a primitive from an array or slice of smaller primitives.
#[doc = crate::_doc_meta!{location("num/grain")}]
///
/// Methods expecting an array are more efficient than the ones expecting an
/// slice. On the other hand slices of any lenght are supported as follows:
/// - If the slice contains fewer elements than required, the method will
///   fill in the missing values with zeros.
/// - If the slice contains more elements than required, the method will
///   ignore the extra elements.
///
/// See also the [`Cast`] type for the equivalent *const* methods, and the
/// [`PrimSplit`][super::PrimSplit] trait for the opposite operations.
#[doc(alias = "PrimitiveJoin")]
pub trait PrimJoin<T, U, const LEN: usize> {
    /// Constructs a primitive `T` from an array of `U` in big-endian order.
    #[must_use]
    fn from_array_be(values: [U; LEN]) -> T;
    /// Constructs a primitive `T` from an array of `U` in little-endian order.
    #[must_use]
    fn from_array_le(values: [U; LEN]) -> T;
    /// Constructs a primitive `T` from an array of `U` in native-endian order.
    #[must_use]
    fn from_array_ne(values: [U; LEN]) -> T;

    /// Constructs a primitive `T` from a slice of `U` in big-endian order.
    #[must_use]
    fn from_slice_be(values: &[U]) -> T;
    /// Constructs a primitive `T` from a slice of `U` in little-endian order.
    #[must_use]
    fn from_slice_le(values: &[U]) -> T;
    /// Constructs a primitive `T` from a slice of `U` in native-endian order.
    #[must_use]
    fn from_slice_ne(values: &[U]) -> T;
}

/// Implements the trait methods.
macro_rules! _num_grain_cast_trait_join_impl_from {
    ( $( $T:ident, $U:ident, $LEN:literal );+ $(;)? ) => {
        $( _num_grain_cast_trait_join_impl_from![@$T, $U, $LEN]; )+
    };
    (@$T:ident, $U:ident, $LEN:literal) => { crate::paste! {
        impl PrimJoin<$T, $U, $LEN> for $T {
            fn from_array_be(values: [$U; $LEN]) -> $T { Cast::<$T>::[<from_ $U _be>](values) }
            fn from_array_le(values: [$U; $LEN]) -> $T { Cast::<$T>::[<from_ $U _le>](values) }
            fn from_array_ne(values: [$U; $LEN]) -> $T { Cast::<$T>::[<from_ $U _ne>](values) }
            fn from_slice_be(values: &[$U]) -> $T {
                let mut array = [0; $LEN];
                for (i, &v) in values.iter().enumerate() {
                    array[i] = v;
                }
                Cast::<$T>::[<from_ $U _be>](array)
            }
            fn from_slice_le(values: &[$U]) -> $T {
                let mut array = [0; $LEN];
                for (i, &v) in values.iter().enumerate() {
                    array[i] = v;
                }
                Cast::<$T>::[<from_ $U _le>](array)
            }
            fn from_slice_ne(values: &[$U]) -> $T {
                let mut array = [0; $LEN];
                for (i, &v) in values.iter().enumerate() {
                    array[i] = v;
                }
                Cast::<$T>::[<from_ $U _ne>](array)
            }
        }
    }};
}
_num_grain_cast_trait_join_impl_from![
    u128, u64, 2; u128, u32, 4; u128, u16, 8; u128, u8, 16;
    u64, u32, 2; u64, u16, 4; u64, u8, 8;
    u32, u16, 2; u32, u8, 4;
    u16, u8, 2;
];