Zip

https://docs.rs/zip/latest/zip/
Admin
Zip is a Rust library that supports reading and writing ZIP archives with various compression...
Tokens:157,350
Snippets:1,692
Trust Score:9.1
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Basic ZipWriter usage example

Source: https://docs.rs/zip/latest/zip/write/struct.ZipWriter.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to create a ZipWriter, add a file with SimpleFileOptions, write data, and finish the archive. The example uses a Cursor and Vec for in-memory output.

```rust
use zip::ZipWriter;
use std::io::Write;
use zip::write::SimpleFileOptions;

// We use a cursor + vec here, though you'd normally use a `File`
let mut cursor = std::io::Cursor::new(Vec::new());
let mut archive = ZipWriter::new(&mut cursor);

let options = SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored);
archive.start_file("hello_world.txt", options)?;
archive.write(b"Hello, World!")?;
// also direct write with
// std::io::copy(&mut file, &mut zip)?;

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

// raw zip data is available as a Vec<u8>
let zip_bytes = cursor.into_inner();
```

--------------------------------

### Result::is_ok_and example

Source: https://docs.rs/zip/latest/zip/result/type.ZipResult.html?search=

Example for Result::is_ok_and, checking if the result is Ok and the value matches a predicate.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.is_ok_and(|x| x > 1), true);

let x: Result<u32, &str> = Ok(0);
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<u32, &str> = Err("hey");
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<String, &str> = Ok("ownership".to_string());
assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

--------------------------------

### start_file

Source: https://docs.rs/zip/latest/zip/write/struct.ZipWriter.html?search=std%3A%3Avec

Creates a file in the archive and starts writing its contents.

```APIDOC
## start_file

### Description
Creates a file in the archive and starts writing its contents. The file must not have the same name as a file already in the archive. The data should be written using the `Write` implementation on this `ZipWriter`.

### Method
pub fn start_file<S: ToString, T: FileOptionExtension>(&mut self, name: S, options: FileOptions<'_, T>) -> ZipResult<()>

### Parameters
- **name** (S) - Required - The name of the file to create.
- **options** (FileOptions<'_, T>) - Required - The file options for the new file.

### Returns
- **ZipResult<()>** - Result indicating success or failure.
```

--------------------------------

### start_file_from_path

Source: https://docs.rs/zip/latest/zip/write/struct.ZipWriter.html?search=

Starts a file, taking a Path as argument.

