### Spur Key Usage Example

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/keys.md

Demonstrates how to use the `Spur` key type with a `Rodeo` instance to intern and resolve strings. This example shows the basic workflow of getting a key for a string and then resolving it back.

```rust
use lasso::{Rodeo, Spur};

let mut rodeo: Rodeo<Spur> = Rodeo::new();
let key = rodeo.get_or_intern("hello");
assert_eq!(rodeo.resolve(&key), "hello");
```

--------------------------------

### Examples Provided

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/COMPLETION_REPORT.txt

Summary of the usage examples available for the Lasso project, covering various scenarios from single-threaded to multi-threaded operations and error handling.

```APIDOC
## Examples Provided

30+ usage examples covering:

### Single-threaded usage:
  - Basic internment
  - Reading/querying
  - Resolution
  - Iteration
  - Configuration

### Multi-threaded usage:
  - Concurrent internment
  - Arc<ThreadedRodeo> pattern
  - Thread spawning
  - Cross-thread coordination

### Conversion patterns:
  - Rodeo → RodeoReader
  - RodeoReader → RodeoResolver
  - Direct Rodeo → RodeoResolver

### Key selection:
  - Using MicroSpur for fixed sets
  - Using Spur for general purpose
  - Using LargeSpur for unbounded
  - Custom key implementation

### Configuration:
  - Setting capacity
  - Setting memory limits
  - Using custom hashers
  - Combining multiple settings

### Error handling:
  - try_get_or_intern pattern
  - Error matching
  - Recovery patterns

All examples are:
  - Complete (can be copy-pasted)
  - Runnable (valid Rust syntax)
  - Realistic (production patterns)
  - Commented (explain the intent)
```

--------------------------------

### Rust Example Code Block

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/DOCUMENTATION_OVERVIEW.md

A placeholder for a real, runnable Rust code example demonstrating realistic usage patterns and standard library idioms.

```rust
// Real working example
```

--------------------------------

### LassoError Display Format Examples

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/errors.md

These examples show the human-readable messages produced by the `Display` implementation of `LassoError` when different error conditions occur.

```text
Lasso encountered an error: The configured memory limit was reached
Lasso encountered an error: The key space was exhausted
Lasso encountered an error: Failed to allocate memory
```

--------------------------------

### Multi-threaded Rodeo Example

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/START_HERE.md

Shows how to use ThreadedRodeo for string interning in a multi-threaded environment. Requires importing ThreadedRodeo and Arc.

```rust
use lasso::ThreadedRodeo;
use std::sync::Arc;

let rodeo = Arc::new(ThreadedRodeo::new());
let key = rodeo.get_or_intern("hello");
assert_eq!(rodeo.resolve(&key), "hello");
```

--------------------------------

### IRC DCC SEND Command Example

Source: https://github.com/kixiron/lasso/blob/master/benches/input.txt

An example of a DCC SEND command string that might trigger security products on IRC clients.

```irc
DCC SEND STARTKEYLOGGER 0 0 0
```

--------------------------------

### Custom Key Implementation Example

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/keys.md

Illustrates how to implement the Key trait for a custom NicheKey type, reserving a range of values for specific optimizations.

```rust
use lasso::{Key, Rodeo};

#[derive(Copy, Clone, PartialEq, Eq)]
struct NicheKey(u32);

const NICHE: usize = 0xFF000000; // Reserve upper 255 values

unsafe impl Key for NicheKey {
    fn into_usize(self) -> usize {
        self.0 as usize
    }

    fn try_from_usize(int: usize) -> Option<Self> {
        if int < NICHE {
            Some(Self(int as u32))
        } else {
            None
        }
    }
}

let mut rodeo: Rodeo<NicheKey> = Rodeo::new();
let key = rodeo.get_or_intern("hello");
assert_eq!(rodeo.resolve(&key), "hello");
```

--------------------------------

### XXE Injection Example (XML)

Source: https://github.com/kixiron/lasso/blob/master/benches/input.txt

This XML string can reveal system files when parsed by a badly configured XML parser.

```xml
<?xml version="1.0" encoding="ISO-8859-1"?><!DOCTYPE foo [ <!ELEMENT foo ANY ><!ENTITY xxe SYSTEM "file:///etc/passwd" >]><foo>&xxe;</foo>
```

--------------------------------

### Rust Method Documentation Example

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/DOCUMENTATION_OVERVIEW.md

Demonstrates the detailed format for documenting Rust methods, including signature, one-line description, parameter table, return/panic information, and source location.

```rust
### method_name

```rust
pub fn method_name(param: Type) -> ReturnType
```

One-line description.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| param | Type | Yes | — | What it does |

**Returns:** ReturnType description

**Throws/Panics:** Conditions where it fails

**Example:**
```rust
// Real working example
```

**Source:** `src/file.rs:123`
```

--------------------------------

### Command Injection Examples (Ruby)

Source: https://github.com/kixiron/lasso/blob/master/benches/input.txt

These strings can be used to execute system commands within Ruby/Rails applications.

```ruby
eval("puts 'hello world'")
```

```ruby
System("ls -al /")
```

```ruby
`ls -al /`
```

```ruby
Kernel.exec("ls -al /")
```

```ruby
Kernel.exit(1)
```

```ruby
%x('ls -al /')
```

--------------------------------

### Embedded System Configuration

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/configuration.md

