Struct Writer

pub struct Writer<'a, W, E>
where
    W: 'a + Write,
    E: Endian,
{ /* private fields */ }

Wraps a seekable writer with extra functions to conveniently write data in various common binary formats and keep track of labelled offsets to help calculate section sizes and object positions.

Each writer has an endianness as part of its type, which dictates how it will write out multi-byte values. The endianness is built into the writer because most formats exclusively use a single endianness throughout, but for situations where that isn’t true you can use an endian override for a particular value and thus ignore the writer’s default.

During writing the underlying writer will contain placeholder data for any deferred values, which will then be overwritten with true values during finalization. If the underlying writer is a file on disk then other applications may be able to observe the placeholder values if they happen to inspect the file while it’s under construction.

If any operation on a Writer returns an error, the underlying stream is left in an undefined state and the user should cease further use of the writer and treat the result as invalid.

Implementations

impl<'a, W, E> Writer<'a, W, E>

where W: Write, E: Endian,

Methods that only write to the current position in the underlying stream.

pub fn write<V: IntoPack>(&mut self, v: V) -> Result<usize>

Writes a value to the current position in the output.

write can accept any value that implements IntoPack, and will write the result from packing the value to the underlying stream.

pub fn skip(&mut self, count: usize) -> Result<usize>

Inserts the given number of bytes of padding.

pub fn set_padding(&mut self, v: u8)

Changes the padding value used for future calls to align, and possibly for other functionality added in future that might also create padding.

impl<'a, W, E> Writer<'a, W, E>

where W: Seek + Write, E: Endian,

Methods that use std::io::Seek.

pub fn position(&mut self) -> Result<u64>

Returns the current write position in the underlying writer.

Use this with resolve to resolve a deferred slot that ought to contain the offset of whatever new content you are about to write.

pub fn align(&mut self, n: usize) -> Result<usize>

Moves the current stream position forward to a position aligned to the given number of bytes, writing padding bytes as necessary. Returns the number of padding bytes written.

A new Writer defaults to using zeros for padding. Use set_padding to override the padding byte for future writes, if needed.

pub fn subregion<F>(&mut self, f: F) -> Result<Range<u64>>

where F: FnOnce(&mut Self) -> Result<()>,

Creates a region of the output whose final bounds must be known for use elsewhere in the output.

If the given function completes successfully, subregion returns a range describing the start and end positions of the subregion in the underlying stream.

pub fn deferred<T>(&mut self, initial: T) -> Deferred<'a, T>

where T: IntoPack + Copy, <T as IntoPack>::PackType: FixedLenPack,

Creates a slot for a value whose resolution will come later in the process of writing all of the data.

You can use write_placeholder to reserve an area of the output where the final value will eventually be written. The reserved space will initially contain the value given in initial.

Call resolve to set the final value for this slot. That will then overwrite any placeholders written earlier with the final value.

pub fn write_placeholder<T>( &mut self, deferred: Deferred<'a, T>, ) -> Result<usize>

where T: IntoPack, <T as IntoPack>::PackType: FixedLenPack,

Writes a placeholder for the given deferred slot to the current position in the output.

At some later point you should pass the same deferred slot to resolve along with its final value, at which point the placeholder will be overwritten.

pub fn write_deferred<T>(&mut self, initial: T) -> Result<Deferred<'a, T>>

where T: IntoPack + Copy, <T as IntoPack>::PackType: FixedLenPack,

A shorthand combining deferred and write_placeholder, to create a new deferred slot and write a placeholder for it in a single call.

pub fn resolve<T>(&mut self, deferred: Deferred<'a, T>, v: T) -> Result<T>

where T: IntoPack + Copy, <T as IntoPack>::PackType: FixedLenPack,

Assigns a final value to a deferred data slot previously established using deferred.

impl<'a, W, E> Writer<'a, W, E>

where W: Seek + Write + Read, E: Endian,

Methods that use std::io::Read and std::io::Seek.

pub fn derive<F, T>(&mut self, rng: Range<u64>, f: F) -> Result<T>

where F: FnOnce(&mut DeriveRead<'_, W>) -> Result<T>,

Derive a value from an already-written region of the underlying stream.

This function is available only for streams that implement Read in addition to the usually-required Write and Seek.

The given function recieves a reader over the requested region, and can return any value derived from the contents of that region. For example, some binary formats include checksums to help with error detection, and you could potentially use derive over the relevant subregion to calculate such a checksum.

Trait Implementations

impl<'a, T, E> Write for Writer<'a, T, E>

where T: Seek + Write, E: Endian,

fn write(&mut self, buf: &[u8]) -> Result<usize>

Writes a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

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

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.