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::cmp::Ordering;
  16 use core::hash::{Hash, Hasher};
  17 use core::ops::{Add, AddAssign, Deref};
  18
  19 use fmt;
  20 use string::String;
  21
  22 use self::Cow::*;
  23
  24 #[stable(feature = "rust1", since = "1.0.0")]
  25 pub use core::borrow::{Borrow, BorrowMut};
  26
  27 #[stable(feature = "rust1", since = "1.0.0")]
  28 impl<'a, B: ?Sized> Borrow<B> for Cow<'a, B>
  29     where B: ToOwned,
  30           <B as ToOwned>::Owned: 'a
  31 {
  32     fn borrow(&self) -> &B {
  33         &**self
  34     }
  35 }
  36
  37 /// A generalization of `Clone` to borrowed data.
  38 ///
  39 /// Some types make it possible to go from borrowed to owned, usually by
  40 /// implementing the `Clone` trait. But `Clone` works only for going from `&T`
  41 /// to `T`. The `ToOwned` trait generalizes `Clone` to construct owned data
  42 /// from any borrow of a given type.
  43 #[stable(feature = "rust1", since = "1.0.0")]
  44 pub trait ToOwned {
  45     #[stable(feature = "rust1", since = "1.0.0")]
  46     type Owned: Borrow<Self>;
  47
  48     /// Creates owned data from borrowed data, usually by cloning.
  49     ///
  50     /// # Examples
  51     ///
  52     /// Basic usage:
  53     ///
  54     /// ```
  55     /// let s: &str = "a";
  56     /// let ss: String = s.to_owned();
  57     ///
  58     /// let v: &[i32] = &[1, 2];
  59     /// let vv: Vec<i32> = v.to_owned();
  60     /// ```
  61     #[stable(feature = "rust1", since = "1.0.0")]
  62     fn to_owned(&self) -> Self::Owned;
  63
  64     /// Uses borrowed data to replace owned data, usually by cloning.
  65     ///
  66     /// This is borrow-generalized version of `Clone::clone_from`.
  67     ///
  68     /// # Examples
  69     ///
  70     /// Basic usage:
  71     ///
  72     /// ```
  73     /// # #![feature(toowned_clone_into)]
  74     /// let mut s: String = String::new();
  75     /// "hello".clone_into(&mut s);
  76     ///
  77     /// let mut v: Vec<i32> = Vec::new();
  78     /// [1, 2][..].clone_into(&mut v);
  79     /// ```
  80     #[unstable(feature = "toowned_clone_into",
  81                reason = "recently added",
  82                issue = "41263")]
  83     fn clone_into(&self, target: &mut Self::Owned) {
  84         *target = self.to_owned();
  85     }
  86 }
  87
  88 #[stable(feature = "rust1", since = "1.0.0")]
  89 impl<T> ToOwned for T
  90     where T: Clone
  91 {
  92     type Owned = T;
  93     fn to_owned(&self) -> T {
  94         self.clone()
  95     }
  96
  97     fn clone_into(&self, target: &mut T) {
  98         target.clone_from(self);
  99     }
 100 }
 101
 102 /// A clone-on-write smart pointer.
 103 ///
 104 /// The type `Cow` is a smart pointer providing clone-on-write functionality: it
 105 /// can enclose and provide immutable access to borrowed data, and clone the
 106 /// data lazily when mutation or ownership is required. The type is designed to
 107 /// work with general borrowed data via the `Borrow` trait.
 108 ///
 109 /// `Cow` implements `Deref`, which means that you can call
 110 /// non-mutating methods directly on the data it encloses. If mutation
 111 /// is desired, `to_mut` will obtain a mutable reference to an owned
 112 /// value, cloning if necessary.
 113 ///
 114 /// # Examples
 115 ///
 116 /// ```
 117 /// use std::borrow::Cow;
 118 ///
 119 /// fn abs_all(input: &mut Cow<[i32]>) {
 120 ///     for i in 0..input.len() {
 121 ///         let v = input[i];
 122 ///         if v < 0 {
 123 ///             // Clones into a vector if not already owned.
 124 ///             input.to_mut()[i] = -v;
 125 ///         }
 126 ///     }
 127 /// }
 128 ///
 129 /// // No clone occurs because `input` doesn't need to be mutated.
 130 /// let slice = [0, 1, 2];
 131 /// let mut input = Cow::from(&slice[..]);
 132 /// abs_all(&mut input);
 133 ///
 134 /// // Clone occurs because `input` needs to be mutated.
 135 /// let slice = [-1, 0, 1];
 136 /// let mut input = Cow::from(&slice[..]);
 137 /// abs_all(&mut input);
 138 ///
 139 /// // No clone occurs because `input` is already owned.
 140 /// let mut input = Cow::from(vec![-1, 0, 1]);
 141 /// abs_all(&mut input);
 142 /// ```
 143 #[stable(feature = "rust1", since = "1.0.0")]
 144 pub enum Cow<'a, B: ?Sized + 'a>
 145     where B: ToOwned
 146 {
 147     /// Borrowed data.
 148     #[stable(feature = "rust1", since = "1.0.0")]
 149     Borrowed(#[stable(feature = "rust1", since = "1.0.0")]
 150              &'a B),
 151
 152     /// Owned data.
 153     #[stable(feature = "rust1", since = "1.0.0")]
 154     Owned(#[stable(feature = "rust1", since = "1.0.0")]
 155           <B as ToOwned>::Owned),
 156 }
 157
 158 #[stable(feature = "rust1", since = "1.0.0")]
 159 impl<'a, B: ?Sized> Clone for Cow<'a, B>
 160     where B: ToOwned
 161 {
 162     fn clone(&self) -> Cow<'a, B> {
 163         match *self {
 164             Borrowed(b) => Borrowed(b),
 165             Owned(ref o) => {
 166                 let b: &B = o.borrow();
 167                 Owned(b.to_owned())
 168             }
 169         }
 170     }
 171
 172     fn clone_from(&mut self, source: &Cow<'a, B>) {
 173         if let Owned(ref mut dest) = *self {
 174             if let Owned(ref o) = *source {
 175                 o.borrow().clone_into(dest);
 176                 return;
 177             }
 178         }
 179
 180         *self = source.clone();
 181     }
 182 }
 183
 184 impl<'a, B: ?Sized> Cow<'a, B>
 185     where B: ToOwned
 186 {
 187     /// Acquires a mutable reference to the owned form of the data.
 188     ///
 189     /// Clones the data if it is not already owned.
 190     ///
 191     /// # Examples
 192     ///
 193     /// ```
 194     /// use std::borrow::Cow;
 195     ///
 196     /// let mut cow: Cow<[_]> = Cow::Owned(vec![1, 2, 3]);
 197     ///
 198     /// let hello = cow.to_mut();
 199     ///
 200     /// assert_eq!(hello, &[1, 2, 3]);
 201     /// ```
 202     #[stable(feature = "rust1", since = "1.0.0")]
 203     pub fn to_mut(&mut self) -> &mut <B as ToOwned>::Owned {
 204         match *self {
 205             Borrowed(borrowed) => {
 206                 *self = Owned(borrowed.to_owned());
 207                 match *self {
 208                     Borrowed(..) => unreachable!(),
 209                     Owned(ref mut owned) => owned,
 210                 }
 211             }
 212             Owned(ref mut owned) => owned,
 213         }
 214     }
 215
 216     /// Extracts the owned data.
 217     ///
 218     /// Clones the data if it is not already owned.
 219     ///
 220     /// # Examples
 221     ///
 222     /// Calling `into_owned` on a `Cow::Borrowed` clones the underlying data
 223     /// and becomes a `Cow::Owned`:
 224     ///
 225     /// ```
 226     /// use std::borrow::Cow;
 227     ///
 228     /// let s = "Hello world!";
 229     /// let cow = Cow::Borrowed(s);
 230     ///
 231     /// assert_eq!(
 232     ///   cow.into_owned(),
 233     ///   Cow::Owned(String::from(s))
 234     /// );
 235     /// ```
 236     ///
 237     /// Calling `into_owned` on a `Cow::Owned` is a no-op:
 238     ///
 239     /// ```
 240     /// use std::borrow::Cow;
 241     ///
 242     /// let s = "Hello world!";
 243     /// let cow: Cow<str> = Cow::Owned(String::from(s));
 244     ///
 245     /// assert_eq!(
 246     ///   cow.into_owned(),
 247     ///   Cow::Owned(String::from(s))
 248     /// );
 249     /// ```
 250     #[stable(feature = "rust1", since = "1.0.0")]
 251     pub fn into_owned(self) -> <B as ToOwned>::Owned {
 252         match self {
 253             Borrowed(borrowed) => borrowed.to_owned(),
 254             Owned(owned) => owned,
 255         }
 256     }
 257 }
 258
 259 #[stable(feature = "rust1", since = "1.0.0")]
 260 impl<'a, B: ?Sized> Deref for Cow<'a, B>
 261     where B: ToOwned
 262 {
 263     type Target = B;
 264
 265     fn deref(&self) -> &B {
 266         match *self {
 267             Borrowed(borrowed) => borrowed,
 268             Owned(ref owned) => owned.borrow(),
 269         }
 270     }
 271 }
 272
 273 #[stable(feature = "rust1", since = "1.0.0")]
 274 impl<'a, B: ?Sized> Eq for Cow<'a, B> where B: Eq + ToOwned {}
 275
 276 #[stable(feature = "rust1", since = "1.0.0")]
 277 impl<'a, B: ?Sized> Ord for Cow<'a, B>
 278     where B: Ord + ToOwned
 279 {
 280     #[inline]
 281     fn cmp(&self, other: &Cow<'a, B>) -> Ordering {
 282         Ord::cmp(&**self, &**other)
 283     }
 284 }
 285
 286 #[stable(feature = "rust1", since = "1.0.0")]
 287 impl<'a, 'b, B: ?Sized, C: ?Sized> PartialEq<Cow<'b, C>> for Cow<'a, B>
 288     where B: PartialEq<C> + ToOwned,
 289           C: ToOwned
 290 {
 291     #[inline]
 292     fn eq(&self, other: &Cow<'b, C>) -> bool {
 293         PartialEq::eq(&**self, &**other)
 294     }
 295 }
 296
 297 #[stable(feature = "rust1", since = "1.0.0")]
 298 impl<'a, B: ?Sized> PartialOrd for Cow<'a, B>
 299     where B: PartialOrd + ToOwned
 300 {
 301     #[inline]
 302     fn partial_cmp(&self, other: &Cow<'a, B>) -> Option<Ordering> {
 303         PartialOrd::partial_cmp(&**self, &**other)
 304     }
 305 }
 306
 307 #[stable(feature = "rust1", since = "1.0.0")]
 308 impl<'a, B: ?Sized> fmt::Debug for Cow<'a, B>
 309     where B: fmt::Debug + ToOwned,
 310           <B as ToOwned>::Owned: fmt::Debug
 311 {
 312     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 313         match *self {
 314             Borrowed(ref b) => fmt::Debug::fmt(b, f),
 315             Owned(ref o) => fmt::Debug::fmt(o, f),
 316         }
 317     }
 318 }
 319
 320 #[stable(feature = "rust1", since = "1.0.0")]
 321 impl<'a, B: ?Sized> fmt::Display for Cow<'a, B>
 322     where B: fmt::Display + ToOwned,
 323           <B as ToOwned>::Owned: fmt::Display
 324 {
 325     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 326         match *self {
 327             Borrowed(ref b) => fmt::Display::fmt(b, f),
 328             Owned(ref o) => fmt::Display::fmt(o, f),
 329         }
 330     }
 331 }
 332
 333 #[stable(feature = "default", since = "1.11.0")]
 334 impl<'a, B: ?Sized> Default for Cow<'a, B>
 335     where B: ToOwned,
 336           <B as ToOwned>::Owned: Default
 337 {
 338     /// Creates an owned Cow<'a, B> with the default value for the contained owned value.
 339     fn default() -> Cow<'a, B> {
 340         Owned(<B as ToOwned>::Owned::default())
 341     }
 342 }
 343
 344 #[stable(feature = "rust1", since = "1.0.0")]
 345 impl<'a, B: ?Sized> Hash for Cow<'a, B>
 346     where B: Hash + ToOwned
 347 {
 348     #[inline]
 349     fn hash<H: Hasher>(&self, state: &mut H) {
 350         Hash::hash(&**self, state)
 351     }
 352 }
 353
 354 #[stable(feature = "rust1", since = "1.0.0")]
 355 #[allow(deprecated)]
 356 impl<'a, T: ?Sized + ToOwned> AsRef<T> for Cow<'a, T> {
 357     fn as_ref(&self) -> &T {
 358         self
 359     }
 360 }
 361
 362 #[stable(feature = "cow_add", since = "1.14.0")]
 363 impl<'a> Add<&'a str> for Cow<'a, str> {
 364     type Output = Cow<'a, str>;
 365
 366     #[inline]
 367     fn add(mut self, rhs: &'a str) -> Self::Output {
 368         self += rhs;
 369         self
 370     }
 371 }
 372
 373 #[stable(feature = "cow_add", since = "1.14.0")]
 374 impl<'a> Add<Cow<'a, str>> for Cow<'a, str> {
 375     type Output = Cow<'a, str>;
 376
 377     #[inline]
 378     fn add(mut self, rhs: Cow<'a, str>) -> Self::Output {
 379         self += rhs;
 380         self
 381     }
 382 }
 383
 384 #[stable(feature = "cow_add", since = "1.14.0")]
 385 impl<'a> AddAssign<&'a str> for Cow<'a, str> {
 386     fn add_assign(&mut self, rhs: &'a str) {
 387         if self.is_empty() {
 388             *self = Cow::Borrowed(rhs)
 389         } else if rhs.is_empty() {
 390             return;
 391         } else {
 392             if let Cow::Borrowed(lhs) = *self {
 393                 let mut s = String::with_capacity(lhs.len() + rhs.len());
 394                 s.push_str(lhs);
 395                 *self = Cow::Owned(s);
 396             }
 397             self.to_mut().push_str(rhs);
 398         }
 399     }
 400 }
 401
 402 #[stable(feature = "cow_add", since = "1.14.0")]
 403 impl<'a> AddAssign<Cow<'a, str>> for Cow<'a, str> {
 404     fn add_assign(&mut self, rhs: Cow<'a, str>) {
 405         if self.is_empty() {
 406             *self = rhs
 407         } else if rhs.is_empty() {
 408             return;
 409         } else {
 410             if let Cow::Borrowed(lhs) = *self {
 411                 let mut s = String::with_capacity(lhs.len() + rhs.len());
 412                 s.push_str(lhs);
 413                 *self = Cow::Owned(s);
 414             }
 415             self.to_mut().push_str(&rhs);
 416         }
 417     }
 418 }