Shows how to configure `Rodeo` for embedded systems with tight memory and string count limitations. This example uses `MiniSpur` and specific capacity and memory limits.

```rust
use lasso::{Rodeo, MiniSpur, Capacity, MemoryLimits};

// Embedded device: 1000 strings max, 512 KB limit
let mut rodeo: Rodeo<MiniSpur> = Rodeo::with_capacity_and_memory_limits(
    Capacity::for_strings(1000),
    MemoryLimits::for_memory_usage(512 * 1024),
);
```

--------------------------------

### Markdown File Header Example

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/DOCUMENTATION_OVERVIEW.md

Illustrates the standard header format for markdown files, including the type/module name, a brief description, import statements, and file location.

```markdown
# Type/Module Name

Brief description.

**Import:** `use lasso::TypeName;`

**File location:** `src/path/to/file.rs`
```

--------------------------------

### Server Code Injection Examples

Source: https://github.com/kixiron/lasso/blob/master/benches/input.txt

These strings can lead to code execution on the server as a privileged user. Use with caution.

```shell
-
```

```shell
--
```

```shell
--version
```

```shell
--help
```

```shell
$USER
```

```shell
/dev/null; touch /tmp/blns.fail ; echo
```

```shell
`touch /tmp/blns.fail`
```

```shell
$(touch /tmp/blns.fail)
```

```shell
@{[system "touch /tmp/blns.fail"]}
```

--------------------------------

### Single-threaded Rodeo Example

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/START_HERE.md

Demonstrates basic string interning using Rodeo in a single-threaded context. Requires importing the Rodeo struct.

```rust
use lasso::Rodeo;

let mut rodeo = Rodeo::new();
let key = rodeo.get_or_intern("hello");
assert_eq!(rodeo.resolve(&key), "hello");
```

--------------------------------

### File Inclusion Examples

Source: https://github.com/kixiron/lasso/blob/master/benches/input.txt

These strings can cause a user to pull in files that should not be part of a web server.

```text
../../../../../../../../../../../../etc/passwd%00
```

```text
../../../../../../../../../../../../etc/hosts
```

--------------------------------

### Rust Struct Definition Example

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/DOCUMENTATION_OVERVIEW.md

Shows the format for defining Rust structs within the documentation, including visibility, generics, and inline comments for fields.

```rust
pub struct TypeName<T> {
    // fields
}
```

--------------------------------

### get_or_intern

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/rodeo.md

Gets the key for a string, interning it if it does not yet exist. Returns the same key for identical strings.

```APIDOC
## get_or_intern

### Description
Gets the key for a string, interning it if it does not yet exist. Returns the same key for identical strings.

### Method
Rust function signature

### Parameters
#### Path Parameters
- **val** (T: AsRef<str>) - Required - String to intern

### Returns
`K` - Unique key associated with the string

### Throws
Panics if the key space is exhausted or memory limits are reached

### Example
```rust
use lasso::Rodeo;

let mut rodeo = Rodeo::new();
let key1 = rodeo.get_or_intern("hello");
let key2 = rodeo.get_or_intern("hello");

assert_eq!(key1, key2); // Same string returns same key
```
```

--------------------------------

### Concurrent Access Example with ThreadedRodeo

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/threaded-rodeo.md

Demonstrates how to use ThreadedRodeo concurrently across multiple threads. It shows creating a shared rodeo instance using Arc, spawning threads to intern strings and resolve keys, and joining the threads.

```rust
use lasso::ThreadedRodeo;
use std::sync::Arc;
use std::thread;

let rodeo = Arc::new(ThreadedRodeo::new());
let mut handles = vec![];

for i in 0..10 {
    let r = Arc::clone(&rodeo);
    handles.push(thread::spawn(move || {
        let key = r.get_or_intern(&format!("string_{}", i));
        r.resolve(&key)
    }));
}

for handle in handles {
    handle.join().unwrap();
}

```

--------------------------------

### Get Key for Existing String with Rodeo

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/rodeo.md

Use `get` to retrieve the key for a string if it has already been interned. Returns `None` if the string is not found in the interner.

```rust
use lasso::Rodeo;

let mut rodeo = Rodeo::new();
let key = rodeo.get_or_intern("hello");

assert_eq!(rodeo.get("hello"), Some(key));
assert_eq!(rodeo.get("world"), None);
```

--------------------------------

### Example of KeySpaceExhaustion Error in Rust

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/errors.md

Demonstrates `LassoErrorKind::KeySpaceExhaustion` by attempting to intern more strings than supported by the `MicroSpur` key type. It shows how to intern up to the limit and then handle the exhaustion error.

```rust
use lasso::{Rodeo, MicroSpur};

// MicroSpur only supports up to 254 unique strings
let mut rodeo: Rodeo<MicroSpur> = Rodeo::new();

// Intern 254 strings (the maximum)
for i in 0..254 {
    rodeo.get_or_intern(&format!("string_{}", i)).ok();
}

// This will fail - key space exhausted
match rodeo.try_get_or_intern("one more") {
    Ok(_) => println!("Success"),
    Err(e) => {
        if e.kind().is_keyspace_exhaustion() {
            println!("Key space exhausted: {}", e);
        }
    }
}
```

--------------------------------

### MicroSpur Usage Example

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/keys.md

Demonstrates how to use MicroSpur with a Rodeo instance to intern a small, fixed set of strings. Note the limitation of 254 unique strings.

