rsmarisa

https://docs.rs/rsmarisa/0.4.2/rsmarisa/
Admin
rsmarisa is a Rust port of marisa-trie, providing a static and space-efficient trie data structure...
Tokens:12,854
Snippets:215
Trust Score:9.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Perform Predictive Search

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/trie/struct.Trie.html

Finds all keys that start with the specified query string.

```rust
use rsmarisa::{Trie, Keyset, Agent};

let mut keyset = Keyset::new();
keyset.push_back_str("apple");
keyset.push_back_str("application");

let mut trie = Trie::new();
trie.build(&mut keyset, 0);

let mut agent = Agent::new();
agent.set_query_str("app");

// Find all keys starting with "app"
let mut count = 0;
while trie.predictive_search(&mut agent) {
    count += 1;
}
assert_eq!(count, 2);
```

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

### make_range(begin: usize, end: usize, key_pos: usize) -> Range

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/range/fn.make_range.html

Creates a new Range instance with the specified starting index, ending index, and key position.

```APIDOC
## Function: make_range

### Description
Creates a new Range object with the given values.

### Signature
`pub fn make_range(begin: usize, end: usize, key_pos: usize) -> Range`

### Arguments
- **begin** (usize) - Starting index
- **end** (usize) - Ending index
- **key_pos** (usize) - Key position

### Returns
- **Range** - A new Range with the specified values
```

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

### predictive_search

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/trie/struct.Trie.html

Performs a predictive search to find keys that start with the query string. Call repeatedly to iterate through all matching keys.

```APIDOC
## pub fn predictive_search(&self, agent: &mut Agent) -> bool

### Description
Finds keys that start with the query string. Call repeatedly to get all matching keys.

### Arguments
- **agent** (Agent) - Agent with query set

### Returns
- **bool** - true if a match was found, false if no more matches

### Panics
Panics if the trie is empty (not built)
```

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

### Define the Sortable trait

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/algorithm/sort/trait.Sortable.html

The trait requires implementing get and length methods to support byte-level indexed access.

```rust
pub trait Sortable {
    // Required methods
    fn get(&self, index: usize) -> Option<u8>;
    fn length(&self) -> usize;
}
```

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

### Build a Trie from a Keyset

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/trie/struct.Trie.html

Demonstrates initializing a Keyset, adding strings, and building the Trie structure.

```rust
use rsmarisa::{Trie, Keyset};

// Build a trie
let mut keyset = Keyset::new();
keyset.push_back_str("apple");
keyset.push_back_str("application");
keyset.push_back_str("apply");

let mut trie = Trie::new();
trie.build(&mut keyset, 0);

assert_eq!(trie.num_keys(), 3);
```

```rust
use rsmarisa::{Trie, Keyset};

let mut keyset = Keyset::new();
keyset.push_back_str("hello");
keyset.push_back_str("world");

let mut trie = Trie::new();
trie.build(&mut keyset, 0);
```

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

### Config::new

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/config/struct.Config.html

Creates a new configuration instance with default values.

```APIDOC
## pub fn new() -> Self

### Description
Creates a new configuration with default values.

### Returns
- **Self** - A new Config instance.
```

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

### Key::new

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/key/struct.Key.html

Creates a new empty key instance.

```APIDOC
### pub fn new() -> Self

Creates a new empty key.
```

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

### Keyset::new

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/keyset/struct.Keyset.html

Creates a new empty keyset.

```APIDOC
## pub fn new() -> Self

### Description
Creates a new empty keyset.
```

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

### Config::parse

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/config/struct.Config.html

Parses configuration settings from provided bit flags.

```APIDOC
## pub fn parse(&mut self, config_flags: i32)

### Description
Parses configuration from flags. Note that this method may panic if invalid flags are provided.

### Parameters
- **config_flags** (i32) - Required - Bit flags specifying configuration options.
```

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

### Config::flags

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/config/struct.Config.html

Returns the current configuration settings as bit flags.

```APIDOC
## pub fn flags(&self) -> i32

### Description
Returns the configuration as bit flags.

### Returns
- **i32** - Integer containing all configuration settings as bit flags.
```

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

### FlatVector Methods

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/vector/flat_vector/struct.FlatVector.html

Methods for creating, building, and interacting with a FlatVector instance.

