Struct Capped

pub struct Capped<T> {
    pub value: T,
    pub n: N,
}

Encapsulates a value capped to a data limit.

A Capped<T> type represents a T that has been limited (capped) to some number of bytes. The internal N specifies whether the value is complete (also Capped::is_complete()) or whether it was capped prematurely. A Capped is returned by various methods of DataStream. Some Capped<T> types, like Capped<String> and Capped<TempFile>, implement traits like FromData and FromForm.

Example

Since Capped<TempFile> implements FromData, it can be used as a data guard. The following Rocket route accepts a raw upload and stores the upload in a different directory depending on whether the file exceeded the data limit or not. See TempFile for details on temporary file storage locations and limits.

use rocket::data::Capped;
use rocket::fs::TempFile;

#[post("/upload", data = "<file>")]
async fn upload(mut file: Capped<TempFile<'_>>) -> std::io::Result<()> {
    if file.is_complete() {
        file.persist_to("/tmp/complete/file.txt").await?;
    } else {
        file.persist_to("/tmp/incomplete/file.txt").await?;
    }

    Ok(())
}

Fields

value: T

The capped value itself.

n: N

The number of bytes written and whether value is complete.

Implementations

impl<T> Capped<T>

pub fn new(value: T, n: N) -> Self

Creates a new Capped from a value and an n. Prefer to use Capped::from() when possible.

Example

use rocket::data::{Capped, N};

let n = N { written: 2, complete: true };
let capped = Capped::new("hi".to_string(), n);

pub fn complete(value: T, len: usize) -> Self

Creates a new Capped from a value and the length of value n, marking value as complete. Prefer to use Capped::from() when possible.

Example

use rocket::data::{Capped, N};

let string = "hi";
let capped = Capped::complete("hi", string.len());

pub fn map<U, F: FnOnce(T) -> U>(self, f: F) -> Capped<U>

Converts a Capped<T> to Capped<U> by applying f to the contained value.

Example

use rocket::data::{Capped, N};

let n = N { written: 2, complete: true };
let capped: Capped<usize> = Capped::new(10usize, n);
let mapped: Capped<String> = capped.map(|n| n.to_string());

pub fn is_empty(&self) -> bool

Returns true if self.n.written is 0, that is, no bytes were written to value.

Example

use rocket::data::{Capped, N};

let n = N { written: 2, complete: true };
let capped = Capped::new("hi".to_string(), n);
assert!(!capped.is_empty());

let n = N { written: 0, complete: true };
let capped = Capped::new("".to_string(), n);
assert!(capped.is_empty());

pub fn is_complete(&self) -> bool

Returns true if self.n.complete, that is, value represents the entire data stream.

Example

use rocket::data::{Capped, N};

let n = N { written: 2, complete: true };
let capped = Capped::new("hi".to_string(), n);
assert!(capped.is_complete());

let n = N { written: 4, complete: false };
let capped = Capped::new("hell".to_string(), n);
assert!(!capped.is_complete());

pub fn into_inner(self) -> T

Returns the internal value.

Example

use rocket::data::{Capped, N};

let n = N { written: 2, complete: true };
let capped = Capped::new("hi".to_string(), n);
assert_eq!(capped.into_inner(), "hi");

Trait Implementations

impl<T: Clone> Clone for Capped<T>

fn clone(&self) -> Capped<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for Capped<T>

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

Formats the value using the given formatter.

impl<T> Deref for Capped<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T> DerefMut for Capped<T>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T: AsRef<[u8]>> From<T> for Capped<T>

fn from(value: T) -> Self

Creates a Capped<T> from a value, setting complete to true.

impl<'r> FromData<'r> for Capped<&'r [u8]>

type Error = Error

The associated error to be returned when the guard fails.

