Crate os_str_bytes

This crate allows interacting with the data stored internally by OsStr and OsString, without resorting to panics or 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 OsStr::new(str::from_utf8(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.

Encoding

The encoding of bytes returned or accepted by methods of this crate is intentionally left unspecified. It may vary for different platforms, so defining it would run contrary to the goal of generic string handling. However, the following invariants will always be upheld:

• The encoding will be compatible with UTF-8. In particular, splitting an encoded byte sequence by a UTF-8–encoded character always produces other valid byte sequences. They can be re-encoded without error using OsStrBytes::from_bytes and similar methods.

• All characters valid in platform strings are representable. OsStr and OsString can always be losslessly reconstructed from extracted bytes.

Note that the chosen encoding may not match how Rust stores these strings internally, which is undocumented. For instance, the result of calling OsStr::len will not necessarily match the number of bytes this crate uses to represent the same string.

Additionally, concatenation may yield unexpected results without a UTF-8 separator. If two platform strings need to be concatenated, the only safe way to do so is using OsString::push. This limitation also makes it undesirable to use the bytes in interchange unless absolutely necessary. If the strings need to be written as output, crate print_bytes can do so more safely than directly writing the bytes.

User Input

Traits in this crate should ideally not be used to convert byte sequences that did not originate from OsStr or a related struct. The encoding used by this crate is an implementation detail, so it does not make sense to expose it to users.

Crate bstr offers some useful alternative methods, such as ByteSlice::to_os_str and ByteVec::into_os_string, that are meant for user input. But, they reject some byte sequences used to represent valid platform strings, which would be undesirable for reliable path handling. They are best used only when accepting unknown input.

This crate is meant to help when you already have an instance of OsStr and need to modify the data in a lossless way.

Features

These features are optional and can be enabled or disabled in a "Cargo.toml" file.

Optional Features

• raw - Enables use of the raw module.

Implementation

Some methods return Cow to account for platform differences. However, no guarantee is made that the same variant of that enum will always be returned for the same platform. Whichever can be constructed most efficiently will be returned.

All traits are sealed, meaning that they can only be implemented by this crate. Otherwise, backward 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.

Examples

use std::env;
use std::fs;

use os_str_bytes::OsStrBytes;

for file in env::args_os().skip(1) {
    if file.to_bytes().first() != Some(&b'-') {
        let string = "Hello, world!";
        fs::write(&file, string)?;
        assert_eq!(string, fs::read_to_string(file)?);
    }
}

Modules

raw	Functions that cannot be implemented outside of this crate.

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.