```APIDOC
## pub fn new() -> Self
Creates a new empty flat vector.

## pub fn build(&mut self, values: &Vector<u32>)
Builds the flat vector from a vector of values, determining the optimal bit-width.
- **values**: Vector of u32 values to store

## pub fn get(&self, i: usize) -> u32
Returns the value at the given index.
- **i**: Index of the value to retrieve
- **Returns**: The value at index i
- **Panics**: Panics if i >= size()

## pub fn value_size(&self) -> usize
Returns the number of bits per value.

## pub fn mask(&self) -> u32
Returns the mask used for extracting values.

## pub fn empty(&self) -> bool
Returns true if the vector is empty.

## pub fn size(&self) -> usize
Returns the number of values stored.

## pub fn total_size(&self) -> usize
Returns the total size in bytes.

## pub fn io_size(&self) -> usize
Returns the I/O size needed for serialization.

## pub fn clear(&mut self)
Clears the flat vector.

## pub fn swap(&mut self, other: &mut FlatVector)
Swaps the contents of two flat vectors.
```

```APIDOC
## pub fn map(&mut self, mapper: &mut Mapper) -> Result<()>
Maps the flat vector from a mapper.
- **mapper**: Mapper to read from
- **Errors**: Returns an error if mapping fails or if value_size > 32.

## pub fn read(&mut self, reader: &mut Reader<'_>) -> Result<()>
Reads the flat vector from a reader.
- **reader**: Reader to read from
- **Errors**: Returns an error if reading fails or if value_size > 32.

## pub fn write(&self, writer: &mut Writer<'_>) -> Result<()>
Writes the flat vector to a writer.
- **writer**: Writer to write to
- **Errors**: Returns an error if writing fails.
```

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

### Header::new

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/header/struct.Header.html

Creates a new instance of the Header struct.

```APIDOC
### pub fn new() -> Self

Creates a new header instance.
```

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

### Key::set_str

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/key/struct.Key.html

Sets the string content for the key.

```APIDOC
### pub fn set_str(&mut self, bytes: &'a [u8])

Sets the string content.

#### Arguments
- **bytes** (&[u8]) - Byte slice to use as the key

#### Panics
Panics if bytes.len() > u32::MAX
```

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

### Config::swap

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/config/struct.Config.html

Swaps the contents of two configuration instances.

```APIDOC
## pub fn swap(&mut self, other: &mut Config)

### Description
Swaps the contents of two configurations.

### Parameters
- **other** (&mut Config) - Required - The other configuration instance to swap with.
```

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

### Key::as_bytes

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/key/struct.Key.html

Returns a pointer to the string data.

```APIDOC
### pub fn as_bytes(&self) -> &[u8]

Returns a pointer to the string data.
```

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

### Keyset::push_back_str

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/keyset/struct.Keyset.html

Adds a string to the keyset with a default weight of 1.0.

```APIDOC
## pub fn push_back_str(&mut self, s: &str) -> Result<()>

### Description
Adds a string to the keyset with default weight of 1.0.
```

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

### Keyset::get

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/keyset/struct.Keyset.html

Returns a reference to the key at the specified index.

```APIDOC
## pub fn get(&self, i: usize) -> &Key

### Description
Returns a reference to the key at the specified index. Panics if index is out of bounds.
```

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

### Config::clear

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/config/struct.Config.html

Resets the configuration to its default state.

```APIDOC
## pub fn clear(&mut self)

### Description
Clears the configuration to default values.
```

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

### Key::get

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/key/struct.Key.html

Returns the byte at the specified index.

```APIDOC
### pub fn get(&self, i: usize) -> u8

Returns the byte at the given index.

#### Arguments
- **i** (usize) - Index into the key string

#### Panics
Panics if i >= length()
```

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

### Perform Trie Lookups

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/trie/struct.Trie.html

Using an Agent to verify the existence of keys within a built Trie.

```rust
use rsmarisa::{Trie, Keyset, Agent};

let mut keyset = Keyset::new();
keyset.push_back_str("apple");

let mut trie = Trie::new();
trie.build(&mut keyset, 0);

let mut agent = Agent::new();
agent.set_query_str("apple");
assert!(trie.lookup(&mut agent));

agent.set_query_str("orange");
assert!(!trie.lookup(&mut agent));
```

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

