arena_lib/
lib.rs

1//! # arena-lib
2//!
3//! TYPED MEMORY ARENAS AND SLAB ALLOCATION
4//!
5//! `arena-lib` collects four allocator primitives behind a single, safe Rust
6//! surface: a generational [`Arena`], a string [`Interner`], a [`Bump`]
7//! arena, and the supporting [`Index`] / [`Symbol`] / [`Error`] types. Every
8//! public path is safe Rust; `unsafe` is internal-only, measured, and
9//! documented at the call site.
10//!
11//! # Quick tour
12//!
13//! ```
14//! use arena_lib::{Arena, Bump, Interner};
15//!
16//! // Generational arena — stable handles, use-after-free detection.
17//! let mut arena = Arena::new();
18//! let alice = arena.insert("alice");
19//! let bob = arena.insert("bob");
20//! assert_eq!(arena.get(alice), Some(&"alice"));
21//! let _ = arena.remove(alice);
22//! assert_eq!(arena.get(alice), None); // stale handle, safely rejected
23//!
24//! // Interner — O(1) equality on repeated identifiers.
25//! let mut interner = Interner::new();
26//! let id_a = interner.intern("user:42");
27//! let id_b = interner.intern("user:42");
28//! assert_eq!(id_a, id_b);
29//!
30//! // Bump arena — fast scratch, reset in O(1).
31//! let mut bump = Bump::with_capacity(64);
32//! let n = bump.alloc(7_u32);
33//! assert_eq!(*n, 7);
34//! bump.reset();
35//!
36//! let _ = bob;
37//! ```
38//!
39//! # Modules
40//!
41//! - [`arena`] — generational arena and [`Index`] handle.
42//! - [`intern`] — string interner and [`Symbol`] handle.
43//! - [`bump`] — bump arena for short-lived scratch.
44//! - [`error`] — single public [`Error`] type and [`Result`] alias.
45//! - [`prelude`] — convenience re-exports for downstream crates.
46//!
47//! # `no_std`
48//!
49//! Disable default features (`std`) to compile under `#![no_std]`. The crate
50//! still requires `alloc` — it is pulled in automatically.
51//!
52//! # License
53//!
54//! Dual-licensed under Apache-2.0 OR MIT.
55
56#![doc(html_root_url = "https://docs.rs/arena-lib")]
57#![cfg_attr(docsrs, feature(doc_cfg))]
58#![cfg_attr(not(feature = "std"), no_std)]
59#![deny(missing_docs)]
60#![deny(unsafe_op_in_unsafe_fn)]
61#![deny(unused_must_use)]
62#![deny(unused_results)]
63#![deny(clippy::unwrap_used)]
64#![deny(clippy::expect_used)]
65#![deny(clippy::todo)]
66#![deny(clippy::unimplemented)]
67#![deny(clippy::print_stdout)]
68#![deny(clippy::print_stderr)]
69#![deny(clippy::dbg_macro)]
70#![deny(clippy::undocumented_unsafe_blocks)]
71#![deny(clippy::missing_safety_doc)]
72
73extern crate alloc;
74
75pub mod arena;
76pub mod bump;
77pub mod error;
78pub mod intern;
79pub mod prelude;
80
81pub use crate::arena::{Arena, Index};
82pub use crate::bump::Bump;
83pub use crate::error::{Error, Result};
84pub use crate::intern::{Interner, Symbol};
85
86/// Crate version string, populated by Cargo at build time.
87///
88/// Matches the `version` field in `Cargo.toml` exactly. Useful for diagnostics,
89/// telemetry, and `--version` output in tools that embed `arena-lib`.
90///
91/// # Examples
92///
93/// ```
94/// use arena_lib::VERSION;
95///
96/// assert!(!VERSION.is_empty());
97/// assert!(VERSION.chars().next().is_some_and(|c| c.is_ascii_digit()));
98/// ```
99pub const VERSION: &str = env!("CARGO_PKG_VERSION");
arena_lib/lib.rs

arena_lib/
lib.rs
