RetroSearch Browse

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://doc.rust-lang.org/nightly/std/borrow/enum.Cow.html below:

Cow in std::borrow - Rust

pub enum Cow<'a, B>{
    Borrowed(&'a B),
    Owned(<B as ToOwned>::Owned),
}

Expand description

A clone-on-write smart pointer.

The type Cow is a smart pointer providing clone-on-write functionality: it can enclose and provide immutable access to borrowed data, and clone the data lazily when mutation or ownership is required. The type is designed to work with general borrowed data via the Borrow trait.

Cow implements Deref, which means that you can call non-mutating methods directly on the data it encloses. If mutation is desired, to_mut will obtain a mutable reference to an owned value, cloning if necessary.

If you need reference-counting pointers, note that Rc::make_mut and Arc::make_mut can provide clone-on-write functionality as well.

Â§Examples

use std::borrow::Cow;

fn abs_all(input: &mut Cow<'_, [i32]>) {
    for i in 0..input.len() {
        let v = input[i];
        if v < 0 {
            input.to_mut()[i] = -v;
        }
    }
}

let slice = [0, 1, 2];
let mut input = Cow::from(&slice[..]);
abs_all(&mut input);

let slice = [-1, 0, 1];
let mut input = Cow::from(&slice[..]);
abs_all(&mut input);

let mut input = Cow::from(vec![-1, 0, 1]);
abs_all(&mut input);

Another example showing how to keep Cow in a struct:

use std::borrow::Cow;

struct Items<'a, X> where [X]: ToOwned<Owned = Vec<X>> {
    values: Cow<'a, [X]>,
}

impl<'a, X: Clone + 'a> Items<'a, X> where [X]: ToOwned<Owned = Vec<X>> {
    fn new(v: Cow<'a, [X]>) -> Self {
        Items { values: v }
    }
}

let readonly = [1, 2];
let borrowed = Items::new((&readonly[..]).into());
match borrowed {
    Items { values: Cow::Borrowed(b) } => println!("borrowed {b:?}"),
    _ => panic!("expect borrowed value"),
}

let mut clone_on_write = borrowed;
clone_on_write.values.to_mut().push(3);
println!("clone_on_write = {:?}", clone_on_write.values);

match clone_on_write {
    Items { values: Cow::Owned(_) } => println!("clone_on_write contains owned data"),
    _ => panic!("expect owned data"),
}

Â§1.0.0

Borrowed data.

Â§1.0.0

Owned data.

