cow2 0.3.0

Like Cow, but T is covariant
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

#![cfg_attr(not(feature = "std"), no_std)]
#![doc = include_str!("../README.md")]

extern crate alloc;

use core::{borrow::Borrow, ops::Deref};

use alloc::borrow::ToOwned;

mod like_impls;

/// Like [`borrow::Cow`](alloc::borrow::Cow), but `T` is covariant
///
/// # Examples
///
/// ```
/// use cow2::Cow;
///
/// fn foo<'a>(_: Cow<'a, [Cow<'a, str>]>) { }
/// fn bar<'a>(x: Cow<'a, [Cow<'static, str>]>) {
///     foo(x);
/// }
/// ```
///
/// ```
/// use cow2::Cow;
///
/// fn foo<'a>(_: Cow<'a, Cow<'a, [Cow<'a, str>]>>) { }
/// fn bar<'a>(x: Cow<'a, Cow<'a, [Cow<'static, str>]>>) {
///     foo(x);
/// }
/// fn baz<'a>(x: Cow<'a, Cow<'static, [Cow<'static, str>]>>) {
///     bar(x);
/// }
/// ```
pub enum Cow<'a, B: ?Sized + 'a, O = <B as ToOwned>::Owned> {
    Borrowed(&'a B),
    Owned(O),
}

impl<B: ?Sized + ToOwned> Cow<'_, B> {
    /// Acquires a mutable reference to the owned form of the data.
    ///
    /// Clones the data if it is not already owned.
    ///
    /// # Examples
    ///
    /// ```
    /// use cow2::Cow;
    ///
    /// let mut cow = Cow::Borrowed("foo");
    /// cow.to_mut().make_ascii_uppercase();
    ///
    /// assert_eq!(
    ///   cow,
    ///   Cow::Owned(String::from("FOO")) as Cow<'_, str>
    /// );
    /// ```
    pub fn to_mut(&mut self) -> &mut B::Owned {
        match self {
            Cow::Borrowed(borrowed) => {
                *self = Self::Owned(borrowed.to_owned());
                match self {
                    Cow::Borrowed(_) => unreachable!(),
                    Cow::Owned(owned) => owned,
                }
            },
            Cow::Owned(owned) => owned,
        }
    }

    /// Extracts the owned data.
    ///
    /// Clones the data if it is not already owned.
    ///
    /// # Examples
    ///
    /// Calling `into_owned` on a `Cow::Borrowed` returns a clone of the borrowed data:
    ///
    /// ```
    /// use cow2::Cow;
    ///
    /// let s = "Hello world!";
    /// let cow = Cow::Borrowed(s);
    ///
    /// assert_eq!(
    ///   cow.into_owned(),
    ///   String::from(s)
    /// );
    /// ```
    ///
    /// Calling `into_owned` on a `Cow::Owned` returns the owned data. The data is moved out of the
    /// `Cow` without being cloned.
    ///
    /// ```
    /// use cow2::Cow;
    ///
    /// let s = "Hello world!";
    /// let cow: Cow<'_, str> = Cow::Owned(String::from(s));
    ///
    /// assert_eq!(
    ///     cow.into_owned(),
    ///     String::from(s)
    /// );
    /// ```
    pub fn into_owned(self) -> B::Owned {
        match self {
            Cow::Borrowed(borrowed) => borrowed.to_owned(),
            Cow::Owned(owned) => owned,
        }
    }
}

impl<B: ?Sized + ToOwned<Owned = O>, O: Clone> Clone for Cow<'_, B, O> {
    fn clone(&self) -> Self {
        match self {
            Self::Borrowed(borrowed) => Self::Borrowed(borrowed),
            Self::Owned(owned) => Self::Owned(owned.clone()),
        }
    }
}

impl<B: ?Sized + ToOwned<Owned = O>, O: Borrow<B>> Deref for Cow<'_, B, O> {
    type Target = B;

    fn deref(&self) -> &Self::Target {
        match self {
            Cow::Borrowed(borrowed) => borrowed,
            Cow::Owned(owned) => owned.borrow(),
        }
    }
}