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`] — multi-chunk bump arena for short-lived scratch (no drop).
44//! - [`drop_arena`] — typed bump-style arena that runs destructors.
45//! - [`error`] — single public [`Error`] type and [`Result`] alias.
46//! - [`prelude`] — convenience re-exports for downstream crates.
47//!
48//! # `no_std`
49//!
50//! Disable default features (`std`) to compile under `#![no_std]`. The crate
51//! still requires `alloc` — it is pulled in automatically.
52//!
53//! # License
54//!
55//! Dual-licensed under Apache-2.0 OR MIT.
56
57#![doc(html_root_url = "https://docs.rs/arena-lib")]
58#![cfg_attr(docsrs, feature(doc_cfg))]
59#![cfg_attr(not(feature = "std"), no_std)]
60#![deny(missing_docs)]
61#![deny(unsafe_op_in_unsafe_fn)]
62#![deny(unused_must_use)]
63#![deny(unused_results)]
64#![deny(clippy::unwrap_used)]
65#![deny(clippy::expect_used)]
66#![deny(clippy::todo)]
67#![deny(clippy::unimplemented)]
68#![deny(clippy::print_stdout)]
69#![deny(clippy::print_stderr)]
70#![deny(clippy::dbg_macro)]
71#![deny(clippy::undocumented_unsafe_blocks)]
72#![deny(clippy::missing_safety_doc)]
73
74extern crate alloc;
75
76pub mod arena;
77pub mod bump;
78pub mod drop_arena;
79pub mod error;
80pub mod intern;
81pub mod prelude;
82
83pub use crate::arena::{Arena, Index};
84pub use crate::bump::Bump;
85pub use crate::drop_arena::DropArena;
86pub use crate::error::{Error, Result};
87pub use crate::intern::{Interner, Symbol};
88
89/// Crate version string, populated by Cargo at build time.
90///
91/// Matches the `version` field in `Cargo.toml` exactly. Useful for diagnostics,
92/// telemetry, and `--version` output in tools that embed `arena-lib`.
93///
94/// # Examples
95///
96/// ```
97/// use arena_lib::VERSION;
98///
99/// assert!(!VERSION.is_empty());
100/// assert!(VERSION.chars().next().is_some_and(|c| c.is_ascii_digit()));
101/// ```
102pub const VERSION: &str = env!("CARGO_PKG_VERSION");
arena_lib/lib.rs

arena_lib/
lib.rs
