Struct multer::Field

pub struct Field<'r> { /* private fields */ }

A single field in a multipart stream.

Its content can be accessed via the [Stream] API or the methods defined in this type.

Lifetime

The lifetime of the stream 'r corresponds to the lifetime of the underlying Stream. If the underlying stream holds no references directly or transitively, then the lifetime can be 'static.

Examples

use std::convert::Infallible;

use bytes::Bytes;
use futures_util::stream::once;
use multer::Multipart;

let data = "--X-BOUNDARY\r\nContent-Disposition: form-data; \
    name=\"my_text_field\"\r\n\r\nabcd\r\n--X-BOUNDARY--\r\n";

let stream = once(async move { Result::<Bytes, Infallible>::Ok(Bytes::from(data)) });
let mut multipart = Multipart::new(stream, "X-BOUNDARY");

while let Some(field) = multipart.next_field().await.unwrap() {
    let content = field.text().await.unwrap();
    assert_eq!(content, "abcd");
}

Implementations

impl<'r> Field<'r>

pub fn name(&self) -> Option<&str>

The field name found in the Content-Disposition header.

pub fn file_name(&self) -> Option<&str>

The file name found in the Content-Disposition header.

pub fn content_type(&self) -> Option<&Mime>

Get the content type of the field.

pub fn headers(&self) -> &HeaderMap

Get a map of headers as HeaderMap.

pub async fn bytes(self) -> Result<Bytes>

Get the full data of the field as Bytes.

Examples

use std::convert::Infallible;

use bytes::Bytes;
use futures_util::stream::once;
use multer::Multipart;

let data =
    "--X-BOUNDARY\r\nContent-Disposition: form-data; name=\"my_text_field\"\r\n\r\nabcd\r\n--X-BOUNDARY--\r\n";
let stream = once(async move { Result::<Bytes, Infallible>::Ok(Bytes::from(data)) });
let mut multipart = Multipart::new(stream, "X-BOUNDARY");

while let Some(field) = multipart.next_field().await.unwrap() {
    let bytes = field.bytes().await.unwrap();
    assert_eq!(bytes.len(), 4);
}

pub async fn chunk(&mut self) -> Result<Option<Bytes>>

Stream a chunk of the field data.

When the field data has been exhausted, this will return None.

Examples

use std::convert::Infallible;

use bytes::Bytes;
use futures_util::stream::once;
use multer::Multipart;

let data =
    "--X-BOUNDARY\r\nContent-Disposition: form-data; name=\"my_text_field\"\r\n\r\nabcd\r\n--X-BOUNDARY--\r\n";
let stream = once(async move { Result::<Bytes, Infallible>::Ok(Bytes::from(data)) });
let mut multipart = Multipart::new(stream, "X-BOUNDARY");

while let Some(mut field) = multipart.next_field().await.unwrap() {
    while let Some(chunk) = field.chunk().await.unwrap() {
        println!("Chunk: {:?}", chunk);
    }
}

pub async fn json<T: DeserializeOwned>(self) -> Result<T>

Available on crate feature json only.

Try to deserialize the field data as JSON.

Optional

This requires the optional json feature to be enabled.

Examples

use multer::Multipart;
use bytes::Bytes;
use std::convert::Infallible;
use futures_util::stream::once;
use serde::Deserialize;

// This `derive` requires the `serde` dependency.
#[derive(Deserialize)]
struct User {
    name: String
}

let data = "--X-BOUNDARY\r\nContent-Disposition: form-data; name=\"my_text_field\"\r\n\r\n{ \"name\": \"Alice\" }\r\n--X-BOUNDARY--\r\n";
let stream = once(async move { Result::<Bytes, Infallible>::Ok(Bytes::from(data)) });
let mut multipart = Multipart::new(stream, "X-BOUNDARY");

while let Some(field) = multipart.next_field().await.unwrap() {
    let user = field.json::<User>().await.unwrap();
    println!("User Name: {}", user.name);
}

Errors

This method fails if the field data is not in JSON format or it cannot be properly deserialized to target type T. For more details please see serde_json::from_slice.

pub async fn text(self) -> Result<String>

Get the full field data as text.

This method decodes the field data with BOM sniffing and with malformed sequences replaced with the REPLACEMENT CHARACTER. Encoding is determined from the charset parameter of Content-Type header, and defaults to utf-8 if not presented.

Examples

use std::convert::Infallible;

use bytes::Bytes;
use futures_util::stream::once;
use multer::Multipart;

let data =
    "--X-BOUNDARY\r\nContent-Disposition: form-data; name=\"my_text_field\"\r\n\r\nabcd\r\n--X-BOUNDARY--\r\n";
let stream = once(async move { Result::<Bytes, Infallible>::Ok(Bytes::from(data)) });
let mut multipart = Multipart::new(stream, "X-BOUNDARY");

while let Some(field) = multipart.next_field().await.unwrap() {
    let content = field.text().await.unwrap();
    assert_eq!(content, "abcd");
}

pub async fn text_with_charset(self, default_encoding: &str) -> Result<String>

Get the full field data as text given a specific encoding.

This method decodes the field data with BOM sniffing and with malformed sequences replaced with the REPLACEMENT CHARACTER. You can provide a default encoding for decoding the raw message, while the charset parameter of Content-Type header is still prioritized. For more information about the possible encoding name, please go to encoding_rs docs.

Examples

use std::convert::Infallible;

use bytes::Bytes;
use futures_util::stream::once;
use multer::Multipart;

let data =
    "--X-BOUNDARY\r\nContent-Disposition: form-data; name=\"my_text_field\"\r\n\r\nabcd\r\n--X-BOUNDARY--\r\n";
let stream = once(async move { Result::<Bytes, Infallible>::Ok(Bytes::from(data)) });
let mut multipart = Multipart::new(stream, "X-BOUNDARY");

while let Some(field) = multipart.next_field().await.unwrap() {
    let content = field.text_with_charset("utf-8").await.unwrap();
    assert_eq!(content, "abcd");
}

pub fn index(&self) -> usize

Get the index of this field in order they appeared in the stream.

Examples

use std::convert::Infallible;

use bytes::Bytes;
use futures_util::stream::once;
use multer::Multipart;

let data =
    "--X-BOUNDARY\r\nContent-Disposition: form-data; name=\"my_text_field\"\r\n\r\nabcd\r\n--X-BOUNDARY--\r\n";
let stream = once(async move { Result::<Bytes, Infallible>::Ok(Bytes::from(data)) });
let mut multipart = Multipart::new(stream, "X-BOUNDARY");

while let Some(field) = multipart.next_field().await.unwrap() {
    let idx = field.index();
    println!("Field index: {}", idx);
}

Trait Implementations

impl<'r> Debug for Field<'r>

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

Formats the value using the given formatter.

impl Stream for Field<'_>

type Item = Result<Bytes, Error>

Values yielded by the stream.

fn poll_next(
    self: Pin<&mut Self>,
    cx: &mut Context<'_>
) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.