### pub fn popcount(x: u64) -> usize

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/vector/pop_count/fn.popcount.html

Counts the number of set bits in a 64-bit value using hardware-optimized instructions.

```APIDOC
## Function: popcount

### Description
Counts the number of set bits in a 64-bit value. This function uses Rust's built-in count_ones() which is optimized to use the hardware POPCNT instruction when available.

### Signature
`pub fn popcount(x: u64) -> usize`

### Arguments
- **x** (u64) - The value to count bits in.

### Returns
- **usize** - The number of bits set to 1.
```

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

### Key::set_weight

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/key/struct.Key.html

Sets the weight for the key.

```APIDOC
### pub fn set_weight(&mut self, weight: f32)

Sets the weight.
```

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

### Keyset::push_back_key

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/keyset/struct.Keyset.html

Adds a key to the keyset.

```APIDOC
## pub fn push_back_key(&mut self, key: &Key)

### Description
Adds a key to the keyset.
```

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

### StringComparer::compare

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/entry/struct.StringComparer.html

Compares two entries by their string content in reverse order.

```APIDOC
## pub fn compare(lhs: &Entry<'_>, rhs: &Entry<'_>) -> bool

### Description
Compares two entries by their string content. Returns true if lhs > rhs, facilitating descending order sorting.

### Parameters
- **lhs** (&Entry) - Required - The first entry to compare.
- **rhs** (&Entry) - Required - The second entry to compare.

### Returns
- **bool** - Returns true if the left-hand side entry is greater than the right-hand side entry in reverse string order.
```

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

### Key::weight

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/key/struct.Key.html

Returns the weight of the key.

```APIDOC
### pub fn weight(&self) -> f32

Returns the weight (if set).

#### Panics
Panics if terminal was set instead of weight
```

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

### ReverseKey Methods

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/key/struct.ReverseKey.html

Public methods available for the ReverseKey struct.

```APIDOC
## pub fn new() -> Self
Creates a new empty reverse key.

## pub fn get(&self, i: usize) -> u8
Returns the byte at the given reverse index. Panics if i >= length().

## pub fn substr(&mut self, pos: usize, length: usize)
Creates a reverse substring. Panics if pos or length are out of bounds.

## pub fn set_str(&mut self, bytes: &'a [u8])
Sets the string content. Panics if bytes.len() > u32::MAX.

## pub fn set_weight(&mut self, weight: f32)
Sets the weight.

## pub fn set_terminal(&mut self, terminal: usize)
Sets the terminal position. Panics if terminal > u32::MAX.

## pub fn set_id(&mut self, id: usize)
Sets the key ID. Panics if id > u32::MAX.

## pub fn as_bytes(&self) -> &[u8]
Returns the forward byte slice.

## pub fn length(&self) -> usize
Returns the length of the key.

## pub fn weight(&self) -> f32
Returns the weight (if set). Panics if terminal was set instead of weight.

## pub fn terminal(&self) -> usize
Returns the terminal position (if set). Panics if weight was set instead of terminal.

## pub fn id(&self) -> usize
Returns the key ID.
```

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

### Entry Struct Definition

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/entry/struct.Entry.html

The primary structure definition for Entry.

```rust
pub struct Entry<'a> { /* private fields */ }
```

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

### pub fn popcount_u32(x: u32) -> usize

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/vector/pop_count/fn.popcount_u32.html

Counts the number of set bits in a 32-bit value.

```APIDOC
## Function: popcount_u32

### Description
Counts the number of set bits (1s) in a 32-bit unsigned integer.

### Signature
`pub fn popcount_u32(x: u32) -> usize`

### Arguments
- **x** (u32) - The value to count bits in.

### Returns
- **usize** - The number of bits set to 1 in the provided value.
```

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

### Key::substr

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/key/struct.Key.html

Creates a substring of the current key.

```APIDOC
### pub fn substr(&mut self, pos: usize, length: usize)

Creates a substring of this key.

#### Arguments
- **pos** (usize) - Starting position
- **length** (usize) - Length of substring

#### Panics
Panics if pos or length are out of bounds
```

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

### Key::length

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/key/struct.Key.html

Returns the length of the key.

```APIDOC
### pub fn length(&self) -> usize

Returns the length of the key.
```

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

