LLGuidance

https://docs.rs/llguidance/1.7.0/llguidance/
Admin
LLGuidance is a Rust crate for constrained decoding that enforces context-free grammars on LLM...
Tokens:132,756
Snippets:1,060
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Set Start Node

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.GrammarBuilder.html

Designates a specific node as the starting point for grammar parsing.

```rust
pub fn set_start_node(&mut self, node: NodeRef)
```

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

### Option::default Example

Source: https://docs.rs/llguidance/1.7.0/llguidance/ffi/type.LlgCallback.html

Illustrates how to get the default value for an Option<T>, which is always None.

```rust
let opt: Option<u32> = Option::default();
assert!(opt.is_none());
```

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

### Get the start index of ParamRef

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.ParamRef.html

Returns the starting bit index of the parameter reference.

```rust
pub fn start(&self) -> BitIdx
```

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

### HashMap Get Method

Source: https://docs.rs/llguidance/1.7.0/llguidance/type.HashMap.html

Illustrates the usage of the `get` method to retrieve a reference to a value associated with a given key.

```APIDOC
## GET /api/users/{userId}

### Description
Retrieves the details of a specific user identified by their unique ID.

### Method
GET

### Endpoint
/api/users/{userId}

### Parameters
#### Path Parameters
- **userId** (string) - Required - The unique identifier of the user to retrieve.

#### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to include in the response.

### Response
#### Success Response (200 OK)
- **id** (string) - The unique identifier for the user.
- **username** (string) - The username of the user.
- **email** (string) - The email address of the user.
- **createdAt** (string) - The timestamp when the user was created (ISO 8601 format).

#### Response Example
```json
{
  "id": "user-12345",
  "username": "johndoe",
  "email": "john.doe@example.com",
  "createdAt": "2023-10-27T10:00:00Z"
}
```
```

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

### Initialize LlgTokenizerInitV2

Source: https://docs.rs/llguidance/1.7.0/llguidance/ffi/struct.LlgTokenizerInitV2.html

Example initialization of the LlgTokenizerInitV2 struct. Ensure `struct_size` is set to `sizeof(init)` for forward compatibility.

```c
LlgTokenizerInitV2 init = {};
init.struct_size = sizeof(init);

```

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

### Option::reduce Example

Source: https://docs.rs/llguidance/1.7.0/llguidance/ffi/type.LlgCallback.html

Demonstrates the usage of the `reduce` method on Option<T> with a binary function. Requires the `option_reduce` feature.

```rust
#![feature(option_reduce)]

let s12 = Some(12);
let s17 = Some(17);
let n = None;
let f = |a, b| a + b;

assert_eq!(s12.reduce(s17, f), Some(29));
assert_eq!(s12.reduce(n, f), Some(12));
assert_eq!(n.reduce(s17, f), Some(17));
assert_eq!(n.reduce(n, f), None);
```

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

### Option::from_iter with Checked Addition

Source: https://docs.rs/llguidance/1.7.0/llguidance/ffi/type.LlgCallback.html

Example of collecting an iterator of Option<T> into an Option<Collection<T>> using `from_iter`. If any element is None, the entire result is None. This example uses checked addition.

```rust
let items = vec![0_u16, 1, 2];

let res: Option<Vec<u16>> = items
    .iter()
    .map(|x| x.checked_add(1))
    .collect();

assert_eq!(res, Some(vec![1, 2, 3]));
```

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

### Option::from Example

Source: https://docs.rs/llguidance/1.7.0/llguidance/ffi/type.LlgCallback.html

Demonstrates converting a value of type T into an Option<T> using the `from` function.

```rust
let o: Option<u8> = Option::from(67);

assert_eq!(Some(67), o);
```

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

### Trie Iteration Start: trie_started

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.ParserRecognizer.html

Callback function invoked when iteration over the trie begins.

```rust
fn trie_started(&mut self, lbl: &str)
Called when iteration over the trie is started
```

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

### Start Constraint Without Prompt

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.Constraint.html

Initializes the constraint state machine without processing an initial prompt.

```rust
pub fn start_without_prompt(&mut self)>
```

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

### Get Hidden Start Index

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.Parser.html

Returns the starting index of hidden tokens in the parser.

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

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

### llguidance::ffi - llg_constraint_init_set_defaults

Source: https://docs.rs/llguidance/1.7.0/llguidance/ffi/fn.llg_constraint_init_set_defaults.html

Initializes LlgConstraintInit with default values and configures logging.

```APIDOC
## llg_constraint_init_set_defaults

### Description
Sets the default values for the ConstraintInit. This function disables ff_tokens and backtracking, enables warnings on stderr, and directs all logging to the buffer (which can be retrieved using llg_flush_logs()). The tokenizer field must be set manually.

### Method
C Function (extern "C")

### Endpoint
N/A (This is a function call, not a network endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
// Assuming init is a mutable pointer to LlgConstraintInit and tokenizer is a pointer to LlgTokenizer
llg_constraint_init_set_defaults(init, tokenizer);
```

### Response
#### Success Response (void)
This function does not return a value.

#### Response Example
N/A
```

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

### HashSet Initialization Methods

Source: https://docs.rs/llguidance/1.7.0/llguidance/type.HashSet.html

Methods for creating a new HashSet with custom hashers and capacities.

```APIDOC
## with_hasher(hasher: S) -> HashSet<T, S>