Source Â§ Source ð¬This is a nightly-only experimental API. (cow_is_borrowed #65143)

Returns true if the data is borrowed, i.e. if to_mut would require additional work.

Â§Examples

#![feature(cow_is_borrowed)]
use std::borrow::Cow;

let cow = Cow::Borrowed("moo");
assert!(cow.is_borrowed());

let bull: Cow<'_, str> = Cow::Owned("...moo?".to_string());
assert!(!bull.is_borrowed());

Source ð¬This is a nightly-only experimental API. (cow_is_borrowed #65143)

Returns true if the data is owned, i.e. if to_mut would be a no-op.

Â§Examples

#![feature(cow_is_borrowed)]
use std::borrow::Cow;

let cow: Cow<'_, str> = Cow::Owned("moo".to_string());
assert!(cow.is_owned());

let bull = Cow::Borrowed("...moo?");
assert!(!bull.is_owned());

1.0.0 Â· Source

Acquires a mutable reference to the owned form of the data.

Clones the data if it is not already owned.

Â§Examples

use std::borrow::Cow;

let mut cow = Cow::Borrowed("foo");
cow.to_mut().make_ascii_uppercase();

assert_eq!(
  cow,
  Cow::Owned(String::from("FOO")) as Cow<'_, str>
);

1.0.0 Â· Source

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 std::borrow::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 std::borrow::Cow;

let s = "Hello world!";
let cow: Cow<'_, str> = Cow::Owned(String::from(s));

assert_eq!(
  cow.into_owned(),
  String::from(s)
);

1.14.0 Â· SourceÂ§ 1.14.0 Â· SourceÂ§ 1.14.0 Â· SourceÂ§ 1.14.0 Â· SourceÂ§ 1.8.0 Â· SourceÂ§ Source Â§

Converts this type into a shared reference of the (usually inferred) input type.

1.0.0 Â· SourceÂ§ Source Â§

Converts this type into a shared reference of the (usually inferred) input type.

1.0.0 Â· SourceÂ§ 1.0.0 Â· SourceÂ§ 1.0.0 Â· SourceÂ§ 1.11.0 Â· SourceÂ§ Source Â§

Creates an owned Cow<âa, B> with the default value for the contained owned value.

1.0.0 Â· SourceÂ§ Source Â§

The resulting type after dereferencing.

Source Â§

Dereferences the value.

1.0.0 Â· SourceÂ§ 1.52.0 Â· SourceÂ§ Source Â§

Extends a collection with the contents of an iterator.

Read more Source Â§ ð¬This is a nightly-only experimental API. (extend_one #72631)

Extends a collection with exactly one element.

Source Â§ ð¬This is a nightly-only experimental API. (extend_one #72631)

Reserves capacity in a collection for the given number of additional elements.

Read more 1.19.0 Â· SourceÂ§ Source Â§

Extends a collection with the contents of an iterator.

Read more Source Â§ ð¬This is a nightly-only experimental API. (extend_one #72631)

Extends a collection with exactly one element.

Source Â§ ð¬This is a nightly-only experimental API. (extend_one #72631)

Reserves capacity in a collection for the given number of additional elements.

Read more 1.8.0 Â· SourceÂ§ Source Â§

Creates a Borrowed variant of Cow from a slice.

This conversion does not allocate or clone the data.

1.77.0 Â· SourceÂ§ Source Â§

Creates a Borrowed variant of Cow from a reference to an array.

This conversion does not allocate or clone the data.

Source Â§ Source Â§

Converts to this type from the input type.

Source Â§ Source Â§

Converts to this type from the input type.

1.28.0 Â· SourceÂ§ Source Â§

Converts a CStr into a borrowed Cow without copying or allocating.

1.28.0 Â· SourceÂ§ 1.28.0 Â· SourceÂ§ 1.28.0 Â· SourceÂ§ 1.6.0 Â· SourceÂ§ Source Â§

Creates a clone-on-write pointer from a reference to Path.

This conversion does not clone or allocate.

1.28.0 Â· SourceÂ§ Source Â§

Creates a clone-on-write pointer from a reference to PathBuf.

This conversion does not clone or allocate.

1.28.0 Â· SourceÂ§ Source Â§

Converts a String reference into a Borrowed variant. No heap allocation is performed, and the string is not copied.

Â§Example

let s = "eggplant".to_string();
assert_eq!(Cow::from(&s), Cow::Borrowed("eggplant"));

1.28.0 Â· SourceÂ§ Source Â§

Creates a Borrowed variant of Cow from a reference to Vec.

This conversion does not allocate or clone the data.

1.0.0 Â· SourceÂ§ Source Â§

Converts a string slice into a Borrowed variant. No heap allocation is performed, and the string is not copied.

Â§Example

assert_eq!(Cow::from("eggplant"), Cow::Borrowed("eggplant"));

Source Â§ Source Â§

Converts to this type from the input type.

1.28.0 Â· SourceÂ§ 1.45.0 Â· SourceÂ§ Source Â§

Converts a Cow<'_, [T]> into a Box<[T]>

When cow is the Cow::Borrowed variant, this conversion allocates on the heap and copies the underlying slice. Otherwise, it will try to reuse the owned Vecâs allocation.

1.45.0 Â· SourceÂ§ Source Â§

Converts a Cow<'a, CStr> into a Box<CStr>, by copying the contents if they are borrowed.

1.45.0 Â· SourceÂ§ Source Â§

Converts a Cow<'a, OsStr> into a Box<OsStr>, by copying the contents if they are borrowed.

1.45.0 Â· SourceÂ§ Source Â§

Creates a boxed Path from a clone-on-write pointer.

Converting from a Cow::Owned does not clone or allocate.

1.45.0 Â· SourceÂ§ Source Â§

Converts a Cow<'_, str> into a Box<str>

When cow is the Cow::Borrowed variant, this conversion allocates on the heap and copies the underlying str. Otherwise, it will try to reuse the owned Stringâs allocation.

Â§Examples

use std::borrow::Cow;

let unboxed = Cow::Borrowed("hello");
let boxed: Box<str> = Box::from(unboxed);
println!("{boxed}");

let unboxed = Cow::Owned("hello".to_string());
let boxed: Box<str> = Box::from(unboxed);
println!("{boxed}");

1.14.0 Â· SourceÂ§ Source Â§

Converts a clone-on-write slice into a vector.

If s already owns a Vec<T>, it will be returned directly. If s is borrowing a slice, a new Vec<T> will be allocated and filled by cloning sâs items into it.

Â§Examples

let o: Cow<'_, [i32]> = Cow::Owned(vec![1, 2, 3]);
let b: Cow<'_, [i32]> = Cow::Borrowed(&[1, 2, 3]);
assert_eq!(Vec::from(o), Vec::from(b));

1.45.0 Â· SourceÂ§ Source Â§

Creates an atomically reference-counted pointer from a clone-on-write pointer by copying its content.

Â§Example

let cow: Cow<'_, str> = Cow::Borrowed("eggplant");
let shared: Arc<str> = Arc::from(cow);
assert_eq!("eggplant", &shared[..]);

1.45.0 Â· SourceÂ§ Source Â§

Creates a reference-counted pointer from a clone-on-write pointer by copying its content.

Â§Example

let cow: Cow<'_, str> = Cow::Borrowed("eggplant");
let shared: Rc<str> = Rc::from(cow);
assert_eq!("eggplant", &shared[..]);

1.28.0 Â· SourceÂ§ Source Â§

Converts a Cow<'a, CStr> into a CString, by copying the contents if they are borrowed.

1.28.0 Â· SourceÂ§ Source Â§

Converts a Cow<'a, OsStr> into an OsString, by copying the contents if they are borrowed.

1.28.0 Â· SourceÂ§ Source Â§

Converts a clone-on-write pointer to an owned path.

Converting from a Cow::Owned does not clone or allocate.

1.14.0 Â· SourceÂ§ Source Â§

Converts a clone-on-write string to an owned instance of String.

This extracts the owned string, clones the string if it is not already owned.

Â§Example

let cow: Cow<'_, str> = Cow::Borrowed("eggplant");
let owned: String = String::from(cow);
assert_eq!(&owned[..], "eggplant");

1.22.0 Â· SourceÂ§ Source Â§

Converts a Cow into a box of dyn Error.

Â§Examples

use std::error::Error;
use std::borrow::Cow;

let a_cow_str_error = Cow::from("a str error");
let a_boxed_error = Box::<dyn Error>::from(a_cow_str_error);
assert!(size_of::<Box<dyn Error>>() == size_of_val(&a_boxed_error))

1.22.0 Â· SourceÂ§ Source Â§

Converts a Cow into a box of dyn Error + Send + Sync.

Â§Examples

use std::error::Error;
use std::borrow::Cow;

let a_cow_str_error = Cow::from("a str error");
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(a_cow_str_error);
assert!(
    size_of::<Box<dyn Error + Send + Sync>>() == size_of_val(&a_boxed_error))

1.28.0 Â· SourceÂ§ 1.6.0 Â· SourceÂ§ Source Â§

Creates a clone-on-write pointer from an owned instance of PathBuf.

This conversion does not clone or allocate.

1.0.0 Â· SourceÂ§ Source Â§

Converts a String into an Owned variant. No heap allocation is performed, and the string is not copied.

Â§Example

let s = "eggplant".to_string();
let s2 = "eggplant".to_string();
assert_eq!(Cow::from(s), Cow::<'static, str>::Owned(s2));

1.8.0 Â· SourceÂ§ Source Â§

Creates an Owned variant of Cow from an owned instance of Vec.

This conversion does not allocate or clone the data.

1.12.0 Â· SourceÂ§ 1.52.0 Â· SourceÂ§ 1.80.0 Â· SourceÂ§ 1.19.0 Â· SourceÂ§ 1.12.0 Â· SourceÂ§ 1.0.0 Â· SourceÂ§ 1.12.0 Â· SourceÂ§ 1.0.0 Â· SourceÂ§ 1.0.0 Â· SourceÂ§ 1.0.0 Â· SourceÂ§ Source Â§