README.md
1# OsStr Bytes
2
3This crate allows interacting with the data stored by [`OsStr`] and
4[`OsString`], without resorting to panics or corruption for invalid UTF-8.
5Thus, methods can be used that are already defined on [`[u8]`][slice] and
6[`Vec<u8>`].
7
8Typically, the only way to losslessly construct [`OsStr`] or [`OsString`] from
9a byte sequence is to use `OsStr::new(str::from_utf8(bytes)?)`, which requires
10the bytes to be valid in UTF-8. However, since this crate makes conversions
11directly between the platform encoding and raw bytes, even some strings invalid
12in UTF-8 can be converted.
13
14[](https://github.com/dylni/os_str_bytes/actions?query=branch%3Amaster)
15
16## Usage
17
18Add the following lines to your "Cargo.toml" file:
19
20```toml
21[dependencies]
22os_str_bytes = "6.4"
23```
24
25See the [documentation] for available functionality and examples.
26
27## Rust version support
28
29The minimum supported Rust toolchain version depends on the platform:
30
31<table>
32 <tr>
33 <th>Target</th>
34 <th>Target Triple</th>
35 <th>Minimum Version</th>
36 </tr>
37 <tr>
38 <td>Fortanix</td>
39 <td><code>*-fortanix-*-sgx</code></td>
40 <td>nightly (<a href="https://doc.rust-lang.org/unstable-book/library-features/sgx-platform.html"><code>sgx_platform</code></a>)</td>
41 </tr>
42 <tr>
43 <td>HermitCore</td>
44 <td><code>*-*-hermit</code></td>
45 <td>1.57.0</td>
46 </tr>
47 <tr>
48 <td>SOLID</td>
49 <td><code>*-*-solid_asp3(-*)</code></td>
50 <td>1.57.0</td>
51 </tr>
52 <tr>
53 <td>Unix</td>
54 <td>Unix</td>
55 <td>1.57.0</td>
56 </tr>
57 <tr>
58 <td>WASI</td>
59 <td><code>*-wasi</code></td>
60 <td>1.57.0</td>
61 </tr>
62 <tr>
63 <td>WebAssembly</td>
64 <td><code>wasm32-*-unknown</code></td>
65 <td>1.57.0</td>
66 </tr>
67 <tr>
68 <td>Windows</td>
69 <td><code>*-*-windows-*</code></td>
70 <td>1.57.0</td>
71 </tr>
72 <tr>
73 <td>Xous</td>
74 <td><code>*-*-xous-*</code></td>
75 <td>unstable</td>
76 </tr>
77</table>
78
79Minor version updates may increase these version requirements. However, the
80previous two Rust releases will always be supported. If the minimum Rust
81version must not be increased, use a tilde requirement to prevent updating this
82crate's minor version:
83
84```toml
85[dependencies]
86os_str_bytes = "~6.4"
87```
88
89## License
90
91Licensing terms are specified in [COPYRIGHT].
92
93Unless you explicitly state otherwise, any contribution submitted for inclusion
94in this crate, as defined in [LICENSE-APACHE], shall be licensed according to
95[COPYRIGHT], without any additional terms or conditions.
96
97[COPYRIGHT]: https://github.com/dylni/os_str_bytes/blob/master/COPYRIGHT
98[documentation]: https://docs.rs/os_str_bytes
99[LICENSE-APACHE]: https://github.com/dylni/os_str_bytes/blob/master/LICENSE-APACHE
100[slice]: https://doc.rust-lang.org/std/primitive.slice.html
101[`OsStr`]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html
102[`OsString`]: https://doc.rust-lang.org/std/ffi/struct.OsString.html
103[`Vec<u8>`]: https://doc.rust-lang.org/std/vec/struct.Vec.html
104
){kind=link}