stable-osstring-encoding 1.1.1

A stable way to convert OsString and OsStr to and from raw data.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# Rust Stable OsString Encoding

This was made for one very specific reason: the encoding of `OsStr::as_encoded_bytes()`'s output might change based on the Rust compiler version the code is built with (according to [this](https://doc.rust-lang.org/std/ffi/struct.OsStr.html#safety) comment). If you want the the guarantee that the encoded data's encoding will never change depending on the compiler version you're using, this crate provides methods which convert `OsStr` and `OsString` to and from a `Vec<u8>` or `Vec<u16>` (depending on the platform). This is made possible by the platform-specific `OsStrExt` and `OsStringExt` traits, which give and take data that does have an encoding which the standard library promises will not change.

### Important caveats:

- This is not meant for sending data from one platform to another (e.g. from a windows program to a linux program).
- This currently only supports Windows and Unix (Linux and MacOs), but other platforms should be easy to implement if needed.

## Example:

```rust
use std::ffi::OsString;
use stable_osstring_encoding::*;

let my_string = OsString::from("My String");
let stable_string: Vec<_> = my_string.into_stable_encoding();
// send stable_string to another program

// in another program:
let my_string = unsafe { OsString::from_stable_encoding(stable_string) };
```

### Provided methods:

```rust,ignore
// note: `StableOsString` is just an alias for `Vec<u8>` or `Vec<u16>` (depending on the platform)
OsStr::to_stable_encoding(&self) -> StableOsString
OsString::to_stable_encoding(&self) -> StableOsString
// into_stable_encoding() avoids memory copies whenever possible
OsString::into_stable_encoding(self) -> StableOsString
Cow<OsStr>::into_stable_encoding(self) -> StableOsString
OsString::from_stable_encoding(encoded: Into<Cow<[EncodingWidth]>>) -> OsString
```