avila-atom

Atomic Computational Structures - High-performance fundamental data structures built from first principles.

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

• SmallString - Small string optimization

  • Stores ≤23 bytes inline (no heap)
  • Automatic heap promotion for larger strings

Usage

Add to your Cargo.toml:

[dependencies]
avila-atom = "0.2"

Examples

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

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 Characteristics

Compile-Time Guarantees

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:

[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)
• MIT license (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.