//! Sound unchecked indexing using the techniques from generative lifetimes,
//! extended to string slices and without pointer or mutability support.
//!
//! Major kudos go to Gankro and especially Bluss for the original [indexing]
//! crate, from which this crate blatantly steals all of its cleverness.
//!
//! # Basic Structure
//!
//! - A scope is created using the [`scope`] function; inside this scope,
//! there is a [`Container`] object that has two roles: (1) it gives out or
//! vets trusted indices, pointers and ranges (2) it provides access to the
//! underlying data through these indices and ranges.
//!
//! - The container and its indices and ranges are “branded” with a lifetime
//! parameter `'id` which is an identity marker. Branded items
//! can't leave their scope, and they tie the items uniquely to a particular
//! container. This makes it possible to trust them.
//!
//! - `Index<'id>` is a trusted index
//! - `Range<'id, Emptiness>` is a trusted range.
//!
//! - For a range, if the proof parameter `Emptiness` is `NonEmpty`, then the
//! range is known to have at least one element. An observation: A non-empty
//! range always has a valid front index, so it is interchangeable with the
//! index representation.
//!
//! - Indices also use the same proof parameter. A `NonEmpty` index points to a
//! valid element, while an `Unknown` index is an edge index (it can be used
//! to slice the container, but not to dereference to an element).
//!
//! - All ranges have a `.first()` method to get the first index in the range,
//! but it's only when the range is nonempty that the returned index is also
//! `NonEmpty` and thus dereferenceable.
//!
//! # Borrowing
//!
//! - Indices and ranges are freely copyable and do not track the backing data
//! themselves. All access to the underlying data goes through the
//! [`Container`] (e.g. by indexing the container with a trusted index).
//!
//! [indexing]: <https://github.com/bluss/indexing>
extern crate std;
use crate TrustedContainer;
pub use crate::;
/// Create an indexing scope for a container.
///
/// The indexing scope is a closure that is passed a unique lifetime for the
/// parameter `'id`; this lifetime brands the container and its indices and
/// ranges, so that they are trusted to be in bounds.
///
/// Indices and ranges branded with `'id` cannot leave the closure. The
/// container can only be accessed through the `Container` wrapper passed as
/// the first argument to the indexing scope.
/// [`scope`], but for a backing container behind a reference
/// (such as an unsized string slice).