devela 0.27.0

A development layer 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
87
88

// devela::sys::mem::view::borrow::alloc
//
//! Defines the [`Backing`] enum.
//

#[cfg(feature = "alloc")]
use devela::RangeFull;

#[doc = crate::_tags!(maybe lifetime)]
/// Controls how memory is provided for a value.
#[doc = crate::_doc_location!("sys/mem")]
///
/// Complements [`MaybeOwned`][super::MaybeOwned] by specifying whether to:
/// - Use an existing mutable buffer (`Buf`)
/// - Allocate new memory (`Alloc`)
///
/// Enables APIs to flexibly accept either caller-provided buffers or fall back to
/// allocations (when `alloc` is enabled)
///
/// # Example
/// ```ignore
/// # use devela::{Backing, MaybeOwned};
/// fn process(mode: Backing<'_>) -> MaybeOwned<'_, str> {
///     match mode {
///         Backing::Buf(buffer) => MaybeOwned::borrowed(/*...*/),
///         Backing::Alloc => MaybeOwned::owned(/*...*/),
///     }
/// }
/// ```
/// ## Features
/// The `Alloc` variant disappears when `alloc` is disabled.
#[derive(Debug, PartialEq)]
pub enum Backing<'a> {
    /// Reuse an existing exclusive buffer.
    Buf(&'a mut [u8]),

    /// Allocate new memory via the global allocator.
    #[cfg(feature = "alloc")]
    #[cfg_attr(nightly_doc, doc(cfg(feature = "alloc")))]
    Alloc,
}

impl Backing<'_> {
    /// Returns `true` if this mode requires allocation.
    #[inline(always)]
    pub const fn is_buf(&self) -> bool {
        #[cfg(not(feature = "alloc"))]
        return false;
        #[cfg(feature = "alloc")]
        matches!(self, Self::Alloc)
    }

    /// Returns `true` if this mode uses existing memory.
    #[inline(always)]
    pub const fn is_alloc(&self) -> bool {
        matches!(self, Self::Buf(_))
    }
}

// The following conversions can be used when accepting Into<Backing>.
// The problem is the buffer would get moved if not re-referenced.

impl<'a> From<&'a mut [u8]> for Backing<'a> {
    /// Convert an exclusive slice into borrowing mode.
    fn from(buf: &'a mut [u8]) -> Self {
        Self::Buf(buf)
    }
}
impl<'a, const LEN: usize> From<&'a mut [u8; LEN]> for Backing<'a> {
    /// Convert an exclusive reference to an array into borrowing mode.
    fn from(buf: &'a mut [u8; LEN]) -> Self {
        Self::Buf(buf)
    }
}
#[cfg(feature = "alloc")]
#[cfg_attr(nightly_doc, doc(cfg(feature = "alloc")))]
impl<'a> From<RangeFull> for Backing<'a> {
    /// Convert `..` into allocation mode.
    ///
    /// The range syntax visually suggests "fill everything":
    /// ```ignore
    /// #[cfg(feature = "alloc")]
    /// let s = load_string(..); // Indicates allocation
    /// ```
    fn from(_: RangeFull) -> Self {
        Self::Alloc
    }
}