Struct dangerous::Input

#[must_use = "input must be consumed"]pub struct Input<'i> { /* fields omitted */ }

Input is an immutable wrapper around bytes to be processed.

It can only be created via dangerous::input() as so to clearly point out where untrusted / dangerous input is consumed.

It is used along with Reader to process the input.

Formatting

Input implements both fmt::Debug and fmt::Display with support for pretty printing. See InputDisplay for formatting options.

Implementations

impl<'i> Input<'i>

#[must_use]pub const fn len(&self) -> usize

Returns the underlying byte slice length.

#[must_use]pub const fn is_empty(&self) -> bool

Returns true if the underlying byte slice length is zero.

#[must_use]pub const fn is_bound(&self) -> bool

Returns true if the underlying byte slice is bound.

See Input::bound() for more documentation.

#[must_use]pub fn is_within(&self, parent: &Input<'_>) -> bool

Returns true if the underlying byte slice for parent contains that of self in the same section of memory with no bounds out of range.

#[must_use]pub fn count(&self, needle: u8) -> usize

Returns the occurrences of needle within the underlying byte slice.

It is recommended to enable the bytecount dependency when using this function for better performance.

pub fn bound(self) -> Self

Returns self as a bound Input.

Bound Input carries the guarantee that it will not be extended in future passes and as a result will not produce RetryRequirements.

Example

use dangerous::{Invalid, ToRetryRequirement};

let error: Invalid = dangerous::input(b"1234")
    .bound()
    .read_partial(|r| r.take(5))
    .unwrap_err();

// If the input was not bound, this wouldn't be fatal.
assert!(error.is_fatal());

#[must_use]pub fn span_of(&self, parent: &Input<'_>) -> Option<Range<usize>>

Returns Some(Range) with the start and end offsets of self within the parent. None is returned if self is not within in the parent.

Example

let parent = dangerous::input(&[1, 2, 3, 4]);
let sub_range = 1..2;
let sub = dangerous::input(&parent.as_dangerous()[sub_range.clone()]);

assert_eq!(sub.span_of(&parent), Some(sub_range))

#[must_use]pub fn span_of_non_empty(&self, parent: &Input<'_>) -> Option<Range<usize>>

Returns Some(Range) with the start and end offsets of self within the parent. None is returned if self is not within in the parent or self is empty.

pub fn display(&self) -> InputDisplay<'i>

Returns an InputDisplay for formatting.

pub fn read_all<F, T, E>(self, f: F) -> Result<T, E> where
    F: FnOnce(&mut Reader<'i, E>) -> Result<T, E>,
    E: WithContext<'i>,
    E: From<ExpectedLength<'i>>, 

Create a reader with the expectation all of the input is read.

Errors

Returns an error if either the provided function does, or there is trailing input.

pub fn read_partial<F, T, E>(self, f: F) -> Result<(T, Input<'i>), E> where
    F: FnOnce(&mut Reader<'i, E>) -> Result<T, E>,
    E: WithContext<'i>, 

Create a reader to read a part of the input and return the rest.

Errors

Returns an error if the provided function does.

pub fn read_infallible<F, T>(self, f: F) -> (T, Input<'i>) where
    F: FnOnce(&mut Reader<'i, Infallible>) -> T, 

Create a reader to read a part of the input and return the rest without any errors.

#[must_use]pub const fn as_dangerous(&self) -> &'i [u8]

Returns the underlying byte slice.

The naming of this function is to a degree hyperbole, and should not be necessarily taken as proof of something dangerous or memory unsafe. It is named this way simply for users to clearly note where the panic-free guarantees end when handling the input.

pub fn to_dangerous_non_empty<E>(&self) -> Result<&'i [u8], E> where
    E: From<ExpectedLength<'i>>, 

Returns the underlying byte slice if it is not empty.

See as_dangerous for naming.

Errors

Returns ExpectedLength if the input is empty.

pub fn to_dangerous_str<E>(&self) -> Result<&'i str, E> where
    E: From<ExpectedValid<'i>>, 

Decodes the underlying byte slice into a UTF-8 str slice.

See as_dangerous for naming.

If the underlying byte slice is known to be valid UTF-8 this is will a cheap operation, otherwise the bytes will be validated.

Errors

Returns ExpectedValid if the input is not valid UTF-8.

pub fn to_dangerous_non_empty_str<E>(&self) -> Result<&'i str, E> where
    E: From<ExpectedValid<'i>>,
    E: From<ExpectedLength<'i>>, 

Decodes the underlying byte slice into a UTF-8 str slice.

See as_dangerous for naming.

Errors

Returns ExpectedLength if the input is empty or ExpectedValid if the input is not valid UTF-8.

Trait Implementations

impl<'i> Clone for Input<'i>

pub fn clone(&self) -> Self

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'i> Debug for Input<'i>

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'i> Display for Input<'i>

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'i> NoInteriorMut for Input<'i>

impl<'i> PartialEq<&'_ [u8]> for Input<'i>

pub fn eq(&self, other: &&[u8]) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'i> PartialEq<[u8]> for Input<'i>

pub fn eq(&self, other: &[u8]) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'i> PartialEq<[u8]> for &Input<'i>

pub fn eq(&self, other: &[u8]) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'i> PartialEq<Input<'i>> for Input<'i>

pub fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.