Struct binbin::Writer [−][src]
Expand description
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
Methods that only write to the current position in the underlying stream.
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.
Inserts the given number of bytes of padding.
Changes the padding value used for future calls to
align
, and possibly for other functionality added
in future that might also create padding.
Methods that use std::io::Seek
.
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.
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.
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.
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,
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,
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.
Methods that use std::io::Read
and
std::io::Seek
.
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
Write a buffer into this writer, returning how many bytes were written. Read more
Flush this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
can_vector
)Determines if this Write
r has an efficient write_vectored
implementation. Read more
Attempts to write an entire buffer into this writer. Read more
write_all_vectored
)Attempts to write multiple buffers into this writer. Read more
Writes a formatted string into this writer, returning any error encountered. Read more
Auto Trait Implementations
impl<'a, W, E> RefUnwindSafe for Writer<'a, W, E> where
E: RefUnwindSafe,
W: RefUnwindSafe,
impl<'a, W, E> UnwindSafe for Writer<'a, W, E> where
E: RefUnwindSafe,
W: UnwindSafe,