### Load Trie from File or Memory

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/trie/struct.Trie.html

Methods for loading trie data from external files or static memory buffers.

```rust
use rsmarisa::Trie;

let mut trie = Trie::new();
trie.mmap("dictionary.marisa").unwrap();
```

```rust
use rsmarisa::Trie;

static TRIE_DATA: &[u8] = include_bytes!("dictionary.marisa");

let mut trie = Trie::new();
trie.map(TRIE_DATA).unwrap();
```

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

### Key::set_id

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/key/struct.Key.html

Sets the key ID.

```APIDOC
### pub fn set_id(&mut self, id: usize)

Sets the key ID.

#### Panics
Panics if id > u32::MAX
```

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

### LoudsTrie Methods

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/louds_trie/struct.LoudsTrie.html

Public methods available for the LoudsTrie structure.

```APIDOC
## new()
Creates a new empty LOUDS trie.

## build(keyset: &mut Keyset, flags: i32)
Builds the trie from a provided keyset using specified configuration flags.

## map(data: &'static [u8]) -> Result<()>
Maps the trie from static memory. Returns an error if mapping fails.

## mmap(filename: &str) -> Result<()>
Maps the trie from a file using memory mapping. Requires the 'mmap' feature.

## lookup(agent: &mut Agent) -> bool
Looks up a key in the trie. Returns true if the query string exists as a complete key. Panics if agent state is not initialized.

## common_prefix_search(agent: &mut Agent) -> bool
Finds all keys that are prefixes of the query string. Call repeatedly to iterate through matches.

## predictive_search(agent: &mut Agent) -> bool
Finds all keys that start with the query string. Call repeatedly to iterate through matches.
```

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

### Define Config struct

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/config/struct.Config.html

The internal structure definition for trie configuration.

```rust
pub struct Config { /* private fields */ }
```

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

### Perform Common Prefix Search

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/trie/struct.Trie.html

Finds keys that are prefixes of the query string by calling the method repeatedly.

```rust
use rsmarisa::{Trie, Keyset, Agent};

let mut keyset = Keyset::new();
keyset.push_back_str("app");
keyset.push_back_str("apple");

let mut trie = Trie::new();
trie.build(&mut keyset, 0);

let mut agent = Agent::new();
agent.set_query_str("application");

// Find all prefixes - only "app" is a prefix of "application"
// Note: "apple" is NOT a prefix of "application"
assert!(trie.common_prefix_search(&mut agent));
assert_eq!(std::str::from_utf8(agent.key().as_bytes()).unwrap(), "app");
assert!(!trie.common_prefix_search(&mut agent)); // No more matches
```

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

### Key::terminal

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/key/struct.Key.html

Returns the terminal position of the key.

```APIDOC
### pub fn terminal(&self) -> usize

Returns the terminal position (if set).

#### Panics
Panics if weight was set instead of terminal
```

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

### Define Keyset struct

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/keyset/struct.Keyset.html

The internal structure definition for Keyset.

```rust
pub struct Keyset { /* private fields */ }
```

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

### Key::id

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/key/struct.Key.html

Returns the key ID.

```APIDOC
### pub fn id(&self) -> usize

Returns the key ID.
```

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

### make_weighted_range(begin: usize, end: usize, key_pos: usize, weight: f32) -> WeightedRange

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/range/fn.make_weighted_range.html

Creates a new WeightedRange with the given values.

```APIDOC
## make_weighted_range

### Description
Creates a new WeightedRange with the given values.

### Signature
`pub fn make_weighted_range(begin: usize, end: usize, key_pos: usize, weight: f32) -> WeightedRange`

### Arguments
- **begin** (usize) - Starting index
- **end** (usize) - Ending index
- **key_pos** (usize) - Key position
- **weight** (f32) - Weight value

### Returns
- **WeightedRange** - A new WeightedRange with the specified values
```

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

### make_range function signature

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/range/fn.make_range.html

The function signature for creating a new Range instance.

```rust
pub fn make_range(begin: usize, end: usize, key_pos: usize) -> Range
```

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

### Header::bytes

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/header/struct.Header.html

Returns a copy of the raw header bytes.

```APIDOC
### pub fn bytes() -> [u8; 16]

Returns a 16-byte array containing the header.
```

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

