# avila-atom
**Atomic Computational Structures** - High-performance fundamental data structures built from first principles.
[](https://crates.io/crates/avila-atom)
[](https://docs.rs/avila-atom)
[](LICENSE)
## Features
- **Zero-cost abstractions** - No runtime overhead vs manual implementation
- **Memory efficiency** - Contiguous allocation for optimal cache locality
- **Compile-time optimization** - Monomorphization enables aggressive inlining
- **no_std compatible** - Works in embedded and OS development contexts
## Data Structures
### Core Types
- **`Option<T>`** - Optional value (presence/absence)
- Zero-cost abstraction with enum-based representation
- Null pointer optimization for references
- **`Result<T, E>`** - Result type (success/failure)
- Tagged union for error handling
- Zero-cost compared to manual error codes
- **`DynamicArray<T>`** - Growable contiguous array
- O(1) amortized push with geometric growth
- 24 bytes header (ptr + len + capacity)
- **`AssociativeArray<K, V>`** - Key-value storage
- `std`: HashMap with O(1) average lookup
- `no_std`: BTreeMap with O(log n) lookup
- **`StringBuffer`** - UTF-8 encoded string
- Guaranteed valid UTF-8 at all times
- Efficient growable capacity
### Advanced Types
- **`FixedArray<T, N>`** - Stack-allocated fixed-size array
- Zero heap allocation
- Compile-time size known
- **`CacheAlignedArray<T, N>`** - Cache-line aligned array
- 64-byte alignment prevents false sharing
- Optimal for multithreaded performance
- **`SmallString`** - Small string optimization
- Stores ≤23 bytes inline (no heap)
- Automatic heap promotion for larger strings
### Performance Modules
- **`perf`** - Branch prediction hints and alignment
- `likely()` / `unlikely()` - Branch prediction hints
- `assume_aligned()` - Pointer alignment assertions
- **`simd`** - SIMD-optimized operations (x86_64)
- AVX2/AVX-512 feature detection
- Vectorized memory operations
- 2-4x faster for large buffers
- **`DynamicArrayExt`** - Extended array operations
- `reserve_exact_fast()` - Smart capacity management
- `extend_from_slice_fast()` - Optimized slice extension
- `clear_and_resize()` - Memory-efficient resizing
## Usage
Add to your `Cargo.toml`:```toml
[dependencies]
avila-atom = "0.3"
```
### Examples
```rust
use avila_atom::{DynamicArray, AssociativeArray, StringBuffer};
// Dynamic array with type inference
let mut numbers = DynamicArray::new();
numbers.push(1);
numbers.push(2);
numbers.push(3);
// Map with convenient macro
use avila_atom::map;
let config = map! {
"host" => "localhost",
"port" => "8080",
};
// UTF-8 string buffer
let mut text = StringBuffer::from("Hello, ");
text.push_str("Ávila!");
assert_eq!(text.len(), 14); // UTF-8 byte count
```
### Macros
```rust
use avila_atom::{map, list, array};
// Map with capacity pre-allocation
let m = map! {
"key1" => "value1",
"key2" => "value2",
};
// Dynamic array
let v = list![1, 2, 3, 4, 5];
// Fixed-size stack array
let arr = array![10, 20, 30];
assert_eq!(arr.len(), 3);
```
### Performance Optimizations
```rust
use avila_atom::{DynamicArray, DynamicArrayExt};
use avila_atom::fixed::CacheAlignedArray;
use avila_atom::perf::{likely, unlikely};
// Cache-aligned array for multithreading
let aligned = CacheAlignedArray::new([0u64; 8]);
// Smart capacity management
let mut v = DynamicArray::new();
v.reserve_exact_fast(1000); // Only allocates if needed
v.extend_from_slice_fast(&[1, 2, 3]);
// Branch prediction hints
fn process(value: i32) -> i32 {
if likely(value > 0) {
value * 2
} else {
0
}
}
```
### SIMD Operations (x86_64)
```rust
#[cfg(target_arch = "x86_64")]
use avila_atom::simd::{has_avx2, has_avx512f, fast_copy};
#[cfg(target_arch = "x86_64")]
fn optimized_copy(dst: &mut [u8], src: &[u8]) {
if has_avx512f() {
unsafe {
fast_copy(
dst.as_mut_ptr(),
src.as_ptr(),
src.len()
);
}
} else {
dst.copy_from_slice(src);
}
}
```
## Performance Characteristics
| `DynamicArray::push` | O(1) amortized | Geometric growth (2x) |
| `DynamicArray::get` | O(1) | Direct index access |
| `AssociativeArray::get` | O(1) avg / O(log n) | HashMap / BTree |
| `StringBuffer::push_str` | O(n) | UTF-8 validation required |
| `FixedArray` operations | O(1) | Stack-allocated, inlined |
## Compile-Time Guarantees
```rust
use avila_atom::static_assert_size;
// Verify structure sizes for ABI compatibility
static_assert_size!(Option<&str>, 16); // Two pointers on 64-bit
```
## no_std Support
Disable default features and enable `alloc`:
```toml
[dependencies]
avila-atom = { version = "0.2", default-features = false }
```
Note: `AssociativeArray` falls back to BTreeMap in `no_std` mode.
## Architecture
Built following the **Ávila Engineering Philosophy**:
- **Stack-preferred** - Minimize heap allocations
- **Zero dependencies** - Built from Rust core types
- **Performance-first** - Optimized for modern CPU architectures
- **Type-safe** - Compile-time guarantees prevent runtime errors
## License
Licensed under either of:
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))
at your option.
## Contributing
Contributions are welcome! Please ensure:
1. All tests pass (`cargo test`)
2. Code is formatted (`cargo fmt`)
3. No clippy warnings (`cargo clippy`)
4. Documentation is updated
---
**Part of the Ávila Computational Stack** - Building high-performance systems from first principles.