```rust
use lasso::{Rodeo, MicroSpur};

let mut rodeo: Rodeo<MicroSpur> = Rodeo::new();
// Can only intern up to 254 unique strings
rodeo.get_or_intern("red");
rodeo.get_or_intern("green");
rodeo.get_or_intern("blue");

assert_eq!(rodeo.len(), 3);
```

--------------------------------

### O(1) Operations with Rodeo

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/README.md

Demonstrates the O(1) amortized time complexity for interning or retrieving a string, O(1) for resolving a key to a string, and O(1) for looking up a string to get its key using Rodeo.

```rust
let mut rodeo = Rodeo::new();

// O(1) amortized - interns or retrieves
let key = rodeo.get_or_intern("hello");

// O(1) - key to string lookup
let s = rodeo.resolve(&key);

// O(1) - string to key lookup
let k = rodeo.get("hello");
```

--------------------------------

### Default Capacity Implementation

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/configuration.md

Provides the default Capacity implementation, allocating for 50 strings and 4096 bytes. This is a reasonable starting point for small applications.

```rust
impl Default for Capacity {
    fn default() -> Self {
        Self {
            strings: 50,
            bytes: unsafe { NonZeroUsize::new_unchecked(4096) },
        }
    }
}
```

--------------------------------

### Upside Down Text Example

Source: https://github.com/kixiron/lasso/blob/master/benches/input.txt

Demonstrates a string with an 'upsidedown' Unicode effect. This is for illustrative purposes and does not represent executable code.

```text
˙ɐnbᴉlɐ ɐuƃɐɯ ǝɹolop ʇǝ ǝɹoqɐl ʇn ʇunpᴉpᴉɔuᴉ ɹodɯǝʇ poɯsnᴉǝ op pǝs 'ʇᴉlǝ ƃuᴉɔsᴉdᴉpɐ ɹnʇǝʇɔǝsuoɔ 'ʇǝɯɐ ʇᴉs ɹolop ɯnsdᴉ ɯǝɹo˥
00˙Ɩ$-
```

--------------------------------

### Basic Lasso String Interning Example

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/types.md

This snippet shows how to create a Rodeo, intern strings, check for their presence, resolve them, and iterate over the interned data. It utilizes the `Rodeo`, `Capacity`, `MemoryLimits`, `LassoResult`, and `LassoError` types.

```rust
use lasso::{Rodeo, Capacity, MemoryLimits, LassoResult, LassoError};

fn example() -> LassoResult<()> {
    // Create a rodeo with specific capacity and memory limits
    let mut rodeo = Rodeo::with_capacity_and_memory_limits(
        Capacity::for_strings(1000),
        MemoryLimits::for_memory_usage(1024 * 1024), // 1 MB limit
    );
    
    // Intern strings using the Interner trait
    let key = rodeo.try_get_or_intern("hello")?;
    
    // Read using the Reader trait
    if rodeo.contains("hello") {
        println!("Found: {}", rodeo.get("hello").unwrap());
    }
    
    // Resolve using the Resolver trait
    let resolved = rodeo.try_resolve(&key)?;
    println!("Resolved: {}", resolved);
    
    // Convert to reader for thread-safe access
    let reader = rodeo.into_reader();
    for (key, string) in reader.iter() {
        println!("{:?}: {}", key, string);
    }
    
    Ok(())
}

```

--------------------------------

### Human Injection Example

Source: https://github.com/kixiron/lasso/blob/master/benches/input.txt

A string designed to test 'human injection', potentially causing a user to reinterpret their reality if they encounter it unexpectedly.

```text
If you're reading this, you've been in a coma for almost 20 years now. We're trying a new technique. We don't know where this message will end up in your dream, but we hope it works. Please wake up, we miss you.
```

--------------------------------

### Dynamic Workload with AHash for Multi-threading

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/configuration.md

Illustrates the setup for a multi-threaded `ThreadedRodeo` with a custom, faster hasher (implied by `ahash` feature, though not explicitly shown in code) and defined capacity/memory limits. This is suitable for high-throughput, concurrent applications.

```rust
use lasso::{ThreadedRodeo, Capacity, MemoryLimits};
use std::sync::Arc;

// Multi-threaded with faster hashing
let rodeo = Arc::new(ThreadedRodeo::with_capacity_and_memory_limits(
    Capacity::for_strings(10_000),
    MemoryLimits::for_memory_usage(100 * 1024 * 1024),
));
```

--------------------------------

### Serialize and Deserialize Lasso Spur

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/INDEX.md

This example demonstrates how to serialize a Lasso `Spur` to JSON and then deserialize it back. Ensure the `serialize` feature is enabled for the `lasso` crate.

```rust
use lasso::Rodeo;

let mut rodeo = Rodeo::new();
let key = rodeo.get_or_intern("hello");

let json = serde_json::to_string(&key).unwrap();
let deserialized: lasso::Spur = serde_json::from_str(&json).unwrap();
```

--------------------------------

### Try Get or Intern String

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/threaded-rodeo.md

A fallible version of `get_or_intern` that returns a `LassoResult` instead of panicking. Use this when you need to handle potential errors during interning.

```rust
pub fn try_get_or_intern<T>(&self, val: T) -> LassoResult<K>
where
    T: AsRef<str>,
```

--------------------------------

### Example of MemoryLimitReached Error in Rust

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/errors.md

Illustrates how `LassoErrorKind::MemoryLimitReached` can occur when interning a string that causes the interner to exceed its memory limit. It shows how to set a memory limit and handle the error.

