This crate requires a nightly (unstable, experimental) compiler version. To switch to it, you must have Rust installed via Rustup, and run:

rustup default nightly

Run rustup default stable to switch back.

Adding `alloc_checked` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add alloc-checked

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

alloc-checked = "0.1.3"

The alloc_checked library will be automatically available globally. Read the alloc_checked library documentation.

Back to the crate overview.

Readme

Overview

The alloc-checked crate provides wrapper types for common collections that require an explicit allocator and return a Result instead of panicking on allocation failure.

The wrapper collection types provide two main benefits:

They can't be used incorrectly by virtue of lacking APIs which panic.
Provide additional convenience methods for working with the collection in a checked manner.

Restrictions

The crate requires a recent build of the Rust "nightly" compiler, as it uses the allocator_api feature.

No Std

By default, the crate compiles against the Rust standard library.

The crate is also #![no_std] compatible via the no_std feature. When compiled in no_std mode, it still relies on the alloc, core crates.

Usage

Add the dependency

cargo add alloc-checked # --features no_std

Chances are you might have been using Vec in a few places. Import the type you need

use alloc_checked::vec::Vec;

let vec = Vec::new_in(your_allocator);
vec.push(42)?;  // -> Result<(), TryReserveError>

and fix any resulting compile errors.

Along the way, you probably want to implement the From trait for your error type to make it easier to bubble up allocation errors.

use alloc::AllocError;
use alloc::collections::TryReserveError;

impl From<AllocError> for YourErrorType { /* ... */ }
impl From<TryReserveError> for YourErrorType { /* ... */ }

Current state of the project and design philosophy

We (QuestDB) are adding to this crate on a per-need basis. There's currently decent support for the Vec type, with more types to come. Contributions are quite welcome even if they extend beyond our needs.

The core design philosophy here is that it should never be possible to use this crate in a way that it silently allocates memory. Having a different type that can't be misused also allows for improved API ergonomics.

As a small example, std's Vec has both fn with_capacity_in(alloc: Allocator) -> Vec and fn try_with_capacity_in(alloc: Allocator) -> Result<Vec, TryReserveError> variants.

The Vec implementation in alloc-checked has a single fn with_capacity_in(alloc: Allocator) -> Vec, likewise many common methods that silently panic in the standard library, here return a Result instead with the idea of an easier code migration.

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

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.

Adding alloc_checked library as a dependency

Adding `alloc_checked` library as a dependency