1 | //! A module for working with borrowed data. |
2 | |
3 | #![stable (feature = "rust1" , since = "1.0.0" )] |
4 | |
5 | #[stable (feature = "rust1" , since = "1.0.0" )] |
6 | pub use core::borrow::{Borrow, BorrowMut}; |
7 | use core::cmp::Ordering; |
8 | use core::hash::{Hash, Hasher}; |
9 | #[cfg (not(no_global_oom_handling))] |
10 | use core::ops::{Add, AddAssign}; |
11 | use core::ops::{Deref, DerefPure}; |
12 | |
13 | use Cow::*; |
14 | |
15 | use crate::fmt; |
16 | #[cfg (not(no_global_oom_handling))] |
17 | use crate::string::String; |
18 | |
19 | #[stable (feature = "rust1" , since = "1.0.0" )] |
20 | impl<'a, B: ?Sized> Borrow<B> for Cow<'a, B> |
21 | where |
22 | B: ToOwned, |
23 | { |
24 | fn borrow(&self) -> &B { |
25 | &**self |
26 | } |
27 | } |
28 | |
29 | /// A generalization of `Clone` to borrowed data. |
30 | /// |
31 | /// Some types make it possible to go from borrowed to owned, usually by |
32 | /// implementing the `Clone` trait. But `Clone` works only for going from `&T` |
33 | /// to `T`. The `ToOwned` trait generalizes `Clone` to construct owned data |
34 | /// from any borrow of a given type. |
35 | #[rustc_diagnostic_item = "ToOwned" ] |
36 | #[stable (feature = "rust1" , since = "1.0.0" )] |
37 | pub trait ToOwned { |
38 | /// The resulting type after obtaining ownership. |
39 | #[stable (feature = "rust1" , since = "1.0.0" )] |
40 | type Owned: Borrow<Self>; |
41 | |
42 | /// Creates owned data from borrowed data, usually by cloning. |
43 | /// |
44 | /// # Examples |
45 | /// |
46 | /// Basic usage: |
47 | /// |
48 | /// ``` |
49 | /// let s: &str = "a" ; |
50 | /// let ss: String = s.to_owned(); |
51 | /// |
52 | /// let v: &[i32] = &[1, 2]; |
53 | /// let vv: Vec<i32> = v.to_owned(); |
54 | /// ``` |
55 | #[stable (feature = "rust1" , since = "1.0.0" )] |
56 | #[must_use = "cloning is often expensive and is not expected to have side effects" ] |
57 | #[rustc_diagnostic_item = "to_owned_method" ] |
58 | fn to_owned(&self) -> Self::Owned; |
59 | |
60 | /// Uses borrowed data to replace owned data, usually by cloning. |
61 | /// |
62 | /// This is borrow-generalized version of [`Clone::clone_from`]. |
63 | /// |
64 | /// # Examples |
65 | /// |
66 | /// Basic usage: |
67 | /// |
68 | /// ``` |
69 | /// let mut s: String = String::new(); |
70 | /// "hello" .clone_into(&mut s); |
71 | /// |
72 | /// let mut v: Vec<i32> = Vec::new(); |
73 | /// [1, 2][..].clone_into(&mut v); |
74 | /// ``` |
75 | #[stable (feature = "toowned_clone_into" , since = "1.63.0" )] |
76 | fn clone_into(&self, target: &mut Self::Owned) { |
77 | *target = self.to_owned(); |
78 | } |
79 | } |
80 | |
81 | #[stable (feature = "rust1" , since = "1.0.0" )] |
82 | impl<T> ToOwned for T |
83 | where |
84 | T: Clone, |
85 | { |
86 | type Owned = T; |
87 | fn to_owned(&self) -> T { |
88 | self.clone() |
89 | } |
90 | |
91 | fn clone_into(&self, target: &mut T) { |
92 | target.clone_from(self); |
93 | } |
94 | } |
95 | |
96 | /// A clone-on-write smart pointer. |
97 | /// |
98 | /// The type `Cow` is a smart pointer providing clone-on-write functionality: it |
99 | /// can enclose and provide immutable access to borrowed data, and clone the |
100 | /// data lazily when mutation or ownership is required. The type is designed to |
101 | /// work with general borrowed data via the `Borrow` trait. |
102 | /// |
103 | /// `Cow` implements `Deref`, which means that you can call |
104 | /// non-mutating methods directly on the data it encloses. If mutation |
105 | /// is desired, `to_mut` will obtain a mutable reference to an owned |
106 | /// value, cloning if necessary. |
107 | /// |
108 | /// If you need reference-counting pointers, note that |
109 | /// [`Rc::make_mut`][crate::rc::Rc::make_mut] and |
110 | /// [`Arc::make_mut`][crate::sync::Arc::make_mut] can provide clone-on-write |
111 | /// functionality as well. |
112 | /// |
113 | /// # Examples |
114 | /// |
115 | /// ``` |
116 | /// use std::borrow::Cow; |
117 | /// |
118 | /// fn abs_all(input: &mut Cow<'_, [i32]>) { |
119 | /// for i in 0..input.len() { |
120 | /// let v = input[i]; |
121 | /// if v < 0 { |
122 | /// // Clones into a vector if not already owned. |
123 | /// input.to_mut()[i] = -v; |
124 | /// } |
125 | /// } |
126 | /// } |
127 | /// |
128 | /// // No clone occurs because `input` doesn't need to be mutated. |
129 | /// let slice = [0, 1, 2]; |
130 | /// let mut input = Cow::from(&slice[..]); |
131 | /// abs_all(&mut input); |
132 | /// |
133 | /// // Clone occurs because `input` needs to be mutated. |
134 | /// let slice = [-1, 0, 1]; |
135 | /// let mut input = Cow::from(&slice[..]); |
136 | /// abs_all(&mut input); |
137 | /// |
138 | /// // No clone occurs because `input` is already owned. |
139 | /// let mut input = Cow::from(vec![-1, 0, 1]); |
140 | /// abs_all(&mut input); |
141 | /// ``` |
142 | /// |
143 | /// Another example showing how to keep `Cow` in a struct: |
144 | /// |
145 | /// ``` |
146 | /// use std::borrow::Cow; |
147 | /// |
148 | /// struct Items<'a, X> where [X]: ToOwned<Owned = Vec<X>> { |
149 | /// values: Cow<'a, [X]>, |
150 | /// } |
151 | /// |
152 | /// impl<'a, X: Clone + 'a> Items<'a, X> where [X]: ToOwned<Owned = Vec<X>> { |
153 | /// fn new(v: Cow<'a, [X]>) -> Self { |
154 | /// Items { values: v } |
155 | /// } |
156 | /// } |
157 | /// |
158 | /// // Creates a container from borrowed values of a slice |
159 | /// let readonly = [1, 2]; |
160 | /// let borrowed = Items::new((&readonly[..]).into()); |
161 | /// match borrowed { |
162 | /// Items { values: Cow::Borrowed(b) } => println!("borrowed {b:?}" ), |
163 | /// _ => panic!("expect borrowed value" ), |
164 | /// } |
165 | /// |
166 | /// let mut clone_on_write = borrowed; |
167 | /// // Mutates the data from slice into owned vec and pushes a new value on top |
168 | /// clone_on_write.values.to_mut().push(3); |
169 | /// println!("clone_on_write = {:?}" , clone_on_write.values); |
170 | /// |
171 | /// // The data was mutated. Let's check it out. |
172 | /// match clone_on_write { |
173 | /// Items { values: Cow::Owned(_) } => println!("clone_on_write contains owned data" ), |
174 | /// _ => panic!("expect owned data" ), |
175 | /// } |
176 | /// ``` |
177 | #[stable (feature = "rust1" , since = "1.0.0" )] |
178 | #[rustc_diagnostic_item = "Cow" ] |
179 | pub enum Cow<'a, B: ?Sized + 'a> |
180 | where |
181 | B: ToOwned, |
182 | { |
183 | /// Borrowed data. |
184 | #[stable (feature = "rust1" , since = "1.0.0" )] |
185 | Borrowed(#[stable (feature = "rust1" , since = "1.0.0" )] &'a B), |
186 | |
187 | /// Owned data. |
188 | #[stable (feature = "rust1" , since = "1.0.0" )] |
189 | Owned(#[stable (feature = "rust1" , since = "1.0.0" )] <B as ToOwned>::Owned), |
190 | } |
191 | |
192 | #[stable (feature = "rust1" , since = "1.0.0" )] |
193 | impl<B: ?Sized + ToOwned> Clone for Cow<'_, B> { |
194 | fn clone(&self) -> Self { |
195 | match *self { |
196 | Borrowed(b: &B) => Borrowed(b), |
197 | Owned(ref o: &::Owned) => { |
198 | let b: &B = o.borrow(); |
199 | Owned(b.to_owned()) |
200 | } |
201 | } |
202 | } |
203 | |
204 | fn clone_from(&mut self, source: &Self) { |
205 | match (self, source) { |
206 | (&mut Owned(ref mut dest: &mut ::Owned), &Owned(ref o: &::Owned)) => o.borrow().clone_into(target:dest), |
207 | (t: &mut Cow<'_, B>, s: &Cow<'_, B>) => *t = s.clone(), |
208 | } |
209 | } |
210 | } |
211 | |
212 | impl<B: ?Sized + ToOwned> Cow<'_, B> { |
213 | /// Returns true if the data is borrowed, i.e. if `to_mut` would require additional work. |
214 | /// |
215 | /// # Examples |
216 | /// |
217 | /// ``` |
218 | /// #![feature(cow_is_borrowed)] |
219 | /// use std::borrow::Cow; |
220 | /// |
221 | /// let cow = Cow::Borrowed("moo" ); |
222 | /// assert!(cow.is_borrowed()); |
223 | /// |
224 | /// let bull: Cow<'_, str> = Cow::Owned("...moo?" .to_string()); |
225 | /// assert!(!bull.is_borrowed()); |
226 | /// ``` |
227 | #[unstable (feature = "cow_is_borrowed" , issue = "65143" )] |
228 | pub const fn is_borrowed(&self) -> bool { |
229 | match *self { |
230 | Borrowed(_) => true, |
231 | Owned(_) => false, |
232 | } |
233 | } |
234 | |
235 | /// Returns true if the data is owned, i.e. if `to_mut` would be a no-op. |
236 | /// |
237 | /// # Examples |
238 | /// |
239 | /// ``` |
240 | /// #![feature(cow_is_borrowed)] |
241 | /// use std::borrow::Cow; |
242 | /// |
243 | /// let cow: Cow<'_, str> = Cow::Owned("moo" .to_string()); |
244 | /// assert!(cow.is_owned()); |
245 | /// |
246 | /// let bull = Cow::Borrowed("...moo?" ); |
247 | /// assert!(!bull.is_owned()); |
248 | /// ``` |
249 | #[unstable (feature = "cow_is_borrowed" , issue = "65143" )] |
250 | pub const fn is_owned(&self) -> bool { |
251 | !self.is_borrowed() |
252 | } |
253 | |
254 | /// Acquires a mutable reference to the owned form of the data. |
255 | /// |
256 | /// Clones the data if it is not already owned. |
257 | /// |
258 | /// # Examples |
259 | /// |
260 | /// ``` |
261 | /// use std::borrow::Cow; |
262 | /// |
263 | /// let mut cow = Cow::Borrowed("foo" ); |
264 | /// cow.to_mut().make_ascii_uppercase(); |
265 | /// |
266 | /// assert_eq!( |
267 | /// cow, |
268 | /// Cow::Owned(String::from("FOO" )) as Cow<'_, str> |
269 | /// ); |
270 | /// ``` |
271 | #[stable (feature = "rust1" , since = "1.0.0" )] |
272 | pub fn to_mut(&mut self) -> &mut <B as ToOwned>::Owned { |
273 | match *self { |
274 | Borrowed(borrowed) => { |
275 | *self = Owned(borrowed.to_owned()); |
276 | match *self { |
277 | Borrowed(..) => unreachable!(), |
278 | Owned(ref mut owned) => owned, |
279 | } |
280 | } |
281 | Owned(ref mut owned) => owned, |
282 | } |
283 | } |
284 | |
285 | /// Extracts the owned data. |
286 | /// |
287 | /// Clones the data if it is not already owned. |
288 | /// |
289 | /// # Examples |
290 | /// |
291 | /// Calling `into_owned` on a `Cow::Borrowed` returns a clone of the borrowed data: |
292 | /// |
293 | /// ``` |
294 | /// use std::borrow::Cow; |
295 | /// |
296 | /// let s = "Hello world!" ; |
297 | /// let cow = Cow::Borrowed(s); |
298 | /// |
299 | /// assert_eq!( |
300 | /// cow.into_owned(), |
301 | /// String::from(s) |
302 | /// ); |
303 | /// ``` |
304 | /// |
305 | /// Calling `into_owned` on a `Cow::Owned` returns the owned data. The data is moved out of the |
306 | /// `Cow` without being cloned. |
307 | /// |
308 | /// ``` |
309 | /// use std::borrow::Cow; |
310 | /// |
311 | /// let s = "Hello world!" ; |
312 | /// let cow: Cow<'_, str> = Cow::Owned(String::from(s)); |
313 | /// |
314 | /// assert_eq!( |
315 | /// cow.into_owned(), |
316 | /// String::from(s) |
317 | /// ); |
318 | /// ``` |
319 | #[stable (feature = "rust1" , since = "1.0.0" )] |
320 | pub fn into_owned(self) -> <B as ToOwned>::Owned { |
321 | match self { |
322 | Borrowed(borrowed) => borrowed.to_owned(), |
323 | Owned(owned) => owned, |
324 | } |
325 | } |
326 | } |
327 | |
328 | #[stable (feature = "rust1" , since = "1.0.0" )] |
329 | impl<B: ?Sized + ToOwned> Deref for Cow<'_, B> |
330 | where |
331 | B::Owned: Borrow<B>, |
332 | { |
333 | type Target = B; |
334 | |
335 | fn deref(&self) -> &B { |
336 | match *self { |
337 | Borrowed(borrowed: &B) => borrowed, |
338 | Owned(ref owned: &impl Borrow) => owned.borrow(), |
339 | } |
340 | } |
341 | } |
342 | |
343 | // `Cow<'_, T>` can only implement `DerefPure` if `<T::Owned as Borrow<T>>` (and `BorrowMut<T>`) is trusted. |
344 | // For now, we restrict `DerefPure for Cow<T>` to `T: Sized` (`T as Borrow<T>` is trusted), |
345 | // `str` (`String as Borrow<str>` is trusted) and `[T]` (`Vec<T> as Borrow<[T]>` is trusted). |
346 | // In the future, a `BorrowPure<T>` trait analogous to `DerefPure` might generalize this. |
347 | #[unstable (feature = "deref_pure_trait" , issue = "87121" )] |
348 | unsafe impl<T: Clone> DerefPure for Cow<'_, T> {} |
349 | #[cfg (not(no_global_oom_handling))] |
350 | #[unstable (feature = "deref_pure_trait" , issue = "87121" )] |
351 | unsafe impl DerefPure for Cow<'_, str> {} |
352 | #[cfg (not(no_global_oom_handling))] |
353 | #[unstable (feature = "deref_pure_trait" , issue = "87121" )] |
354 | unsafe impl<T: Clone> DerefPure for Cow<'_, [T]> {} |
355 | |
356 | #[stable (feature = "rust1" , since = "1.0.0" )] |
357 | impl<B: ?Sized> Eq for Cow<'_, B> where B: Eq + ToOwned {} |
358 | |
359 | #[stable (feature = "rust1" , since = "1.0.0" )] |
360 | impl<B: ?Sized> Ord for Cow<'_, B> |
361 | where |
362 | B: Ord + ToOwned, |
363 | { |
364 | #[inline ] |
365 | fn cmp(&self, other: &Self) -> Ordering { |
366 | Ord::cmp(&**self, &**other) |
367 | } |
368 | } |
369 | |
370 | #[stable (feature = "rust1" , since = "1.0.0" )] |
371 | impl<'a, 'b, B: ?Sized, C: ?Sized> PartialEq<Cow<'b, C>> for Cow<'a, B> |
372 | where |
373 | B: PartialEq<C> + ToOwned, |
374 | C: ToOwned, |
375 | { |
376 | #[inline ] |
377 | fn eq(&self, other: &Cow<'b, C>) -> bool { |
378 | PartialEq::eq(&**self, &**other) |
379 | } |
380 | } |
381 | |
382 | #[stable (feature = "rust1" , since = "1.0.0" )] |
383 | impl<'a, B: ?Sized> PartialOrd for Cow<'a, B> |
384 | where |
385 | B: PartialOrd + ToOwned, |
386 | { |
387 | #[inline ] |
388 | fn partial_cmp(&self, other: &Cow<'a, B>) -> Option<Ordering> { |
389 | PartialOrd::partial_cmp(&**self, &**other) |
390 | } |
391 | } |
392 | |
393 | #[stable (feature = "rust1" , since = "1.0.0" )] |
394 | impl<B: ?Sized> fmt::Debug for Cow<'_, B> |
395 | where |
396 | B: fmt::Debug + ToOwned<Owned: fmt::Debug>, |
397 | { |
398 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
399 | match *self { |
400 | Borrowed(ref b: &&B) => fmt::Debug::fmt(self:b, f), |
401 | Owned(ref o: &impl Debug) => fmt::Debug::fmt(self:o, f), |
402 | } |
403 | } |
404 | } |
405 | |
406 | #[stable (feature = "rust1" , since = "1.0.0" )] |
407 | impl<B: ?Sized> fmt::Display for Cow<'_, B> |
408 | where |
409 | B: fmt::Display + ToOwned<Owned: fmt::Display>, |
410 | { |
411 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
412 | match *self { |
413 | Borrowed(ref b: &&B) => fmt::Display::fmt(self:b, f), |
414 | Owned(ref o: &impl Display) => fmt::Display::fmt(self:o, f), |
415 | } |
416 | } |
417 | } |
418 | |
419 | #[stable (feature = "default" , since = "1.11.0" )] |
420 | impl<B: ?Sized> Default for Cow<'_, B> |
421 | where |
422 | B: ToOwned<Owned: Default>, |
423 | { |
424 | /// Creates an owned Cow<'a, B> with the default value for the contained owned value. |
425 | fn default() -> Self { |
426 | Owned(<B as ToOwned>::Owned::default()) |
427 | } |
428 | } |
429 | |
430 | #[stable (feature = "rust1" , since = "1.0.0" )] |
431 | impl<B: ?Sized> Hash for Cow<'_, B> |
432 | where |
433 | B: Hash + ToOwned, |
434 | { |
435 | #[inline ] |
436 | fn hash<H: Hasher>(&self, state: &mut H) { |
437 | Hash::hash(&**self, state) |
438 | } |
439 | } |
440 | |
441 | #[stable (feature = "rust1" , since = "1.0.0" )] |
442 | impl<T: ?Sized + ToOwned> AsRef<T> for Cow<'_, T> { |
443 | fn as_ref(&self) -> &T { |
444 | self |
445 | } |
446 | } |
447 | |
448 | #[cfg (not(no_global_oom_handling))] |
449 | #[stable (feature = "cow_add" , since = "1.14.0" )] |
450 | impl<'a> Add<&'a str> for Cow<'a, str> { |
451 | type Output = Cow<'a, str>; |
452 | |
453 | #[inline ] |
454 | fn add(mut self, rhs: &'a str) -> Self::Output { |
455 | self += rhs; |
456 | self |
457 | } |
458 | } |
459 | |
460 | #[cfg (not(no_global_oom_handling))] |
461 | #[stable (feature = "cow_add" , since = "1.14.0" )] |
462 | impl<'a> Add<Cow<'a, str>> for Cow<'a, str> { |
463 | type Output = Cow<'a, str>; |
464 | |
465 | #[inline ] |
466 | fn add(mut self, rhs: Cow<'a, str>) -> Self::Output { |
467 | self += rhs; |
468 | self |
469 | } |
470 | } |
471 | |
472 | #[cfg (not(no_global_oom_handling))] |
473 | #[stable (feature = "cow_add" , since = "1.14.0" )] |
474 | impl<'a> AddAssign<&'a str> for Cow<'a, str> { |
475 | fn add_assign(&mut self, rhs: &'a str) { |
476 | if self.is_empty() { |
477 | *self = Cow::Borrowed(rhs) |
478 | } else if !rhs.is_empty() { |
479 | if let Cow::Borrowed(lhs: &str) = *self { |
480 | let mut s: String = String::with_capacity(lhs.len() + rhs.len()); |
481 | s.push_str(string:lhs); |
482 | *self = Cow::Owned(s); |
483 | } |
484 | self.to_mut().push_str(string:rhs); |
485 | } |
486 | } |
487 | } |
488 | |
489 | #[cfg (not(no_global_oom_handling))] |
490 | #[stable (feature = "cow_add" , since = "1.14.0" )] |
491 | impl<'a> AddAssign<Cow<'a, str>> for Cow<'a, str> { |
492 | fn add_assign(&mut self, rhs: Cow<'a, str>) { |
493 | if self.is_empty() { |
494 | *self = rhs |
495 | } else if !rhs.is_empty() { |
496 | if let Cow::Borrowed(lhs: &str) = *self { |
497 | let mut s: String = String::with_capacity(lhs.len() + rhs.len()); |
498 | s.push_str(string:lhs); |
499 | *self = Cow::Owned(s); |
500 | } |
501 | self.to_mut().push_str(&rhs); |
502 | } |
503 | } |
504 | } |
505 | |