Function mutf8::from_mutf8

pub fn from_mutf8(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 decode() 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, decode() works on the assumption that the slice of bytes, if not valid UTF-8, is valid MUTF-8. It will then decode the bytes given to it and return the newly constructed string slice.

If the slice of bytes is found not to be valid MUTF-8 data, decode() returns Err(DecodingError) to signify that an error has occured.

Panics

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

Examples

use std::borrow::Cow;
use mutf8::from_mutf8;

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

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

let str = "\0";
let mutf8_data = &[0xC0, 0x80];
// 'mutf8_data' is a byte slice containing MUTF-8 data containing a null
// code point which becomes a null character.
assert_eq!(from_mutf8(mutf8_data), Cow::Borrowed(str));