### Description
Creates a new empty hash set which will use the given hasher to hash keys. The hash set is created with the default initial capacity.

### Parameters
- **hasher** (S) - Required - The hasher to use for keys.

## with_capacity_and_hasher(capacity: usize, hasher: S) -> HashSet<T, S>

### Description
Creates an empty HashSet with at least the specified capacity, using the provided hasher.

### Parameters
- **capacity** (usize) - Required - The initial capacity of the set.
- **hasher** (S) - Required - The hasher to use for keys.
```

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

### Get Type ID: type_id

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.ParserRecognizer.html

Gets the `TypeId` of the current type. This is part of the `Any` trait implementation.

```rust
fn type_id(&self) -> TypeId
Gets the `TypeId` of `self`. Read more
```

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

### Parser Initialization

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.Parser.html

Creates a new instance of the Parser.

```APIDOC
## pub fn new(tok_env: TokEnv, grammar: Arc<CGrammar>, limits: ParserLimits, perf_counters: Arc<ParserPerfCounters>) -> Result<Self>

### Description
Initializes a new Parser instance with the provided environment, grammar, limits, and performance counters.

### Parameters
- **tok_env** (TokEnv) - Required - The token environment.
- **grammar** (Arc<CGrammar>) - Required - The grammar definition.
- **limits** (ParserLimits) - Required - Parsing constraints.
- **perf_counters** (Arc<ParserPerfCounters>) - Required - Performance tracking object.
```

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

### Create ParamRef from start and end indices

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.ParamRef.html

Creates a new ParamRef with the specified start and end bit indices.

```rust
pub fn new(start: BitIdx, end: BitIdx) -> Self
```

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

### Instant Struct Overview

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.Instant.html

Provides a summary and detailed description of the Instant struct, its properties, and guarantees.

```APIDOC
## Struct Instant

### Summary
```rust
pub struct Instant(/* private fields */);
```

### Description
A measurement of a monotonically nondecreasing clock. Opaque and useful only with `Duration`.
Instants are always guaranteed, barring platform bugs, to be no less than any previously measured instant when created, and are often useful for tasks such as measuring benchmarks or timing how long an operation takes.
Note, however, that instants are **not** guaranteed to be **steady**. In other words, each tick of the underlying clock might not be the same length (e.g. some seconds may be longer than others). An instant may jump forwards or experience time dilation (slow down or speed up), but it will never go backwards. As part of this non-guarantee it is also not specified whether system suspends count as elapsed time or not. The behavior varies across platforms and Rust versions.
Instants are opaque types that can only be compared to one another. There is no method to get “the number of seconds” from an instant. Instead, it only allows measuring the duration between two instants (or comparing two instants).
The size of an `Instant` struct may vary depending on the target operating system.
```

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

### Get Value from HashMap

Source: https://docs.rs/llguidance/1.7.0/llguidance/type.HashMap.html

Demonstrates retrieving a reference to a value associated with a key using `get`. Returns `None` if the key is not found.

```rust
use std::collections::HashMap;

let mut map = HashMap::new();
map.insert(1, "a");
assert_eq!(map.get(&1), Some(&"a"));
assert_eq!(map.get(&2), None);
```

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

### Initialize GrammarBuilder

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.GrammarBuilder.html

Creates a new instance of GrammarBuilder. Requires an optional TokEnv and ParserLimits.

```rust
pub fn new(tok_env: Option<TokEnv>, limits: ParserLimits) -> Self>
```

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

### Manage HashMap Capacity

Source: https://docs.rs/llguidance/1.7.0/llguidance/type.HashMap.html

Demonstrates how to initialize a HashMap with a specific capacity and then reduce it using `shrink_to`.

```rust
use std::collections::HashMap;

let mut map: HashMap<i32, i32> = HashMap::with_capacity(100);
map.insert(1, 2);
map.insert(3, 4);
assert!(map.capacity() >= 100);
map.shrink_to(10);
assert!(map.capacity() >= 10);
map.shrink_to(0);
assert!(map.capacity() >= 2);
```

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

### HashMap Get Key-Value Method

Source: https://docs.rs/llguidance/1.7.0/llguidance/type.HashMap.html

Shows how to use `get_key_value` to retrieve both the key and the value associated with a lookup key, useful for complex key types.

```APIDOC
## PUT /api/users/{userId}

### Description
Updates the details of an existing user identified by their unique ID.

### Method
PUT

### Endpoint
/api/users/{userId}

### Parameters
#### Path Parameters
- **userId** (string) - Required - The unique identifier of the user to update.

#### Request Body
- **username** (string) - Optional - The new username for the user.
- **email** (string) - Optional - The new email address for the user.

### Request Example
```json
{
  "email": "john.doe.updated@example.com"
}
```

### Response
#### Success Response (200 OK)
- **id** (string) - The unique identifier for the user.
- **username** (string) - The updated username of the user.
- **email** (string) - The updated email address of the user.
- **updatedAt** (string) - The timestamp when the user was last updated (ISO 8601 format).

#### Response Example
```json
{
  "id": "user-12345",
  "username": "johndoe",
  "email": "john.doe.updated@example.com",
  "updatedAt": "2023-10-27T11:30:00Z"
}
```
```

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

### Option<T> Implementations

Source: https://docs.rs/llguidance/1.7.0/llguidance/ffi/type.LlgTokenizeFn.html

Provides documentation for various implementations of `Option<T>`, including methods for checking the presence of a value (`is_some`, `is_none`), transforming the option (`into_flat_iter`), and accessing references (`as_ref`, `as_mut`).

```APIDOC
## Implementations

