Struct body_image::BodySink

pub struct BodySink { /* fields omitted */ }

A logical buffer of bytes, which may or may not be RAM resident, in the process of being written. This is the write-side corollary to BodyImage.

A BodySink is always in one of the following states, as a buffering strategy:

Ram : A vector of zero, one, or many discontinuous (AKA scattered) byte buffers in Random Access Memory. This state is also used to represent an empty body (without allocation).

FsWrite : Body being written to a (temporary) file.

Methods

impl BodySink

pub fn empty() -> BodySink

Create new empty instance, which does not pre-allocate. The state is Ram with a zero-capacity vector.

pub fn with_ram(size_estimate: u64) -> BodySink

Create a new Ram instance by pre-allocating a vector of buffers based on the given size estimate in bytes, assuming 8 KiB buffers. With a size_estimate of 0, this is the same as empty.

pub fn with_ram_buffers(capacity: usize) -> BodySink

Create a new Ram instance by pre-allocating a vector of the specified capacity.

pub fn with_fs<P>(dir: P) -> Result<BodySink, BodyError> where
    P: AsRef<Path>, 

Create a new instance in state FsWrite, using a new temporary file created in dir.

pub fn is_ram(&self) -> bool

Return true if in state Ram.

pub fn is_empty(&self) -> bool

Return true if body is empty.

pub fn len(&self) -> u64

Return the current length of body in bytes.

pub fn save<T>(&mut self, buf: T) -> Result<(), BodyError> where
    T: Into<Bytes>, 

Deprecated since 2.0.0:

use push or write_all instead

Push Bytes-convertable buffer to end of Ram vector, or by writing to end of FsWrite file.

pub fn push<T>(&mut self, buf: T) -> Result<(), Error> where
    T: Into<Bytes> + AsRef<[u8]>, 

Push Bytes-convertable buffer to end of Ram vector, or by writing to end of FsWrite file.

Note the additional Into<Bytes> bound vs write_all. When in state Ram, push is more efficient than write_all if Into<Bytes> does not copy. When in state FsWrite it is the same.

pub fn write_all<T>(&mut self, buf: T) -> Result<(), Error> where
    T: AsRef<[u8]>, 

Write all bytes to end of self.

Prefer push to this method if the additional bound is met. Only when in state FsWrite is this method copy free.

pub fn write_back<P>(&mut self, dir: P) -> Result<&mut Self, BodyError> where
    P: AsRef<Path>, 

If Ram, convert to FsWrite by writing all bytes in RAM to a temporary file, created in dir. No-op if already FsWrite. Buffers are eagerly dropped as they are written. As a consequence, if any error result is returned (e.g. opening or writing to the file), self will be empty and in the Ram state. There is no practical recovery for the original body.

pub fn prepare(self) -> Result<BodyImage, BodyError>

Consumes self, converts and returns as BodyImage ready for read.

Trait Implementations

impl Debug for BodySink

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

Formats the value using the given formatter.

impl Default for BodySink

fn default() -> BodySink

Returns the "default value" for a type.