# Crate os_str_bytes

source · [−]
Expand description

This crate allows interacting with the data stored 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 `RawOsString::into_os_string` 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.

Since this encoding can change between versions and platforms, it should not be used for storage. The standard library provides implementations of `OsStrExt` and `OsStringExt` for various platforms, which should be preferred for that use case.

## 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.

#### Default Features

- memchr - Changes the implementation to use crate memchr for better performance. This feature is useless when “raw_os_str” is disabled.

  For more information, see `RawOsStr`.

- raw_os_str - Provides:

  - `iter`
  - `Pattern`
  - `RawOsStr`
  - `RawOsStrCow`
  - `RawOsString`

#### Optional Features

- checked_conversions - Provides:

  - `EncodingError`
  - `OsStrBytes::from_raw_bytes`
  - `OsStringBytes::from_raw_vec`
  - [`RawOsStr::from_raw_bytes`]
  - [`RawOsString::from_raw_vec`]

  Because this feature should not be used in libraries, the “OS_STR_BYTES_CHECKED_CONVERSIONS” environment variable must be defined during compilation.

- print_bytes - Provides implementations of [`print_bytes::ToBytes`] for `RawOsStr` and `RawOsString`.

- uniquote - Provides implementations of [`uniquote::Quote`] for `RawOsStr` and `RawOsString`.

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

Conversion method complexities 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, `RawOsString::into_os_string` might be able to reuse its allocation.

## Examples

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

    use os_str_bytes::RawOsStr;

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

## Modules

iter

Iterators provided by this crate.

## Structs

EncodingError Deprecated

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

RawOsStr

A container for borrowed byte strings converted by this crate.

RawOsString

A container for owned byte strings converted by this crate.

## Traits

OsStrBytes

A platform agnostic variant of `OsStrExt`.

OsStringBytes

A platform agnostic variant of `OsStringExt`.

Pattern

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

RawOsStrCow

Extensions to `Cow<RawOsStr>` for additional conversions.