Struct zip::write::ZipWriter

pub struct ZipWriter<W: Write + Seek> { /* private fields */ }

ZIP archive generator

Handles the bookkeeping involved in building an archive, and provides an API to edit its contents.

use std::io::Write;
use zip::write::FileOptions;

// We use a buffer here, though you'd normally use a `File`
let mut buf = [0; 65536];
let mut zip = zip::ZipWriter::new(std::io::Cursor::new(&mut buf[..]));

let options = zip::write::FileOptions::default().compression_method(zip::CompressionMethod::Stored);
zip.start_file("hello_world.txt", options)?;
zip.write(b"Hello, World!")?;

// Apply the changes you've made.
// Dropping the `ZipWriter` will have the same effect, but may silently fail
zip.finish()?;

Implementations

impl<A: Read + Write + Seek> ZipWriter<A>

pub fn new_append(readwriter: A) -> ZipResult<ZipWriter<A>>

Initializes the archive from an existing ZIP archive, making it ready for append.

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

pub fn new(inner: W) -> ZipWriter<W>

Initializes the archive.

Before writing to this object, the ZipWriter::start_file function should be called.

pub fn set_comment<S>(&mut self, comment: S)

where S: Into<String>,

Set ZIP archive comment.

pub fn set_raw_comment(&mut self, comment: Vec<u8>)

Set ZIP archive comment.

This sets the raw bytes of the comment. The comment is typically expected to be encoded in UTF-8

pub fn start_file<S>(&mut self, name: S, options: FileOptions) -> ZipResult<()>

where S: Into<String>,

Create a file in the archive and start writing its’ contents.

The data should be written using the io::Write implementation on this ZipWriter

pub fn start_file_from_path( &mut self, path: &Path, options: FileOptions ) -> ZipResult<()>

👎Deprecated since 0.5.7: by stripping ..s from the path, the meaning of paths can change. Use start_file instead.

Starts a file, taking a Path as argument.

This function ensures that the ‘/’ path separator is used. It also ignores all non ‘Normal’ Components, such as a starting ‘/’ or ‘..’ and ‘.’.

pub fn start_file_aligned<S>( &mut self, name: S, options: FileOptions, align: u16 ) -> Result<u64, ZipError>

where S: Into<String>,

Create an aligned file in the archive and start writing its’ contents.

Returns the number of padding bytes required to align the file.

The data should be written using the io::Write implementation on this ZipWriter

pub fn start_file_with_extra_data<S>( &mut self, name: S, options: FileOptions ) -> ZipResult<u64>

where S: Into<String>,

Create a file in the archive and start writing its extra data first.

Finish writing extra data and start writing file data with ZipWriter::end_extra_data. Optionally, distinguish local from central extra data with ZipWriter::end_local_start_central_extra_data.

Returns the preliminary starting offset of the file data without any extra data allowing to align the file data by calculating a pad length to be prepended as part of the extra data.

The data should be written using the io::Write implementation on this ZipWriter

use byteorder::{LittleEndian, WriteBytesExt};
use zip::{ZipArchive, ZipWriter, result::ZipResult};
use zip::{write::FileOptions, CompressionMethod};
use std::io::{Write, Cursor};

let mut archive = Cursor::new(Vec::new());

{
    let mut zip = ZipWriter::new(&mut archive);
    let options = FileOptions::default()
        .compression_method(CompressionMethod::Stored);

    zip.start_file_with_extra_data("identical_extra_data.txt", options)?;
    let extra_data = b"local and central extra data";
    zip.write_u16::<LittleEndian>(0xbeef)?;
    zip.write_u16::<LittleEndian>(extra_data.len() as u16)?;
    zip.write_all(extra_data)?;
    zip.end_extra_data()?;
    zip.write_all(b"file data")?;

    let data_start = zip.start_file_with_extra_data("different_extra_data.txt", options)?;
    let extra_data = b"local extra data";
    zip.write_u16::<LittleEndian>(0xbeef)?;
    zip.write_u16::<LittleEndian>(extra_data.len() as u16)?;
    zip.write_all(extra_data)?;
    let data_start = data_start as usize + 4 + extra_data.len() + 4;
    let align = 64;
    let pad_length = (align - data_start % align) % align;
    assert_eq!(pad_length, 19);
    zip.write_u16::<LittleEndian>(0xdead)?;
    zip.write_u16::<LittleEndian>(pad_length as u16)?;
    zip.write_all(&vec![0; pad_length])?;
    let data_start = zip.end_local_start_central_extra_data()?;
    assert_eq!(data_start as usize % align, 0);
    let extra_data = b"central extra data";
    zip.write_u16::<LittleEndian>(0xbeef)?;
    zip.write_u16::<LittleEndian>(extra_data.len() as u16)?;
    zip.write_all(extra_data)?;
    zip.end_extra_data()?;
    zip.write_all(b"file data")?;

    zip.finish()?;
}

