Struct Writer 

pub struct Writer<W> { /* private fields */ }

A 7z archive writer.

Implementations

impl<W: Write + Seek + Send> Writer<W>

pub fn add_path( &mut self, disk_path: impl AsRef<Path>, archive_path: ArchivePath, ) -> Result<()>

Adds a file from a filesystem path.

Arguments

• disk_path - Path to the file on disk
• archive_path - Path within the archive

Errors

Returns an error if the file cannot be read or if the writer is in an invalid state.

pub fn add_directory( &mut self, archive_path: ArchivePath, meta: EntryMeta, ) -> Result<()>

Adds a directory entry.

Arguments

• archive_path - Path within the archive
• meta - Entry metadata

Errors

Returns an error if the writer is in an invalid state.

pub fn add_anti_item(&mut self, archive_path: ArchivePath) -> Result<()>

Adds an anti-item entry (file marked for deletion in incremental backups).

Anti-items are empty entries that indicate a file or directory should be deleted when the incremental archive is applied. This is useful for incremental backup systems.

Arguments

• archive_path - Path within the archive to mark for deletion

Example

let mut writer = Writer::create_file("incremental.7z")?;
writer.add_anti_item(ArchivePath::new("deleted_file.txt")?)?;
writer.finish()?;

pub fn add_anti_directory(&mut self, archive_path: ArchivePath) -> Result<()>

Adds an anti-item directory (directory marked for deletion).

Arguments

• archive_path - Directory path within the archive to mark for deletion

pub fn add_stream( &mut self, archive_path: ArchivePath, source: &mut dyn Read, meta: EntryMeta, ) -> Result<()>

Adds data from a stream.

Arguments

• archive_path - Path within the archive
• source - Reader providing the data
• meta - Entry metadata

Errors

Returns an error if compression fails or if the writer is in an invalid state.

pub fn add_bytes( &mut self, archive_path: ArchivePath, data: &[u8], ) -> Result<()>

Adds data from a byte slice.

Arguments

• archive_path - Path within the archive
• data - The data to add

Errors

Returns an error if compression fails or if the writer is in an invalid state.

impl Writer<BufWriter<File>>

pub fn create_path(path: impl AsRef<Path>) -> Result<Self>

Creates a new archive file at the given path.

The file is created, and an existing one truncated, before a single entry has been written - so a run that fails partway leaves neither the finished archive nor what was at that path before. Where that matters, write to a path of your own beside it and rename onto the destination when Writer::finish returns; that is what this crate’s own command-line tool does.

Arguments

• path - Path to the archive file to create

Errors

Returns an error if the file cannot be created.

pub fn finish(self) -> Result<WriteResult>

Finishes writing the archive.

Returns

A WriteResult with statistics about the written archive.

Errors

Returns an error if header writing fails.

impl Writer<Cursor<Vec<u8>>>

pub fn finish(self) -> Result<WriteResult>

Finishes writing the archive to an owned cursor.

impl Writer<Cursor<&mut Vec<u8>>>

pub fn finish(self) -> Result<WriteResult>

Finishes writing the archive to a borrowed cursor.

impl Writer<MultiVolumeWriter>

pub fn create_multivolume(config: VolumeConfig) -> Result<Self>

Creates a new multi-volume archive writer.

The archive will be split across multiple files when each volume reaches the configured size limit.

Arguments

• config - Volume configuration specifying size and base path

Each volume is created, and an existing file of that name truncated, as the archive reaches it - so a run that fails partway leaves a set of volumes that is neither complete nor what was there before.

Errors

Returns an error if the first volume file cannot be created.

Example

use zesven::{Writer, VolumeConfig, ArchivePath};

let config = VolumeConfig::new("archive.7z", 50 * 1024 * 1024); // 50 MB volumes
let mut writer = Writer::create_multivolume(config)?;
writer.add_bytes(ArchivePath::new("data.bin")?, &large_data)?;
let result = writer.finish()?;
println!("Created {} volumes", result.volume_count);

pub fn finish(self) -> Result<WriteResult>

Finishes writing the multi-volume archive.

This finalizes all volumes and returns a WriteResult with volume information.

Returns

A WriteResult with statistics including volume_count and volume_sizes.

Errors

Returns an error if header writing or volume finalization fails.

impl<W: Write + Seek> Writer<W>

pub fn create(sink: W) -> Result<Self>

Creates a new archive writer.

Arguments

• sink - The writer to output archive data to

Errors

Returns an error if the initial seek fails.

pub fn progress(self, reporter: impl ProgressReporter + 'static) -> Self

Reports what is being written to reporter as the archive is built.

Writing an archive is mostly silent from the outside: entries are gathered and compressed together, so the call that accepts an entry usually returns before anything has been compressed and the work lands on whichever call fills the batch, or on finish. A caller timing its own calls sees that as one long pause among instant ones, which is a description of the batching rather than of the work.

The reporter is told what actually happens: which entries are being worked on, how far an entry large enough to be compressed on its own has got, and when each one is in.

The three say different things, and each says what it can honestly say:

• on_entry_start comes before the work, and for a batch it comes for every entry in it at once, because they are compressed at the same time as each other and no one of them is the one being worked on.
• on_progress reports bytes of archive produced against the size the entry declared, and only for an entry compressed on its own. It is the work rather than the reading: such an entry is taken in far faster than it is compressed, so a count of what has been read would reach the end within a second and leave the rest of the wait silent.
• on_ratio comes with each completed entry and covers the archive so far on both sides, which is the only total a writer knows: what it will hold in the end depends on calls that have not been made yet.

Entries do not begin and end one at a time. An entry large enough to be compressed on its own is left finishing while the entry after it is read, and a batch is compressed while a large entry is, so a reporter can be told an entry has started before it is told the one before it has finished. What is guaranteed is the order they are finished in, which is the order they were added: an entry is reported finished when its bytes are in the archive, and they go in as they were accepted.

A reporter can call the writing off from either of two places. Answering on_progress with false stops the entry being written where it stands, and is the only way to stop during one; should_cancel is asked before each entry is accepted. Both give the caller Error::Cancelled, but they leave different things behind: an entry stopped partway has put bytes in the sink that belong to no folder, so the archive cannot be finished, while one refused before it started leaves an archive that can.

use zesven::{StatisticsProgress, write::Writer};

let writer = Writer::create_path("archive.7z")?
    .progress(StatisticsProgress::new());

pub fn options(self, options: WriteOptions) -> Self

Sets the write options.

Entries already accepted keep the options they were accepted under. Anything still waiting is written out with those before the next entry is taken, so a change here never reaches back over work already done.

pub fn finish_into_inner(self) -> Result<(WriteResult, W)>

Finishes writing the archive and returns the underlying sink.

This is useful when you need access to the written data, such as when writing to a Cursor<Vec<u8>> and need to retrieve the buffer.

Returns

A tuple of (WriteResult, W) where W is the underlying sink.

Errors

Returns an error if header writing fails.

Example

use zesven::write::Writer;
use std::io::Cursor;

let mut writer = Writer::create(Cursor::new(Vec::new()))?;
writer.add_bytes("test.txt".try_into()?, b"Hello")?;
let (result, cursor) = writer.finish_into_inner()?;
let archive_bytes = cursor.into_inner();