### impl<T> Option<T>

#### pub fn into_flat_iter<A>(self) -> OptionFlatten<A>

**Description**: Transforms an optional iterator into an iterator. If `self` is `None`, the resulting iterator is empty. Otherwise, an iterator is made from the `Some` value and returned.

**Note**: This is a nightly-only experimental API.

**Examples**:
```rust
#![feature(option_into_flat_iter)]

let o1 = Some([1, 2]);
let o2 = None::<&[usize]>;

assert_eq!(o1.into_flat_iter().collect::<Vec<_>>(), [1, 2]);
assert_eq!(o2.into_flat_iter().collect::<Vec<_>>(), Vec::<&usize>::new());
```

### impl<T> Option<T>

#### pub const fn is_some(&self) -> bool

**Description**: Returns `true` if the option is a `Some` value.

**Examples**:
```rust
let x: Option<u32> = Some(2);
assert_eq!(x.is_some(), true);

let x: Option<u32> = None;
assert_eq!(x.is_some(), false);
```

#### pub fn is_some_and(self, f: impl FnOnce(T) -> bool) -> bool

**Description**: Returns `true` if the option is a `Some` and the value inside of it matches a predicate.

**Examples**:
```rust
let x: Option<u32> = Some(2);
assert_eq!(x.is_some_and(|x| x > 1), true);

let x: Option<u32> = Some(0);
assert_eq!(x.is_some_and(|x| x > 1), false);

let x: Option<u32> = None;
assert_eq!(x.is_some_and(|x| x > 1), false);

let x: Option<String> = Some("ownership".to_string());
assert_eq!(x.as_ref().is_some_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

#### pub const fn is_none(&self) -> bool

**Description**: Returns `true` if the option is a `None` value.

**Examples**:
```rust
let x: Option<u32> = Some(2);
assert_eq!(x.is_none(), false);

let x: Option<u32> = None;
assert_eq!(x.is_none(), true);
```

#### pub fn is_none_or(self, f: impl FnOnce(T) -> bool) -> bool

**Description**: Returns `true` if the option is a `None` or the value inside of it matches a predicate.

**Examples**:
```rust
let x: Option<u32> = Some(2);
assert_eq!(x.is_none_or(|x| x > 1), true);

let x: Option<u32> = Some(0);
assert_eq!(x.is_none_or(|x| x > 1), false);

let x: Option<u32> = None;
assert_eq!(x.is_none_or(|x| x > 1), true);