### Accessing the CONFIG constant

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/base/config_mask/constant.CONFIG.html

Represents the bitmask used for all configuration bits.

```rust
pub const CONFIG: u32 = 0xFFFFF;
```

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

### make_weighted_range function signature

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/range/fn.make_weighted_range.html

Displays the function signature for creating a new WeightedRange.

```rust
pub fn make_weighted_range(
    begin: usize,
    end: usize,
    key_pos: usize,
    weight: f32,
) -> WeightedRange
```

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

### Keyset::num_keys

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/keyset/struct.Keyset.html

Returns the number of keys in the keyset.

```APIDOC
## pub fn num_keys(&self) -> usize

### Description
Returns the number of keys in the keyset.
```

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

### ReverseKey Definition

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/key/struct.ReverseKey.html

The structure definition for ReverseKey.

```rust
pub struct ReverseKey<'a> { /* private fields */ }
```

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

### Trie Metadata Methods

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/trie/struct.Trie.html

Methods to retrieve information about the trie structure, size, and configuration.

```APIDOC
## Metadata Methods

- **num_tries() -> usize**: Returns the number of trie levels.
- **num_keys() -> usize**: Returns the number of keys in the trie.
- **num_nodes() -> usize**: Returns the number of nodes in the trie.
- **tail_mode() -> TailMode**: Returns the tail storage mode.
- **node_order() -> NodeOrder**: Returns the node ordering mode.
- **empty() -> bool**: Checks if the trie is empty.
- **size() -> usize**: Returns the number of keys.
- **total_size() -> usize**: Returns the total memory size in bytes.
- **io_size() -> usize**: Returns the I/O size for serialization.

### Panics
All methods panic if the trie is empty (not built), except empty() which panics if the trie is not built.
```

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

### NumTries constants

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/base/struct.NumTries.html

Constants defining the minimum, maximum, and default number of tries allowed.

```rust
pub const MIN: u32 = 0x00001
pub const MAX: u32 = 0x0007F
pub const DEFAULT: u32 = 0x00003
```

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

### Key::set_terminal

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/key/struct.Key.html

Sets the terminal position for the key.

```APIDOC
### pub fn set_terminal(&mut self, terminal: usize)

Sets the terminal position.

#### Panics
Panics if terminal > u32::MAX
```

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

### select_bit_u64

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/vector/select_bit/fn.select_bit_u64.html

Finds the position of the i-th set bit in a 64-bit unit.

```APIDOC
## Function: select_bit_u64

### Description
Finds the absolute position of the i-th set bit within a 64-bit unit.

### Signature
`pub fn select_bit_u64(i: usize, bit_id: usize, unit: u64) -> usize`

### Arguments
- **i** (usize) - The rank of the bit to find (0-indexed).
- **bit_id** (usize) - The starting bit position for this unit.
- **unit** (u64) - The 64-bit value to search.

### Returns
- **usize** - The absolute position of the i-th set bit.
```

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

### select_bit_u64

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/vector/select_bit/index.html

Finds the position of the i-th set bit in a 64-bit unit.

```APIDOC
## select_bit_u64

### Description
Finds the position of the i-th set bit in a 64-bit unit. On supported x86_64 hardware, this operation utilizes the PDEP instruction for optimized performance.
```

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

### Range API

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/range/struct.Range.html

Methods for interacting with the Range struct to manage key segment indices and positions.

```APIDOC
## Range Struct Methods

### new()
Creates a new Range instance with all fields initialized to zero.

### set_begin(begin: usize)
Sets the beginning index of the range. Panics if the value exceeds u32::MAX.

### set_end(end: usize)
Sets the ending index of the range. Panics if the value exceeds u32::MAX.

### set_key_pos(key_pos: usize)
Sets the current position within the key string. Panics if the value exceeds u32::MAX.

### begin() -> usize
Returns the current beginning index.

### end() -> usize
Returns the current ending index.

### key_pos() -> usize
Returns the current key position.
```

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

### pub fn sort<T: Sortable>(data: &mut [T]) -> usize

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/algorithm/sort/fn.sort.html

Sorts a slice of sortable elements and returns the count of unique string prefixes.

