Crate os_str_bytes[][src]

Expand description

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.

In most cases, RawOsStr and RawOsString should be used. OsStrBytes and OsStringBytes provide lower-level APIs that are easier to misuse.

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_raw_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

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 trait methods will vary based on what functionality is available for the platform. At worst, they will all be linear, but some can take constant time. For example, OsStringBytes::from_raw_vec might be able to reuse the allocation for its argument.

Examples

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

use os_str_bytes::OsStrBytes;

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

Modules

iterraw_os_str

Iterators provided by this crate.

Structs

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

RawOsStrraw_os_str

A container for the byte strings converted by OsStrBytes.

RawOsStringraw_os_str

A container for the byte strings converted by OsStringBytes.

Traits

A platform agnostic variant of OsStrExt.

A platform agnostic variant of OsStringExt.

Patternraw_os_str

Allows a type to be used for searching by RawOsStr and RawOsString.