Struct std::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 std::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, Global>) -> 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, Global>) -> String

pub fn into_bytes(self) -> Vec<u8, Global>ⓘNotable traits for Vec<u8, A>impl<A: Allocator> Write for Vec<u8, A>

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]ⓘNotable traits for &[u8]impl Read for &[u8]impl Write for &mut [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<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, Global>ⓘNotable traits for Vec<u8, A>impl<A: Allocator> Write for Vec<u8, A>

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>,

Methods from Deref<Target = str>

pub const fn len(&self) -> usize

pub const fn is_empty(&self) -> bool

pub fn is_char_boundary(&self, index: usize) -> bool

pub const fn as_bytes(&self) -> &[u8]ⓘNotable traits for &[u8]impl Read for &[u8]impl Write for &mut [u8]

pub unsafe fn as_bytes_mut(&mut self) -> &mut [u8]ⓘNotable traits for &[u8]impl Read for &[u8]impl Write for &mut [u8]

pub const fn as_ptr(&self) -> *const u8

pub fn as_mut_ptr(&mut self) -> *mut u8

pub fn get<I>(&self, i: I) -> Option<&<I as SliceIndex<str>>::Output> where I: SliceIndex<str>,

pub fn get_mut<I>( &mut self, i: I) -> Option<&mut <I as SliceIndex<str>>::Output> where I: SliceIndex<str>,

pub unsafe fn get_unchecked<I>(&self, i: I) -> &<I as SliceIndex<str>>::Output where I: SliceIndex<str>,

pub unsafe fn get_unchecked_mut<I>( &mut self, i: I) -> &mut <I as SliceIndex<str>>::Output where I: SliceIndex<str>,

pub unsafe fn slice_unchecked(&self, begin: usize, end: usize) -> &str

pub unsafe fn slice_mut_unchecked( &mut self, begin: usize, end: usize) -> &mut str

pub fn split_at(&self, mid: usize) -> (&str, &str)

pub fn split_at_mut(&mut self, mid: usize) -> (&mut str, &mut str)

pub fn chars(&self) -> Chars<'_>ⓘNotable traits for Chars<'a>impl<'a> Iterator for Chars<'a> type Item = char;

pub fn char_indices(&self) -> CharIndices<'_>ⓘNotable traits for CharIndices<'a>impl<'a> Iterator for CharIndices<'a> type Item = (usize, char);

pub fn bytes(&self) -> Bytes<'_>ⓘNotable traits for Bytes<'_>impl<'_> Iterator for Bytes<'_> type Item = u8;

pub fn split_whitespace(&self) -> SplitWhitespace<'_>ⓘNotable traits for SplitWhitespace<'a>impl<'a> Iterator for SplitWhitespace<'a> type Item = &'a str;

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 fn into_bytes(self) -> Vec<u8, Global>ⓘ
Notable traits for Vec<u8, A>
`impl<A: Allocator> Write for Vec<u8, A>`

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 as_bytes(&self) -> &[u8 ]ⓘ
Notable traits for &[u8 ]
`impl Read for &[u8]impl Write for &mut [u8]`

pub fn remove_matches<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 unsafe fn as_mut_vec(&mut self) -> &mut Vec<u8, Global>ⓘ
Notable traits for Vec<u8, A>
`impl<A: Allocator> Write for Vec<u8, A>`

#[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 const fn as_bytes(&self) -> &[u8 ]ⓘ
Notable traits for &[u8 ]
`impl Read for &[u8]impl Write for &mut [u8]`

pub unsafe fn as_bytes_mut(&mut self) -> &mut [u8 ]ⓘ
Notable traits for &[u8 ]
`impl Read for &[u8]impl Write for &mut [u8]`

pub fn get<I>(&self, i: I) -> Option<&<I as SliceIndex<str>>::Output> where
I: SliceIndex<str>,

pub fn get_mut<I>(
&mut self,
i: I
) -> Option<&mut <I as SliceIndex<str>>::Output> where
I: SliceIndex<str>,

pub unsafe fn get_unchecked<I>(&self, i: I) -> &<I as SliceIndex<str>>::Output where
I: SliceIndex<str>,

pub unsafe fn get_unchecked_mut<I>(
&mut self,
i: I
) -> &mut <I as SliceIndex<str>>::Output where
I: SliceIndex<str>,

pub unsafe fn slice_mut_unchecked(
&mut self,
begin: usize,
end: usize
) -> &mut str

pub fn split_at(&self, mid: usize) -> (&str, &str )

pub fn split_at_mut(&mut self, mid: usize) -> (&mut str, &mut str )

pub fn chars(&self) -> Chars<'_>ⓘ
Notable traits for Chars<'a>
`impl<'a> Iterator for Chars<'a> type Item = char;`

pub fn char_indices(&self) -> CharIndices<'_>ⓘ
Notable traits for CharIndices<'a>
`impl<'a> Iterator for CharIndices<'a> type Item = (usize, char);`

pub fn bytes(&self) -> Bytes<'_>ⓘ
Notable traits for Bytes<'_>
`impl<'_> Iterator for Bytes<'_> type Item = u8;`

pub fn split_whitespace(&self) -> SplitWhitespace<'_>ⓘ
Notable traits for SplitWhitespace<'a>
`impl<'a> Iterator for SplitWhitespace<'a> type Item = &'a str;`