Enum alloc::borrow::Cow

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

写入时克隆智能指针。

Cow 类型是一种智能指针，提供了写时克隆功能: 它可以封装并提供对借用数据的不可变访问，并在需要可变的或所有权时懒惰地克隆数据。

该类型旨在通过 Borrow trait 处理常规借用数据。

Cow 实现 Deref，这意味着您可以直接在其所包含的数据上调用非可变方法。 如果需要进行可变的，则 to_mut 将获得一个拥有值的变量引用，必要时进行克隆。

如果需要引用计数指针，请注意 Rc::make_mut 和 Arc::make_mut 也可以提供写时克隆功能。

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 {
            // 如果尚未拥有，则克隆到 vector 中。
            input.to_mut()[i] = -v;
        }
    }
}

// 因为 `input` 不需要可变的，所以不会发生克隆。
let slice = [0, 1, 2];
let mut input = Cow::from(&slice[..]);
abs_all(&mut input);

// 发生克隆是因为需要对 `input` 进行可变的。
let slice = [-1, 0, 1];
let mut input = Cow::from(&slice[..]);
abs_all(&mut input);

// 因为 `input` 已被拥有，所以不会发生克隆。
let mut input = Cow::from(vec![-1, 0, 1]);
abs_all(&mut input);

另一个示例显示如何将 Cow 保留在结构体中:

use std::borrow::Cow;

struct Items<'a, X: 'a> 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;
// 将切片中的数据可变的为拥有的 vec，并在顶部推入新值
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"),
}

Variants

Borrowed(&'a B)

借用的数据。

Owned(<B as ToOwned>::Owned)

拥有的数据。

Implementations

impl<B: ?Sized + ToOwned> Cow<'_, B>

pub fn is_borrowed(&self) -> bool

🔬 This is a nightly-only experimental API. (cow_is_borrowed #65143)

如果借用了数据 (即 to_mut 需要其他工作)，则返回 true。

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());

pub fn is_owned(&self) -> bool

🔬 This is a nightly-only experimental API. (cow_is_borrowed #65143)

如果数据已拥有，即 to_mut 为无操作，则返回 true。

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());

pub fn to_mut(&mut self) -> &mut <B as ToOwned>::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>
);

pub fn into_owned(self) -> <B as ToOwned>::Owned

提取拥有的数据。

如果尚未拥有该数据，则将其克隆。

Examples

在 Cow::Borrowed 上调用 into_owned 会克隆基础数据并成为 Cow::Owned:

use std::borrow::Cow;

let s = "Hello world!";
let cow = Cow::Borrowed(s);

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

禁止在 Cow::Owned 上调用 into_owned:

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)
);

Trait Implementations

impl<'a> Add<&'a str> for Cow<'a, str>

type Output = Cow<'a, str>

应用 + 运算符后的结果类型。

