Skip to content

Commit 8fe3741

Browse files
dpaoliellodpaoliello
authored
Cleanup readme, add comparison table (#7)
1 parent f988b14 commit 8fe3741

File tree

2 files changed

+68
-16
lines changed

2 files changed

+68
-16
lines changed

‎README.md‎

Lines changed: 63 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,38 +2,89 @@
22

33
Fallible allocation functions for the Rust standard library's [`alloc::vec::Vec`](https://doc.rust-lang.org/std/vec/struct.Vec.html) type.
44

5-
These functions are designed to be usable with `#![no_std]` and `#[cfg(no_global_oom_handling)]`(see <https://github.com/rust-lang/rust/pull/84266>) enabled.
5+
These functions are designed to be usable with `#![no_std]`, `#[cfg(no_global_oom_handling)]` (see
6+
<https://github.com/rust-lang/rust/pull/84266>) enabled and Allocators (see <https://github.com/rust-lang/wg-allocators>).
67

78
## Usage
89

9-
The recommended way to add these functions to `Vec` is by adding a `use` declaration for the entire module: `use fallible_vec::*`:
10+
The recommended way to add these functions to `Vec` is by adding a `use` declaration for the
11+
`FallibleVec` trait: `use fallible_vec::FallibleVec`:
1012
```rust
11-
use fallible_vec::*;
13+
use fallible_vec::{FallibleVec, try_vec};
14+
1215
let mut vec = try_vec![1, 2]?;
1316
vec.try_push(3)?;
1417
assert_eq!(vec, [1, 2, 3]);
1518
```
1619

1720
## Panic Safety
1821

19-
These methods are "panic safe", meaning that if a call to external code (e.g., an iterator's `next()` method or an implementation of `Clone::clone()`) panics, then these methods will leave the `Vec` in a consistent state:
22+
These methods are "panic safe", meaning that if a call to external code (e.g., an iterator's
23+
`next()` method or an implementation of `Clone::clone()`) panics, then these methods will leave the
24+
`Vec` in a consistent state:
2025
* `len()` will be less than or equal to `capacity()`.
21-
* Items in `0..len()` will only be items originally in the `Vec` or items being added to the `Vec`. It will never include uninitialized memory, duplicated items or dropped items.
22-
* Items originally (but no longer) in the `Vec` or being added to (but not yet in) the `Vec` may be leaked - any method that may leak items like this will have a note to specify its behavior.
26+
* Items in `0..len()` will only be items originally in the `Vec` or items being added to the `Vec`.
27+
It will never include uninitialized memory, duplicated items or dropped items.
28+
* Items originally (but no longer) in the `Vec` or being added to (but not yet in) the `Vec` may be
29+
leaked - any method that may leak items like this will have a note to specify its behavior.
2330

2431
The exact behavior of each method is specified in its documentation.
2532

2633
## Code origin
2734

28-
Most of this code is forked from [Rust's Standard Library](https://github.com/rust-lang/rust). While we will attempt to keep the code and docs in sync, if you notice any issues please check if they have been fixed in the Standard Library first.
35+
Most of this code is forked from [Rust's Standard Library](https://github.com/rust-lang/rust). While
36+
we will attempt to keep the code and docs in sync, if you notice any issues please check if they
37+
have been fixed in the Standard Library first.
2938

3039
## This API is incomplete
3140

32-
There are many more infallible functions on `Vec` which have not been ported yet. If there's a particular API that you're missing feel free to open a PR or file an Issue to get it added.
33-
34-
## Why are these not already in the Standard Library
35-
36-
There is a [PR to add these and more](https://github.com/rust-lang/rust/pull/95051) to the Standard Library, followed by an [RFC to discuss if it's a good idea or not to do so](https://github.com/rust-lang/rfcs/pull/3271).
41+
There are many more infallible functions on `Vec` which have not been ported yet. If there's a
42+
particular API that you're missing feel free to open a PR or file an Issue to get it added.
43+
44+
## Why are these not already in the Standard Library?
45+
46+
There is a [PR to add these and more](https://github.com/rust-lang/rust/pull/95051) to the Standard
47+
Library, followed by an [RFC to discuss if it's a good idea or not to do so](https://github.com/rust-lang/rfcs/pull/3271).
48+
49+
## Why would I use this crate versus similar crates?
50+
51+
In general, `fallible_vec` is only useful in situations where `#[cfg(no_global_oom_handling)]` is
52+
required, or if using the Allocator API (functions ending in `_in`). Other crates use APIs that
53+
don't exist when `#[cfg(no_global_oom_handling)]` is enabled (like `vec::push`), whereas
54+
`fallible_vec` reimplements each function to avoid these APIs and builds with `#[cfg(no_global_oom_handling)]`
55+
in its CI.
56+
57+
`fallible_vec` focuses on `vec` alone, whereas other crates provide support for additional types
58+
(like `Box` and `HashMap`).
59+
60+
Comparing `fallible_vec` to [`fallible_collections`](https://crates.io/crates/fallible_collections):
61+
62+
| | `fallible_vec` v0.1.0 | `fallible_collections` v0.4.7 |
63+
|-------------------------------------------|:---------------------:|:-----------------------------:|
64+
| Supports `no_std` | X | X |
65+
| Supports `#[cfg(no_global_oom_handling)]` | X | |
66+
| Requires nightly | X | |
67+
| `vec::try_append` | | X |
68+
| `vec::try_extend` | X | |
69+
| `vec::try_extend_from_slice` | X | X |
70+
| `vec::try_insert` | X | X |
71+
| `vec::try_push` | X | X |
72+
| `vec::try_push_give_back` | | X |
73+
| `vec::try_resize` | X | X |
74+
| `vec::try_resize_with` | X | X |
75+
| `vec::try_splice_in` | X | |
76+
| `try_collect` | X | X |
77+
| `try_collect_in` | X | |
78+
| `try_from_iterator` | | X |
79+
| `try_with_capacity` | X | |
80+
| `try_with_capacity_in` | X | |
81+
| `try_vec!` | X | |
82+
| `try_vec_in!` | X | |
83+
| `Box::*` | | X |
84+
| `Arc::*` | | X |
85+
| `Rc::*` | | X |
86+
| `HashMap::*` | | X |
87+
| `try_format!` | | X |
3788

3889
## Contributing
3990

‎src/lib.rs‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,19 @@
11
//! Fallible allocation functions for the Rust standard library's [`alloc::vec::Vec`]
22
//! type.
33
//!
4-
//! These functions are designed to be usable with `#![no_std]` and
4+
//! These functions are designed to be usable with `#![no_std]`,
55
//! `#[cfg(no_global_oom_handling)]`(see <https://github.com/rust-lang/rust/pull/84266>)
6-
//! enabled.
6+
//! enabled and Allocators (see <https://github.com/rust-lang/wg-allocators>).
77
//!
88
//! # Usage
99
//!
1010
//! The recommended way to add these functions to `Vec` is by adding a `use`
11-
//! declaration for the entire module: `use fallible_vec::*`:
11+
//! declaration for the `FallibleVec` trait: `use fallible_vec::FallibleVec`:
1212
//! ```
1313
//! # #![feature(allocator_api)]
1414
//! # #[macro_use] extern crate fallible_vec;
15-
//! use fallible_vec::*;
15+
//! use fallible_vec::{FallibleVec, try_vec};
16+
//!
1617
//! let mut vec = try_vec![1, 2]?;
1718
//! vec.try_push(3)?;
1819
//! assert_eq!(vec, [1, 2, 3]);

0 commit comments

Comments
 (0)