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

• 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

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

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)

#[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

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.