let mut zip = ZipArchive::new(archive)?;
assert_eq!(&zip.by_index(0)?.extra_data()[4..], b"local and central extra data");
assert_eq!(&zip.by_index(1)?.extra_data()[4..], b"central extra data");

pub fn end_local_start_central_extra_data(&mut self) -> ZipResult<u64>

End local and start central extra data. Requires ZipWriter::start_file_with_extra_data.

Returns the final starting offset of the file data.

pub fn end_extra_data(&mut self) -> ZipResult<u64>

End extra data and start file data. Requires ZipWriter::start_file_with_extra_data.

Returns the final starting offset of the file data.

pub fn raw_copy_file_rename<S>( &mut self, file: ZipFile<'_>, name: S ) -> ZipResult<()>

where S: Into<String>,

Add a new file using the already compressed data from a ZIP file being read and renames it, this allows faster copies of the ZipFile since there is no need to decompress and compress it again. Any ZipFile metadata is copied and not checked, for example the file CRC.

use std::fs::File;
use std::io::{Read, Seek, Write};
use zip::{ZipArchive, ZipWriter};

fn copy_rename<R, W>(
    src: &mut ZipArchive<R>,
    dst: &mut ZipWriter<W>,
) -> zip::result::ZipResult<()>
where
    R: Read + Seek,
    W: Write + Seek,
{
    // Retrieve file entry by name
    let file = src.by_name("src_file.txt")?;

    // Copy and rename the previously obtained file entry to the destination zip archive
    dst.raw_copy_file_rename(file, "new_name.txt")?;

    Ok(())
}

pub fn raw_copy_file(&mut self, file: ZipFile<'_>) -> ZipResult<()>

Add a new file using the already compressed data from a ZIP file being read, this allows faster copies of the ZipFile since there is no need to decompress and compress it again. Any ZipFile metadata is copied and not checked, for example the file CRC.

use std::fs::File;
use std::io::{Read, Seek, Write};
use zip::{ZipArchive, ZipWriter};

fn copy<R, W>(src: &mut ZipArchive<R>, dst: &mut ZipWriter<W>) -> zip::result::ZipResult<()>
where
    R: Read + Seek,
    W: Write + Seek,
{
    // Retrieve file entry by name
    let file = src.by_name("src_file.txt")?;

    // Copy the previously obtained file entry to the destination zip archive
    dst.raw_copy_file(file)?;

    Ok(())
}

pub fn add_directory<S>( &mut self, name: S, options: FileOptions ) -> ZipResult<()>

where S: Into<String>,

Add a directory entry.

As directories have no content, you must not call ZipWriter::write before adding a new file.

pub fn add_directory_from_path( &mut self, path: &Path, options: FileOptions ) -> ZipResult<()>

👎Deprecated since 0.5.7: by stripping ..s from the path, the meaning of paths can change. Use add_directory instead.

Add a directory entry, taking a Path as argument.

This function ensures that the ‘/’ path separator is used. It also ignores all non ‘Normal’ Components, such as a starting ‘/’ or ‘..’ and ‘.’.

pub fn finish(&mut self) -> ZipResult<W>

Finish the last file and write all other zip-structures

This will return the writer, but one should normally not append any data to the end of the file. Note that the zipfile will also be finished on drop.

pub fn add_symlink<N, T>( &mut self, name: N, target: T, options: FileOptions ) -> ZipResult<()>

where N: Into<String>, T: Into<String>,

Add a symlink entry.

The zip archive will contain an entry for path name which is a symlink to target.

No validation or normalization of the paths is performed. For best results, callers should normalize \ to / and ensure symlinks are relative to other paths within the zip archive.

WARNING: not all zip implementations preserve symlinks on extract. Some zip implementations may materialize a symlink as a regular file, possibly with the content incorrectly set to the symlink target. For maximum portability, consider storing a regular file instead.

Trait Implementations

impl<W: Write + Seek> Drop for ZipWriter<W>

fn drop(&mut self)

Executes the destructor for this type.

impl<W: Write + Seek> Write for ZipWriter<W>

fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this writer, returning how many bytes were written.

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

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

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

Attempts to write an entire buffer into this writer.

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, fmt: 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.