try_reserve

A stable implementation of TryReserveError that exposes TryReserveErrorKind.

Overview

This crate provides a stable implementation of the TryReserveError and TryReserveErrorKind types, which are currently not fully exposed in the Rust standard library.
This is a workaround for rust-lang/rust#48043, an RFC that has been pending for stabilization for 7 years.

Purpose

The sole purpose of this crate is to expose the normally private TryReserveErrorKind enum.
This allows for easier and unified creation of custom collections that need to return appropriate allocation error types.

Features

no_std support by default
Full compatibility with std's TryReserveError when available using tansmutation
Complete integration with already existing types inside the std that use try_reserve() if the std flag is turned on

Usage

Add this to your Cargo.toml:

[dependencies]
try_reserve = "0.2" # No std

Or with the std integrations:

[dependencies]
try_reserve = { version = "0.2", features = ["std"] }

Basic usage

use try_reserve::{TryReserve, error::{TryReserveError, TryReserveErrorKind}};

// Implement the TryReserve trait for your custom collection
struct MyCollection<T> {
    data: Vec<T>,
}

impl<T> TryReserve for MyCollection<T> {
fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> {
    // Attempt to reserve space
    self.data.try_reserve(additional)
    .map_err(TryReserveError::from)
    }
}

// Or create your own error with specific kinds
fn example() -> Result<(), TryReserveError> {
    // Create a capacity overflow error
    let overflow_error = TryReserveErrorKind::CapacityOverflow;
    Err(overflow_error.into())
}

With `std`

To use this crate in a std environment, enable the no_std feature:

[dependencies]
try_reserve = { version = "0.2", features = ["std"] }

Error Types

`TryReserveError`

This is the main error type returned by try_reserve methods. It wraps a TryReserveErrorKind and provides a clean API.

`TryReserveErrorKind`

An enum with the following variants:

CapacityOverflow: Error due to the computed capacity exceeding the collection's maximum (usually isize::MAX bytes).
AllocError { layout }: Error returned when the memory allocator fails. Contains the layout of the allocation request that failed.

Conversions

When in a std environment, the crate provides conversions between its error types and the standard library's error types:

use try_reserve::error::TryReserveError;

// Convert from std to this crate's error type
let std_error = Vec::<i32>::with_capacity(100)
    .try_reserve(usize::MAX)
    .unwrap_err();
let our_error = TryReserveError::from(std_error);
// or
// let our_error: TryReserveError = std_error.into();

// And back again
let std_error_again = std::collections::TryReserveError::from(our_error);

Why this crate exists

The Rust standard library has had a pending RFC for the stabilization of the TryReserveErrorKind enum for 7 years (see rust-lang/rust#48043).
Without access to this enum, it's difficult to create custom collections that properly handle and report allocation errors.

This crate provides a stable workaround until the standard library stabilizes this API.

License

Licensed under

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.

try_reserve 0.2.1