```rust
use lasso::{Rodeo, Capacity, MemoryLimits};

// Create rodeo with 100 byte limit
let mut rodeo: Rodeo = Rodeo::with_capacity_and_memory_limits(
    Capacity::default(),
    MemoryLimits::for_memory_usage(100),
);

// Intern short strings successfully
let key1 = rodeo.try_get_or_intern("hi").unwrap();

// This will likely fail due to memory limit
match rodeo.try_get_or_intern("this is a much longer string that exceeds our limit") {
    Ok(_) => println!("Interned successfully"),
    Err(e) => {
        if e.kind().is_memory_limit() {
            println!("Ran out of memory: {}", e);
        }
    }
}
```

--------------------------------

### Use Smaller Keys

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/INDEX.md

Utilize smaller key types like `MiniSpur` to reduce memory usage per key. This example demonstrates initializing a `Rodeo` with `MiniSpur` for 16-bit keys.

```rust
use lasso::{Rodeo, MiniSpur};

// Use 16-bit keys instead of 32-bit (saves 50% per key)
let mut rodeo: Rodeo<MiniSpur> = Rodeo::new();
let key = rodeo.get_or_intern("hello");
```

--------------------------------

### Perform Multi-threaded Analysis with Lasso

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/README.md

Utilize `ThreadedRodeo` for concurrent symbol interning across multiple threads. This example uses Rayon for parallel iteration to intern strings and collect their keys.

```rust
use lasso::ThreadedRodeo;
use std::sync::Arc;
use rayon::prelude::*;

let interner = Arc::new(ThreadedRodeo::new());

let strings = vec!["a", "b", "c"];
let keys: Vec<_> = strings
    .par_iter()
    .map(|s| interner.get_or_intern(s))
    .collect();

```

--------------------------------

### Get or Intern Static String

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/threaded-rodeo.md

Gets the key for a static string reference without copying or reallocating. This is efficient for strings with a `'static` lifetime.

```rust
pub fn get_or_intern_static(&self, string: &'static str) -> K
```

--------------------------------

### get_or_intern_static

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/rodeo.md

Gets the key for a static string without copying or reallocating.

```APIDOC
## get_or_intern_static

### Description
Gets the key for a static string without copying or reallocating.

### Method
Rust function signature

### Parameters
#### Path Parameters
- **string** (`&'static str`) - Required - Static string reference to intern

### Returns
`K` - Unique key associated with the string

### Throws
Panics if the key space is exhausted

### Example
```rust
use lasso::Rodeo;

let mut rodeo = Rodeo::new();
let key = rodeo.get_or_intern_static("constant string");
assert_eq!(rodeo.resolve(&key), "constant string");
```
```

--------------------------------

### Custom Hasher with Capacity and Limits

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/configuration.md

Shows how to initialize `Rodeo` with a custom hasher, along with specific capacity and memory limits. This allows fine-grained control over resource usage.

```rust
use lasso::{Rodeo, Spur, Capacity, MemoryLimits};
use std::collections::hash_map::RandomState;

let rodeo: Rodeo<Spur, RandomState> = Rodeo::with_capacity_memory_limits_and_hasher(
    Capacity::for_strings(100),
    MemoryLimits::for_memory_usage(1024 * 1024),
    RandomState::new(),
);
```

--------------------------------

### Get Bytes Allocation from Capacity

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/configuration.md

Retrieves the number of bytes that the Capacity will allocate.

```rust
pub fn bytes(&self) -> NonZeroUsize
```

--------------------------------

### Get Strings Allocation from Capacity

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/configuration.md

Retrieves the number of strings that the Capacity will allocate.

```rust
pub fn strings(&self) -> usize
```

--------------------------------

### new

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/threaded-rodeo.md

Creates a new empty ThreadedRodeo with default capacity and no memory limits.

```APIDOC
## new

### Description
Creates a new empty `ThreadedRodeo` with default capacity and no memory limits.

### Parameters
None

### Returns
`ThreadedRodeo<Spur, RandomState>`

### Example
```rust
use lasso::ThreadedRodeo;
use std::sync::Arc;

let rodeo = Arc::new(ThreadedRodeo::new());
let key = rodeo.get_or_intern("hello");
assert_eq!(rodeo.resolve(&key), "hello");
```
```

--------------------------------

### Option<Spur> and Option<MicroSpur> Size Optimization

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/keys.md

Demonstrates how Option<Key> types have the same memory size as the Key type itself due to NonZero wrappers and niche optimization. This is useful for memory-sensitive applications.

```rust
use lasso::Spur;
use std::mem;

// Option<Spur> is the same size as Spur (4 bytes), not 5 bytes
assert_eq!(
    mem::size_of::<Option<Spur>>(),
    mem::size_of::<Spur>()
);

// Option<MicroSpur> is the same size as MicroSpur (1 byte)
use lasso::MicroSpur;
assert_eq!(
    mem::size_of::<Option<MicroSpur>>(),
    mem::size_of::<MicroSpur>()
);
```

--------------------------------

### get

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/reader.md

Retrieves the key associated with a given string if it has been interned. Returns None if the string is not found.

```APIDOC
## get

### Description
Gets the key for a string if it has been interned, returning `None` otherwise.

### Method
`&self` (implicitly a read operation)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **val** (`T: AsRef<str>`) - Required - The string to look up.

