Enum alloc::borrow::Cow

pub enum Cow<'a, B>where
    B: ToOwned + ?Sized + 'a,{
    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> 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 会返回借用数据的克隆:

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 会返回拥有所有权的数据。 数据被移出 Cow 而不被克隆。

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> Borrow<B> for Cow<'a, B>where B: ToOwned + ?Sized,

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> Debug for Cow<'_, B>where B: Debug + ToOwned<Owned: Debug> + ?Sized,

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

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

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

fn default() -> Self

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

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

type Target = B

解引用后的结果类型。

fn deref(&self) -> &B

解引用值。

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

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 CStr> for Cow<'a, CStr>

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

将 CStr 转换为借用的 Cow，无需复制或分配。

impl<'a> From<&'a CString> for Cow<'a, CStr>

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

将 &CString 转换为借用的 Cow，无需复制或分配。

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<'a> From<CString> for Cow<'a, CStr>

fn from(s: CString) -> Cow<'a, CStr>

无需复制或分配即可将 CString 转换为拥有所有权的 Cow。

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

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

将 Cow<'_, [T]> 转换为 Box<[T]>

当 cow 是 Cow::Borrowed 变体时，此转换在堆上分配并复制底层切片。 否则，它将尝试重用拥有所有权的 Vec 的分配。

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

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

通过复制借用的内容将 Cow<'a, CStr> 转换为 Box<CStr>。

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

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

将 Cow<'_, str> 转换为 Box<str>

当 cow 是 Cow::Borrowed 变体时，此转换在堆上分配并复制底层 str。 否则，它将尝试重用拥有所有权的 String 的分配。

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

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> From<Cow<'a, B>> for Arc<B>where B: ToOwned + ?Sized, 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, B> From<Cow<'a, B>> for Rc<B>where B: ToOwned + ?Sized, 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> From<Cow<'a, CStr>> for CString

fn from(s: Cow<'a, CStr>) -> Self

通过复制借用的内容将 Cow<'a, CStr> 转换为 CString。

impl<'a> From<Cow<'a, str>> for Box<dyn Error>

fn from(err: Cow<'a, str>) -> Box<dyn Error>

将 Cow 转换为 dyn Error 的 box。

Examples

use std::error::Error;
use std::mem;
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!(mem::size_of::<Box<dyn Error>>() == mem::size_of_val(&a_boxed_error))

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, 'b> From<Cow<'b, str>> for Box<dyn Error + Send + Sync + 'a>

fn from(err: Cow<'b, str>) -> Box<dyn Error + Send + Sync + 'a>

将 Cow 转换为 Dyn Error + Send + Sync 的 box。

Examples

use std::error::Error;
use std::mem;
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!(
    mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))

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> Hash for Cow<'_, B>where B: Hash + ToOwned + ?Sized,

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

将该值输入给定的 Hasher。

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

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

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

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

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

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

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

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

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

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

将值限制在某个时间间隔内。

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

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

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

fn ne(&self, other: &&[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<T, U> PartialEq<&mut [U]> for Cow<'_, [T]>where T: PartialEq<U> + Clone,

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

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

fn ne(&self, other: &&mut [U]) -> 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> 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, B, C> PartialEq<Cow<'b, C>> for Cow<'a, B>where B: PartialEq<C> + ToOwned + ?Sized, C: ToOwned + ?Sized,

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

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

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> + 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> PartialOrd<Cow<'a, B>> for Cow<'a, B>where B: PartialOrd + ToOwned + ?Sized,

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

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

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

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

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

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

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

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

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

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

impl ToString for Cow<'_, str>

fn to_string(&self) -> String

将给定值转换为 String。

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