]> git.proxmox.com Git - rustc.git/blob - src/libcollections/borrow.rs
Imported Upstream version 1.9.0+dfsg1
[rustc.git] / src / libcollections / borrow.rs
1 // Copyright 2014 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
4 //
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
10
11 //! A module for working with borrowed data.
12
13 #![stable(feature = "rust1", since = "1.0.0")]
14
15 use core::clone::Clone;
16 use core::cmp::{Eq, Ord, Ordering, PartialEq, PartialOrd};
17 use core::convert::AsRef;
18 use core::hash::{Hash, Hasher};
19 use core::marker::Sized;
20 use core::ops::Deref;
21 use core::option::Option;
22
23 use fmt;
24
25 use self::Cow::*;
26
27 #[stable(feature = "rust1", since = "1.0.0")]
28 pub use core::borrow::{Borrow, BorrowMut};
29
30 #[stable(feature = "rust1", since = "1.0.0")]
31 impl<'a, B: ?Sized> Borrow<B> for Cow<'a, B>
32 where B: ToOwned,
33 <B as ToOwned>::Owned: 'a
34 {
35 fn borrow(&self) -> &B {
36 &**self
37 }
38 }
39
40 /// A generalization of `Clone` to borrowed data.
41 ///
42 /// Some types make it possible to go from borrowed to owned, usually by
43 /// implementing the `Clone` trait. But `Clone` works only for going from `&T`
44 /// to `T`. The `ToOwned` trait generalizes `Clone` to construct owned data
45 /// from any borrow of a given type.
46 #[stable(feature = "rust1", since = "1.0.0")]
47 pub trait ToOwned {
48 #[stable(feature = "rust1", since = "1.0.0")]
49 type Owned: Borrow<Self>;
50
51 /// Creates owned data from borrowed data, usually by cloning.
52 ///
53 /// # Examples
54 ///
55 /// Basic usage:
56 ///
57 /// ```
58 /// let s = "a"; // &str
59 /// let ss = s.to_owned(); // String
60 ///
61 /// let v = &[1, 2]; // slice
62 /// let vv = v.to_owned(); // Vec
63 /// ```
64 #[stable(feature = "rust1", since = "1.0.0")]
65 fn to_owned(&self) -> Self::Owned;
66 }
67
68 #[stable(feature = "rust1", since = "1.0.0")]
69 impl<T> ToOwned for T where T: Clone {
70 type Owned = T;
71 fn to_owned(&self) -> T {
72 self.clone()
73 }
74 }
75
76 /// A clone-on-write smart pointer.
77 ///
78 /// The type `Cow` is a smart pointer providing clone-on-write functionality: it
79 /// can enclose and provide immutable access to borrowed data, and clone the
80 /// data lazily when mutation or ownership is required. The type is designed to
81 /// work with general borrowed data via the `Borrow` trait.
82 ///
83 /// `Cow` implements `Deref`, which means that you can call
84 /// non-mutating methods directly on the data it encloses. If mutation
85 /// is desired, `to_mut` will obtain a mutable reference to an owned
86 /// value, cloning if necessary.
87 ///
88 /// # Examples
89 ///
90 /// ```
91 /// use std::borrow::Cow;
92 ///
93 /// # #[allow(dead_code)]
94 /// fn abs_all(input: &mut Cow<[i32]>) {
95 /// for i in 0..input.len() {
96 /// let v = input[i];
97 /// if v < 0 {
98 /// // clones into a vector the first time (if not already owned)
99 /// input.to_mut()[i] = -v;
100 /// }
101 /// }
102 /// }
103 /// ```
104 #[stable(feature = "rust1", since = "1.0.0")]
105 pub enum Cow<'a, B: ?Sized + 'a>
106 where B: ToOwned
107 {
108 /// Borrowed data.
109 #[stable(feature = "rust1", since = "1.0.0")]
110 Borrowed(#[stable(feature = "rust1", since = "1.0.0")] &'a B),
111
112 /// Owned data.
113 #[stable(feature = "rust1", since = "1.0.0")]
114 Owned(
115 #[stable(feature = "rust1", since = "1.0.0")] <B as ToOwned>::Owned
116 ),
117 }
118
119 #[stable(feature = "rust1", since = "1.0.0")]
120 impl<'a, B: ?Sized> Clone for Cow<'a, B> where B: ToOwned {
121 fn clone(&self) -> Cow<'a, B> {
122 match *self {
123 Borrowed(b) => Borrowed(b),
124 Owned(ref o) => {
125 let b: &B = o.borrow();
126 Owned(b.to_owned())
127 }
128 }
129 }
130 }
131
132 impl<'a, B: ?Sized> Cow<'a, B> where B: ToOwned {
133 /// Acquires a mutable reference to the owned form of the data.
134 ///
135 /// Clones the data if it is not already owned.
136 ///
137 /// # Examples
138 ///
139 /// ```
140 /// use std::borrow::Cow;
141 ///
142 /// let mut cow: Cow<[_]> = Cow::Owned(vec![1, 2, 3]);
143 ///
144 /// let hello = cow.to_mut();
145 ///
146 /// assert_eq!(hello, &[1, 2, 3]);
147 /// ```
148 #[stable(feature = "rust1", since = "1.0.0")]
149 pub fn to_mut(&mut self) -> &mut <B as ToOwned>::Owned {
150 match *self {
151 Borrowed(borrowed) => {
152 *self = Owned(borrowed.to_owned());
153 self.to_mut()
154 }
155 Owned(ref mut owned) => owned,
156 }
157 }
158
159 /// Extracts the owned data.
160 ///
161 /// Clones the data if it is not already owned.
162 ///
163 /// # Examples
164 ///
165 /// ```
166 /// use std::borrow::Cow;
167 ///
168 /// let cow: Cow<[_]> = Cow::Owned(vec![1, 2, 3]);
169 ///
170 /// let hello = cow.into_owned();
171 ///
172 /// assert_eq!(vec![1, 2, 3], hello);
173 /// ```
174 #[stable(feature = "rust1", since = "1.0.0")]
175 pub fn into_owned(self) -> <B as ToOwned>::Owned {
176 match self {
177 Borrowed(borrowed) => borrowed.to_owned(),
178 Owned(owned) => owned,
179 }
180 }
181 }
182
183 #[stable(feature = "rust1", since = "1.0.0")]
184 impl<'a, B: ?Sized> Deref for Cow<'a, B> where B: ToOwned {
185 type Target = B;
186
187 fn deref(&self) -> &B {
188 match *self {
189 Borrowed(borrowed) => borrowed,
190 Owned(ref owned) => owned.borrow(),
191 }
192 }
193 }
194
195 #[stable(feature = "rust1", since = "1.0.0")]
196 impl<'a, B: ?Sized> Eq for Cow<'a, B> where B: Eq + ToOwned {}
197
198 #[stable(feature = "rust1", since = "1.0.0")]
199 impl<'a, B: ?Sized> Ord for Cow<'a, B> where B: Ord + ToOwned {
200 #[inline]
201 fn cmp(&self, other: &Cow<'a, B>) -> Ordering {
202 Ord::cmp(&**self, &**other)
203 }
204 }
205
206 #[stable(feature = "rust1", since = "1.0.0")]
207 impl<'a, 'b, B: ?Sized, C: ?Sized> PartialEq<Cow<'b, C>> for Cow<'a, B>
208 where B: PartialEq<C> + ToOwned,
209 C: ToOwned
210 {
211 #[inline]
212 fn eq(&self, other: &Cow<'b, C>) -> bool {
213 PartialEq::eq(&**self, &**other)
214 }
215 }
216
217 #[stable(feature = "rust1", since = "1.0.0")]
218 impl<'a, B: ?Sized> PartialOrd for Cow<'a, B> where B: PartialOrd + ToOwned {
219 #[inline]
220 fn partial_cmp(&self, other: &Cow<'a, B>) -> Option<Ordering> {
221 PartialOrd::partial_cmp(&**self, &**other)
222 }
223 }
224
225 #[stable(feature = "rust1", since = "1.0.0")]
226 impl<'a, B: ?Sized> fmt::Debug for Cow<'a, B>
227 where B: fmt::Debug + ToOwned,
228 <B as ToOwned>::Owned: fmt::Debug
229 {
230 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
231 match *self {
232 Borrowed(ref b) => fmt::Debug::fmt(b, f),
233 Owned(ref o) => fmt::Debug::fmt(o, f),
234 }
235 }
236 }
237
238 #[stable(feature = "rust1", since = "1.0.0")]
239 impl<'a, B: ?Sized> fmt::Display for Cow<'a, B>
240 where B: fmt::Display + ToOwned,
241 <B as ToOwned>::Owned: fmt::Display
242 {
243 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
244 match *self {
245 Borrowed(ref b) => fmt::Display::fmt(b, f),
246 Owned(ref o) => fmt::Display::fmt(o, f),
247 }
248 }
249 }
250
251 #[stable(feature = "rust1", since = "1.0.0")]
252 impl<'a, B: ?Sized> Hash for Cow<'a, B> where B: Hash + ToOwned {
253 #[inline]
254 fn hash<H: Hasher>(&self, state: &mut H) {
255 Hash::hash(&**self, state)
256 }
257 }
258
259 #[stable(feature = "rust1", since = "1.0.0")]
260 #[allow(deprecated)]
261 impl<'a, T: ?Sized + ToOwned> AsRef<T> for Cow<'a, T> {
262 fn as_ref(&self) -> &T {
263 self
264 }
265 }