### Returns
`Option<K>` - `Some(key)` if the string is interned, `None` otherwise.

### Example
```rust
use lasso::Rodeo;

let mut rodeo = Rodeo::new();
let key = rodeo.get_or_intern("hello");

let reader = rodeo.into_reader();
assert_eq!(reader.get("hello"), Some(key));
assert_eq!(reader.get("world"), None);
```
```

--------------------------------

### Instantiate and Use MiniSpur with Rodeo

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/keys.md

Demonstrates interning a small set of strings using MiniSpur with Rodeo and verifying the count. This is ideal for applications with a fixed, small set of interned strings.

```rust
use lasso::{Rodeo, MiniSpur};

let mut rodeo: Rodeo<MiniSpur> = Rodeo::new();
for i in 0..100 {
    rodeo.get_or_intern(&format!("string_{}", i));
}

let rodeo = rodeo.into_reader();
assert_eq!(rodeo.len(), 100);
```

--------------------------------

### Space-Optimized Keys with Spur

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/README.md

Demonstrates how Lasso's key types, like `Spur`, utilize `NonZero*` wrappers for niche optimization, resulting in `Option<Spur>` having the same memory size as `Spur` itself.

```rust
use std::mem;
use lasso::Spur;

// Option<Spur> is same size as Spur (4 bytes, not 8)
assert_eq!(
    mem::size_of::<Option<Spur>>(),
    mem::size_of::<Spur>()
);
```

--------------------------------

### SQL Injection Examples

Source: https://github.com/kixiron/lasso/blob/master/benches/input.txt

These strings can be used to exploit SQL injection vulnerabilities if user inputs are not sanitized.

```sql
1;DROP TABLE users
```

```sql
1'; DROP TABLE users--
```

```sql
' OR 1=1 -- 1
```

```sql
' OR '1'='1
```

```sql
%
```

```sql
_
```

--------------------------------

### Get Number of Interned Strings

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/reader.md

Returns the count of unique interned strings stored within the reader.

```rust
pub fn len(&self) -> usize
```

```rust
use lasso::Rodeo;

let mut rodeo = Rodeo::new();
rodeo.get_or_intern("one");
rodeo.get_or_intern("two");

let reader = rodeo.into_reader();
assert_eq!(reader.len(), 2);
```

--------------------------------

### Instantiate and Use LargeSpur with Rodeo

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/keys.md

Demonstrates how to create a Rodeo instance with LargeSpur and intern a string. This is useful when you need to intern more than 4 billion strings.

```rust
use lasso::{Rodeo, LargeSpur};

let mut rodeo: Rodeo<LargeSpur> = Rodeo::new();
let key = rodeo.get_or_intern("hello");
assert_eq!(rodeo.resolve(&key), "hello");
```

--------------------------------

### Create ThreadedRodeo with capacity and custom hasher

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/threaded-rodeo.md

Use `ThreadedRodeo::with_capacity_and_hasher()` to configure both initial capacity and a custom hash builder. This allows for optimized string interning with specific performance characteristics.

```rust
pub fn with_capacity_and_hasher<
    K: Key + Hash,
    S: BuildHasher + Clone,
>(
    capacity: Capacity,
    hash_builder: S,
) -> Self {
    // Implementation details omitted for brevity
    unimplemented!("This is a placeholder for the actual implementation.")
}
```

--------------------------------

### Get Interned String Key

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/threaded-rodeo.md

Retrieves the key for a string if it has already been interned, returning `None` if the string is not found.

```rust
pub fn get<T>(&self, val: T) -> Option<K>
where
    T: AsRef<str>,
```

--------------------------------

### Rodeo::new

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/rodeo.md

Creates a new empty Rodeo with default capacity and no memory limits.

```APIDOC
## Rodeo::new

### Description
Creates a new empty `Rodeo` with default capacity and no memory limits.

### Parameters
None

### Returns
`Rodeo<Spur, RandomState>`

### Example
```rust
use lasso::Rodeo;

let mut rodeo = Rodeo::new();
let key = rodeo.get_or_intern("hello");
assert_eq!(rodeo.resolve(&key), "hello");
```
```

--------------------------------

### Iterate Over Strings

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/INDEX.md

Iterate over all interned strings in a `RodeoReader`. This snippet shows how to get both the key and the string slice for each interned entry.

```rust
let mut rodeo = Rodeo::new();
rodeo.get_or_intern("one");
rodeo.get_or_intern("two");

let rodeo = rodeo.into_reader();
for (key, string) in rodeo.iter() {
    println!("{:?}: {}", key, string);
}
```

--------------------------------

### Create ThreadedRodeo with capacity and memory limits

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/threaded-rodeo.md

Use `ThreadedRodeo::with_capacity_and_memory_limits()` to configure both initial capacity and maximum memory usage. This provides fine-grained control over resource allocation.

```rust
pub fn with_capacity_and_memory_limits(
    capacity: Capacity,
    memory_limits: MemoryLimits,
) -> Self
where
    K: Key + Hash,
{
    // Implementation details omitted for brevity
    unimplemented!("This is a placeholder for the actual implementation.")
}
```

--------------------------------

### Unwanted Interpolation Examples

Source: https://github.com/kixiron/lasso/blob/master/benches/input.txt

These strings can be accidentally expanded into different strings if evaluated in the wrong context, such as printf format strings or eval.

```text
$HOME
```

```text
$ENV{'HOME'}
```

```text
%d
```

```text
%s
```

```text
{0}
```

```text
%*.*s
```

```text
File:///
```

--------------------------------

### Convert to Read-Only

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/INDEX.md

Convert a `Rodeo` instance into a read-only `RodeoReader` to prevent further modifications. This is useful when you only need to resolve or get existing strings.

```rust
let mut rodeo = Rodeo::new();
let key = rodeo.get_or_intern("hello");

