| 1 |
# core2 |
| 2 |
|
| 3 |
[](https://github.com/bbqsrc/core2/actions) |
| 4 |
[](https://docs.rs/core2) |
| 5 |
 |
| 6 |
|
| 7 |
Ever wanted a `Cursor` or the `Error` trait in `no_std`? Well now you can have it. A 'fork' of Rust's `std` modules for `no_std` environments, with the added benefit of optionally taking advantage of `alloc`. |
| 8 |
|
| 9 |
The goal of this crate is to provide a stable interface for building I/O and error trait functionality in |
| 10 |
`no_std` environments. The current code corresponds to the most recent stable API of Rust 1.47.0. |
| 11 |
It is also a goal to achieve a true alloc-less experience, with opt-in alloc support. |
| 12 |
|
| 13 |
This crate works on `stable` with some limitations in functionality, and `nightly` without limitations by adding |
| 14 |
the relevant feature flag. |
| 15 |
|
| 16 |
This crate is `std` by default -- use no default features to get `no_std` mode. |
| 17 |
|
| 18 |
## Usage |
| 19 |
|
| 20 |
```toml |
| 21 |
[dependencies] |
| 22 |
core2 = "0.3" |
| 23 |
``` |
| 24 |
|
| 25 |
Add the crate, use the things you would usually want from `std::io`, but instead from `core2::io`, and |
| 26 |
use `core2::error::Error` in place of `std::error::Error`. |
| 27 |
|
| 28 |
### Features |
| 29 |
|
| 30 |
- **std**: enables `std` pass-throughs for the polyfilled types, but allows accessing the new types |
| 31 |
- **alloc**: enable aspects of the `Read` and `Write` traits that require `alloc` support (WIP) |
| 32 |
- **nightly**: enables **nightly**-only features, such as `BufReader` and `BufWriter` with const generic buffers. |
| 33 |
|
| 34 |
### Differences to `std::io` |
| 35 |
|
| 36 |
- No `std::io::Error`, so we have our own copy without any `Os` error functions |
| 37 |
- `IoSlice` and the `*_vectored` family of functions are not implemented. |
| 38 |
- `BufReader` and `BufWriter` have a different signature, as they now use a const generic bounded array for the internal buffer. (Requires **nightly** feature) |
| 39 |
|
| 40 |
Other than items perhaps being entirely missing or certain functions unavailable on some traits, no function signatures have been changed. |
| 41 |
|
| 42 |
### Limitations |
| 43 |
|
| 44 |
- Using the buffer types currently requires **nightly** due to the use of const generics. |
| 45 |
- Using `copy` or the buffer types with `std` support currently requires **nightly** due to the `initializer` API. |
| 46 |
|
| 47 |
## Where is it used? |
| 48 |
|
| 49 |
All of the below are works in progress, but should help with demonstrating how to use this crate. |
| 50 |
|
| 51 |
- [thiserror_core2](https://github.com/bbqsrc/thiserror-core2): fork of `thiserror` using the `core2::error::Error` trait. |
| 52 |
|
| 53 |
## License |
| 54 |
|
| 55 |
Licensed under either of |
| 56 |
|
| 57 |
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) |
| 58 |
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) |
| 59 |
|
| 60 |
at your option. |
| 61 |
|
| 62 |
--- |
| 63 |
|
| 64 |
Almost all of the code in this repository is a copy of the [Rust language codebase](https://github.com/rust-lang/rust) with minor modifications. |
| 65 |
|
| 66 |
For attributions, see https://thanks.rust-lang.org/. |