avila-atom 0.3.0

# avila-atom

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

[![Crates.io](https://img.shields.io/crates/v/avila-atom.svg)](https://crates.io/crates/avila-atom)
[![Documentation](https://docs.rs/avila-atom/badge.svg)](https://docs.rs/avila-atom)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](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

- **`SmallString`** - Small string optimization
  - Stores ≤23 bytes inline (no heap)
  - Automatic heap promotion for larger strings

## Usage

Add to your `Cargo.toml`:

```toml
[dependencies]
avila-atom = "0.2"
```

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

| Operation | Complexity | Notes |
|-----------|-----------|-------|
| `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.