Struct alloc::string::String1.0.0[−][src]

pub struct String { /* fields omitted */ }

Expand description

一个 UTF-8 编码的可增长字符串。

String 类型是最常见的字符串类型，拥有对该字符串内容的所有权。它与其借来的对等体 str 有着密切的关系。

Examples

您可以使用 String::from 从 a literal string 创建 String:

let hello = String::from("Hello, world!");

Run

您可以使用 push 方法将 char 附加到 String，并使用 push_str 方法将 &str 附加:

let mut hello = String::from("Hello, ");

hello.push('w');
hello.push_str("orld!");

Run

如果具有 UTF-8 字节的 vector，则可以使用 from_utf8 方法从中创建一个 String:

// vector 中的一些字节
let sparkle_heart = vec![240, 159, 146, 150];

// 我们知道这些字节是有效的，因此我们将使用 `unwrap()`。
let sparkle_heart = String::from_utf8(sparkle_heart).unwrap();

assert_eq!("💖", sparkle_heart);

Run

UTF-8

Strings 始终是有效的 UTF-8。这有一些含义，首先是如果您需要非 UTF-8 字符串，请考虑使用 OsString。它是相似的，但是没有 UTF-8 约束。第二个含义是您不能索引到 String:

let s = "hello";

println!("The first letter of s is {}", s[0]); // ERROR!!!

Run

索引旨在进行恒定时间操作，但是 UTF-8 编码不允许我们执行此操作。此外，尚不清楚索引应返回哪种类型: 字节，代码点或字形簇。 bytes 和 chars 方法分别返回前两个迭代器。

Deref

字符串实现 Deref<Target=str>，因此继承了 str 的所有方法。另外，这意味着您可以使用与号 (&) 将 String 传递给采用 &str 的函数:

fn takes_str(s: &str) { }

let s = String::from("Hello");

takes_str(&s);

Run

这将从 String 创建 &str 并将其传入。这种转换非常便宜，因此通常，函数会接受 &str 作为参数，除非出于某些特定原因它们需要 String。

在某些情况下，Rust 没有足够的信息来进行此转换，称为 Deref 强制。在以下示例中，字符串切片 &'a str 实现 trait TraitExample，函数 example_func 接受实现 trait 的所有内容。在这种情况下，Rust 将需要进行两次隐式转换，而 Rust 没有办法进行转换。因此，以下示例将无法编译。

trait TraitExample {}

impl<'a> TraitExample for &'a str {}

fn example_func<A: TraitExample>(example_arg: A) {}

let example_string = String::from("example_string");
example_func(&example_string);

Run

有两种选择可以代替。第一种是使用方法 as_str() 显式提取包含该字符串的字符串切片，从而将 example_func(&example_string); 行更改为 example_func(example_string.as_str());。第二种方法将 example_func(&example_string); 更改为 example_func(&*example_string);。在这种情况下，我们将 String 解引用为 str，然后将 str 引用回 &str。第二种方法更惯用，但是两种方法都可以显式地进行转换，而不是依赖于隐式转换。

Representation

String 由三个部分组成: 指向某些字节的指针，长度和容量。指针指向 String 用于存储其数据的内部缓冲区。长度是当前存储在缓冲区中的字节数，容量是缓冲区的大小 (以字节为单位)。

这样，长度将始终小于或等于容量。

此缓冲区始终存储在堆中。

您可以使用 as_ptr，len 和 capacity 方法查看它们:

use std::mem;

let story = String::from("Once upon a time...");

// 防止自动丢弃字符串的数据
let mut story = mem::ManuallyDrop::new(story);

let ptr = story.as_mut_ptr();
let len = story.len();
let capacity = story.capacity();

// story 有十九个字节
assert_eq!(19, len);

// 我们可以根据 ptr，len 和容量重新构建一个 String。
// 这都是不安全的，因为我们有责任确保组件有效:
let s = unsafe { String::from_raw_parts(ptr, len, capacity) } ;

assert_eq!(String::from("Once upon a time..."), s);

Run

如果 String 具有足够的容量，则向其添加元素将不会重新分配。例如，考虑以下程序:

let mut s = String::new();

println!("{}", s.capacity());

for _ in 0..5 {
    s.push_str("hello");
    println!("{}", s.capacity());
}

Run

这将输出以下内容:

最初，我们根本没有分配任何内存，但是当我们追加到字符串后，它会适当地增加其容量。如果我们改为使用 with_capacity 方法来初始分配正确的容量，请执行以下操作:

let mut s = String::with_capacity(25);

println!("{}", s.capacity());

for _ in 0..5 {
    s.push_str("hello");
    println!("{}", s.capacity());
}

Run

我们最终得到了不同的输出:

在这里，不需要在循环内分配更多的内存。

Struct alloc::string::String1.0.0[−][src]

Implementations

impl String

pub const fn new() -> String

pub fn with_capacity(capacity: usize) -> String

pub fn from_utf8(vec: Vec<u8>) -> Result<String, FromUtf8Error>

pub fn from_utf8_lossy(v: &[u8]) -> Cow<'_, str>

