Function cesu8::from_cesu8

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

Converts a slice of bytes to a string slice.

First, if the slice of bytes is already valid UTF-8, this function is functionally no different than std::str::from_utf8; this means that from_cesu8() does not need to perform any further operations and doesn’t need to allocate additional memory.

If the slice of bytes is not valid UTF-8, from_cesu8() works on the assumption that the slice of bytes, if not valid UTF-8, is valid CESU-8. It will then decode the bytes given to it and return the newly constructed string slice.

Panics

Panics if the slice of bytes is found not to be valid CESU-8 data.

Examples

Basic usage:

use std::borrow::Cow;
use cesu8::from_cesu8;

let str = "Hello, world!";
// Since 'str' is valid UTF-8 and CESU-8 data, 'from_cesu8' can decode
// the string slice without allocating memory.
assert_eq!(from_cesu8(str.as_bytes()), Cow::Borrowed(str));

let str = "\u{10400}";
let cesu8_data = &[0xED, 0xA0, 0x81, 0xED, 0xB0, 0x80];
// 'cesu8_data' is a byte slice containing a 6-byte surrogate pair which
// becomes a 4-byte UTF-8 character.
assert_eq!(from_cesu8(cesu8_data), Cow::Borrowed(str));