#collection #fallible #allocation #oom #hash-map #try-reserve

no-std fallible_collections

a crate which adds fallible allocation api to std collections

19 releases

0.5.1 Nov 7, 2024
0.4.9 Jul 2, 2023
0.4.7 Mar 4, 2023
0.4.6 Nov 14, 2022
0.1.0 Oct 28, 2019

#97 in Rust patterns

Download history 17330/week @ 2024-08-08 15772/week @ 2024-08-15 22158/week @ 2024-08-22 15990/week @ 2024-08-29 17860/week @ 2024-09-05 14520/week @ 2024-09-12 16503/week @ 2024-09-19 25418/week @ 2024-09-26 12875/week @ 2024-10-03 17910/week @ 2024-10-10 18940/week @ 2024-10-17 14117/week @ 2024-10-24 15542/week @ 2024-10-31 12476/week @ 2024-11-07 52818/week @ 2024-11-14 14751/week @ 2024-11-21

98,963 downloads per month
Used in 50 crates (13 directly)

MIT/Apache

230KB
4.5K SLoC

Fallible Collections.rs

Implements APIs on Rust collections wich gracefully return a Result when an allocation error occurs. This is inspired a lot by RFC 2116.

There are APIs for a fallible interface for Vec, Box, BTree, HashMap, and a TryClone trait wich is implemented for primitive Rust traits and a fallible format macro. You can use this with try_clone_derive crate wich derive TryClone for your own types.

Getting Started

fallible_collections is available on crates.io. It is recommended to look there for the newest released version, as well as links to the newest builds of the docs.

Add the following dependency to your Cargo manifest:

[dependencies]
fallible_collections = "0.5"

# or
fallible_collections = { version = "0.5", features = ["std"] }

...and see the docs for how to use it.

Example

Exemple of using the FallibleBox interface.

use fallible_collections::FallibleBox;

fn main() {
	// this crate an Ordinary box but return an error on allocation failure
	let mut a = <Box<_> as FallibleBox<_>>::try_new(5).unwrap();
	let mut b = Box::new(5);

	assert_eq!(a, b);
	*a = 3;
	assert_eq!(*a, 3);
}

Exemple of using the FallibleVec interface.

use fallible_collections::FallibleVec;

fn main() {
	// this crate an Ordinary Vec<Vec<u8>> but return an error on allocation failure
	let a: Vec<Vec<u8>> = try_vec![try_vec![42; 10].unwrap(); 100].unwrap();
	let b: Vec<Vec<u8>> = vec![vec![42; 10]; 100];
	assert_eq!(a, b);
	assert_eq!(a.try_clone().unwrap(), a);
	...
}

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~0–450KB