let x: Option<String> = Some("ownership".to_string());
assert_eq!(x.as_ref().is_none_or(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

#### pub const fn as_ref(&self) -> Option<&T>

**Description**: Converts from `&Option<T>` to `Option<&T>`.

**Examples**:
Calculates the length of an `Option<String>` as an `Option<usize>` without moving the `String`. The `map` method takes the `self` argument by value, consuming the original, so this technique uses `as_ref` to first take an `Option` to a reference to the value inside the original.
```rust
let text: Option<String> = Some("Hello, world!".to_string());
// First, cast `Option<String>` to `Option<&String>` with `as_ref`,
// then consume *that* with `map`, leaving `text` on the stack.
let text_length: Option<usize> = text.as_ref().map(|s| s.len());
println!("still can print text: {:?}", text);
```

#### pub const fn as_mut(&mut self) -> Option<&mut T>

**Description**: Converts from `&mut Option<T>` to `Option<&mut T>`.

**Examples**:
```rust
let mut x = Some(2);
match x.as_mut() {
    Some(v) => *v = 42,
    None => {},
}
assert_eq!(x, Some(42));
```

#### pub const fn as_pin_ref(self: Pin<&Option<T>>) -> Option<Pin<&T>>

**Description**: Converts from `Pin<&Option<T>>` to `Option<Pin<&T>>`.

#### pub const fn as_pin_mut(self: Pin<&mut Option<T>>) -> Option<Pin<&mut T>>

**Description**: Converts from `Pin<&mut Option<T>>` to `Option<Pin<&mut T>>`.
```

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

### ParserFactory::slicer

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.ParserFactory.html

Gets the slicer component used by the ParserFactory.

```APIDOC
### pub fn slicer(&self) -> Arc<SlicedBiasComputer>

#### Description
Returns an `Arc` pointing to the `SlicedBiasComputer` used for slicing operations within the `ParserFactory`.
```

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

### ParserFactory::create_parser_from_init_ext

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.ParserFactory.html

Creates a TokenParser with extended initialization options.

```APIDOC
### pub fn create_parser_from_init_ext( &self, grammar_init: GrammarInit, logger: Logger, inference_caps: InferenceCapabilities, limits: ParserLimits, ) -> Result<TokenParser>

#### Description
Creates a `TokenParser` with detailed initialization, including custom logger, inference capabilities, and parser limits.
```

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

### ParserFactory::stderr_log_level

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.ParserFactory.html

Gets the current stderr log level.

```APIDOC
### pub fn stderr_log_level(&self) -> u32

#### Description
Returns the current log level for standard error output.
```

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

### ParserFactory::buffer_log_level

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.ParserFactory.html

Gets the current buffer log level.

```APIDOC
### pub fn buffer_log_level(&self) -> u32

#### Description
Returns the current log level for the internal buffer.
```

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

### Option::context Usage

Source: https://docs.rs/llguidance/1.7.0/llguidance/ffi/type.LlgCallback.html

Shows how to use the `context` method to add descriptive information to an Option<T> when converting it to a Result. Requires the `anyhow` crate.

```rust
use anyhow::{Context, Result};

fn maybe_get() -> Option<T> {
    ...
}

fn demo() -> Result<()> {
    let t = maybe_get().context("there is no T")?;
    ...
```

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

### HashMap Creation and Initialization

Source: https://docs.rs/llguidance/1.7.0/llguidance/type.HashMap.html

Provides methods for creating new HashMaps, including default and with capacity.

```APIDOC
## HashMap Creation and Initialization

### `Default::default()`

Creates an empty `HashMap<K, V, S>`, with the `Default` value for the hasher.

### `HashMapExt::new()`

Constructs a new HashMap.

### `HashMapExt::with_capacity(capacity: usize)`

Constructs a new HashMap with a given initial capacity.
```

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

### Get Grammar Warnings

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.Parser.html

Retrieves any warnings generated by the grammar during parsing.

```rust
pub fn grammar_warnings(&mut self) -> Vec<String>
```

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

### Underlying System calls

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.Instant.html

Lists the system calls used by Instant::now() on different platforms.

```APIDOC
## §Underlying System calls

The following system calls are currently being used by `now()` to find out the current time:

Platform| System call  
---|---
SGX| `insecure_time` usercall. More information on timekeeping in SGX  
UNIX| clock_gettime with `CLOCK_MONOTONIC`  
Darwin| clock_gettime with `CLOCK_UPTIME_RAW`  
VXWorks| clock_gettime with `CLOCK_MONOTONIC`  
SOLID| `get_tim`  
WASI| __wasi_clock_time_get with `monotonic`  
Windows| QueryPerformanceCounter  

**Disclaimer:** These system calls might change over time.
```

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

### Get Parser Error

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.Parser.html

Retrieves the last parser error, if any occurred.

```rust
pub fn get_error(&self) -> Option<ParserError>
```

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

### Get Lexer Statistics

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.Parser.html

Returns the statistics from the lexer used by the parser.

```rust
pub fn lexer_stats(&self) -> LexerStats
```

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

### OS-specific behaviors

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.Instant.html

Details on how Instant behaves differently across various operating systems and potential issues with time calculations.

```APIDOC
## §OS-specific behaviors

An `Instant` is a wrapper around system-specific types and it may behave differently depending on the underlying operating system. For example, the following snippet is fine on Linux but panics on macOS:
```rust
use std::time::{Instant, Duration};

let now = Instant::now();
let days_per_10_millennia = 365_2425;
let solar_seconds_per_day = 60 * 60 * 24;
let millennium_in_solar_seconds = 31_556_952_000;
assert_eq!(millennium_in_solar_seconds, days_per_10_millennia * solar_seconds_per_day / 10);

let duration = Duration::new(millennium_in_solar_seconds, 0);
println!("{:?}", now + duration);
```

For cross-platform code, you can comfortably use durations of up to around one hundred years.
```

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

### Create an Instant

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.Instant.html

Basic usage of the now() method to capture the current time.

```rust
use std::time::Instant;

let now = Instant::now();
```

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

### Get Parser Statistics

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.Parser.html

Returns a reference to the parser's statistics.

```rust
pub fn stats(&self) -> &ParserStats
```

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

### Get HashSet Length

Source: https://docs.rs/llguidance/1.7.0/llguidance/type.HashSet.html

Returns the number of elements currently present in the HashSet.

```rust
use std::collections::HashSet;

let mut v = HashSet::new();
assert_eq!(v.len(), 0);
v.insert(1);
assert_eq!(v.len(), 1);
```

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

### OS-Specific Instant Behavior

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.Instant.html

Illustrates potential platform-specific panics when performing arithmetic on Instant objects with large durations.

```rust
use std::time::{Instant, Duration};

let now = Instant::now();
let days_per_10_millennia = 365_2425;
let solar_seconds_per_day = 60 * 60 * 24;
let millennium_in_solar_seconds = 31_556_952_000;
assert_eq!(millennium_in_solar_seconds, days_per_10_millennia * solar_seconds_per_day / 10);

let duration = Duration::new(millennium_in_solar_seconds, 0);
println!("{:?}", now + duration);
```

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

### Initialize HashMap with Capacity and Hasher

Source: https://docs.rs/llguidance/1.7.0/llguidance/type.HashMap.html

Creates an empty HashMap with pre-allocated capacity using a specific hash builder.

```rust
use std::collections::HashMap;
use std::hash::RandomState;

let s = RandomState::new();
let mut map = HashMap::with_capacity_and_hasher(10, s);
map.insert(1, 2);
```

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

### Get Grammar Size

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.GrammarBuilder.html

Returns the current number of nodes in the grammar being built.

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

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

### Get Grammar Reference

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.Parser.html

Returns an immutable reference to the grammar used by the parser.

```rust
pub fn grammar(&self) -> &CGrammar
```

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

### ParserFactory::create_parser_from_init_default

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.ParserFactory.html

Creates a TokenParser using default initialization from GrammarInit.

```APIDOC
### pub fn create_parser_from_init_default( &self, init: GrammarInit, ) -> Result<TokenParser>

#### Description
Creates a `TokenParser` using the provided `GrammarInit` with default settings.
```

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

### Instant Trait Implementations

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.Instant.html

Details on various trait implementations for the Instant type.

```APIDOC
## GET /api/instant/copy

### Description
Checks if the Instant type implements the Copy trait.

### Method
GET

### Endpoint
/api/instant/copy

### Response
#### Success Response (200)
- **ImplementsCopy** (boolean) - True if Instant implements Copy, false otherwise.

## GET /api/instant/eq

### Description
Checks if the Instant type implements the Eq trait.

### Method
GET

### Endpoint
/api/instant/eq

### Response
#### Success Response (200)
- **ImplementsEq** (boolean) - True if Instant implements Eq, false otherwise.

## GET /api/instant/structural_partial_eq

### Description
Checks if the Instant type implements the StructuralPartialEq trait.

### Method
GET

### Endpoint
/api/instant/structural_partial_eq

### Response
#### Success Response (200)
- **ImplementsStructuralPartialEq** (boolean) - True if Instant implements StructuralPartialEq, false otherwise.
```

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

### Get Parser Bytes

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.Parser.html

Returns a slice of the bytes currently being processed by the parser.

```rust
pub fn get_bytes(&self) -> &[u8]
```

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

### Logger Initialization and Logging

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.Logger.html

Methods for creating a new Logger instance and writing log messages.

```APIDOC
## Logger::new

### Description
Creates a new Logger instance with specified buffer and stderr levels.

### Parameters
- **buffer_level** (u32) - Required - The log level for the internal buffer.
- **stderr_level** (u32) - Required - The log level for stderr output.

## Logger::info

### Description
Logs an info message.

### Parameters
- **s** (&str) - Required - The message to log.

## Logger::warn

### Description
Logs a warning message.

### Parameters
- **s** (&str) - Required - The message to log.
```

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

### Get Error: get_error

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.ParserRecognizer.html

Checks for and returns any errors that need to be reported to the user.

```rust
fn get_error(&mut self) -> Option<String>
Check if there are any errors to be reported to the user.
```

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

### Get Lexer State: lexer_state

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.ParserRecognizer.html

Retrieves the current state ID of the lexer.

```rust
pub fn lexer_state(&self) -> StateID
```

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

### fn try_into

Source: https://docs.rs/llguidance/1.7.0/llguidance/ffi/struct.LlgTokenizerInit.html

Documentation for the try_into conversion function.

```APIDOC
## fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

### Description
Performs the conversion from the current type to the target type U.

### Parameters
- **self** - Required - The instance to be converted.

### Response
- **Result<U, <U as TryFrom<T>>::Error>** - Returns the converted type U or an error if the conversion fails.
```

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

### HashMap Insertion

Source: https://docs.rs/llguidance/1.7.0/llguidance/type.HashMap.html

Demonstrates how to insert key-value pairs into a HashMap and handle existing keys.

```APIDOC
## POST /hashmap/insert

### Description
Inserts a key-value pair into the map. If the map did not have this key present, `None` is returned. If the map did have this key present, the value is updated, and the old value is returned.

### Method
POST

### Endpoint
/hashmap

### Parameters
#### Request Body
- **k** (K) - Required - The key to insert.
- **v** (V) - Required - The value to insert.

### Request Example
```json
{
  "k": "some_key",
  "v": "some_value"
}
```

### Response
#### Success Response (200)
- **Option<V>** (Option<V>) - The old value associated with the key, if any.

#### Response Example
```json
"old_value"
```
```

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

### HashMap Retrieval

Source: https://docs.rs/llguidance/1.7.0/llguidance/type.HashMap.html

Shows how to get a mutable reference to a value associated with a key in a HashMap.

```APIDOC
## GET /hashmap/{key}

### Description
Returns a mutable reference to the value corresponding to the key.

### Method
GET

### Endpoint
/hashmap/{key}

### Parameters
#### Path Parameters
- **key** (Q) - Required - The key to look up.

### Response
#### Success Response (200)
- **Option<&mut V>** (Option<&mut V>) - A mutable reference to the value, if the key exists.

#### Response Example
```json
"mutable_value_reference"
```
```

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

### Get Number of Nodes

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.GrammarBuilder.html

Returns the total number of nodes currently in the grammar builder.

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

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

### New Parser Instance

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.Parser.html

Creates a new instance of the Parser. Requires token environment, grammar, parser limits, and performance counters.

```rust
pub fn new( tok_env: TokEnv, grammar: Arc<CGrammar>, limits: ParserLimits, perf_counters: Arc<ParserPerfCounters>, ) -> Result<Self>
```

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

### Get Token Trie

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.Constraint.html

Returns a reference to the token trie used by the constraint parser.

```rust
pub fn tok_trie(&self) -> &TokTrie>
```

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

### llguidance Crate - Macros

Source: https://docs.rs/llguidance

List of macros available in the llguidance crate.

```APIDOC
## Macros

* `id32_type`
* `infoln`
* `loginfo`
* `warn`
```

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

### Get Current Step Result

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.Constraint.html

Retrieves the current step result from the constraint parser.

```rust
pub fn step_result(&self) -> &StepResult>
```

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

### Get Parser Performance Counters

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.Parser.html

Returns a reference to the parser's performance counters.

```rust
pub fn perf_counters(&self) -> &ParserPerfCounters
```

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

### llguidance Structs

Source: https://docs.rs/llguidance/1.7.0/llguidance/output/index.html

Documentation for the structs available in the llguidance crate.

```APIDOC
## Structs

### BytesOutput

Represents byte output data.

### ParserStats

Contains statistics related to parsing.

### Reporter

Information about a reporter.
```

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

### Get Parser Captures

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.Parser.html

Retrieves all captured strings and their associated byte slices from the parser.

```rust
pub fn captures(&self) -> &[(String, Vec<u8>)]
```

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

### Get the length of ParamRef

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.ParamRef.html

Calculates and returns the total number of bits represented by the ParamRef.

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

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

### ParserFactory::new_simple

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.ParserFactory.html

Creates a simple ParserFactory using only the tokenizer environment.

```APIDOC
### pub fn new_simple( tok_env: &TokEnv, ) -> Result<Self>

#### Description
Creates a simplified `ParserFactory` using only the provided tokenizer environment.
```

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

### ParserFactory::create_parser_from_init

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.ParserFactory.html

Creates a TokenParser using GrammarInit with specified log levels.

```APIDOC
### pub fn create_parser_from_init( &self, init: GrammarInit, buffer_log_level: u32, stderr_log_level: u32, ) -> Result<TokenParser>

#### Description
Creates a `TokenParser` from `GrammarInit`, specifying custom log levels for the buffer and standard error.
```

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

### Get the end index of ParamRef

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.ParamRef.html

Returns the ending bit index of the parameter reference.

```rust
pub fn end(&self) -> BitIdx
```

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

### Get Immutable Lexer: lexer

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.ParserRecognizer.html

Provides immutable access to the Lexer associated with the ParserRecognizer.

```rust
pub fn lexer(&self) -> &Lexer
```

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

### Blanket Implementations for Generic Types

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.Instant.html

Documentation for blanket implementations that apply to various types, including Instant.

```APIDOC
## GET /api/generic/any/type_id

### Description
Gets the `TypeId` of a given type.

### Method
GET

### Endpoint
/api/generic/any/type_id

### Query Parameters
- **type_name** (string) - Required - The name of the type to get the TypeId for.

### Response
#### Success Response (200)
- **TypeId** (string) - The TypeId of the specified type.

## GET /api/generic/borrow/borrow

### Description
Immutably borrows from an owned value.

### Method
GET

### Endpoint
/api/generic/borrow/borrow

### Query Parameters
- **value** (string) - Required - The owned value to borrow from.

### Response
#### Success Response (200)
- **BorrowedValue** (string) - The borrowed value.

## GET /api/generic/borrow_mut/borrow_mut

### Description
Mutably borrows from an owned value.

### Method
GET

### Endpoint
/api/generic/borrow_mut/borrow_mut

### Query Parameters
- **value** (string) - Required - The owned value to borrow from.

### Response
#### Success Response (200)
- **MutablyBorrowedValue** (string) - The mutably borrowed value.

## POST /api/generic/clone_to_uninit/clone_to_uninit

### Description
🔬 This is a nightly-only experimental API. Performs copy-assignment from `self` to `dest`.

### Method
POST

### Endpoint
/api/generic/clone_to_uninit/clone_to_uninit

### Request Body
- **source** (bytes) - Required - The source data to copy.
- **destination_pointer** (usize) - Required - The pointer to the destination memory.

### Response
#### Success Response (200)
- **Status** (string) - Indicates the operation was successful.

## POST /api/generic/comparable/compare

### Description
Compares self to `key` and returns their ordering.

### Method
POST

### Endpoint
/api/generic/comparable/compare

### Request Body
- **self** (any) - Required - The value to compare.
- **key** (any) - Required - The key to compare against.

### Response
#### Success Response (200)
- **Ordering** (string) - The ordering between self and key (e.g., "Less", "Equal", "Greater").

## POST /api/generic/equivalent/equivalent_eq

### Description
Checks if this value is equivalent to the given key.

### Method
POST

### Endpoint
/api/generic/equivalent/equivalent_eq

### Request Body
- **self** (any) - Required - The value to check.
- **key** (any) - Required - The key to compare for equivalence.

### Response
#### Success Response (200)
- **IsEquivalent** (boolean) - True if the values are equivalent, false otherwise.

## POST /api/generic/equivalent/equivalent_eq_compare

### Description
Compares self to `key` and returns `true` if they are equal.

### Method
POST

### Endpoint
/api/generic/equivalent/equivalent_eq_compare

### Request Body
- **self** (any) - Required - The value to compare.
- **key** (any) - Required - The key to compare for equality.

### Response
#### Success Response (200)
- **IsEqual** (boolean) - True if the values are equal, false otherwise.

## POST /api/generic/from/from

### Description
Returns the argument unchanged.

### Method
POST

### Endpoint
/api/generic/from/from

### Request Body
- **value** (any) - Required - The value to return.

### Response
#### Success Response (200)
- **ReturnedValue** (any) - The same value that was provided.

## POST /api/generic/into/into

### Description
Calls `U::from(self)` to perform a conversion.

### Method
POST

### Endpoint
/api/generic/into/into

### Request Body
- **value** (any) - Required - The value to convert.
- **target_type** (string) - Required - The target type for conversion (e.g., "String", "i32").

### Response
#### Success Response (200)
- **ConvertedValue** (any) - The converted value.

## POST /api/generic/into_either/into_either

### Description
Converts `self` into a `Left` or `Right` variant of `Either` based on the `into_left` flag.

### Method
POST

### Endpoint
/api/generic/into_either/into_either

### Request Body
- **value** (any) - Required - The value to convert.
- **into_left** (boolean) - Required - If true, converts to `Left`; otherwise, converts to `Right`.

### Response
#### Success Response (200)
- **EitherValue** (object) - The resulting Either value (e.g., `{"Left": value}` or `{"Right": value}`).

## POST /api/generic/into_either/into_either_with

### Description
Converts `self` into a `Left` or `Right` variant of `Either` based on a closure.

### Method
POST

### Endpoint
/api/generic/into_either/into_either_with

### Request Body
- **value** (any) - Required - The value to convert.
- **predicate** (string) - Required - A string representation of a closure that takes the value and returns a boolean (e.g., "|x| x > 10").

### Response
#### Success Response (200)
- **EitherValue** (object) - The resulting Either value (e.g., `{"Left": value}` or `{"Right": value}`).

## POST /api/generic/pointable/init

### Description
Initializes a memory location with the given initializer.

### Method
POST

### Endpoint
/api/generic/pointable/init

### Request Body
- **initializer** (any) - Required - The initializer for the type.

### Response
#### Success Response (200)
- **Pointer** (usize) - The pointer to the initialized memory.

## GET /api/generic/pointable/deref

### Description
Dereferences the given pointer to get an immutable reference.

### Method
GET

### Endpoint
/api/generic/pointable/deref

### Query Parameters
- **ptr** (usize) - Required - The pointer to dereference.

### Response
#### Success Response (200)
- **Value** (any) - The value at the dereferenced pointer.

## GET /api/generic/pointable/deref_mut

### Description
Mutably dereferences the given pointer to get a mutable reference.

### Method
GET

### Endpoint
/api/generic/pointable/deref_mut

### Query Parameters
- **ptr** (usize) - Required - The pointer to mutably dereference.

### Response
#### Success Response (200)
- **MutValue** (any) - The mutable value at the dereferenced pointer.

## POST /api/generic/pointable/drop

### Description
Drops the object pointed to by the given pointer.

### Method
POST

### Endpoint
/api/generic/pointable/drop

### Request Body
- **ptr** (usize) - Required - The pointer to the object to drop.

### Response
#### Success Response (200)
- **Status** (string) - Indicates the drop operation was successful.

## POST /api/generic/to_owned/to_owned

### Description
Creates owned data from borrowed data, usually by cloning.

### Method
POST

### Endpoint
/api/generic/to_owned/to_owned

### Request Body
- **borrowed_data** (any) - Required - The borrowed data to create owned data from.

### Response
#### Success Response (200)
- **OwnedData** (any) - The owned data.

## POST /api/generic/to_owned/clone_into

### Description
Uses borrowed data to replace owned data, usually by cloning.

### Method
POST

### Endpoint
/api/generic/to_owned/clone_into

### Request Body
- **source** (any) - Required - The borrowed data.
- **target** (any) - Required - The owned data to be replaced.

### Response
#### Success Response (200)
- **Status** (string) - Indicates the operation was successful.

## POST /api/generic/try_from/try_from

### Description
Performs a fallible conversion from one type to another.

### Method
POST

### Endpoint
/api/generic/try_from/try_from

### Request Body
- **value** (any) - Required - The value to convert.
- **target_type** (string) - Required - The target type for conversion.

### Response
#### Success Response (200)
- **Result** (Result<any, Error>) - The result of the conversion. Ok(value) on success, Err(error) on failure.

## POST /api/generic/try_into/try_into

### Description
Performs a fallible conversion from one type into another.

### Method
POST

### Endpoint
/api/generic/try_into/try_into

### Request Body
- **value** (any) - Required - The value to convert.
- **target_type** (string) - Required - The target type for conversion.

### Response
#### Success Response (200)
- **Result** (Result<any, Error>) - The result of the conversion. Ok(value) on success, Err(error) on failure.
```

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

### Get Mutable Lexer: lexer_mut

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.ParserRecognizer.html

Provides mutable access to the Lexer associated with the ParserRecognizer.

```rust
pub fn lexer_mut(&mut self) -> &mut Lexer
```

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

### Initialize HashMap with Hasher

Source: https://docs.rs/llguidance/1.7.0/llguidance/type.HashMap.html

Creates an empty HashMap using a specific hash builder. Manual setting of the hash builder can expose DoS attack vectors.

```rust
use std::collections::HashMap;
use std::hash::RandomState;

let s = RandomState::new();
let mut map = HashMap::with_hasher(s);
map.insert(1, 2);
```

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

### Get Mutable Parser Metrics: metrics_mut

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.ParserRecognizer.html

Provides mutable access to the ParserMetrics associated with the ParserRecognizer.

```rust
pub fn metrics_mut(&mut self) -> &mut ParserMetrics
```

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

### llguidance API Overview

Source: https://docs.rs/llguidance/1.7.0/llguidance/api/index.html

Overview of the primary structs and re-exports available in the llguidance module.

```APIDOC
## Module: api

### Description
The `api` module provides the core interface for interacting with the llguidance library, including grammar definition and parser configuration.

### Re-exports
- **ValidationResult**: Re-exported from `crate::earley::ValidationResult`.

### Structs
- **GenGrammarOptions**: Configuration for grammar generation.
- **GenOptions**: General options for the generation process.
- **GrammarWithLexer**: Combines a grammar definition with its associated lexer.
- **LLGuidanceOptions**: Configuration options, often specified as a JSON object after the '%llguidance' declaration in Lark syntax.
- **NodeProps**: Optional fields applicable to any node in the grammar.
- **ParserLimits**: Configuration for parser constraints and limits.
- **RegexExt**: Extensions for regex handling.
- **TopLevelGrammar**: Represents a collection of grammars with a designated start grammar.

### Enums
- **GrammarId**: Identifier for grammars.
- **GrammarInit**: Initialization states for grammars.
- **StopReason**: Reasons for parser termination.
```

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

### Get Mutable Parser Statistics: stats_mut

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.ParserRecognizer.html

Provides mutable access to the ParserStats associated with the ParserRecognizer.

```rust
pub fn stats_mut(&mut self) -> &mut ParserStats
```

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

### Pointer and Initialization Utilities

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.Matcher.html

Provides fundamental types and unsafe functions for managing pointers and initialization within the library.

```APIDOC
## ALIGN

### Description
The alignment of a pointer.

### Type
`usize`

## Init

### Description
The type for initializers.

### Type
`T`

## init

### Description
Initializes an object with the given initializer.

### Method
`unsafe fn init(init: <T as Pointable>::Init) -> usize`

## deref

### Description
Dereferences the given pointer.

### Method
`unsafe fn deref<'a>(ptr: usize) -> &'a T`

## deref_mut

### Description
Mutably dereferences the given pointer.

### Method
`unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T`

## drop

### Description
Drops the object pointed to by the given pointer.

### Method
`unsafe fn drop(ptr: usize)`
```

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

### Create HashSet with Capacity and Custom Hasher

Source: https://docs.rs/llguidance/1.7.0/llguidance/type.HashSet.html

Creates an empty HashSet with a specified initial capacity and a custom hasher. The set can hold at least `capacity` elements without reallocating. Similar to `with_hasher`, manually setting the hasher can be a security risk.

```rust
use std::collections::HashSet;
use std::hash::RandomState;

let s = RandomState::new();
let mut set = HashSet::with_capacity_and_hasher(10, s);
set.insert(1);
```

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

### Get Alignment of Pointer

Source: https://docs.rs/llguidance/1.7.0/llguidance/api/struct.TopLevelGrammar.html

Associated constant defining the alignment of a pointer for a given type T.

```rust
const ALIGN: usize
```

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

### Option::from_iter with Checked Subtraction (Success)

Source: https://docs.rs/llguidance/1.7.0/llguidance/ffi/type.LlgCallback.html

Demonstrates `from_iter` with checked subtraction. The collection succeeds as no underflow occurs.

```rust
let items = vec![2_u16, 1, 0];

let res: Option<Vec<u16>> = items
    .iter()
    .map(|x| x.checked_sub(1))
    .collect();

assert_eq!(res, None);
```

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

### Type ID for GenOptions

Source: https://docs.rs/llguidance/1.7.0/llguidance/api/struct.GenOptions.html

Implements the Any trait for GenOptions, providing a method to get the TypeId of the struct.

```rust
fn type_id(&self) -> TypeId
```

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

### Insert or Get

Source: https://docs.rs/llguidance/1.7.0/llguidance/type.HashSet.html

Inserts a value if it's not present and returns a reference to the value in the set. This is an experimental API.

```APIDOC
## POST /websites/rs_llguidance_1_7_0_llguidance/get_or_insert

### Description
Inserts the given `value` into the set if it is not present, then returns a reference to the value in the set. This is a nightly-only experimental API.

### Method
POST

### Endpoint
/websites/rs_llguidance_1_7_0_llguidance/get_or_insert

### Parameters
#### Request Body
- **value** (T) - Required - The value to insert or get.

### Request Example
```json
{
  "value": 100
}
```

### Response
#### Success Response (200)
- **value** (&T) - A reference to the value in the set.

#### Response Example
```json
{
  "value": 100
}
```
```

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

### Monotonicity

Source: https://docs.rs/llguidance/1.7.0/llguidance/struct.Instant.html

Explains the monotonicity guarantees of Instant and how potential violations are handled.

```APIDOC
### §Monotonicity

On all platforms `Instant` will try to use an OS API that guarantees monotonic behavior if available, which is the case for all tier 1 platforms. In practice such guarantees are – under rare circumstances – broken by hardware, virtualization or operating system bugs. To work around these bugs and platforms not offering monotonic clocks `duration_since`, `elapsed` and `sub` saturate to zero. In older Rust versions this lead to a panic instead. `checked_duration_since` can be used to detect and handle situations where monotonicity is violated, or `Instant`s are subtracted in the wrong order.

This workaround obscures programming errors where earlier and later instants are accidentally swapped. For this reason future Rust versions may reintroduce panics.
```

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

### Get Parser Temperature

Source: https://docs.rs/llguidance/1.7.0/llguidance/earley/struct.Parser.html

Retrieves the temperature setting of the parser, which may influence probabilistic parsing decisions.

```rust
pub fn temperature(&self) -> Option<f32>
```
Tokens:
Raw