fn from_data<'life0, 'async_trait>( req: &'r Request<'life0>, data: Data<'r>, ) -> Pin<Box<dyn Future<Output = Outcome<'r, Self>> + Send + 'async_trait>>

where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait,

Asynchronously validates, parses, and converts an instance of Self from the incoming request body data.

impl<'r> FromData<'r> for Capped<&'r RawStr>

type Error = Error

The associated error to be returned when the guard fails.

fn from_data<'life0, 'async_trait>( req: &'r Request<'life0>, data: Data<'r>, ) -> Pin<Box<dyn Future<Output = Outcome<'r, Self>> + Send + 'async_trait>>

where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait,

Asynchronously validates, parses, and converts an instance of Self from the incoming request body data.

impl<'r> FromData<'r> for Capped<&'r str>

type Error = Error

The associated error to be returned when the guard fails.

fn from_data<'life0, 'async_trait>( req: &'r Request<'life0>, data: Data<'r>, ) -> Pin<Box<dyn Future<Output = Outcome<'r, Self>> + Send + 'async_trait>>

where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait,

Asynchronously validates, parses, and converts an instance of Self from the incoming request body data.

impl<'r> FromData<'r> for Capped<Cow<'_, str>>

type Error = Error

The associated error to be returned when the guard fails.

fn from_data<'life0, 'async_trait>( req: &'r Request<'life0>, data: Data<'r>, ) -> Pin<Box<dyn Future<Output = Outcome<'r, Self>> + Send + 'async_trait>>

where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait,

Asynchronously validates, parses, and converts an instance of Self from the incoming request body data.

impl<'r> FromData<'r> for Capped<String>

type Error = Error

The associated error to be returned when the guard fails.

fn from_data<'life0, 'async_trait>( req: &'r Request<'life0>, data: Data<'r>, ) -> Pin<Box<dyn Future<Output = Outcome<'r, Self>> + Send + 'async_trait>>

where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait,

Asynchronously validates, parses, and converts an instance of Self from the incoming request body data.

impl<'r> FromData<'r> for Capped<TempFile<'_>>

type Error = Error

The associated error to be returned when the guard fails.

fn from_data<'life0, 'async_trait>( req: &'r Request<'life0>, data: Data<'r>, ) -> Pin<Box<dyn Future<Output = Outcome<'r, Self>> + Send + 'async_trait>>

where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait,

Asynchronously validates, parses, and converts an instance of Self from the incoming request body data.

impl<'r> FromData<'r> for Capped<Vec<u8>>

type Error = Error

The associated error to be returned when the guard fails.

fn from_data<'life0, 'async_trait>( req: &'r Request<'life0>, data: Data<'r>, ) -> Pin<Box<dyn Future<Output = Outcome<'r, Self>> + Send + 'async_trait>>

where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait,

Asynchronously validates, parses, and converts an instance of Self from the incoming request body data.

impl<'v> FromFormField<'v> for Capped<&'v [u8]>

fn from_value(field: ValueField<'v>) -> Result<'v, Self>

Parse a value of T from a form value field.

fn from_data<'life0, 'async_trait>( f: DataField<'v, 'life0>, ) -> Pin<Box<dyn Future<Output = Result<'v, Self>> + Send + 'async_trait>>

where Self: 'async_trait, 'v: 'async_trait, 'life0: 'async_trait,

Parse a value of T from a form data field.

fn default() -> Option<Self>

Returns a default value, if any exists, to be used during lenient parsing when the form field is missing.

impl<'v> FromFormField<'v> for Capped<&'v str>

fn from_value(field: ValueField<'v>) -> Result<'v, Self>

Parse a value of T from a form value field.

fn from_data<'life0, 'async_trait>( f: DataField<'v, 'life0>, ) -> Pin<Box<dyn Future<Output = Result<'v, Self>> + Send + 'async_trait>>

where Self: 'async_trait, 'v: 'async_trait, 'life0: 'async_trait,

Parse a value of T from a form data field.

fn default() -> Option<Self>

Returns a default value, if any exists, to be used during lenient parsing when the form field is missing.

impl<'v> FromFormField<'v> for Capped<Cow<'v, str>>

fn from_value(field: ValueField<'v>) -> Result<'v, Self>

Parse a value of T from a form value field.

fn from_data<'life0, 'async_trait>( field: DataField<'v, 'life0>, ) -> Pin<Box<dyn Future<Output = Result<'v, Self>> + Send + 'async_trait>>

where Self: 'async_trait, 'v: 'async_trait, 'life0: 'async_trait,

Parse a value of T from a form data field.

fn default() -> Option<Self>

Returns a default value, if any exists, to be used during lenient parsing when the form field is missing.

impl<'v> FromFormField<'v> for Capped<String>

fn from_value(field: ValueField<'v>) -> Result<'v, Self>

Parse a value of T from a form value field.

fn from_data<'life0, 'async_trait>( f: DataField<'v, 'life0>, ) -> Pin<Box<dyn Future<Output = Result<'v, Self>> + Send + 'async_trait>>

where Self: 'async_trait, 'v: 'async_trait, 'life0: 'async_trait,

Parse a value of T from a form data field.

fn default() -> Option<Self>

Returns a default value, if any exists, to be used during lenient parsing when the form field is missing.

impl<'v> FromFormField<'v> for Capped<TempFile<'v>>

fn from_value(field: ValueField<'v>) -> Result<Self, Errors<'v>>

Parse a value of T from a form value field.

fn from_data<'life0, 'async_trait>( f: DataField<'v, 'life0>, ) -> Pin<Box<dyn Future<Output = Result<Self, Errors<'v>>> + Send + 'async_trait>>

where Self: 'async_trait, 'v: 'async_trait, 'life0: 'async_trait,

Parse a value of T from a form data field.

fn default() -> Option<Self>

Returns a default value, if any exists, to be used during lenient parsing when the form field is missing.

impl<L, T: Len<L>> Len<L> for Capped<T>

fn len(&self) -> L

The length of the value.

fn len_into_u64(len: L) -> u64

Convert len into u64.

fn zero_len() -> L

The zero value for L.

impl<'r, 'o: 'r, T: Responder<'r, 'o>> Responder<'r, 'o> for Capped<T>

fn respond_to(self, request: &'r Request<'_>) -> Result<'o>

Returns Ok if a Response could be generated successfully. Otherwise, returns an Err with a failing Status.

impl<T: Copy> Copy for Capped<T>