```APIDOC
## Function: sort

### Description
Sorts a slice of sortable elements. This function implements a depth-based string sorting algorithm optimized for trie construction.

### Signature
`pub fn sort<T: Sortable>(data: &mut [T]) -> usize`

### Arguments
- **data** (&mut [T]) - A mutable slice of elements to sort.

### Returns
- **usize** - The count of unique string prefixes found during sorting.
```

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

### BitVector Operations

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/vector/bit_vector/struct.BitVector.html

Methods for managing, querying, and serializing bit vectors.

```APIDOC
## BitVector Methods

### new()
Creates a new empty bit vector.

### push_back(bit: bool)
Pushes a bit onto the end of the vector. Panics if size exceeds u32::MAX.

### get(i: usize) -> bool
Returns the bit at the given index. Panics if i >= size().

### rank0(i: usize) -> usize
Returns the number of 0-bits in the range [0, i). Panics if index is out of bounds.

### rank1(i: usize) -> usize
Returns the number of 1-bits in the range [0, i). Panics if index is out of bounds.

### select0(i: usize) -> usize
Returns the position of the i-th 0-bit. Panics if index is out of bounds.

### select1(i: usize) -> usize
Returns the position of the i-th 1-bit. Panics if index is out of bounds.

### build(enables_select0: bool, enables_select1: bool)
Builds the rank and select indices. Must be called before using rank or select operations.

### read(reader: &mut Reader) -> Result<()>
Reads the bit vector from a reader.

### write(writer: &mut Writer) -> Result<()>
Writes the bit vector to a writer.
```

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

### Perform Reverse Lookup

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/trie/struct.Trie.html

Retrieving a key from the Trie using its associated ID via an Agent.

```rust
use rsmarisa::{Trie, Keyset, Agent};

let mut keyset = Keyset::new();
keyset.push_back_str("apple");
keyset.push_back_str("banana");

let mut trie = Trie::new();
trie.build(&mut keyset, 0);
```

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

### Header::io_size

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/header/struct.Header.html

Returns the size of the header in bytes.

```APIDOC
### pub fn io_size(&self) -> usize

Returns the size in bytes (always HEADER_SIZE).
```

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

### common_prefix_search

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/trie/struct.Trie.html

Performs a common prefix search to find keys that are prefixes of the query string. Call repeatedly to iterate through all matching prefixes.

```APIDOC
## pub fn common_prefix_search(&self, agent: &mut Agent) -> bool

### Description
Finds keys that are prefixes of the query string. Call repeatedly to get all matching prefixes.

### Arguments
- **agent** (Agent) - Agent with query set

### Returns
- **bool** - true if a match was found, false if no more matches

### Panics
Panics if the trie is empty (not built)
```

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

### Header::write

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/header/struct.Header.html

Writes the current header data to a provided writer.

```APIDOC
### pub fn write(&self, writer: &mut Writer<'_>) -> Result<()>

Writes the header to a writer. Returns an error if writing fails.
```

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

### Header::read

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/header/struct.Header.html

Reads the header data from a provided reader.

```APIDOC
### pub fn read(&mut self, reader: &mut Reader<'_>) -> Result<()>

Reads the header from a reader. Returns an error if the header is invalid or reading fails.
```

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

### Perform Reverse Lookup

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/trie/struct.Trie.html

Retrieves the key associated with a specific ID using an Agent.

```rust
let mut agent = Agent::new();
agent.set_query_id(0);
trie.reverse_lookup(&mut agent);
// agent.key() now contains the key for ID 0
```

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

### Query Struct Definition

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/query/struct.Query.html

The internal structure of the Query type.

```rust
pub struct Query { /* private fields */ }
```

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

### Compare entries by ID

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/entry/struct.IDComparer.html

Compares two entries and returns true if the left-hand side ID is less than the right-hand side ID.

```rust
pub fn compare(lhs: &Entry<'_>, rhs: &Entry<'_>) -> bool
```

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

### Header::map

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/header/struct.Header.html

Maps the header from a mapper, typically used for memory-mapped I/O operations.

```APIDOC
### pub fn map(&mut self, mapper: &mut Mapper) -> Result<()>

Maps the header from a mapper. Returns an error if the header is invalid or mapping fails.
```

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

### select_bit_u64 function signature

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/vector/select_bit/fn.select_bit_u64.html

The function signature for finding the position of the i-th set bit in a 64-bit unit.

