managed/
object.rs

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
use core::ops::{Deref, DerefMut};
use core::fmt;

#[cfg(feature = "std")]
use std::boxed::Box;
#[cfg(all(feature = "alloc", not(feature = "std")))]
use alloc::boxed::Box;
#[cfg(feature = "std")]
use std::vec::Vec;
#[cfg(all(feature = "alloc", not(feature = "std")))]
use alloc::vec::Vec;

/// A managed object.
///
/// This enum can be used to represent exclusive access to objects. In Rust, exclusive access
/// to an object is obtained by either owning the object, or owning a mutable pointer
/// to the object; hence, "managed".
///
/// The purpose of this enum is providing good ergonomics with `std` present while making
/// it possible to avoid having a heap at all (which of course means that `std` is not present).
/// To achieve this, the variants other than `Borrow` are only available when the corresponding
/// feature is opted in.
///
/// A function that requires a managed object should be generic over an `Into<Managed<'a, T>>`
/// argument; then, it will be possible to pass either a `Box<T>`, `Vec<T>`, or a `&'a mut T`
/// without any conversion at the call site.
///
/// Note that a `Vec<T>` converted into an `Into<Managed<'a, [T]>>` gets transformed
/// into a boxed slice, and can no longer be resized. See also
/// [ManagedSlice](enum.ManagedSlice.html), which does not have this drawback.
pub enum Managed<'a, T: 'a + ?Sized> {
    /// Borrowed variant.
    Borrowed(&'a mut T),
    /// Owned variant, only available with the `std` or `alloc` feature enabled.
    #[cfg(any(feature = "std", feature = "alloc"))]
    Owned(Box<T>)
}

impl<'a, T: 'a + ?Sized> fmt::Debug for Managed<'a, T>
        where T: fmt::Debug {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            &Managed::Borrowed(ref x) => write!(f, "Borrowed({:?})", x),
            #[cfg(any(feature = "std", feature = "alloc"))]
            &Managed::Owned(ref x)    => write!(f, "Owned({:?})", x)
        }
    }
}

impl<'a, T: 'a + ?Sized> From<&'a mut T> for Managed<'a, T> {
    fn from(value: &'a mut T) -> Self {
        Managed::Borrowed(value)
    }
}

#[cfg(any(feature = "std", feature = "alloc"))]
impl<'a, T: ?Sized + 'a> From<Box<T>> for Managed<'a, T> {
    fn from(value: Box<T>) -> Self {
        Managed::Owned(value)
    }
}

#[cfg(any(feature = "std", feature = "alloc"))]
impl<'a, T: 'a> From<Vec<T>> for Managed<'a, [T]> {
    fn from(value: Vec<T>) -> Self {
        Managed::Owned(value.into_boxed_slice())
    }
}

impl<'a, T: 'a + ?Sized> Deref for Managed<'a, T> {
    type Target = T;

    fn deref(&self) -> &Self::Target {
        match self {
            &Managed::Borrowed(ref value) => value,
            #[cfg(any(feature = "std", feature = "alloc"))]
            &Managed::Owned(ref value) => value
        }
    }
}

impl<'a, T: 'a + ?Sized> DerefMut for Managed<'a, T> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        match self {
            &mut Managed::Borrowed(ref mut value) => value,
            #[cfg(any(feature = "std", feature = "alloc"))]
            &mut Managed::Owned(ref mut value) => value
        }
    }
}