Структура `FromUtf8Error`

Описание

Возможное значение ошибки при преобразовании String из вектора UTF-8 байт.

Этот тип является типом ошибки для метода from_utf8 у String. Он разработан таким образом, чтобы тщательно избежать перераспределений памяти: метод into_bytes вернет вектор байт, который использовался в попытке преобразования.

Тип Utf8Error, предоставляемый std::str, представляет ошибку, которая может произойти при преобразовании среза u8 в &str. В этом смысле он является аналогом FromUtf8Error, и вы можете получить его из FromUtf8Error через метод utf8_error.

Синтаксис

#![allow(unused)]
fn main() {
pub struct FromUtf8Error { /* приватные поля */ }
}

Методы

`as_bytes`

#![allow(unused)]
fn main() {
pub fn as_bytes(&self) -> &[u8] ⓘ
}

Возвращает срез байт u8, которые пытались преобразовать в String.

Доступность: 1.26.0

Примеры

#![allow(unused)]
fn main() {
// некоторые невалидные байты в векторе
let bytes = vec![0, 159];

let value = String::from_utf8(bytes);

assert_eq!(&[0, 159], value.unwrap_err().as_bytes());
}

`into_utf8_lossy` ⚡️

#![allow(unused)]
fn main() {
pub fn into_utf8_lossy(self) -> String
}

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

Доступность: Экспериментальный API (только в ночных сборках)

Смотрите String::from_utf8_lossy для получения дополнительной информации о замене невалидных последовательностей и String::from_utf8_lossy_owned для функции String, которая соответствует этой функции.

Примеры

#![allow(unused)]
#![feature(string_from_utf8_lossy_owned)]
fn main() {
// некоторые невалидные байты
let input: Vec<u8> = b"Hello \xF0\x90\x80World".into();
let output = String::from_utf8(input).unwrap_or_else(|e| e.into_utf8_lossy());

assert_eq!(String::from("Hello �World"), output);
}

`into_bytes`

#![allow(unused)]
fn main() {
pub fn into_bytes(self) -> Vec<u8> ⓘ
}

Возвращает байты, которые пытались преобразовать в String.

Этот метод тщательно сконструирован, чтобы избежать аллокации. Он потребит ошибку, переместив байты, так что копия байт не должна быть создана.

Доступность: 1.0.0

Примеры

#![allow(unused)]
fn main() {
// некоторые невалидные байты в векторе
let bytes = vec![0, 159];

let value = String::from_utf8(bytes);

assert_eq!(vec![0, 159], value.unwrap_err().into_bytes());
}

`utf8_error`

#![allow(unused)]
fn main() {
pub fn utf8_error(&self) -> Utf8Error
}

Получает Utf8Error для получения более подробной информации о неудаче преобразования.

Тип Utf8Error, предоставляемый std::str, представляет ошибку, которая может произойти при преобразовании среза u8 в &str. В этом смысле он является аналогом FromUtf8Error. Смотрите его документацию для получения более подробной информации об использовании.

Доступность: 1.0.0

Примеры

#![allow(unused)]
fn main() {
// некоторые невалидные байты в векторе
let bytes = vec![0, 159];

let error = String::from_utf8(bytes).unwrap_err().utf8_error();

// первый байт невалиден здесь
assert_eq!(1, error.valid_up_to());
}

Примеры использования

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

#![allow(unused)]
fn main() {
// некоторые невалидные байты в векторе
let bytes = vec![0, 159];

let value = String::from_utf8(bytes);

assert!(value.is_err());
assert_eq!(vec![0, 159], value.unwrap_err().into_bytes());
}

Обработка ошибок с получением деталей

#![allow(unused)]
fn main() {
let invalid_bytes = vec![0xF0, 0x90, 0x80, 0x41]; // неполная UTF-8 последовательность

match String::from_utf8(invalid_bytes) {
    Ok(string) => println!("Успешно: {}", string),
    Err(e) => {
        println!("Ошибка преобразования:");
        println!("Байты: {:?}", e.as_bytes());
        println!("Позиция ошибки: {}", e.utf8_error().valid_up_to());
        println!("Возвращенные байты: {:?}", e.into_bytes());
    }
}
}

Восстановление с потерями

#![allow(unused)]
#![feature(string_from_utf8_lossy_owned)]
fn main() {
let corrupted = vec![b'H', b'e', b'l', b'l', b'o', 0xFF, b'W', b'o', b'r', b'l', b'd'];

let result = String::from_utf8(corrupted)
    .unwrap_or_else(|e| e.into_utf8_lossy());

assert_eq!("Hello�World", result);
}

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

`Clone`

#![allow(unused)]
fn main() {
impl Clone for FromUtf8Error
}

Позволяет клонирование FromUtf8Error.

`Debug` и `Display`

#![allow(unused)]
fn main() {
impl Debug for FromUtf8Error
impl Display for FromUtf8Error
}

Позволяют форматирование для отладки и пользовательского отображения.

`Error`

#![allow(unused)]
fn main() {
impl Error for FromUtf8Error
}

Реализует трейт ошибки, позволяя использование в системах обработки ошибок.

`PartialEq` и `Eq`

#![allow(unused)]
fn main() {
impl PartialEq for FromUtf8Error
impl Eq for FromUtf8Error
}

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

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

Freeze for FromUtf8Error - может быть заморожен
RefUnwindSafe for FromUtf8Error - безопасен для паники
Send for FromUtf8Error - может быть передан между потоками
Sync for FromUtf8Error - может быть разделен между потоками
Unpin for FromUtf8Error - может быть безопасно перемещено
UnwindSafe for FromUtf8Error - безопасен для паники

Особенности проектирования

Эффективность памяти: избегает лишних аллокаций
Информативность: предоставляет детальную информацию об ошибке
Совместимость: интегрируется с системой ошибок Rust
Гибкость: позволяет различные стратегии обработки ошибок

Использование в реальных сценариях

#![allow(unused)]
fn main() {
fn load_string_from_file(path: &str) -> Result<String, FromUtf8Error> {
    let bytes = std::fs::read(path).map_err(|_| {
        // В реальном коде здесь должна быть proper обработка ошибок
        FromUtf8Error { /* ... */ }
    })?;
    
    String::from_utf8(bytes)
}

// Использование
match load_string_from_file("data.txt") {
    Ok(content) => println!("Содержимое: {}", content),
    Err(e) => {
        eprintln!("Ошибка загрузки файла: {}", e);
        eprintln!("Невалидные байты: {:?}", e.as_bytes());
    }
}
}

Библиотека RUST