```rust
pub fn select_bit_u64(i: usize, bit_id: usize, unit: u64) -> usize
```

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

### Header::validate

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/header/struct.Header.html

Validates a byte slice to determine if it represents a valid MARISA header.

```APIDOC
### pub fn validate(bytes: &[u8]) -> bool

Validates a byte slice as a valid header. Returns true if the bytes represent a valid MARISA header.
```

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

### Default::default

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/vector/bit_vector/struct.BitVector.html

Returns the default value for the BitVector type.

```APIDOC
## fn default() -> BitVector

### Description
Returns the "default value" for the BitVector type.
```

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

### popcount

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/vector/pop_count/index.html

Counts the number of set bits in a 64-bit value.

```APIDOC
## fn popcount(value: u64) -> u32

### Description
Counts the number of set bits in a 64-bit unsigned integer.

### Parameters
- **value** (u64) - The 64-bit integer to evaluate.

### Returns
- (u32) - The count of set bits.
```

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

### Trie Mutation Methods

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/trie/struct.Trie.html

Methods to modify or reset the state of the trie.

```APIDOC
## Mutation Methods

- **clear(&mut self)**: Clears the trie.
- **swap(&mut self, other: &mut Trie)**: Swaps with another trie.
```

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

### popcount function signature

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/vector/pop_count/fn.popcount.html

The function signature for counting set bits in a 64-bit unsigned integer.

```rust
pub fn popcount(x: u64) -> usize
```

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

### WORD_SIZE constant definition

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/base/constant.WORD_SIZE.html

The constant is defined as a 64-bit unsigned integer, ensuring consistent dictionary format across different CPU architectures.

```rust
pub const WORD_SIZE: usize = 64;
```

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

### Define IDComparer struct

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/entry/struct.IDComparer.html

The definition of the IDComparer unit struct.

```rust
pub struct IDComparer;
```

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

### HEADER_SIZE Constant Definition

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/header/constant.HEADER_SIZE.html

Represents the size of the header in bytes for the trie structure.

```rust
pub const HEADER_SIZE: usize = 16;
```

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

### popcount_u32

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/vector/pop_count/index.html

Counts the number of set bits in a 32-bit value.

```APIDOC
## fn popcount_u32(value: u32) -> u32

### Description
Counts the number of set bits in a 32-bit unsigned integer.

### Parameters
- **value** (u32) - The 32-bit integer to evaluate.

### Returns
- (u32) - The count of set bits.
```

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

### Define NODE_ORDER constant

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/base/config_mask/constant.NODE_ORDER.html

This constant represents the bitmask for extracting node order information.

```rust
pub const NODE_ORDER: u32 = 0xF0000;
```

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

### popcount_u32 function signature

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/vector/pop_count/fn.popcount_u32.html

The function signature for counting set bits in a 32-bit unsigned integer.

```rust
pub fn popcount_u32(x: u32) -> usize
```

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

### sort

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/algorithm/sort/index.html

Sorts a slice of elements that implement the Sortable trait.

```APIDOC
## Function: sort

### Description
Sorts a slice of sortable elements using a hybrid approach of quicksort and insertion sort, optimized for trie construction.

### Signature
`pub fn sort<T: Sortable>(elements: &mut [T])`

### Parameters
- **elements** (&mut [T]) - Required - A mutable slice of elements that implement the Sortable trait to be sorted in-place.
```

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

### Define NumTries struct

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/base/struct.NumTries.html

The core definition of the NumTries struct wrapping a u32 value.

```rust
pub struct NumTries(pub u32);
```

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

### Define Unit type alias

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/vector/pop_count/type.Unit.html

Represents the 64-bit word size used for bit vectors, consistent across all target platforms.

```rust
pub type Unit = u64;
```

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

### SELECT_TABLE Constant Definition

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/vector/select_tables/constant.SELECT_TABLE.html

The constant is defined as a 2D array of bytes used for bit manipulation lookups.

```rust
pub const SELECT_TABLE: [[u8; 256]; 8];
```

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

### popcount_unit function signature

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/vector/pop_count/fn.popcount_unit.html

The function signature for counting set bits in a Unit.

```rust
pub fn popcount_unit(x: Unit) -> usize
```

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

### NUM_TRIES Constant Definition

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/base/config_mask/constant.NUM_TRIES.html

