anon_vec/
lib.rs

1
2//! Anonymous Types and Anonymously Typed Vectors for Dynamic Type Emulation in Rust.
3//! 
4//! anon_vec is essentially an easier-to-use replacement for Box<dyn Any>, without 
5//! the safety checks that come along with Box<dyn Any>.  It was created for strata-ecs
6//! with the goal of storing Components in AnonVecs. 
7//! 
8//! ## Memory Safety
9//! 
10//! Usage of Anon, AnonVec, and AnonVec Iterators is inherently unsafe and should be used with
11//! caution.  Attempting to access these types incorrectly can result in data leaks, incorrect
12//! values, and invalid memory access, leading to catastrophic errors. 
13//! 
14//! Although it may sometime in the future, anon_vec does not currently implement
15//! any error checking.  You are expected to make good decisions about managing the unsafety
16//! of these types. 
17//! 
18//! ## Usage
19//! 
20//! Use this Crate if you need Dynamic Typing and are ok with some unsafe code. 
21//! 
22//! anon_vec supports Anonymous single-types called [`Anon`]. These types are
23//! useful for moving data around in your engine, and the inner value can only be accessed
24//! in a scope where the type is known (`T`).
25//! 
26//! ```
27//! use anon_vec::Anon;
28//! use std::mem::size_of;
29//! use std::any::TypeId;
30//! 
31//! // you can create anons from existing values...
32//! let x: i32 = 5;
33//! let mut anon1 = Anon::new::<i32>(x);
34//! 
35//! // the value within can then be accessed.
36//! let y: &i32 = anon1.cast_ref::<i32>();
37//! let z: &i32 = anon1.cast_ref::<i32>();
38//! 
39//! // Anons can also be uninitialized.
40//! let mut anon2 = Anon::uninit();
41//! 
42//! if anon2.is_uninit() {
43//!     anon2.init::<i32>(5); 
44//! } else {
45//!     // do something to the value
46//! }
47//! ```
48//! 
49//! anon_vec supports Anonymous Vectors called [`AnonVec`]. This type is useful when you
50//! want to store a Vec<T>, but you don't know T at compile-time. AnonVec converts T to u8, allowing 
51//! for sequential storage of T with minimal heap allocation. AnonVec can be accessed either with T,
52//! or by converting the value to Anon. 
53//! 
54//! ```
55//! use anon_vec::AnonVec;
56//! use anon_vec::Anon;
57//! use std::mem::size_of;
58//! use std::any::TypeId;
59//! 
60//! // You can create AnonVecs from a T...
61//! let mut anon1 = AnonVec::new::<i32>();
62//! 
63//! // ...or from a size.
64//! let mut anon2 = AnonVec::from_size(size_of::<i32>(), TypeId::of::<i32>());
65//! 
66//! // values can be pushed to the vec.
67//! anon1.push::<i32>(5);
68//! anon1.push::<i32>(5);
69//! 
70//! // and removed.
71//! anon1.remove(1);
72//! 
73//! // AnonVecs can also be uninitialized
74//! let mut anon3 = Anon::uninit();
75//! 
76//! if anon3.is_uninit() {
77//!     anon3.init::<i32>(5);
78//! } else {
79//!     // do something to the value.
80//! }
81//! ```
82//! 
83//! anon_vec supports typed iterators over [`AnonVec`], and chaining iterators together.
84//! This is particularly useful for ECS, and the motivation behind why chaining iterators were included.
85//! 
86//! ['AnonIter'] can be created with AnonVec::iter::<T>().  It takes a pointer to the inner value of
87//! [`AnonIter`] and is not lifetime-checked. If the Iter outlives its parent AnonVec, iterating it will
88//! access invalid data.
89//! 
90//! [`AnonIterMut`] is the same as AnonIter, and can be created with AnonVec::iter_mut::<T>(). 
91//! 
92//! [`AnonChain`] and [`AnonChainMut`] use the push method to construct a chain of iterators that can be
93//! iterated as one. 
94
95#![allow(dead_code)] 
96
97mod anon;
98mod iter;
99mod vec;
100
101pub use anon::Anon;
102pub use vec::AnonVec;
103pub use iter::{
104    AnonChainMut,
105    AnonChain,
106    AnonIter,
107    AnonIterMut,
108};
anon_vec/lib.rs

anon_vec/
lib.rs
