Struct Encoder 

pub struct Encoder {
    pub cfg: EncoderConfig,
    pub hdr: Vec<u8>,
    pub meta: Vec<u8>,
    pub data: Vec<u8>,
    /* private fields */
}

Stateful encoder that accumulates encoded layer bytes.

Logical temporary buffers live in Codecs and are passed alongside the encoder while a stream is being transformed and serialized. Physical encoders live here with their own scratch buffers, then copy complete payloads into data.

Buffer layout

The MLT layer wire format is:

[varint(body_len + 1)] [tag = 1]
[name: string] [extent: varint] [column_count: varint]   <- hdr
[col_type₁] [col_type₂] … [col_typeN]                    <- meta
[col₁ stream data] [col₂ stream data] … [colN stream data] <- data

The three sections are accumulated into separate buffers so they can be combined at the end without any in-place insertion or extra copies:

• hdr – layer header (name, extent, column_count).
• meta – column-type bytes (one byte + optional name per column).
• data – encoded stream data; also the target of impl Write.

Sort-strategy trialing

Create one Encoder per sort-strategy trial, encode the layer into it, and keep the one whose total_len() is smallest:

let mut codecs = Codecs::default();
let mut best: Option<Encoder> = None;
for strategy in strategies {
    let mut enc = Encoder::new(cfg);
    layer.write_to(&mut enc, &mut codecs)?;
    if best.as_ref().is_none_or(|b| enc.total_len() < b.total_len()) {
        best = Some(enc);
    }
}
return best.unwrap().into_layer_bytes();

Stream-level encoding alternatives

Use Encoder::try_alternatives to open a competition, then submit each candidate via AltSession::with. The guard’s Drop impl finalises the competition automatically:

let mut alt = enc.try_alternatives();
alt.with(|enc| write_stream_as_varint(data, enc))?;
alt.with(|enc| write_stream_as_fastpfor(data, enc))?;
// alt drops → keeps whichever was shorter

Fields

cfg: EncoderConfig

Encoding configuration: controls which optimization strategies are tried (sort orders, compression algorithms, etc.).

Set once at construction time via Encoder::new; propagated automatically to all sub-encoders so individual encode methods do not need a separate cfg argument.

hdr: Vec<u8>

Layer header bytes: name, extent, column_count.

Written to hdr via Encoder::write_header. This section comes first in the wire format and is never subject to alternatives.

meta: Vec<u8>

Column-type metadata bytes.

Each column contributes one type byte (plus a name string for property columns). Written by the write_columns_meta_to methods, which write directly to enc.meta. This section comes second in the wire format and is never subject to alternatives (column types are fixed).

data: Vec<u8>

Encoded stream data.

All stream counts, per-stream encoding-metadata bytes, and encoded data bytes land here via impl Write. This section comes last in the wire format and is where stream-level alternatives compete.

Implementations

impl Encoder

pub fn new(cfg: EncoderConfig) -> Self

Create a new encoder with the given EncoderConfig.

Use Encoder::default() when the default configuration is sufficient.

pub fn with_explicit(cfg: EncoderConfig, explicit: ExplicitEncoder) -> Self

Like Self::new but with the explicit encoder set for deterministic encoding (tests, synthetics). Use with StagedLayer::encode_explicit.

pub fn write_header( &mut self, name: &str, extent: u32, column_count: usize, ) -> MltResult<()>

Write the layer header (name, extent, column_count) to hdr.

Must be called exactly once per layer, after all column meta and data.

pub fn total_len(&self) -> usize

Total encoded bytes across all three sections (hdr + meta + data).

pub fn into_raw_bytes(self) -> Vec<u8>

Concatenate hdr + meta + data into a single buffer without a tag/size prefix.

Use this when the caller expects raw layer body bytes (without the size/tag framing) rather than a complete framed wire record — see Self::into_layer_bytes for the framed form.

pub fn into_layer_bytes(self) -> MltResult<Vec<u8>>

Assemble the complete Tag-01 layer record.

pub fn try_alternatives(&mut self) -> AltSession<'_>

Begin a new encoding competition.

Returns an AltSession guard. Submit each candidate via AltSession::with; the guard’s Drop impl finalises the competition and retains the shortest candidate automatically.

Nesting is supported: calling try_alternatives inside a with closure opens an inner competition on the same stack, resolved before the outer candidate is committed.

Example

let mut alt = enc.try_alternatives();
for cand in candidates {
    alt.with(|enc| write_candidate(cand, enc))?;
}
// alt drops → finalises the competition

Trait Implementations

impl Default for Encoder

fn default() -> Encoder

Returns the “default value” for a type.

impl Write for Encoder

Writes bytes to Encoder::data.

This blanket implementation makes Encoder compatible with all BinarySerializer, VarIntWriter, and other Write-based utilities so that stream-data methods do not need a separate code path.

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_all(&mut self, buf: &[u8]) -> Result<()>

Attempts to write an entire buffer into this writer.

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_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.