Crate os_str_bytes

Traits for converting between byte sequences and platform-native strings.

This crate allows interacting with the bytes stored internally by OsStr and OsString, without resorting to panics or data corruption for invalid UTF-8. Thus, methods can be used that are already defined on [u8] and Vec<u8>.

Typically, the only way to losslessly construct OsStr or OsString from a byte sequence is to use OsString::from(String::from(bytes)?), which requires the bytes to be valid in UTF-8. However, since this crate makes conversions directly between the platform encoding and raw bytes, even some strings invalid in UTF-8 can be converted.

Implementation

All traits are sealed, meaning that they can only be implemented by this crate. Otherwise, backwards compatibility would be more difficult to maintain for new features.

Complexity

The time complexities of methods will vary based on what functionality is available for the platform. The most efficient implementation will be used, but it is important to use the most applicable method. For example, OsStringBytes::from_vec will be at least as efficient as OsStringBytes::from_bytes, but the latter should be used when only a slice is available.

Safety

Some unsafe assumptions are made, with the most egregious being that str::from_utf8_unchecked returns a partially usable string for invalid UTF-8. The alternative would be to encode and decode strings manually, which would be more dangerous, as it would create a reliance on how the standard library encodes invalid UTF-8 strings.

To make this implementation less problematic, it is best to not make any assumptions about the representation of invalid UTF-8 bytes. However, given the purpose of this crate, every measure will be taken to ensure that it matches the raw byte sequence, meaning this is usually not a concern. Tests exist to validate that the conversions are sound.

Examples

use std::env::temp_dir;
use std::ffi::OsStr;
use std::fs::read_to_string;
use std::fs::write;

use os_str_bytes::OsStrBytes;

let string = "hello world";
let file_name = b"\xC3\xA9os_str\xED\xA0\xBDbytes\xF0\x9F\x92\xA9.txt";

let mut file = temp_dir();
// In this example, conversion always succeeds, so `unwrap()` can be used.
file.push(OsStr::from_bytes(file_name).unwrap());

write(&file, string)?;
assert_eq!(string, read_to_string(file)?);

Structs

EncodingError

The error that occurs when a byte sequence is not representable in the platform encoding.

Traits

OsStrBytes	A platform agnostic variant of OsStrExt.
OsStringBytes	A platform agnostic variant of OsStringExt.