Defines the bitmask for extracting the number of tries from bits 0-6.

```rust
pub const NUM_TRIES: u32 = 0x0007F;
```

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

### INVALID_KEY_ID Constant Definition

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/base/constant.INVALID_KEY_ID.html

Represents an invalid key identifier using the maximum value of a u32.

```rust
pub const INVALID_KEY_ID: u32 = u32::MAX; // 4_294_967_295u32
```

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

### Sort function signature

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/algorithm/sort/fn.sort.html

The function requires a mutable slice of elements that implement the Sortable trait.

```rust
pub fn sort<T: Sortable>(data: &mut [T]) -> usize
```

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

### Define CACHE_LEVEL constant

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/base/config_mask/constant.CACHE_LEVEL.html

The constant is defined as a u32 value representing a bitmask for cache level extraction.

```rust
pub const CACHE_LEVEL: u32 = 0x00F80;
```

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

### Define History struct

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/history/struct.History.html

The definition of the History struct used for recording trie traversal state.

```rust
pub struct History { /* private fields */ }
```

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

### StatusCode Enum Definition

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/trie/state/enum.StatusCode.html

The definition of the StatusCode enum, which tracks the state of search operations.

```rust
pub enum StatusCode {
    ReadyToAll,
    ReadyToCommonPrefixSearch,
    ReadyToPredictiveSearch,
    EndOfCommonPrefixSearch,
    EndOfPredictiveSearch,
}
```

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

### ErrorCode Enum Definition

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/base/enum.ErrorCode.html

The primary enumeration defining error codes used across the library.

```rust
pub enum ErrorCode {
    Ok = 0,
    StateError = 1,
    NullError = 2,
    BoundError = 3,
    RangeError = 4,
    CodeError = 5,
    ResetError = 6,
    SizeError = 7,
    MemoryError = 8,
    IoError = 9,
    FormatError = 10,
}
```

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

### INVALID_EXTRA Constant Definition

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/base/constant.INVALID_EXTRA.html

Represents the invalid extra value constant, calculated as UINT32_MAX >> 8.

```rust
pub const INVALID_EXTRA: u32 = _; // 16_777_215u32
```

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

### popcount_unit

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/grimoire/vector/pop_count/index.html

Counts the number of set bits in a Unit value.

```APIDOC
## fn popcount_unit(value: Unit) -> u32

### Description
Counts the number of set bits in a Unit type value.

### Parameters
- **value** (Unit) - The Unit type value to evaluate.

### Returns
- (u32) - The count of set bits.
```

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

### INVALID_LINK_ID Constant Definition

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/base/constant.INVALID_LINK_ID.html

This constant is defined as u32::MAX, which is 4,294,967,295.

```rust
pub const INVALID_LINK_ID: u32 = u32::MAX; // 4_294_967_295u32
```

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

### TAIL_MODE Constant Definition

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/base/config_mask/constant.TAIL_MODE.html

The constant represents a bitmask for extracting tail mode bits.

```rust
pub const TAIL_MODE: u32 = 0x0F000;
```

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

### Define CacheLevel Enum

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/base/enum.CacheLevel.html

The CacheLevel enum represents different cache sizes, with Normal serving as the default value.

```rust
#[repr(u32)]
pub enum CacheLevel {
    Huge = 128,
    Large = 256,
    Normal = 512,
    Small = 1_024,
    Tiny = 2_048,
}
```

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

### Define NodeOrder Enum

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/base/enum.NodeOrder.html

The NodeOrder enum uses a u32 representation to define node arrangement strategies.

```rust
#[repr(u32)]
pub enum NodeOrder {
    Label = 65_536,
    Weight = 131_072,
}
```

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

### TailMode Enum Definition

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/base/enum.TailMode.html

The TailMode enum defines the storage strategy for suffixes, with variants for text and binary data.

```rust
#[repr(u32)]
pub enum TailMode {
    TextTail = 4_096,
    BinaryTail = 8_192,
}
```

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

### Define MapFlags struct

Source: https://docs.rs/rsmarisa/0.4.2/rsmarisa/base/struct.MapFlags.html

The primary definition of the MapFlags struct as a tuple struct containing a u32.

```rust
pub struct MapFlags(pub u32);
```
Tokens:
Raw