Примитивный тип str

Строковые срезы

Смотрите также модуль std::str.

Тип str, также называемый "строковым срезом", является наиболее примитивным строковым типом. Обычно встречается в заимствованной форме &str. Также это тип строковых литералов &'static str.

Базовое использование

Строковые литералы являются строковыми срезами:

#![allow(unused)]
fn main() {
let hello_world = "Hello, World!";
}

Здесь мы объявили строковый срез, инициализированный строковым литералом. Строковые литералы имеют статическое время жизни ('static), что означает, что строка hello_world гарантированно будет корректной на протяжении всей программы. Мы также можем явно указать время жизни hello_world:

#![allow(unused)]
fn main() {
let hello_world: &'static str = "Hello, world!";
}

Представление

&str состоит из двух компонентов: указателя на байты и длины. Вы можете посмотреть их с помощью методов as_ptr и len:

#![allow(unused)]
fn main() {
use std::slice;
use std::str;

let story = "Once upon a time...";

let ptr = story.as_ptr();
let len = story.len();

// story имеет девятнадцать байтов
assert_eq!(19, len);

// Мы можем воссоздать str из ptr и len. Это небезопасно, потому что
// мы ответственны за то, чтобы оба компонента были корректны:
let s = unsafe {
    // Сначала строим &[u8]...
    let slice = slice::from_raw_parts(ptr, len);

    // ... и затем преобразуем этот срез в строковый срез
    str::from_utf8(slice)
};

assert_eq!(s, Ok(story));
}

Примечание: Этот пример показывает внутреннее устройство &str. unsafe не должен использоваться для получения строкового среза в обычных обстоятельствах. Вместо этого используйте as_str.

Инвариант

Библиотеки Rust могут предполагать, что строковые срезы всегда являются корректным UTF-8.

Создание не-UTF-8 строкового среза не является немедленным неопределённым поведением, но любая функция, вызванная на строковом срезе, может предполагать, что он является корректным UTF-8, что означает, что не-UTF-8 строковый срез может привести к неопределённому поведению в дальнейшем.

Реализации

impl str

Методы

`pub const fn len(&self) -> usize`

Возвращает длину self.

Эта длина измеряется в байтах, не в символах или графемах. Другими словами, это может не соответствовать тому, что человек считает длиной строки.

Примеры:

#![allow(unused)]
fn main() {
let len = "foo".len();
assert_eq!(3, len);

assert_eq!("ƒoo".len(), 4); // модная f!
assert_eq!("ƒoo".chars().count(), 3);
}

`pub const fn is_empty(&self) -> bool`

Возвращает true, если self имеет нулевую длину в байтах.

Примеры:

#![allow(unused)]
fn main() {
let s = "";
assert!(s.is_empty());

let s = "not empty";
assert!(!s.is_empty());
}

`pub const fn from_utf8(v: &[u8]) -> Result<&str, Utf8Error>`

Преобразует срез байтов в строковый срез.

Строковый срез (&str) состоит из байтов (u8), и срез байтов (&[u8]) также состоит из байтов, поэтому эта функция выполняет преобразование между ними. Однако не все срезы байтов являются корректными строковыми срезами: &str требует, чтобы данные были корректным UTF-8. from_utf8() проверяет, являются ли байты корректным UTF-8, и затем выполняет преобразование.

Если вы уверены, что срез байтов является корректным UTF-8, и не хотите тратить ресурсы на проверку валидности, существует небезопасная версия этой функции - from_utf8_unchecked, которая имеет такое же поведение, но пропускает проверку.

Если вам нужна String вместо &str, рассмотрите String::from_utf8.

Поскольку вы можете разместить [u8; N] в стеке и взять из него &[u8], эта функция является одним из способов получить строку, размещённую в стеке.

Ошибки: Возвращает Err, если срез не является UTF-8, с описанием причины.

Примеры:

#![allow(unused)]
fn main() {
// несколько байтов в векторе
let sparkle_heart = vec![240, 159, 146, 150];

// Мы можем использовать оператор ? (try) для проверки
let sparkle_heart = str::from_utf8(&sparkle_heart)?;

assert_eq!("💖", sparkle_heart);
}

`pub const fn from_utf8_mut(v: &mut [u8]) -> Result<&mut str, Utf8Error>`

Преобразует изменяемый срез байтов в изменяемый строковый срез.

Примеры:

#![allow(unused)]
fn main() {
// "Hello, Rust!" в виде изменяемого вектора
let mut hellorust = vec![72, 101, 108, 108, 111, 44, 32, 82, 117, 115, 116, 33];

let outstr = str::from_utf8_mut(&mut hellorust).unwrap();
assert_eq!("Hello, Rust!", outstr);
}

`pub const unsafe fn from_utf8_unchecked(v: &[u8]) -> &str`

Преобразует срез байтов в строковый срез без проверки того, что строка содержит корректный UTF-8.

Безопасность: Переданные байты должны быть корректным UTF-8.

Примеры:

#![allow(unused)]
fn main() {
let sparkle_heart = vec![240, 159, 146, 150];
let sparkle_heart = unsafe {
    str::from_utf8_unchecked(&sparkle_heart)
};
assert_eq!("💖", sparkle_heart);
}

`pub const unsafe fn from_utf8_unchecked_mut(v: &mut [u8]) -> &mut str`

Преобразует срез байтов в строковый срез без проверки того, что строка содержит корректный UTF-8; изменяемая версия.

Примеры:

#![allow(unused)]
fn main() {
let mut heart = vec![240, 159, 146, 150];
let heart = unsafe { str::from_utf8_unchecked_mut(&mut heart) };
assert_eq!("💖", heart);
}

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

Проверяет, является ли index-ный байт первым байтом в последовательности UTF-8 или концом строки.

Начало и конец строки (когда index == self.len()) считаются границами.

Возвращает false, если index больше self.len().

Примеры:

#![allow(unused)]
fn main() {
let s = "Löwe 老虎 Léopard";
assert!(s.is_char_boundary(0));
assert!(s.is_char_boundary(6));
assert!(s.is_char_boundary(s.len()));
assert!(!s.is_char_boundary(2));  // второй байт `ö`
assert!(!s.is_char_boundary(8));  // третий байт `老`
}

`pub const fn floor_char_boundary(&self, index: usize) -> usize`

Находит ближайший x, не превышающий index, где is_char_boundary(x) истинно.

Примеры:

#![allow(unused)]
fn main() {
let s = "❤️🧡💛💚💙💜";
assert_eq!(s.len(), 26);
assert!(!s.is_char_boundary(13));

let closest = s.floor_char_boundary(13);
assert_eq!(closest, 10);
assert_eq!(&s[..closest], "❤️🧡");
}

`pub const fn ceil_char_boundary(&self, index: usize) -> usize`

Находит ближайший x, не меньший index, где is_char_boundary(x) истинно.

Примеры:

#![allow(unused)]
fn main() {
let s = "❤️🧡💛💚💙💜";
let closest = s.ceil_char_boundary(13);
assert_eq!(closest, 14);
assert_eq!(&s[..closest], "❤️🧡💛");
}

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

Преобразует строковый срез в срез байтов.

Примеры:

#![allow(unused)]
fn main() {
let bytes = "bors".as_bytes();
assert_eq!(b"bors", bytes);
}

`pub const unsafe fn as_bytes_mut(&mut self) -> &mut [u8]`

Преобразует изменяемый строковый срез в изменяемый срез байтов.

Безопасность: Вызывающий должен гарантировать, что содержимое среза остаётся корректным UTF-8.

Примеры:

#![allow(unused)]
fn main() {
let mut s = String::from("🗻∈🌏");
unsafe {
    let bytes = s.as_bytes_mut();
    bytes[0] = 0xF0;
    bytes[1] = 0x9F;
    bytes[2] = 0x8D;
    bytes[3] = 0x94;
}
assert_eq!("🍔∈🌏", s);
}

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

Преобразует строковый срез в необработанный указатель.

Примеры:

#![allow(unused)]
fn main() {
let s = "Hello";
let ptr = s.as_ptr();
}

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

Преобразует изменяемый строковый срез в необработанный указатель.

`pub fn get(&self, i: I) -> Option<&>::Output>`

Возвращает под-срез str.

Это непанующий альтернатива индексации str. Возвращает None, когда эквивалентная операция индексации вызвала бы панику.

Примеры:

#![allow(unused)]
fn main() {
let v = String::from("🗻∈🌏");
assert_eq!(Some("🗻"), v.get(0..4));
assert!(v.get(1..).is_none());  // не на границе UTF-8
}

Примеры:

#![allow(unused)]
fn main() {
let s = "Per Martin-Löf";
let (first, last) = s.split_at(3);
assert_eq!("Per", first);
assert_eq!(" Martin-Löf", last);
}

#![allow(unused)]
fn main() {
let word = "goodbye";
let mut chars = word.chars();
assert_eq!(Some('g'), chars.next());
}

`pub fn char_indices(&self) -> CharIndices<'_>`

Возвращает итератор по символам строкового среза и их позициям.

`pub fn bytes(&self) -> Bytes<'_>`

Возвращает итератор по байтам строкового среза.

`pub fn split_whitespace(&self) -> SplitWhitespace<'_>`

Разделяет строковый срез по пробельным символам Unicode.

`pub fn split_ascii_whitespace(&self) -> SplitAsciiWhitespace<'_>`

Разделяет строковый срез по ASCII пробельным символам.

`pub fn lines(&self) -> Lines<'_>`

Возвращает итератор по строкам текста.

`pub fn encode_utf16(&self) -> EncodeUtf16<'_>`

Возвращает итератор u16 над строкой, закодированной как UTF-16.

`pub fn contains(&self, pat: P) -> bool`

Возвращает true, если данный паттерн соответствует под-срезу этой строки.

`pub fn starts_with(&self, pat: P) -> bool`

Возвращает true, если данный паттерн соответствует префиксу этой строки.

`pub fn ends_with(&self, pat: P) -> bool`

Возвращает true, если данный паттерн соответствует суффиксу этой строки.

`pub fn find(&self, pat: P) -> Option<usize>`

Возвращает байтовый индекс первого символа, соответствующего паттерну.

`pub fn rfind(&self, pat: P) -> Option<usize>`

Возвращает байтовый индекс первого символа последнего совпадения паттерна.

`pub fn split(&self, pat: P) -> Split<'_, P>`

Возвращает итератор по подстрокам, разделённым паттерном.

`pub fn split_inclusive(&self, pat: P) -> SplitInclusive<'_, P>`

Возвращает итератор по подстрокам, включая разделитель в конец подстроки.

`pub fn rsplit(&self, pat: P) -> RSplit<'_, P>`

Возвращает итератор по подстрокам в обратном порядке.

`pub fn split_terminator(&self, pat: P) -> SplitTerminator<'_, P>`

Возвращает итератор по подстрокам, пропуская пустую завершающую подстроку.

`pub fn rsplit_terminator(&self, pat: P) -> RSplitTerminator<'_, P>`

Возвращает итератор по подстрокам в обратном порядке, пропуская пустую завершающую подстроку.

`pub fn splitn(&self, n: usize, pat: P) -> SplitN<'_, P>`

Возвращает итератор по подстрокам, ограниченный n элементами.

`pub fn rsplitn(&self, n: usize, pat: P) -> RSplitN<'_, P>`

Возвращает итератор по подстрокам в обратном порядке, ограниченный n элементами.

`pub fn split_once(&self, delimiter: P) -> Option<(&str, &str)>`

Разделяет строку по первому вхождению разделителя.

`pub fn rsplit_once(&self, delimiter: P) -> Option<(&str, &str)>`

Разделяет строку по последнему вхождению разделителя.

`pub fn matches(&self, pat: P) -> Matches<'_, P>`

Возвращает итератор по непересекающимся совпадениям паттерна.

`pub fn rmatches(&self, pat: P) -> RMatches<'_, P>`

Возвращает итератор по непересекающимся совпадениям паттерна в обратном порядке.

`pub fn match_indices(&self, pat: P) -> MatchIndices<'_, P>`

Возвращает итератор по совпадениям паттерна и их индексам.

`pub fn rmatch_indices(&self, pat: P) -> RMatchIndices<'_, P>`

Возвращает итератор по совпадениям паттерна и их индексам в обратном порядке.

`pub fn trim(&self) -> &str`

Возвращает строковый срез с удалёнными начальными и конечными пробельными символами Unicode.

`pub fn trim_start(&self) -> &str`

Возвращает строковый срез с удалёнными начальными пробельными символами.

`pub fn trim_end(&self) -> &str`

Возвращает строковый срез с удалёнными конечными пробельными символами.

`pub fn trim_matches(&self, pat: P) -> &str`

Возвращает строковый срез с удалёнными всеми префиксами и суффиксами, соответствующими паттерну.

`pub fn trim_start_matches(&self, pat: P) -> &str`

Возвращает строковый срез с удалёнными всеми префиксами, соответствующими паттерну.

`pub fn strip_prefix(&self, prefix: P) -> Option<&str>`

Возвращает строковый срез с удалённым префиксом (точно один раз).

`pub fn strip_suffix(&self, suffix: P) -> Option<&str>`

Возвращает строковый срез с удалённым суффиксом (точно один раз).

`pub fn trim_end_matches(&self, pat: P) -> &str`

Возвращает строковый срез с удалёнными всеми суффиксами, соответствующими паттерну.

`pub fn parse<F>(&self) -> Result<F, <F as FromStr>::Err>`

Парсит этот строковый срез в другой тип.

`pub const fn is_ascii(&self) -> bool`

Проверяет, находятся ли все символы в строке в диапазоне ASCII.

`pub const fn eq_ignore_ascii_case(&self, other: &str) -> bool`

Проверяет, являются ли две строки одинаковыми без учёта регистра ASCII.

`pub const fn make_ascii_uppercase(&mut self)`

Преобразует строку в верхний регистр ASCII на месте.

`pub const fn make_ascii_lowercase(&mut self)`

Преобразует строку в нижний регистр ASCII на месте.

`pub const fn trim_ascii_start(&self) -> &str`

Возвращает строковый срез с удалёнными начальными пробельными символами ASCII.

`pub const fn trim_ascii_end(&self) -> &str`

Возвращает строковый срез с удалёнными конечными пробельными символами ASCII.

`pub const fn trim_ascii(&self) -> &str`

Возвращает строковый срез с удалёнными начальными и конечными пробельными символами ASCII.

`pub fn escape_debug(&self) -> EscapeDebug<'_>`

Возвращает итератор, экранирующий каждый символ с помощью char::escape_debug.

`pub fn escape_default(&self) -> EscapeDefault<'_>`

Возвращает итератор, экранирующий каждый символ с помощью char::escape_default.

`pub fn escape_unicode(&self) -> EscapeUnicode<'_>`

Возвращает итератор, экранирующий каждый символ с помощью char::escape_unicode.

impl str (Методы для строковых срезов)

`pub fn into_boxed_bytes(self: Box<str>) -> Box<[u8]>`

Преобразует Box<str> в Box<[u8]> без копирования или аллокации.

`pub fn replace(&self, from: P, to: &str) -> String`

Заменяет все вхождения паттерна другой строкой.

`pub fn replacen(&self, pat: P, to: &str, count: usize) -> String`

Заменяет первые N вхождений паттерна другой строкой.

`pub fn to_lowercase(&self) -> String`

Возвращает строку в нижнем регистре Unicode.

`pub fn to_uppercase(&self) -> String`

Возвращает строку в верхнем регистре Unicode.

`pub fn repeat(&self, n: usize) -> String`

Создаёт новую String, повторяя строку n раз.

`pub fn to_ascii_uppercase(&self) -> String`

Возвращает копию строки, где каждый символ преобразован в верхний регистр ASCII.

`pub fn to_ascii_lowercase(&self) -> String`

Возвращает копию строки, где каждый символ преобразован в нижний регистр ASCII.

Реализации трейтов

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

`impl Add<&str> for String`

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

`impl AddAssign<&str> for String`

`impl AsMut<str> for String`

`impl AsRef<[u8]> for str`

`impl AsRef<OsStr> for str`

`impl AsRef<Path> for str`

`impl Borrow<str> for String`

`impl BorrowMut<str> for String`

`impl Clone for Box<str>`

`impl Debug for str`

`impl Default for &str`

`impl Display for str`

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

`impl From<&str> for String`

`impl From<&str> for Vec<u8>`

`impl<'a> FromIterator<&'a str> for String`

`impl Hash for str`

`impl Index for str`

`impl IndexMut for str`

`impl Ord for str`

`impl PartialEq for str`

`impl PartialOrd for str`

`impl<'b> Pattern for &'b str`

`impl ToOwned for str`

`impl ToSocketAddrs for str`

`impl Eq for str`

Автоматические реализации трейтов

Freeze for str
RefUnwindSafe for str
Send for str
!Sized for str (не имеет размера во время компиляции)
Sync for str
Unpin for str
UnwindSafe for str

Библиотека RUST