```APIDOC
## start_file_from_path

### Description
Starts a file, taking a Path as argument. This function ensures that the '/' path separator is used and normalizes `.` and `..`. It ignores any `..` or Windows drive letter that would produce a path outside the ZIP file's root.

### Method
start_file_from_path

### Signature
`pub fn start_file_from_path<E: FileOptionExtension, P: AsRef<Path>>(&mut self, path: P, options: FileOptions<'_, E>) -> ZipResult<()>`

### Parameters
- **path** (P) - Required - The path of the file to start.
- **options** (FileOptions<'_, E>) - Required - The file options.

### Returns
- **ZipResult<()>** - Ok(()) on success, or an error.
```

--------------------------------

### Result::is_ok example

Source: https://docs.rs/zip/latest/zip/result/type.ZipResult.html?search=

Example for Result::is_ok, checking if the result is Ok.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

--------------------------------

### unwrap: basic usage and panic example

Source: https://docs.rs/zip/latest/zip/result/type.ZipResult.html?search=

Shows the basic usage of `unwrap` on an `Ok` value and the panic behavior on an `Err` value. The first example asserts the returned value; the second demonstrates the panic message.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
x.unwrap(); // panics with `emergency failure`
```

--------------------------------

### Zip creation fuzzer output example

Source: https://docs.rs/zip/latest/zip/index.html?search=

Example of Rust code that the write fuzzer might generate, showing how it constructs a zip archive.

```rust
writer.start_file_from_path("", FileOptions { compression_method: Stored, compression_level: None, last_modified_time: DateTime::from_date_and_time(2048, 1, 1, 0, 0, 0)?, permissions: None, large_file: false, encrypt_with: None, extended_options: ExtendedFileOptions {extra_data: vec![].into(), central_extra_data: vec![].into()}, alignment: 0 })?;
writer.write_all(&[])?;
writer
let _ = writer.finish_into_readable()?;
```

--------------------------------

### Example usage of root_dir_common_filter

Source: https://docs.rs/zip/latest/zip/read/fn.root_dir_common_filter.html?search=

Example assertions showing the expected behavior of `root_dir_common_filter`. It returns `true` for normal files like `foo.txt` and `false` for system files like `.DS_Store`, `Thumbs.db`, and paths under `__MACOSX`.

```rust
assert!(zip::read::root_dir_common_filter(Path::new("foo.txt")));
assert!(!zip::read::root_dir_common_filter(Path::new(".DS_Store")));
assert!(!zip::read::root_dir_common_filter(Path::new("Thumbs.db")));
assert!(!zip::read::root_dir_common_filter(Path::new("__MACOSX")));
assert!(!zip::read::root_dir_common_filter(Path::new("__MACOSX/foo.txt")));
```

--------------------------------

### Result::flatten example

Source: https://docs.rs/zip/latest/zip/result/type.ZipResult.html?search=

Example for Result::flatten, converting Result<Result<T, E>, E> to Result<T, E>.

```rust
let x: Result<Result<&'static str, u32>, u32> = Ok(Ok("hello"));
assert_eq!(Ok("hello"), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));
assert_eq!(Err(6), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Err(6);
assert_eq!(Err(6), x.flatten());
```

--------------------------------

### Result::transpose example

Source: https://docs.rs/zip/latest/zip/result/type.ZipResult.html?search=

Example for Result::transpose, converting a Result<Option<T>, E> into an Option<Result<T, E>>.

```rust
#[derive(Debug, Eq, PartialEq)]
struct SomeErr;

let x: Result<Option<i32>, SomeErr> = Ok(Some(5));
let y: Option<Result<i32, SomeErr>> = Some(Ok(5));
assert_eq!(x.transpose(), y);
```

--------------------------------

### and_then: example function returning Result

Source: https://docs.rs/zip/latest/zip/result/type.ZipResult.html?search=

Example for `and_then` showing a function that returns a `Result`. The snippet is incomplete; it only defines the function and does not show the call to `and_then`.

```rust
fn sq_then_to_string(x: u32) -> Result<String, &'static str> {
    x.checked_mul(x).map(|sq| sq.to_string()).ok_or("overflowed")
}
```

--------------------------------

### Result::copied example

Source: https://docs.rs/zip/latest/zip/result/type.ZipResult.html?search=

Example for Result::copied on a Result<&T, E>, copying the Ok value.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

--------------------------------

### ZipArchive::central_directory_start

Source: https://docs.rs/zip/latest/zip/read/struct.ZipArchive.html?search=std%3A%3Avec

Returns the starting offset of the ZIP central directory.

```APIDOC
## ZipArchive::central_directory_start

### Description
Get the starting offset of the zip central directory.

### Method
`pub fn central_directory_start(&self) -> u64`

### Returns
- `u64` - The starting offset of the central directory.
```

--------------------------------

### iter_mut: Mutably iterate over contained Ok value

Source: https://docs.rs/zip/latest/zip/result/type.ZipResult.html?search=

Shows `iter_mut` to get a mutable iterator over the contained value. The example modifies the `Ok` value to 40 and checks that `Err` yields no items.

```rust
let mut x: Result<u32, &str> = Ok(7);
match x.iter_mut().next() {
    Some(v) => *v = 40,
    None => {},
}
assert_eq!(x, Ok(40));

let mut x: Result<u32, &str> = Err("nothing!");
assert_eq!(x.iter_mut().next(), None);
```

--------------------------------

### Mutate Result contents with Result::as_mut

Source: https://docs.rs/zip/latest/zip/result/type.ZipResult.html?search=

Demonstrates `Result::as_mut` to get mutable references to the contained `Ok` or `Err` value. The example defines a helper function that mutates the inner value and then verifies the changes.

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

--------------------------------

### Install cargo-afl

Source: https://docs.rs/zip/latest/zip/index.html?search=

Install the cargo-afl tool required for fuzzing.

```bash
cargo install cargo-afl
```

--------------------------------

### start_file

Source: https://docs.rs/zip/latest/zip/write/struct.ZipWriter.html?search=u32+-%3E+bool

Creates a file in the archive and starts writing its contents. The file must not have the same name as a file already in the archive.

```APIDOC
## start_file

### Description
Creates a file in the archive and starts writing its contents. The file must not have the same name as a file already in the archive.

### Method
`pub fn start_file<S: ToString, T: FileOptionExtension>(&mut self, name: S, options: FileOptions<'_, T>) -> ZipResult<()>`

### Parameters
- `name` (S) - Required - The name of the file to create.
- `options` (FileOptions<'_, T>) - Required - The file options for the new file.

### Returns
- `ZipResult<()>` - Result indicating success or failure.

```

--------------------------------

### finish_into_readable example

Source: https://docs.rs/zip/latest/zip/write/struct.ZipWriter.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates using finish_into_readable to write the zip file and then read it back as a ZipArchive, avoiding parsing the central directory for performance.

```rust
 use std::io::{Cursor, Read, Write};
 use zip::{ZipArchive, ZipWriter, write::SimpleFileOptions};

 let buf = Cursor::new(Vec::new());
 let mut zip = ZipWriter::new(buf);
 let options = SimpleFileOptions::default();
 zip.start_file("a.txt", options)?;
 zip.write_all(b"hello\n")?;

 let mut zip = zip.finish_into_readable()?;
 let mut s: String = String::new();
 zip.by_name("a.txt")?.read_to_string(&mut s)?;
 assert_eq!(s, "hello\n");
```

--------------------------------

### Result::is_err example

Source: https://docs.rs/zip/latest/zip/result/type.ZipResult.html?search=

Example for Result::is_err, checking if the result is Err.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```

--------------------------------

### system

Source: https://docs.rs/zip/latest/zip/write/type.SimpleFileOptions.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Set the `system` field for the new file. If not set, the `zip` crate will use the current system.

```APIDOC
## system

### Description
Set the `system` field for the new file. If not set, the `zip` crate will use the current system.

### Method Signature
```rust
pub const fn system(self, system: System) -> Self
```

### Parameters
- `system` (System) - Required - The system to set.

### Returns
- `Self` - The updated `FileOptions` instance.

```

--------------------------------

### Result::cloned example

Source: https://docs.rs/zip/latest/zip/result/type.ZipResult.html?search=

Example for Result::cloned on a Result<&T, E>, cloning the Ok value.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

--------------------------------

### start_file_from_path

Source: https://docs.rs/zip/latest/zip/write/struct.ZipWriter.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Documentation for the `start_file_from_path` method of `ZipWriter`.

```APIDOC
## `start_file_from_path<E: FileOptionExtension, P: AsRef<Path>>(&mut self, path: P, options: FileOptions<'_, E>) -> ZipResult<()>`

### Description
Starts a file, taking a `Path` as argument. This function ensures that the `/` path separator is used and normalizes `.` and `..`. It ignores any `..` or Windows drive letter that would produce a path outside the ZIP file’s root.

### Method
`start_file_from_path`

### Parameters
- **path** (`P`) - Required - The path of the file to start.
- **options** (`FileOptions<'_, E>`) - Required - The file options for the new file.

### Return Value
- `ZipResult<()>` - Returns `Ok(())` on success, or a `ZipError` on failure.
```

--------------------------------

### System::from_version_made_by

Source: https://docs.rs/zip/latest/zip/enum.System.html

Parses a `version_made_by` block in a local entry block and returns a System instance.

```APIDOC
## System::from_version_made_by

### Description
Parses the `version_made_by` block in a local entry block and returns a `System` instance.

### Method
`pub fn from_version_made_by(version_made_by: u16) -> Self`

### Parameters
- `version_made_by` (u16) - Required - The version made by value to parse.

### Returns
- `Self` - A `System` instance parsed from the input.

```

--------------------------------

### Result::flatten nested example

Source: https://docs.rs/zip/latest/zip/result/type.ZipResult.html?search=

Example showing that flatten only removes one level of nesting at a time.

```rust
let x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));
assert_eq!(Ok(Ok("hello")), x.flatten());
assert_eq!(Ok("hello"), x.flatten().flatten());
```

--------------------------------

### into_full_options

Source: https://docs.rs/zip/latest/zip/write/type.SimpleFileOptions.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Convert to `FullFileOptions`.

```APIDOC
## into_full_options

### Description
Convert to `FullFileOptions`.

### Method Signature
```rust
pub fn into_full_options(self) -> FullFileOptions<'k>
```

### Returns
- `FullFileOptions<'k>` - The converted `FullFileOptions` instance.

```

--------------------------------

### System

Source: https://docs.rs/zip/latest/zip/enum.System.html?search=

Documentation for the System enum in the zip crate, including its variants and the from_version_made_by method.

```APIDOC
## Enum System

### Description
Represents the system that created a ZIP file, as stored in the `version made by` field (upper byte).

### Variants
- **Dos = 0** - `MS-DOS` and `OS/2` (`FAT` / `VFAT` / `FAT32` file systems; default on Windows)
- **Amiga = 1** - `Amiga`
- **OpenVMS = 2** - `OpenVMS`
- **Unix = 3** - Default on Unix; default for symlinks on all platforms
- **VmCms = 4** - `VM/CMS`
- **AtariSt = 5** - `Atari ST`
- **Os2 = 6** - `OS/2 H.P.F.S.`
- **Macintosh = 7** - Legacy `Mac OS`, pre `OS X`
- **ZSystemO = 8** - `Z-System`
- **CPM = 9** - `CP/M`
- **WindowsNTFS = 10** - Windows NTFS (with extra attributes; not used by default)
- **MVS = 11** - `MVS (OS/390 - Z/OS)`
- **VSE = 12** - `VSE`
- **AcornRisc = 13** - `Acorn Risc`
- **VFAT = 14** - `VFAT`
- **AlternateMVS = 15** - alternate MVS
- **BeOS = 16** - `BeOS`
- **Tandem = 17** - `Tandem`
- **Os400 = 18** - `OS/400`
- **OsDarwin = 19** - `OS X` (Darwin) (with extra attributes; not used by default)
- **Unknown = 255** - unused

### Implementations

#### `pub fn from_version_made_by(version_made_by: u16) -> Self`

Parse `version_made_by` block in local entry block.

##### Parameters
- **version_made_by** (u16) - The `version made by` field value.

##### Returns
- **Self** - The corresponding `System` variant.
```

--------------------------------

### expect: Recommended message style for env var

Source: https://docs.rs/zip/latest/zip/result/type.ZipResult.html?search=

Shows the recommended style for `expect` messages: describe the reason you expect the `Result` to be `Ok`. The example reads an environment variable and panics with a message that includes the word 'should'.

```rust
let path = std::env::var("IMPORTANT_PATH")
    .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");
```

--------------------------------

### Result::cloned on mutable reference example

Source: https://docs.rs/zip/latest/zip/result/type.ZipResult.html?search=

Example for Result::cloned on a Result<&mut T, E>, cloning the Ok value.

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

--------------------------------

### Result::copied on mutable reference example

Source: https://docs.rs/zip/latest/zip/result/type.ZipResult.html?search=

Example for Result::copied on a Result<&mut T, E>, copying the Ok value.

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

--------------------------------

### FileOptions<'k, ()> methods

Source: https://docs.rs/zip/latest/zip/write/type.SimpleFileOptions.html

Methods available when the extension type is ().

```APIDOC
## Methods for FileOptions<'k, ()>

### into_full_options

```rust
pub fn into_full_options(self) -> FullFileOptions<'k>
```

Convert to `FullFileOptions`.

```

--------------------------------

### system

Source: https://docs.rs/zip/latest/zip/write/type.FullFileOptions.html?search=

Sets the system field for the new file.

```APIDOC
## system

### Description
Sets the system field for the new file. If not set, the zip crate will use the current system.

### Method
pub const fn system(self, system: System) -> Self

### Parameters
- **system** (System) - Required - The system to set.

### Returns
Self - The updated FileOptions instance.
```

--------------------------------

### ZipArchive::with_config

Source: https://docs.rs/zip/latest/zip/read/struct.ZipArchive.html?search=std%3A%3Avec

Constructs a new ZipArchive with a custom configuration.

```APIDOC
## ZipArchive::with_config

### Description
Read a ZIP archive providing a read configuration, collecting the files it contains. This uses the central directory record of the ZIP file, and ignores local file headers.

### Method
`pub fn with_config(config: Config, reader: R) -> ZipResult<ZipArchive<R>>`

### Parameters
- `config` (Config) - Required - The read configuration.
- `reader` (R) - Required - The reader to read the ZIP archive from.

### Returns
- `ZipResult<ZipArchive<R>>` - The ZIP archive reader.
```

--------------------------------

### FileOptions methods

Source: https://docs.rs/zip/latest/zip/write/type.SimpleFileOptions.html

Builder methods for configuring file options such as encryption, compression, permissions, and more.

```APIDOC
## Methods

### has_encryption

```rust
pub const fn has_encryption(&self) -> bool
```

Indicates whether this file will be encrypted (whether with AES or `ZipCrypto`).

### compression_method

```rust
pub const fn compression_method(self, method: CompressionMethod) -> Self
```

Set the compression method for the new file. The default is `CompressionMethod::Deflated` if it is enabled. If not, `CompressionMethod::Bzip2` is the default if it is enabled. If neither `bzip2` nor `deflate` is enabled, `CompressionMethod::Stored` becomes the default and files are written uncompressed.

### system

```rust
pub const fn system(self, system: System) -> Self
```

Set the `system` field for the new file. If not set, the `zip` crate will use the current system.

### compression_level

```rust
pub const fn compression_level(self, level: Option<i64>) -> Self
```

Set the compression level for the new file. `None` value specifies default compression level. Range of values depends on compression method:
- `Deflated`: 10 - 264 for Zopfli, 0 - 9 for other encoders. Default is 24 if Zopfli is the only encoder, or 6 otherwise.
- `Bzip2`: 0 - 9. Default is 6
- `Zstd`: -7 - 22, with zero being mapped to default level. Default is 3
- others: only `None` is allowed

### last_modified_time

```rust
pub const fn last_modified_time(self, mod_time: DateTime) -> Self
```

Set the last modified time. The default is the current timestamp if the 'time' feature is enabled, and 1980-01-01 otherwise.

### unix_permissions

```rust
pub const fn unix_permissions(self, mode: u32) -> Self
```

Set the permissions for the new file. The format is represented with unix-style permissions. The default is `0o644`, which represents `rw-r--r--` for files, and `0o755`, which represents `rwxr-xr-x` for directories. This method only preserves the file permissions bits (via a `& 0o777`) and discards higher file mode bits. So it cannot be used to denote an entry as a directory, symlink, or other special file type.

### large_file

```rust
pub const fn large_file(self, large: bool) -> Self
```

Set whether the new file's compressed and uncompressed size is less than 4 GiB. If set to `false` and the file exceeds the limit, an I/O error is thrown and the file is aborted. If set to `true`, readers will require ZIP64 support and if the file does not exceed the limit, 20 B are wasted. The default is `false`.

### with_aes_encryption_and_salt

```rust
pub fn with_aes_encryption_and_salt(self, password: &[u8], salt: AesSalt) -> FileOptions<'_, T>
```

Available on **crate feature `aes-crypto`** only. Set the AES encryption parameters. The `salt` must be at least 8 bytes long for AES-128, and at least 16 bytes long for AES-256. This method is not recommended, since having a fixed salt is not secure. Consider using `with_aes_encryption` instead, which uses a random salt and is more secure.

### with_aes_encryption

```rust
pub fn with_aes_encryption(self, mode: AesMode, password: &str) -> FileOptions<'_, T>
```

Available on **crate feature `aes-crypto`** only. Set the AES encryption parameters.

### with_aes_encryption_bytes

```rust
pub fn with_aes_encryption_bytes(self, mode: AesMode, password: &[u8]) -> FileOptions<'_, T>
```

Available on **crate feature `aes-crypto`** only. Set the AES encryption parameters.

### with_zopfli_buffer

```rust
pub const fn with_zopfli_buffer(self, size: Option<usize>) -> Self
```

Available on **crate feature `deflate-zopfli`** only. Sets the size of the buffer used to hold the next block that Zopfli will compress. The larger the buffer, the more effective the compression, but the more memory is required. A value of `None` indicates no buffer, which is recommended only when all non-empty writes are larger than about 32 KiB.

### get_compression_level

```rust
pub const fn get_compression_level(&self) -> Option<i64>
```

Returns the compression level currently set.

### with_alignment

```rust
pub const fn with_alignment(self, alignment: u16) -> Self
```

Sets the alignment to the given number of bytes.

```

--------------------------------

### read_zipfile_from_stream

Source: https://docs.rs/zip/latest/zip/read/fn.read_zipfile_from_stream.html

Reads a ZipFile from a non-seekable reader. Returns Ok(Some(..)) if a file is present at the start of the stream, Ok(None) if the start of the central directory is encountered. The Drop implementation of ZipFile ensures correct positioning after reading.

```APIDOC
## read_zipfile_from_stream

### Description
Reads `ZipFile` structures from a non-seekable reader. This is an alternative method to read a zip file. If possible, use the `ZipArchive` functions as some information will be missing when reading this manner.

### Function Signature
rust
pub fn read_zipfile_from_stream<R: Read>(
    reader: &mut R,
) -> ZipResult<Option<ZipFile<'_, R>>>


### Parameters
- **reader** (`&mut R`) - Required - A mutable reference to a non-seekable reader implementing `Read`.

### Return Value
- `ZipResult<Option<ZipFile<'_, R>>>` - Returns `Ok(Some(..))` if a file is present at the start of the stream. Returns `Ok(None)` if the start of the central directory is encountered. No more files should be read after this.

### Behavior
- The `Drop` implementation of `ZipFile` ensures that the reader will be correctly positioned after the structure is done.

### Missing Fields
- `comment`: set to an empty string
- `data_start`: set to 0
- `external_attributes`: `unix_mode()`: will return None

```

--------------------------------

### System::from_version_made_by

Source: https://docs.rs/zip/latest/zip/enum.System.html?search=u32+-%3E+bool

Documentation for the System enum and its from_version_made_by method.

```APIDOC
## System::from_version_made_by

### Description
Parses the `version_made_by` block in a local entry block and returns the corresponding `System` enum variant.

### Method
`pub fn from_version_made_by(version_made_by: u16) -> Self`

### Parameters
- **version_made_by** (`u16`) - Required - The `version_made_by` value from the ZIP entry header.

### Return Value
- **System** - The `System` enum variant corresponding to the upper byte of the `version_made_by` value.

### Example
```rust
let system = System::from_version_made_by(0x0300);
assert_eq!(system, System::Unix);
```
```

--------------------------------

### by_index

Source: https://docs.rs/zip/latest/zip/read/struct.ZipArchive.html?search=u32+-%3E+bool

Gets a contained file by index.

```APIDOC
## by_index

### Description
Gets a contained file by index.

### Signature
`pub fn by_index(&mut self, file_number: usize) -> ZipResult<ZipFile<'_, R>>`

### Parameters
- `file_number` (usize) - Required - The index of the file entry.

### Returns
- `ZipResult<ZipFile<'_, R>>` - The file entry if found, otherwise an error.
```

--------------------------------

### ZipWriter::start_file

Source: https://docs.rs/zip/latest/zip/write/struct.ZipWriter.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts a new file in the ZIP archive. Must be called before writing file content.

```APIDOC
## ZipWriter::start_file

### Description
Starts a new file in the ZIP archive. This method must be called before writing file content. After a successful write, the file remains open for writing. After a failed write, call `is_writing_file` to determine if the file remains open.

### Method
Method

### Signature
`pub fn start_file(&mut self, name: &str, options: SimpleFileOptions) -> ZipResult<()>`

### Parameters
- **name** (&str) - Required - The name of the file to add to the archive.
- **options** (SimpleFileOptions) - Required - Options for the file, such as compression method.

### Returns
- **ZipResult<()>** - Ok if the file was started successfully, or an error.

### Example
```rust
use zip::write::SimpleFileOptions;
let options = SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored);
archive.start_file("hello_world.txt", options)?;
```
```

--------------------------------

### ZipWriter::get_comment

Source: https://docs.rs/zip/latest/zip/write/struct.ZipWriter.html

Gets the ZIP archive comment.

```APIDOC
## [Rust] ZipWriter::get_comment

### Description
Gets the ZIP archive comment as a UTF-8 string.

### Method
`pub fn get_comment(&mut self) -> Result<&str, Utf8Error>`

### Parameters
None.

### Returns
- `Result<&str, Utf8Error>` - The comment as a string slice, or a UTF-8 error if the comment is not valid UTF-8.
```

--------------------------------

### get_zip64_comment

Source: https://docs.rs/zip/latest/zip/write/struct.ZipWriter.html?search=std%3A%3Avec

Gets the ZIP64 archive comment. Deprecated.

```APIDOC
## get_zip64_comment

### Description
Gets the ZIP64 archive comment. Deprecated: Zip64 comment is not part of the zip specification - see https://github.com/zip-rs/zip2/pull/747

### Method
pub fn get_zip64_comment(&mut self) -> Option<Result<&str, Utf8Error>>

### Parameters
None

### Returns
- **Option<Result<&str, Utf8Error>>** - The comment as a string slice, or `None` if not set, or an error if invalid UTF-8.
```

--------------------------------

### ZipWriter::get_ref

Source: https://docs.rs/zip/latest/zip/write/struct.ZipWriter.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Gets a reference to the underlying writer.

```APIDOC
## ZipWriter::get_ref

### Description
Gets a reference to the underlying writer in this `ZipWriter`.

### Method
Method

### Signature
`pub fn get_ref(&self) -> Option<&W>`

### Parameters
None

### Returns
- **Option<&W>** - A reference to the underlying writer, or `None` if not available.

### Example
```rust
if let Some(writer) = zip.get_ref() {
    // use writer
}
```
```

--------------------------------

### FileOptions::into_full_options

Source: https://docs.rs/zip/latest/zip/write/type.SimpleFileOptions.html?search=std%3A%3Avec

Convert to FullFileOptions.

```APIDOC
## FileOptions::into_full_options

### Description
Convert to `FullFileOptions`.

### Method
`pub fn into_full_options(self) -> FullFileOptions<'k>`

### Returns
- `FullFileOptions<'k>` - The full file options.
```

--------------------------------

### StreamWriter::get_ref

Source: https://docs.rs/zip/latest/zip/write/struct.StreamWriter.html?search=

Gets a reference to the underlying writer.

```APIDOC
## StreamWriter::get_ref

### Description
Gets a reference to the underlying writer.

### Method
`pub fn get_ref(&self) -> &W`

### Parameters
- `self` (&self) - Required - The StreamWriter instance.

### Returns
- `&W` - A reference to the underlying writer.
```

--------------------------------

### Convert Result to Option with Result::ok

Source: https://docs.rs/zip/latest/zip/result/type.ZipResult.html?search=

Demonstrates `Result::ok` which converts a `Result` into an `Option`, returning `Some` for `Ok` and `None` for `Err`. The example shows both cases.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);
```
Tokens:
Raw