Struct ConFrameWriter 

pub struct ConFrameWriter<W: Write> { /* private fields */ }

A writer that can serialize and write ConFrame objects to any output stream.

This struct encapsulates a writer (like a file) and provides a high-level API for writing simulation frames in the .con format.

Example

let mut writer = ConFrameWriter::from_path("output.con").unwrap();
writer.extend(frames.iter()).unwrap();

Implementations

impl<W: Write> ConFrameWriter<W>

pub fn new(writer: W) -> Self

Creates a new ConFrameWriter that wraps a given writer.

Arguments

• writer - Any type that implements std::io::Write, e.g., a File.

pub fn with_precision(writer: W, precision: usize) -> Self

Creates a new ConFrameWriter with a custom floating-point precision.

Arguments

• writer - Any type that implements std::io::Write.
• precision - Number of decimal places for floating-point output.

pub fn with_float_format(writer: W, float_format: FloatFormat) -> Self

Creates a writer with an explicit numeric text representation.

FloatFormat::RoundTrip retains small forces and coordinates exactly. Metadata floats use the JSON serializer independently of this setting.

pub fn parallel_atoms(self, n: usize) -> Self

Format a wide coordinate block on n workers.

n < 2 leaves the serial loop. The bytes match that loop: each worker formats a contiguous run of atoms and the runs are joined in file order.

pub fn map_rows(self, on: bool) -> Self

Copy formatted rows into a shared mapping of stream_file.

The wide path does this on its own when a spare physical core is free. Tests turn it on for short frames so an odd atom count still takes the mapping, including on a runner with no spare core.

pub fn mapped_file(self, file: File) -> Self

File the mapping copies into. Open it read/write; map_rows selects the mapping even when Self::parallel_atoms would otherwise pwrite.

pub fn canonical(self, on: bool) -> Self

Opt-in canonical serialization: BTree-ordered metadata keys in JSON, fixed section order. Use for corpus materialization and content-stable hashes; not required for on-disk fidelity of spans preserved from next_with_raw_span.

pub fn set_canonical(&mut self, on: bool)

Set or clear canonical mode on an existing writer (C ABI / FFI).

pub fn is_canonical(&self) -> bool

Whether canonical serialization is enabled.

pub fn write_frame_binding( &mut self, frame: &mut ConFrame, ) -> Result<(), WriteError>

Writes frame with the binding metadata stamp and the original atoms.

The stamp is installed for the duration of the write and then put back. Atoms are not rebuilt.

pub fn write_frame_bound(&mut self, frame: &ConFrame) -> Result<(), WriteError>

Self::write_frame_binding without a mutable frame.

The header the file emits is the binding stamp. frame’s atoms and its stored header are left as the caller passed them, so a wide frame is not cloned before its rows are formatted.

pub fn write_frame(&mut self, frame: &ConFrame) -> Result<(), WriteError>

Writes a single ConFrame to the output stream.

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

Flushes buffered frames to the underlying writer.

write_frame fills a buffer and does not always reach the sink. After flush returns, a reader sees a complete, parseable prefix. Dropping the writer flushes as well.

pub fn extend<'a>( &mut self, frames: impl Iterator<Item = &'a ConFrame>, ) -> Result<(), WriteError>

Writes all frames from an iterator to the output stream.

This is the most convenient way to write a multi-frame file.

impl ConFrameWriter<File>

pub fn from_path<P: AsRef<Path>>(path: P) -> Result<Self>

Creates a new ConFrameWriter that writes to a file at the given path.

This is a convenience function that creates the file and wraps it.

pub fn from_path_with_precision<P: AsRef<Path>>( path: P, precision: usize, ) -> Result<Self>

Creates a new ConFrameWriter that writes to a file with a custom precision.

pub fn from_path_append<P: AsRef<Path>>(path: P) -> Result<Self>

Opens an uncompressed file for appending.

The file is created when it does not exist. A non-empty file that does not end in a newline receives one, so the next frame header starts on its own line. A file this writer produced already ends in a newline, and appending the remaining frames reproduces one whole-file write. Gzip and zstd paths are refused: a compressed member cannot be extended.

write_frame fills a one-frame scratch buffer and a std::io::BufWriter. Self::flush pushes that buffer to the file before the writer is dropped.

use readcon_core::iterators::read_all_frames;
use readcon_core::types::ConFrameBuilder;
use readcon_core::writer::ConFrameWriter;
let path = std::env::temp_dir().join(format!(
    "readcon-append-doc-{}",
    std::process::id()
));
let mut builder = ConFrameBuilder::new([10.0, 10.0, 10.0], [90.0, 90.0, 90.0]);
builder.add_atom("H", 0.0, 0.0, 0.0, [false; 3], 1, 1.0);
let frame = builder.build().unwrap();
{
    let mut writer = ConFrameWriter::from_path(&path).unwrap();
    writer.write_frame(&frame).unwrap();
    writer.flush().unwrap();
}
{
    let mut writer = ConFrameWriter::from_path_append(&path).unwrap();
    writer.write_frame(&frame).unwrap();
    writer.flush().unwrap();
}
let frames = read_all_frames(&path).unwrap();
assert_eq!(frames.len(), 2);
let _ = std::fs::remove_file(&path);

pub fn from_path_append_with_precision<P: AsRef<Path>>( path: P, precision: usize, ) -> Result<Self>

Opens an uncompressed file for appending with a fixed decimal precision.

impl ConFrameWriter<GzEncoder<File>>

pub fn from_path_gzip<P: AsRef<Path>>(path: P) -> Result<Self>

Creates a gzip-compressed writer for the given path.

pub fn from_path_gzip_with_precision<P: AsRef<Path>>( path: P, precision: usize, ) -> Result<Self>

Creates a gzip-compressed writer with custom precision.