let reader = rodeo.into_reader();
assert_eq!(reader.resolve(&key), "hello");
assert_eq!(reader.get("hello"), Some(key));
```

--------------------------------

### Terminal Escape Codes Example

Source: https://github.com/kixiron/lasso/blob/master/benches/input.txt

Demonstrates the use of terminal escape codes for text formatting and manipulation, which can cause issues when displayed directly.

```ansi
Roses are  [0;31mred [0m, violets are  [0;34mblue. Hope you enjoy terminal hue
But now... [20Cfor my greatest trick... [8m
The quic      k brown fo           x... [Beeeep]
```

--------------------------------

### Scunthorpe Problem Examples

Source: https://github.com/kixiron/lasso/blob/master/benches/input.txt

A collection of innocuous strings that may be blocked by profanity filters due to containing substrings that resemble offensive words.

```text
Scunthorpe General Hospital
Penistone Community Church
Lightwater Country Park
Jimmy Clitheroe
Horniman Museum
shitake mushrooms
RomansInSussex.co.uk
http://www.cum.qc.ca/
Craig Cockburn, Software Specialist
Linda Callahan
Dr. Herman I. Libshitz
magna cum laude
Super Bowl XXX
medieval erection of parapets
evaluate
mocha
expression
Arsenal canal
classic
Tyson Gay
Dick Van Dyke
basement
```

--------------------------------

### Get Key from String using RodeoReader

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/reader.md

Retrieves the interned key for a given string. Returns None if the string has not been interned. This method is thread-safe.

```rust
use lasso::Rodeo;

let mut rodeo = Rodeo::new();
let key = rodeo.get_or_intern("hello");

let reader = rodeo.into_reader();
assert_eq!(reader.get("hello"), Some(key));
assert_eq!(reader.get("world"), None);
```

--------------------------------

### Get Resolver Length

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/resolver.md

Returns the number of interned strings currently stored in the resolver. Useful for tracking the size of the interned string pool.

```rust
use lasso::Rodeo;

let mut rodeo = Rodeo::new();
rodeo.get_or_intern("one");
rodeo.get_or_intern("two");

let resolver = rodeo.into_resolver();
assert_eq!(resolver.len(), 2);
```

--------------------------------

### Create ThreadedRodeo with capacity

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/threaded-rodeo.md

Use `ThreadedRodeo::with_capacity()` to pre-allocate space, reducing reallocations. Specify the desired capacity using `Capacity::for_strings()`.

```rust
use lasso::{ThreadedRodeo, Capacity};

let rodeo: ThreadedRodeo = ThreadedRodeo::with_capacity(Capacity::for_strings(100));
```

--------------------------------

### Use Panicking API for Infallible Scenarios

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/errors.md

Employ `get_or_intern` when you are certain that the string interning operation will succeed. This is typically safe when memory limits are not a concern and the key space is not exhausted.

```rust
use lasso::Rodeo;

fn intern_known_strings(mut rodeo: Rodeo) {
    // These are guaranteed to succeed
    let hello = rodeo.get_or_intern("hello");
    let world = rodeo.get_or_intern("world");
}
```

--------------------------------

### Custom Hasher with Rodeo

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/configuration.md

Demonstrates how to use a custom hasher, such as `std::collections::hash_map::RandomState`, with the `Rodeo` type. This is useful when you need a specific hashing algorithm for your keys.

```rust
use lasso::{Rodeo, Spur};
use std::collections::hash_map::RandomState;

// Use specific hasher
let hasher = RandomState::new();
let rodeo: Rodeo<Spur, RandomState> = Rodeo::with_hasher(hasher);

let key = rodeo.get_or_intern("hello");
assert_eq!(rodeo.resolve(&key), "hello");
```

--------------------------------

### Capacity Constructors

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/types.md

Demonstrates various ways to construct a Capacity struct, including setting string count, byte count, or using defaults.

```rust
- `Capacity::new(strings: usize, bytes: NonZeroUsize) -> Self`
- `Capacity::for_strings(strings: usize) -> Self` - Set string count, use default bytes
- `Capacity::for_bytes(bytes: NonZeroUsize) -> Self` - Set byte count, use default strings
- `Capacity::minimal() -> Self` - Minimal capacity (0 strings, 1 byte)
```

--------------------------------

### Intern a String with Rodeo

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/rodeo.md

Use `get_or_intern` to get the key for a string. If the string is not already interned, it will be added. Identical strings will always return the same key.

```rust
use lasso::Rodeo;

let mut rodeo = Rodeo::new();
let key1 = rodeo.get_or_intern("hello");
let key2 = rodeo.get_or_intern("hello");

assert_eq!(key1, key2); // Same string returns same key
```

--------------------------------

### Set Capacity and Memory Limits

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/INDEX.md

Configure the `Rodeo` with specific initial capacity for strings and maximum memory limits. This helps in pre-allocating memory and controlling resource usage.

```rust
use lasso::{Rodeo, Capacity, MemoryLimits};

let rodeo = Rodeo::with_capacity_and_memory_limits(
    Capacity::for_strings(1000),
    MemoryLimits::for_memory_usage(10 * 1024 * 1024),
);
```

--------------------------------

### Get Maximum Memory Usage

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/configuration.md

Retrieves the maximum number of bytes that the memory limit allows. This method is useful for querying the configured memory constraint.

```rust
use lasso::MemoryLimits;

let limits = MemoryLimits::for_memory_usage(1024 * 1024);
assert_eq!(limits.max_memory_usage(), 1024 * 1024);
```

--------------------------------

### Create and Use RodeoResolver

Source: https://github.com/kixiron/lasso/blob/master/README.md

Shows how to create a RodeoResolver from a Rodeo instance. The resolver can be shared across threads and retains all strings from the parent Rodeo.

```rust
use lasso::Rodeo;

// Rodeo and ThreadedRodeo are interchangeable here
let mut rodeo = Rodeo::default();

let key = rodeo.get_or_intern("Hello, world!");
assert_eq!("Hello, world!", rodeo.resolve(&key));

let resolver = rodeo.into_resolver();

// Resolver keeps all the strings from the parent
assert_eq!("Hello, world!", resolver.resolve(&key));

// The Resolver can now be shared across threads, no matter what kind of Rodeo created it

```

--------------------------------

### Create and Use RodeoReader

Source: https://github.com/kixiron/lasso/blob/master/README.md

Demonstrates how to create a RodeoReader from a Rodeo instance. The reader can be shared across threads and retains all strings from the parent Rodeo.

```rust
use lasso::Rodeo;

// Rodeo and ThreadedRodeo are interchangeable here
let mut rodeo = Rodeo::default();

let key = rodeo.get_or_intern("Hello, world!");
assert_eq!("Hello, world!", rodeo.resolve(&key));

let reader = rodeo.into_reader();

// Reader keeps all the strings from the parent
assert_eq!("Hello, world!", reader.resolve(&key));
assert_eq!(Some(key), reader.get("Hello, world!"));

// The Reader can now be shared across threads, no matter what kind of Rodeo created it

```

--------------------------------

### Example of FailedAllocation Error in Rust

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/errors.md

Illustrates handling `LassoErrorKind::FailedAllocation` when the underlying memory allocator fails. This typically indicates an out-of-memory condition at the operating system level.

```rust
use lasso::Rodeo;

let mut rodeo: Rodeo = Rodeo::new();

match rodeo.try_get_or_intern("string") {
    Ok(key) => println!("Interned: {:?}", key),
    Err(e) => {
        if e.kind().is_failed_alloc() {
            eprintln!("Failed to allocate memory: {}", e);
            // Handle gracefully - maybe exit or retry
        }
    }
}
```

--------------------------------

### Key Serialization and Deserialization with serde_json

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/keys.md

Shows how to serialize and deserialize Lasso key types to and from JSON strings when the 'serialize' feature is enabled. Requires the `serde_json` crate.

```rust
use lasso::{Rodeo, Spur};

let mut rodeo: Rodeo<Spur> = Rodeo::new();
let key = rodeo.get_or_intern("hello");

let json = serde_json::to_string(&key).unwrap();
let deserialized: Spur = serde_json::from_str(&json).unwrap();

assert_eq!(key, deserialized);
```

--------------------------------

### Iterate over interned strings in Rodeo

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/rodeo.md

Use the `strings` method to get an iterator specifically over the interned string values, without their keys. This is helpful when only the string content is needed.

```rust
pub fn strings(&self) -> Strings<'_, K>

```

--------------------------------

### API Reference Navigation

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/COMPLETION_REPORT.txt

This section outlines the structure of the API reference documentation, including the main entry points and the detailed API files available.

```APIDOC
## API Reference Structure

### Main Entry Points

- **START_HERE.md**: Quick navigation guide, task-based routing, quick examples, feature matrix.
- **README.md**: Main documentation, overview & architecture, quick start, key concepts, common patterns.
- **INDEX.md**: Complete API navigation, type comparison table, feature matrix, file structure guide, quick task recipes.

### Detailed API Documentation Files

- **api-reference/rodeo.md**: Detailed Rodeo API.
- **api-reference/threaded-rodeo.md**: Detailed ThreadedRodeo API.
- **api-reference/reader.md**: Detailed RodeoReader API.
- **api-reference/resolver.md**: Detailed RodeoResolver API.
- **api-reference/keys.md**: All key types.

### Supporting Documentation Files

- **configuration.md**: Capacity, MemoryLimits, hashers.
- **types.md**: Trait definitions, iterators, utilities.
- **errors.md**: Error types, conditions, patterns.
```

--------------------------------

### Get the number of interned strings in Rodeo

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/rodeo.md

The `len` method returns the total count of unique interned strings currently stored. This can be used to monitor the size of the interner.

```rust
pub fn len(&self) -> usize

```

--------------------------------

### with_capacity_and_hasher

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/threaded-rodeo.md

Creates a new ThreadedRodeo with custom capacity and hasher.

```APIDOC
## with_capacity_and_hasher

### Description
Creates a new `ThreadedRodeo` with custom capacity and hasher.

### Parameters
#### Query Parameters
- **capacity** (`Capacity`) - Required - Pre-allocated capacity
- **hash_builder** (`S`) - Required - Custom hash builder

### Returns
`Self`
```

--------------------------------

### Large Workload with Memory Constraint

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/configuration.md

Demonstrates setting up `Rodeo` for a large number of strings while imposing a strict memory limit. This is crucial for managing resources in memory-constrained environments or for large datasets.

```rust
use lasso::{Rodeo, Capacity, MemoryLimits};

// 1 million strings, 2 GB limit
let mut rodeo: Rodeo = Rodeo::with_capacity_and_memory_limits(
    Capacity::for_strings(1_000_000),
    MemoryLimits::for_memory_usage(2 * 1024 * 1024 * 1024),
);

match rodeo.try_get_or_intern("string") {
    Ok(key) => println!("Interned with key: {:?}", key),
    Err(e) => eprintln!("Failed to intern: {}", e),
}
```

--------------------------------

### Get or Intern String

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/threaded-rodeo.md

Retrieves the unique key for a string, interning it if it doesn't exist. Ensures the same key is returned for identical strings, even across different threads.

```rust
pub fn get_or_intern<T>(&self, val: T) -> K
where
    T: AsRef<str>,
```

```rust
use lasso::ThreadedRodeo;
use std::sync::Arc;
use std::thread;

let rodeo = Arc::new(ThreadedRodeo::new());

let r = Arc::clone(&rodeo);
let key1 = rodeo.get_or_intern("hello");
let key2 = thread::spawn(move || r.get_or_intern("hello"))
    .join()
    .unwrap();

assert_eq!(key1, key2); // Same key across threads
```

--------------------------------

### Create ThreadedRodeo with capacity, memory limits, and hasher

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/threaded-rodeo.md

Use `ThreadedRodeo::with_capacity_memory_limits_and_hasher()` for comprehensive configuration, specifying initial capacity, memory limits, and a custom hash builder. This offers maximum control over the rodeo's resource usage and performance.

```rust
pub fn with_capacity_memory_limits_and_hasher<
    K: Key + Hash,
    S: BuildHasher + Clone,
>(
    capacity: Capacity,
    memory_limits: MemoryLimits,
    hash_builder: S,
) -> Self {
    // Implementation details omitted for brevity
    unimplemented!("This is a placeholder for the actual implementation.")
}
```

--------------------------------

### Rodeo::with_capacity_memory_limits_and_hasher

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/rodeo.md

Creates a new Rodeo with custom capacity, memory limits, and hasher.

```APIDOC
## Rodeo::with_capacity_memory_limits_and_hasher

### Description
Creates a new `Rodeo` with custom capacity, memory limits, and hasher.

### Parameters
#### Request Body
- **capacity** (`Capacity`) - Required - Pre-allocated capacity
- **memory_limits** (`MemoryLimits`) - Required - Maximum memory limit
- **hash_builder** (`S`) - Required - Custom hash builder

### Returns
`Self`
```

--------------------------------

### Check for FailedAllocation Error in Rust

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/errors.md

Provides an example of how to check if an error kind is `LassoErrorKind::FailedAllocation`. This error occurs when the system's memory allocator fails to allocate memory.

```rust
if error.kind().is_failed_alloc() {
    // Handle allocation failure
}
```

--------------------------------

### with_capacity_memory_limits_and_hasher

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/threaded-rodeo.md

Creates a new ThreadedRodeo with custom capacity, memory limits, and hasher.

```APIDOC
## with_capacity_memory_limits_and_hasher

### Description
Creates a new `ThreadedRodeo` with custom capacity, memory limits, and hasher.

### Parameters
#### Query Parameters
- **capacity** (`Capacity`) - Required - Pre-allocated capacity
- **memory_limits** (`MemoryLimits`) - Required - Maximum memory limit
- **hash_builder** (`S`) - Required - Custom hash builder

### Returns
`Self`
```

--------------------------------

### get_or_intern

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/api-reference/threaded-rodeo.md

Gets the key for a string, interning it if it does not yet exist. Returns the same key for identical strings. This method is suitable for use across threads due to its shared reference availability.

```APIDOC
## get_or_intern

### Description
Gets the key for a string, interning it if it does not yet exist. Returns the same key for identical strings.

### Method
`get_or_intern`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **val** (`T: AsRef<str>`) - Required - String to intern

### Request Example
```rust
use lasso::ThreadedRodeo;
use std::sync::Arc;
use std::thread;

let rodeo = Arc::new(ThreadedRodeo::new());

let r = Arc::clone(&rodeo);
let key1 = rodeo.get_or_intern("hello");
let key2 = thread::spawn(move || r.get_or_intern("hello"))
    .join()
    .unwrap();

assert_eq!(key1, key2); // Same key across threads
```

### Response
#### Success Response
- **Returns:** `K` - Unique key associated with the string

#### Response Example
(No explicit response body example provided, returns a key of type `K`)

### Error Handling
**Throws:** Panics if the key space is exhausted or memory limits are reached
```

--------------------------------

### Small, Fixed Set of Strings

Source: https://github.com/kixiron/lasso/blob/master/_autodocs/configuration.md

Illustrates creating a `Rodeo` instance with a fixed capacity suitable for a small, known set of strings, like enum-like values. This optimizes memory for predictable workloads.

```rust
use lasso::{Rodeo, MicroSpur, Capacity};

// Exactly 20 enum-like values
let mut rodeo: Rodeo<MicroSpur> = Rodeo::with_capacity(
    Capacity::for_strings(20)
);

rodeo.get_or_intern("red");
rodeo.get_or_intern("green");
rodeo.get_or_intern("blue");
```