Struct BorrowedWriter 

pub(crate) struct BorrowedWriter<'buffer, 'data, 'write> {
    bbuf: &'buffer mut BorrowedBuffer<'data>,
    wtr: &'write mut dyn Write,
}

A buffering abstraction on top of BorrowedBuffer.

This lets callers make use of a monomorphic uninitialized buffer while writing variable length data. For example, in use with strftime, where the length of the resulting string can be arbitrarily long.

Essentially, once the buffer is filled up, it is emptied by writing it to an underlying jiff::fmt::Write implementation.

Design

We specifically do not expose the underlying BorrowedBuffer in this API. It is too error prone because it makes it ridiculously easy for the caller to try to write too much data to the buffer, thus causing a panic.

Also, we require that the total capacity of the BorrowedBuffer given is big enough such that any of the integer formatting routines will always fit. This means we don’t need to break up integer formatting to support pathologically small buffer sizes, e.g., 0 or 1 bytes. This is fine because this is a Jiff-internal abstraction.

Callers must call BorrowedWriter::finish when done to ensure the internal buffer is properly flushed.

One somewhat unfortunate aspect of the design here is that the integer formatting routines need to know how much data is going to be written. This sometimes requires doing some work to figure out. And that work is usually repeated by BorrowedBuffer. My hope at time of writing (2026-01-02) is that compiler eliminates the duplication, but I haven’t actually checked this yet.

BorrowedWriter::write_str is the only method where there is some awareness of the underlying Write implementation. This is because the string can be of arbitrary length, and thus, may exceed the size of the buffer. (In which case, we pass it through directly to the Write implementation.)

Fields

bbuf: &'buffer mut BorrowedBuffer<'data>

wtr: &'write mut dyn Write

Implementations

impl<'buffer, 'data, 'write> BorrowedWriter<'buffer, 'data, 'write>

pub(crate) fn new( bbuf: &'buffer mut BorrowedBuffer<'data>, wtr: &'write mut dyn Write, ) -> BorrowedWriter<'buffer, 'data, 'write>

Creates a new borrowed writer that buffers writes in bbuf and flushes them to wtr.

Panics

When BorrowedBuffer is too small to handle formatting a single integer (including padding).

pub(crate) fn finish(self) -> Result<(), Error>

pub(crate) fn flush(&mut self) -> Result<(), Error>

pub(crate) fn if_will_fill_then_flush( &mut self, additional: impl Into<usize>, ) -> Result<(), Error>

pub(crate) fn write_str(&mut self, string: &str) -> Result<(), Error>

pub(crate) fn write_char(&mut self, ch: char) -> Result<(), Error>

pub(crate) fn write_ascii_char(&mut self, byte: u8) -> Result<(), Error>

pub(crate) fn write_int_pad( &mut self, n: impl Into<u64>, pad_byte: u8, pad_len: u8, ) -> Result<(), Error>

pub(crate) fn write_int_pad2(&mut self, n: impl Into<u64>) -> Result<(), Error>

pub(crate) fn write_int_pad2_space( &mut self, n: impl Into<u64>, ) -> Result<(), Error>

pub(crate) fn write_int_pad4(&mut self, n: impl Into<u64>) -> Result<(), Error>

pub(crate) fn write_fraction( &mut self, precision: Option<u8>, n: u32, ) -> Result<(), Error>

Trait Implementations

impl<'buffer, 'data, 'write> Write for BorrowedWriter<'buffer, 'data, 'write>

We come full circle and make a BorrowedWriter implement jiff::fmt::Write.

This is concretely useful for strftime and passing a borrowed writer to methods on the Custom trait.

fn write_str(&mut self, string: &str) -> Result<(), Error>

Write the given string to this writer, returning whether the write succeeded or not.

fn write_char(&mut self, char: char) -> Result<(), Error>

Write the given character to this writer, returning whether the write succeeded or not.

unsafe fn as_mut_vec(&mut self) -> Option<&mut Vec<u8>>

Returns a Vec<u8> backing store for this implementation.