logo
pub struct DataStream<'r> { /* private fields */ }
Expand description

Raw data stream of a request body.

This stream can only be obtained by calling Data::open() with a data limit. The stream contains all of the data in the body of the request.

Reading from a DataStream is accomplished via the various methods on the structure. In general, methods exists in two variants: those that check whether the entire stream was read and those that don’t. The former either directly or indirectly (via Capped) return an N which allows checking if the stream was read to completion while the latter do not.

Read IntoMethodNotes
StringDataStream::into_string()Completeness checked. Preferred.
StringAsyncReadExt::read_to_string()Unchecked w/existing String.
Vec<u8>DataStream::into_bytes()Checked. Preferred.
Vec<u8>DataStream::stream_to(&mut vec)Checked w/existing Vec.
Vec<u8>DataStream::stream_precise_to()Unchecked w/existing Vec.
FileDataStream::into_file()Checked. Preferred.
FileDataStream::stream_to(&mut file)Checked w/ existing File.
FileDataStream::stream_precise_to()Unchecked w/ existing File.
TDataStream::stream_to()Checked. Any T: AsyncWrite.
TDataStream::stream_precise_to()Unchecked. Any T: AsyncWrite.

Implementations

Number of bytes a full read from self will definitely read.

Example
use rocket::data::{Data, ToByteUnit};

async fn f(data: Data<'_>) {
    let definitely_have_n_bytes = data.open(1.kibibytes()).hint();
}

A helper method to write the body of the request to any AsyncWrite type. Returns an N which indicates how many bytes were written and whether the entire stream was read. An additional read from self may be required to check if all of the sream has been read. If that information is not needed, use DataStream::stream_precise_to().

This method is identical to tokio::io::copy(&mut self, &mut writer) except in that it returns an N to check for completeness.

Example
use std::io;
use rocket::data::{Data, ToByteUnit};

async fn data_guard(mut data: Data<'_>) -> io::Result<String> {
    // write all of the data to stdout
    let written = data.open(512.kibibytes())
        .stream_to(tokio::io::stdout()).await?;

    Ok(format!("Wrote {} bytes.", written))
}

Like DataStream::stream_to() except that no end-of-stream check is conducted and thus read/write completeness is unknown.

Example
use std::io;
use rocket::data::{Data, ToByteUnit};

async fn data_guard(mut data: Data<'_>) -> io::Result<String> {
    // write all of the data to stdout
    let written = data.open(512.kibibytes())
        .stream_precise_to(tokio::io::stdout()).await?;

    Ok(format!("Wrote {} bytes.", written))
}

A helper method to write the body of the request to a Vec<u8>.

Example
use std::io;
use rocket::data::{Data, ToByteUnit};

async fn data_guard(data: Data<'_>) -> io::Result<Vec<u8>> {
    let bytes = data.open(4.kibibytes()).into_bytes().await?;
    if !bytes.is_complete() {
        println!("there are bytes remaining in the stream");
    }

    Ok(bytes.into_inner())
}

A helper method to write the body of the request to a String.

Example
use std::io;
use rocket::data::{Data, ToByteUnit};

async fn data_guard(data: Data<'_>) -> io::Result<String> {
    let string = data.open(10.bytes()).into_string().await?;
    if !string.is_complete() {
        println!("there are bytes remaining in the stream");
    }

    Ok(string.into_inner())
}

A helper method to write the body of the request to a file at the path determined by path. If a file at the path already exists, it is overwritten. The opened file is returned.

Example
use std::io;
use rocket::data::{Data, ToByteUnit};

async fn data_guard(mut data: Data<'_>) -> io::Result<String> {
    let file = data.open(1.megabytes()).into_file("/static/file").await?;
    if !file.is_complete() {
        println!("there are bytes remaining in the stream");
    }

    Ok(format!("Wrote {} bytes to /static/file", file.n))
}

Trait Implementations

Attempts to read from the AsyncRead into buf. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Creates a new AsyncRead instance that chains this stream with next. Read more

Pulls some bytes from this source into the specified buffer, returning how many bytes were read. Read more

Pulls some bytes from this source into the specified buffer, advancing the buffer’s internal cursor. Read more

Reads the exact number of bytes required to fill buf. Read more

Reads an unsigned 8 bit integer from the underlying reader. Read more

Reads a signed 8 bit integer from the underlying reader. Read more

Reads an unsigned 16-bit integer in big-endian order from the underlying reader. Read more

Reads a signed 16-bit integer in big-endian order from the underlying reader. Read more

Reads an unsigned 32-bit integer in big-endian order from the underlying reader. Read more

Reads a signed 32-bit integer in big-endian order from the underlying reader. Read more

Reads an unsigned 64-bit integer in big-endian order from the underlying reader. Read more

Reads an signed 64-bit integer in big-endian order from the underlying reader. Read more

Reads an unsigned 128-bit integer in big-endian order from the underlying reader. Read more

Reads an signed 128-bit integer in big-endian order from the underlying reader. Read more

Reads an 32-bit floating point type in big-endian order from the underlying reader. Read more

Reads an 64-bit floating point type in big-endian order from the underlying reader. Read more

Reads an unsigned 16-bit integer in little-endian order from the underlying reader. Read more

Reads a signed 16-bit integer in little-endian order from the underlying reader. Read more

Reads an unsigned 32-bit integer in little-endian order from the underlying reader. Read more

Reads a signed 32-bit integer in little-endian order from the underlying reader. Read more

Reads an unsigned 64-bit integer in little-endian order from the underlying reader. Read more

Reads an signed 64-bit integer in little-endian order from the underlying reader. Read more

Reads an unsigned 128-bit integer in little-endian order from the underlying reader. Read more

Reads an signed 128-bit integer in little-endian order from the underlying reader. Read more

Reads an 32-bit floating point type in little-endian order from the underlying reader. Read more

Reads an 64-bit floating point type in little-endian order from the underlying reader. Read more

Reads all bytes until EOF in this source, placing them into buf. Read more

Reads all bytes until EOF in this source, appending them to buf. Read more

Creates an adaptor which reads at most limit bytes from it. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Converts self into a collection.

Should always be Self

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more