pub fn from_utf16(v: &[u16]) -> Result<String, FromUtf16Error>

pub fn from_utf16_lossy(v: &[u16]) -> String

pub fn into_raw_parts(self) -> (*mut u8, usize, usize)

pub unsafe fn from_raw_parts( buf: *mut u8, length: usize, capacity: usize) -> String

pub unsafe fn from_utf8_unchecked(bytes: Vec<u8>) -> String

pub fn into_bytes(self) -> Vec<u8>

pub fn as_str(&self) -> &str

pub fn as_mut_str(&mut self) -> &mut str

pub fn push_str(&mut self, string: &str)

pub fn extend_from_within<R>(&mut self, src: R) where R: RangeBounds<usize>,

pub fn capacity(&self) -> usize

pub fn reserve(&mut self, additional: usize)

pub fn reserve_exact(&mut self, additional: usize)

pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError>

pub fn try_reserve_exact( &mut self, additional: usize) -> Result<(), TryReserveError>

pub fn shrink_to_fit(&mut self)

pub fn shrink_to(&mut self, min_capacity: usize)

pub fn push(&mut self, ch: char)

pub fn as_bytes(&self) -> &[u8]

pub fn truncate(&mut self, new_len: usize)

pub fn pop(&mut self) -> Option<char>

pub fn remove(&mut self, idx: usize) -> char

pub fn remove_matches<'a, P>(&'a mut self, pat: P) where P: for<'x> Pattern<'x>,

pub fn retain<F>(&mut self, f: F) where F: FnMut(char) -> bool,

pub fn insert(&mut self, idx: usize, ch: char)

pub fn insert_str(&mut self, idx: usize, string: &str)

pub unsafe fn as_mut_vec(&mut self) -> &mut Vec<u8>

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

#[must_use = "use `.truncate()` if you don't need the other half"]pub fn split_off(&mut self, at: usize) -> String

pub fn clear(&mut self)

pub fn drain<R>(&mut self, range: R) -> Drain<'_>ⓘNotable traits for Drain<'_>impl Iterator for Drain<'_> type Item = char; where R: RangeBounds<usize>,

pub fn replace_range<R>(&mut self, range: R, replace_with: &str) where R: RangeBounds<usize>,

pub fn into_boxed_str(self) -> Box<str>ⓘNotable traits for Box<I, A>impl<I: Iterator + ?Sized, A: Allocator> Iterator for Box<I, A> type Item = I::Item;impl<F: ?Sized + Future + Unpin, A: Allocator> Future for Box<F, A> where A: 'static, type Output = F::Output;

Trait Implementations

impl Add<&'_ str> for String

type Output = String

fn add(self, other: &str) -> String

impl AddAssign<&'_ str> for String

fn add_assign(&mut self, other: &str)

impl AsMut<str> for String

fn as_mut(&mut self) -> &mut str

impl AsRef<[u8]> for String

fn as_ref(&self) -> &[u8]

impl AsRef<str> for String

fn as_ref(&self) -> &str

impl Borrow<str> for String

fn borrow(&self) -> &str

impl BorrowMut<str> for String

fn borrow_mut(&mut self) -> &mut str

impl Clone for String

fn clone(&self) -> Self

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

impl Debug for String

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

impl Default for String

fn default() -> String

impl Deref for String

type Target = str

fn deref(&self) -> &str

impl DerefMut for String

fn deref_mut(&mut self) -> &mut str

impl Display for String

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

impl<'a> Extend<&'a char> for String

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

fn extend_one(&mut self, c: &'a char)

fn extend_reserve(&mut self, additional: usize)

impl<'a> Extend<&'a str> for String

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

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

fn extend_reserve(&mut self, additional: usize)

impl Extend<Box<str, Global>> for String

pub unsafe fn from_raw_parts(
buf: *mut u8,
length: usize,
capacity: usize
) -> String

pub fn extend_from_within<R>(&mut self, src: R) where
R: RangeBounds<usize>,

pub fn try_reserve_exact(
&mut self,
additional: usize
) -> Result<(), TryReserveError>

pub fn remove_matches<'a, P>(&'a mut self, pat: P) where
P: for<'x> Pattern<'x>,

pub fn retain<F>(&mut self, f: F) where
F: FnMut(char) -> bool,

#[must_use = "use `.truncate()` if you don't need the other half"]
pub fn split_off(&mut self, at: usize) -> String

pub fn drain<R>(&mut self, range: R) -> Drain<'_>ⓘ
Notable traits for Drain<'_>
`impl Iterator for Drain<'_> type Item = char;`
where
R: RangeBounds<usize>,

pub fn replace_range<R>(&mut self, range: R, replace_with: &str) where
R: RangeBounds<usize>,

pub fn into_boxed_str(self) -> Box<str>ⓘ
Notable traits for Box<I, A>
`impl<I: Iterator + ?Sized, A: Allocator> Iterator for Box<I, A> type Item = I::Item;impl<F: ?Sized + Future + Unpin, A: Allocator> Future for Box<F, A> where A: 'static, type Output = F::Output;`