Struct ArgumentReader

Source

pub struct ArgumentReader<'a> { /* private fields */ }

Expand description

Reads declared arguments exactly once while rejecting duplicates, unknown names, and lossy numeric conversions.

A present parameter can be read at most once. A typed read consumes the parameter before decoding it, so type and range errors also complete that parameter’s consumption. Call Self::finish to reject parameters that were never read.

§Type Parameters

'a: Lifetime shared by the declared parameter names and borrowed values.

§Examples

use qubit_validator::ArgumentReader;
use qubit_validator::NamedValidationArgument;
use qubit_validator::ValidationArgument;

let arguments = [NamedValidationArgument::new(
    "limit",
    ValidationArgument::Unsigned(10),
)];
let mut reader = ArgumentReader::new(&arguments)?;
assert_eq!(reader.required_u32("limit")?, 10);
reader.finish()?;

Implementations§

Source §

impl<'a> ArgumentReader<'a>

Source

pub fn new(args: &'a [NamedValidationArgument<'a>]) -> Result<Self, BindError>

Creates a reader and checks for duplicate parameter names.

§Parameters

args: Declared parameters to read, in caller-provided order.

§Returns

A reader that tracks consumption of each declared parameter.

§Errors

Returns DuplicateParameter when a name occurs more than once.

Examples found in repository ?

examples/local_registry.rs (line 141)

139fn assert_parameters_are_consumed_once() -> Result<(), BindError> {
140    let args = [NamedValidationArgument::new("limit", ValidationArgument::Unsigned(10))];
141    let mut reader = ArgumentReader::new(&args)?;
142    assert_eq!(reader.required_u32("limit")?, 10);
143    let error = reader
144        .required_u32("limit")
145        .expect_err("a parameter cannot be read twice");
146    assert_eq!(error.kind(), BindErrorKind::ParameterAlreadyConsumed);
147    Ok(())
148}

Source

pub fn required_argument( &mut self, name: &str, ) -> Result<ValidationArgument<'a>, BindError>

Reads a required argument once without decoding its value.

The caller is responsible for checking the returned variant’s type and any domain-specific constraints. A successful read consumes the argument.

§Parameters

name: Name of the required parameter.

§Returns

The parameter’s value without decoding its variant.

§Errors

Returns MissingParameter when the name is absent, or ParameterAlreadyConsumed when the argument was previously read.

Source

pub fn required_u32(&mut self, name: &str) -> Result<u32, BindError>

Reads a required unsigned 32-bit integer once.

§Parameters

name: Name of the required integer parameter.

§Returns

The decoded u32 value.

§Errors

Returns MissingParameter when the parameter is absent, ParameterAlreadyConsumed when it was previously read, ParameterTypeMismatch when it is not an integer, or ParameterOutOfRange when its value cannot be represented as a u32.

Examples found in repository ?

examples/local_registry.rs (line 142)

139fn assert_parameters_are_consumed_once() -> Result<(), BindError> {
140    let args = [NamedValidationArgument::new("limit", ValidationArgument::Unsigned(10))];
141    let mut reader = ArgumentReader::new(&args)?;
142    assert_eq!(reader.required_u32("limit")?, 10);
143    let error = reader
144        .required_u32("limit")
145        .expect_err("a parameter cannot be read twice");
146    assert_eq!(error.kind(), BindErrorKind::ParameterAlreadyConsumed);
147    Ok(())
148}

Source

pub fn optional_u32(&mut self, name: &str) -> Result<Option<u32>, BindError>

Reads an optional unsigned 32-bit integer once.

§Parameters

name: Name of the optional integer parameter.

§Returns

Returns Some with the decoded value when the parameter is present, or None when it is absent.

§Errors

Returns ParameterAlreadyConsumed when the present parameter was previously read, ParameterTypeMismatch when it is not an integer, or ParameterOutOfRange when its value cannot be represented as a u32.

Source

pub fn optional_usize(&mut self, name: &str) -> Result<Option<usize>, BindError>

Reads an optional platform-sized unsigned integer once.

The representable range depends on the target architecture, commonly 32 or 64 bits.

§Parameters

name: Name of the optional integer parameter.

§Returns

Returns Some with the decoded value when the parameter is present, or None when it is absent.

§Errors

Returns ParameterAlreadyConsumed when the present parameter was previously read, ParameterTypeMismatch when it is not an integer, or ParameterOutOfRange when it is negative or cannot be represented as a usize. Each error includes the parameter name.

Source

pub fn required_str(&mut self, name: &str) -> Result<&'a str, BindError>

Reads a required string argument once.

§Parameters

name: Name of the required string parameter.

§Returns

The borrowed string value.

§Errors

Returns MissingParameter when the parameter is absent, ParameterAlreadyConsumed when it was previously read, or ParameterTypeMismatch when it is not a string.

Source

pub fn optional_str(&mut self, name: &str) -> Result<Option<&'a str>, BindError>

Reads an optional string argument once without allocating.

The returned string borrows the value supplied when this reader was created. A missing parameter is not consumed and can be queried again. A present parameter is consumed before its type is checked, including when the value has the wrong type.

§Parameters

name: Name of the optional string parameter.

§Returns

Returns Some with the original borrowed string when the parameter is present, or None when it is absent.

§Errors

Returns ParameterAlreadyConsumed when the present parameter was previously read, or ParameterTypeMismatch when its value is not a string. Both errors include the parameter name. A failed read consumes the present parameter; callers must propagate the error instead of continuing with other reads.

Source