fn add(self, rhs: &'a str) -> Self::Output

执行 + 操作。

impl<'a> Add<Cow<'a, str>> for Cow<'a, str>

type Output = Cow<'a, str>

应用 + 运算符后的结果类型。

fn add(self, rhs: Cow<'a, str>) -> Self::Output

执行 + 操作。

impl<'a> AddAssign<&'a str> for Cow<'a, str>

fn add_assign(&mut self, rhs: &'a str)

执行 += 操作。

impl<'a> AddAssign<Cow<'a, str>> for Cow<'a, str>

fn add_assign(&mut self, rhs: Cow<'a, str>)

执行 += 操作。

impl<T: ?Sized + ToOwned> AsRef<T> for Cow<'_, T>

fn as_ref(&self) -> &T

执行转换。

impl<'a, B: ?Sized> Borrow<B> for Cow<'a, B> where
    B: ToOwned,
    <B as ToOwned>::Owned: 'a, 

fn borrow(&self) -> &B

从拥有的值中一成不变地借用。

impl<B: ?Sized + ToOwned> Clone for Cow<'_, B>

fn clone(&self) -> Self

返回值的副本。

fn clone_from(&mut self, source: &Self)

从 source 执行复制分配。

impl<B: ?Sized> Debug for Cow<'_, B> where
    B: Debug + ToOwned<Owned: Debug>, 

fn fmt(&self, f: &mut Formatter<'_>) -> Result

使用给定的格式化程序格式化该值。

impl<B: ?Sized> Default for Cow<'_, B> where
    B: ToOwned<Owned: Default>, 

fn default() -> Self

创建一个拥有的 Cow<’a, B>，其默认值为包含的拥有值。

impl<B: ?Sized + ToOwned> Deref for Cow<'_, B>

type Target = B

解引用后的结果类型。

fn deref(&self) -> &B

解引用值。

impl<B: ?Sized> Display for Cow<'_, B> where
    B: Display + ToOwned<Owned: Display>, 

fn fmt(&self, f: &mut Formatter<'_>) -> Result

使用给定的格式化程序格式化该值。

impl<'a> Extend<Cow<'a, str>> for String

fn extend<I: IntoIterator<Item = Cow<'a, str>>>(&mut self, iter: I)

用迭代器的内容扩展集合。

fn extend_one(&mut self, s: Cow<'a, str>)

🔬 This is a nightly-only experimental API. (extend_one #72631)

用一个元素扩展一个集合。

fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one #72631)

在集合中为给定数量的附加元素保留容量。

impl<'a, T: Clone> From<&'a [T]> for Cow<'a, [T]>

fn from(s: &'a [T]) -> Cow<'a, [T]>

从一个切片创建一个 Cow 的 Borrowed 变体。

此转换不会分配或克隆数据。

impl<'a> From<&'a String> for Cow<'a, str>

fn from(s: &'a String) -> Cow<'a, str>

将 String 引用转换为 Borrowed 变体。 不执行堆分配，并且不复制字符串。

Example

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

impl<'a, T: Clone> From<&'a Vec<T, Global>> for Cow<'a, [T]>

fn from(v: &'a Vec<T>) -> Cow<'a, [T]>

从 Vec 的引用创建 Cow 的 Borrowed 变体。

此转换不会分配或克隆数据。

impl<'a> From<&'a str> for Cow<'a, str>

fn from(s: &'a str) -> Cow<'a, str>

将字符串切片转换为 Borrowed 变体。 不执行堆分配，并且不复制字符串。

Example

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

impl<T: Copy> From<Cow<'_, [T]>> for Box<[T]>

fn from(cow: Cow<'_, [T]>) -> Box<[T]>

执行转换。

impl From<Cow<'_, str>> for Box<str>

fn from(cow: Cow<'_, str>) -> Box<str>

执行转换。

impl<'a, T> From<Cow<'a, [T]>> for Vec<T> where
    [T]: ToOwned<Owned = Vec<T>>, 

fn from(s: Cow<'a, [T]>) -> Vec<T>

将写时克隆切片转换为 vector。

如果 s 已经拥有 Vec<T>，则直接返回。 如果 s 是借用了一个切片，将通过克隆 s 的项来分配和填充一个新的 Vec。

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));

impl<'a, B: ?Sized> From<Cow<'a, B>> for Rc<B> where
    B: ToOwned,
    Rc<B>: From<&'a B> + From<B::Owned>, 

fn from(cow: Cow<'a, B>) -> Rc<B>

通过复制其内容，从写时克隆指针创建一个引用计数指针。

Example

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

impl<'a, B: ?Sized> From<Cow<'a, B>> for Arc<B> where
    B: ToOwned,
    Arc<B>: From<&'a B> + From<B::Owned>, 

fn from(cow: Cow<'a, B>) -> Arc<B>

通过复制其内容，从写时克隆指针创建一个原子引用计数指针。

Example

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

impl<'a> From<Cow<'a, str>> for String

fn from(s: Cow<'a, str>) -> String

将写时克隆字符串转换为 String 的拥有实例。

这将提取拥有所有权的字符串，如果尚未拥有，则克隆该字符串。

Example

// 如果该字符串不被拥有...
let cow: Cow<str> = Cow::Borrowed("eggplant");
// 它将在堆上分配并复制字符串。
let owned: String = String::from(cow);
assert_eq!(&owned[..], "eggplant");

impl<'a> From<String> for Cow<'a, str>

fn from(s: String) -> Cow<'a, str>

将 String 转换为 Owned 变体。 不执行堆分配，并且不复制字符串。

Example

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

impl<'a, T: Clone> From<Vec<T, Global>> for Cow<'a, [T]>

fn from(v: Vec<T>) -> Cow<'a, [T]>

从拥有所有权的 Vec 实例创建 Cow 的 Owned 变体。

此转换不会分配或克隆数据。

impl<'a, 'b> FromIterator<&'b str> for Cow<'a, str>

fn from_iter<I: IntoIterator<Item = &'b str>>(it: I) -> Cow<'a, str>

从迭代器创建一个值。

impl<'a> FromIterator<Cow<'a, str>> for String

fn from_iter<I: IntoIterator<Item = Cow<'a, str>>>(iter: I) -> String

从迭代器创建一个值。

impl<'a> FromIterator<String> for Cow<'a, str>

fn from_iter<I: IntoIterator<Item = String>>(it: I) -> Cow<'a, str>

从迭代器创建一个值。

impl<'a, T> FromIterator<T> for Cow<'a, [T]> where
    T: Clone, 

fn from_iter<I: IntoIterator<Item = T>>(it: I) -> Cow<'a, [T]>

从迭代器创建一个值。

impl<'a> FromIterator<char> for Cow<'a, str>

fn from_iter<I: IntoIterator<Item = char>>(it: I) -> Cow<'a, str>

从迭代器创建一个值。

impl<B: ?Sized> Hash for Cow<'_, B> where
    B: Hash + ToOwned, 

fn hash<H: Hasher>(&self, state: &mut H)

将该值输入给定的 Hasher。

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

将这种类型的切片送入给定的 Hasher 中。

impl<B: ?Sized> Ord for Cow<'_, B> where
    B: Ord + ToOwned, 

fn cmp(&self, other: &Self) -> Ordering

此方法返回 self 和 other 之间的 Ordering。

#[must_use]

fn max(self, other: Self) -> Self

比较并返回两个值中的最大值。

#[must_use]

fn min(self, other: Self) -> Self

比较并返回两个值中的最小值。

#[must_use]

fn clamp(self, min: Self, max: Self) -> Self

将值限制为一定的时间间隔。

impl<T, U> PartialEq<&'_ [U]> for Cow<'_, [T]> where
    T: PartialEq<U>,
    T: Clone, 

fn eq(&self, other: &&[U]) -> bool

此方法测试 self 和 other 值是否相等，并由 == 使用。

fn ne(&self, other: &&[U]) -> bool

此方法测试 !=。

impl<T, U> PartialEq<&'_ mut [U]> for Cow<'_, [T]> where
    T: PartialEq<U>,
    T: Clone, 

fn eq(&self, other: &&mut [U]) -> bool

此方法测试 self 和 other 值是否相等，并由 == 使用。

fn ne(&self, other: &&mut [U]) -> bool

此方法测试 !=。

impl<'a, 'b> PartialEq<&'b str> for Cow<'a, str>

fn eq(&self, other: &&'b str) -> bool

此方法测试 self 和 other 值是否相等，并由 == 使用。

fn ne(&self, other: &&'b str) -> bool

此方法测试 !=。

impl<'a, 'b> PartialEq<Cow<'a, str>> for str

fn eq(&self, other: &Cow<'a, str>) -> bool

此方法测试 self 和 other 值是否相等，并由 == 使用。

fn ne(&self, other: &Cow<'a, str>) -> bool

此方法测试 !=。

impl<'a, 'b> PartialEq<Cow<'a, str>> for &'b str

fn eq(&self, other: &Cow<'a, str>) -> bool

此方法测试 self 和 other 值是否相等，并由 == 使用。

fn ne(&self, other: &Cow<'a, str>) -> bool

此方法测试 !=。

impl<'a, 'b> PartialEq<Cow<'a, str>> for String

fn eq(&self, other: &Cow<'a, str>) -> bool

此方法测试 self 和 other 值是否相等，并由 == 使用。

fn ne(&self, other: &Cow<'a, str>) -> bool

此方法测试 !=。

impl<'a, 'b, B: ?Sized, C: ?Sized> PartialEq<Cow<'b, C>> for Cow<'a, B> where
    B: PartialEq<C> + ToOwned,
    C: ToOwned, 

fn eq(&self, other: &Cow<'b, C>) -> bool

此方法测试 self 和 other 值是否相等，并由 == 使用。

#[must_use]

fn ne(&self, other: &Rhs) -> bool

此方法测试 !=。

impl<'a, 'b> PartialEq<String> for Cow<'a, str>

fn eq(&self, other: &String) -> bool

此方法测试 self 和 other 值是否相等，并由 == 使用。

fn ne(&self, other: &String) -> bool

此方法测试 !=。

impl<T, U, A: Allocator> PartialEq<Vec<U, A>> for Cow<'_, [T]> where
    T: PartialEq<U>,
    T: Clone, 

fn eq(&self, other: &Vec<U, A>) -> bool

此方法测试 self 和 other 值是否相等，并由 == 使用。

fn ne(&self, other: &Vec<U, A>) -> bool

此方法测试 !=。

impl<'a, 'b> PartialEq<str> for Cow<'a, str>

fn eq(&self, other: &str) -> bool

此方法测试 self 和 other 值是否相等，并由 == 使用。

fn ne(&self, other: &str) -> bool

此方法测试 !=。

impl<'a, B: ?Sized> PartialOrd<Cow<'a, B>> for Cow<'a, B> where
    B: PartialOrd + ToOwned, 

fn partial_cmp(&self, other: &Cow<'a, B>) -> Option<Ordering>

如果存在，则此方法返回 self 和 other 值之间的顺序。

#[must_use]

fn lt(&self, other: &Rhs) -> bool

此方法测试的内容少于 (对于 self 和 other)，并且由 < 操作员使用。

#[must_use]

fn le(&self, other: &Rhs) -> bool

此方法测试小于或等于 (对于 self 和 other)，并且由 <= 运算符使用。

#[must_use]

fn gt(&self, other: &Rhs) -> bool

此方法测试大于 (对于 self 和 other)，并且由 > 操作员使用。

#[must_use]

fn ge(&self, other: &Rhs) -> bool

此方法测试是否大于或等于 (对于 self 和 other)，并且由 >= 运算符使用。

impl ToString for Cow<'_, str>

fn to_string(&self) -> String

将给定值转换为 String。

impl<B: ?Sized> Eq for Cow<'_, B> where
    B: Eq + ToOwned,