ZIP Foundation

https://github.com/weichsel/zipfoundation
Admin
ZIP Foundation is a Swift library for creating, reading, and modifying ZIP archive files with...
Tokens:43,274
Snippets:275
Trust Score:8.3
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Zip a directory tree with deflate compression

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/filemanager-zip.md

Example showing how to zip a directory using the deflate compression method and an optional progress object.

```swift
let fileManager = FileManager()
let currentWorkingPath = fileManager.currentDirectoryPath
var sourceURL = URL(fileURLWithPath: currentWorkingPath)
sourceURL.appendPathComponent("folder")
var destinationURL = URL(fileURLWithPath: currentWorkingPath)
destinationURL.appendPathComponent("archive.zip")
let progress = Progress(totalUnitCount: 0)
try fileManager.zipItem(at: sourceURL, to: destinationURL,
                        compressionMethod: .deflate, progress: progress)
```

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

### Zip a single file with error handling

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/filemanager-zip.md

Example demonstrating how to zip a single file and handle specific CocoaError cases.

```swift
do {
    try fileManager.zipItem(at: fileURL, to: archiveURL)
} catch let error as CocoaError {
    switch error.code {
    case .fileWriteFileExists:
        print("Destination archive already exists.")
    case .fileReadNoSuchFile:
        print("Source item does not exist.")
    default:
        print("Zip failed: \(error)")
    }
} catch {
    print("Zip failed: \(error)")
}
```

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

### Compress a chunked in-memory source

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/data-compression.md

Example demonstrating how to compress an in-memory data source using a provider closure to supply chunks and a consumer closure to collect the output.

```swift
let input = Data("hello world, hello world, ...".utf8)
let compressed = try Data.compress(size: Int64(input.count), bufferSize: 8 * 1024,
    provider: { position, size in
        let start = Int(position)
        return input.subdata(in: start..<min(start + size, input.count))
    },
    consumer: { chunk in compressedBuffer.append(chunk) })
```

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

### Unzip an archive

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/filemanager-zip.md

Basic usage example for extracting a ZIP archive to a destination directory.

```swift
let fileManager = FileManager()
let currentWorkingPath = fileManager.currentDirectoryPath
var sourceURL = URL(fileURLWithPath: currentWorkingPath)
sourceURL.appendPathComponent("archive.zip")
var destinationURL = URL(fileURLWithPath: currentWorkingPath)
destinationURL.appendPathComponent("directory")
do {
    try fileManager.createDirectory(at: destinationURL, withIntermediateDirectories: true, attributes: nil)
    try fileManager.unzipItem(at: sourceURL, to: destinationURL)
} catch {
    print("Extraction of ZIP archive failed with error:\(error)")
}
```

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

### extract(entry:bufferSize:skipCRC32:progress:consumer:) with example

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/archive.md

Streams an entry's content to a consumer closure instead of writing to the filesystem. The example prints chunk sizes as data is received.

```swift
public func extract(_ entry: Entry, bufferSize: Int = defaultReadChunkSize, skipCRC32: Bool = false,
                    progress: Progress? = nil, consumer: Consumer) throws -> CRC32
```

```swift
try archive.extract(entry, consumer: { (data) in
    print(data.count) // chunk sizes as the entry is streamed
})
```

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

### Add ZIPFoundation via CocoaPods

Source: https://github.com/weichsel/zipfoundation/blob/development/README.md

Add ZIPFoundation to your Podfile and install it with CocoaPods. The example sets the platform to iOS 10.0 and uses frameworks.

```ruby
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '10.0'
use_frameworks!
target '<Your Target Name>' do
    pod 'ZIPFoundation', '~> 0.9'
end
```

```bash
$ pod install
```

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

### Data.decompress(size:bufferSize:skipCRC32:provider:consumer:)

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/data-compression.md

Documentation for the Data.decompress static method, including parameters, return value, errors, and an example.

```APIDOC
## `Data.decompress(size:bufferSize:skipCRC32:provider:consumer:)`

### Description
Decompresses data using the platform's native compression API (Apple's Compression framework or zlib on other platforms). It accepts a provider closure that supplies compressed input chunks and a consumer closure that receives decompressed output chunks, and returns the CRC32 checksum of the decompressed content.

### Method
`static func decompress`

### Signature
```swift
public static func decompress(size: Int64, bufferSize: Int, skipCRC32: Bool,
                              provider: Provider, consumer: Consumer) throws -> CRC32
```

### Parameters
- **size** (`Int64`) - Required - The compressed size of the data to be decompressed.
- **bufferSize** (`Int`) - Required - The maximum size of the decompression buffer.
- **skipCRC32** (`Bool`) - Required - Skip calculation of the CRC32 checksum to improve performance.
- **provider** (`Provider`) - Required - Closure supplying the compressed input chunks.
- **consumer** (`Consumer`) - Required - Closure receiving the decompressed output chunks.

### Returns
- **CRC32** - The CRC32 checksum of the decompressed content, or `0` when `skipCRC32` is true.

### Throws
- `Data.CompressionError.invalidStream` - If `inflateInit2_` fails.
- `Data.CompressionError.corruptedData` - If zlib returns `Z_NEED_DICT`, `Z_DATA_ERROR`, or `Z_MEM_ERROR`, or if the Apple stream status is not OK/END.
- Errors from `provider`/`consumer` propagate.

### Platform Dispatch
- **Apple** - Uses `Data.process(operation: COMPRESSION_STREAM_DECODE, …)`.
- **Other platforms** - Uses `Data.decode(bufferSize:skipCRC32:provider:consumer:)` (zlib `inflate` with `Z_NO_FLUSH` until `Z_STREAM_END`).

### Example
```swift
let checksum = try Data.decompress(size: Int64(compressedBuffer.count), bufferSize: 8 * 1024,
                                   skipCRC32: false,
    provider: { position, size in
        let start = Int(position)
        return compressedBuffer.subdata(in: start..<min(start + size, compressedBuffer.count))
    },
    consumer: { chunk in decompressed.append(chunk) })
print("round-trip CRC32: \(checksum)") // == input.crc32(checksum: 0)
```
```

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

### Decompressing a buffer

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/data-compression.md

An example showing how to use Data.decompress to process a compressed buffer, providing chunks via a provider closure and consuming them via a consumer closure.

```swift
let checksum = try Data.decompress(size: Int64(compressedBuffer.count), bufferSize: 8 * 1024,
                                   skipCRC32: false,
    provider: { position, size in
        let start = Int(position)
        return compressedBuffer.subdata(in: start..<min(start + size, compressedBuffer.count))
    },
    consumer: { chunk in decompressed.append(chunk) })
print("round-trip CRC32: \(checksum)") // == input.crc32(checksum: 0)
```

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

### Data.crc32(checksum:) usage example

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/data-compression.md

Shows how to compute a CRC32 checksum for a Data object, including chaining multiple Data objects by passing the previous checksum as the seed.

```swift
let data = Data("hello".utf8)
let checksum = data.crc32(checksum: 0) // chained: data1.crc32(checksum: data2.crc32(checksum: 0))
```

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

### Extract with CRC checks and secure symlink containment

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/filemanager-zip.md

Advanced usage example demonstrating progress tracking, CRC32 verification, and symlink security constraints.

```swift
do {
    let progress = Progress(totalUnitCount: 0)
    try fileManager.unzipItem(at: sourceURL, to: destinationURL,
                              skipCRC32: false,
                              symlinksValidWithin: destinationURL,
                              progress: progress, pathEncoding: .utf8)
} catch Archive.ArchiveError.invalidCRC32 {
    print("Checksum mismatch — the archive is corrupt or was tampered with.")
} catch Archive.ArchiveError.uncontainedSymlink {
    print("An entry contains a symlink escaping the destination directory.")
} catch {
    print("Unzip failed: \(error)")
}
```

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

### Remove an entry by name from a ZIP archive

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/archive.md

Example usage of remove(_:bufferSize:progress:) that looks up an entry by name and removes it, printing an error message on failure.

```swift
guard let entry = archive["file.txt"] else { return }
do {
    try archive.remove(entry)
} catch {
    print("Removing entry from ZIP archive failed with error:\(error)")
}
```

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

### Look up and extract entry by path with subscript(path:)

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/archive.md

The subscript(path:) returns the first Entry matching the given path, or nil. Entry paths are not unique; the first match wins. If pathEncoding is set, matching uses $0.path(using: pathEncoding), otherwise $0.path. The example shows looking up an entry by path and extracting it to a destination URL.

```swift
public subscript(path: String) -> Entry?
```

```swift
guard let entry = archive["file.txt"] else { return }
try archive.extract(entry, to: destinationURL)
```

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

### Add entries to a ZIP archive with addEntry overloads

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/archive.md

These Swift signatures and usage example show how to add entries to a ZIP archive using the addEntry(with:relativeTo:) and addEntry(with:fileURL:) overloads. Both throw Archive.ArchiveError.unwritableArchive when the archive is in read mode. The fileURL overload streams file contents in bufferSize chunks, forces compression to .none for directories and symlinks, and can throw CocoaError, POSIXError, or ArchiveError on failure.

```swift
public func addEntry(with path: String, relativeTo baseURL: URL,
                     compressionMethod: CompressionMethod = .none,
                     bufferSize: Int = defaultWriteChunkSize, progress: Progress? = nil) throws
```

```swift
public func addEntry(with path: String, fileURL: URL, compressionMethod: CompressionMethod = .none,
                     bufferSize: Int = defaultWriteChunkSize, progress: Progress? = nil) throws
```

```swift
let archive = try Archive(url: archiveURL, accessMode: .update)
try archive.addEntry(with: "someFile.txt", fileURL: someAbsoluteFileURL,
                     compressionMethod: .deflate)
```

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

### Iterate over archive entries with makeIterator()

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/archive.md

The makeIterator() method returns an iterator that walks the central directory, skipping encrypted entries and ending after totalNumberOfEntriesInCentralDirectory entries (ZIP64-aware). The example shows iterating over all entries in an archive and printing each entry's path.

```swift
public func makeIterator() -> AnyIterator<Entry>
```

```swift
for entry in archive {
    print(entry.path)
}
```

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

### Archive.init(url:accessMode:pathEncoding:)

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/configuration.md

Initializes an Archive instance with a backing file URL. The access mode determines whether the archive is created, read, or updated, and the path encoding can override the decoding of entry paths.

```APIDOC
## Archive.init(url:accessMode:pathEncoding:)

### Description
Initializes an Archive with a backing file URL. The access mode determines whether the archive is created, read, or updated, and the path encoding can override the decoding of entry paths.

### Method
Initializer

### Endpoint
Archive.init(url:accessMode:pathEncoding:)

### Parameters
#### Parameters
- **url** (URL) - Required - Backing file URL. Must be an existing file for `.read`/`.update`, a non-existing file for `.create`.
- **accessMode** (Archive.AccessMode) - Required - `.create`, `.read` or `.update`. Determines writability and backing-file expectations.
- **pathEncoding** (String.Encoding?) - Optional - Default: `nil`. Overrides the encoding used when **decoding** entry paths from the archive. Paths written via `addEntry` are always UTF-8.

### Response
No return value.
```

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

### extract(entry:to:bufferSize:skipCRC32:symlinksValidWithin:progress:) with example

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/archive.md

Extracts an entry to a file URL with optional CRC32 skipping and symlink containment validation. The example shows error handling for uncontained symlinks and other failures.

```swift
public func extract(_ entry: Entry, to url: URL, bufferSize: Int = defaultReadChunkSize,
                    skipCRC32: Bool = false,
                    symlinksValidWithin: URL? = nil,
                    progress: Progress? = nil) throws -> CRC32
```

```swift
do {
    let checksum = try archive.extract(entry, to: destinationURL,
                                       skipCRC32: true)
    print("Wrote entry, checksum: \(checksum)")
} catch Archive.ArchiveError.uncontainedSymlink {
    print("Refusing to create a symlink pointing outside the destination.")
} catch {
    print("Extraction failed: \(error)")
}
```

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

### Open existing archive for reading

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/archive.md

Opens an existing ZIP archive for reading and prints the path of each entry. The archive URL is constructed from the current working directory. Errors are caught and printed.

```swift
import ZIPFoundation

let fileManager = FileManager()
let currentWorkingPath = fileManager.currentDirectoryPath
var archiveURL = URL(fileURLWithPath: currentWorkingPath)
archiveURL.appendPathComponent("archive.zip")
do {
    let archive = try Archive(url: archiveURL, accessMode: .read)
    for entry in archive { print(entry.path) }
} catch {
    print("Opening the archive failed with error:\(error)")
}
```

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

### Archive.init?(url:accessMode:preferredEncoding:)

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/deprecated-api.md

Deprecated failable initializer that creates an Archive from a URL. Use the throwing initializer Archive(url:accessMode:pathEncoding:) instead.

```APIDOC
## [Deprecated] Archive.init?(url:accessMode:preferredEncoding:)

### Description
Deprecated failable initializer that creates an Archive from a URL. Returns nil instead of throwing. Use the throwing initializer instead.

### Method
Initializer

### Endpoint
Archive.init?(url: URL, accessMode: AccessMode, preferredEncoding: String.Encoding? = nil)

### Parameters
#### Parameters
- **url** (URL) - Required - The URL of the archive file.
- **accessMode** (AccessMode) - Required - The access mode (read, create, update).
- **preferredEncoding** (String.Encoding?) - Optional - The preferred encoding for path names. Maps to pathEncoding in the replacement.

### Replacement
Archive(url:accessMode:pathEncoding:)

### Deprecation Message
Please use the throwing initializer.

```

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

### Create a new ZIP archive with Archive(url:accessMode: .create)

Source: https://github.com/weichsel/zipfoundation/blob/development/README.md

Creates a new Archive by passing a non-existing file URL and AccessMode.create. The archive is created at the specified path.

```swift
let fileManager = FileManager()
let currentWorkingPath = fileManager.currentDirectoryPath
var archiveURL = URL(fileURLWithPath: currentWorkingPath)
archiveURL.appendPathComponent("newArchive.zip")
let archive = try Archive(url: archiveURL, accessMode: .create)
```

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

### Archive.init(data:accessMode:pathEncoding:)

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/configuration.md

Initializes an Archive with in-memory data. The access mode determines whether the archive is created, read, or updated, and the path encoding can override the decoding of entry paths.

```APIDOC
## Archive.init(data:accessMode:pathEncoding:)

### Description
Initializes an Archive with in-memory data. The access mode determines whether the archive is created, read, or updated, and the path encoding can override the decoding of entry paths.

### Method
Archive.init

### Parameters
- `data` (Data) - Optional. Default: `Data()`. In-memory backing. Must contain a valid ZIP archive for `.read`/`.update`; must be empty/omitted for `.create`.
- `accessMode` (Archive.AccessMode) - Required. `.create`, `.read` or `.update`. Determines writability and backing-file expectations.
- `pathEncoding` (String.Encoding?) - Optional. Default: `nil`. Overrides the encoding used when **decoding** entry paths from the archive. Paths written via `addEntry` are always UTF-8.

### Response
No return value.
```

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

### Get total unit count for removing an entry

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/archive.md

Returns the total unit count for removing an entry, calculated as Int64(self.offsetToStartOfCentralDirectory - entry.localSize).

```swift
public func totalUnitCountForRemoving(_ entry: Entry) -> Int64
```

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

### Archive.init?(data:accessMode:preferredEncoding:)

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/deprecated-api.md

Deprecated failable initializer that creates an Archive from in-memory data. Use the throwing initializer Archive(data:accessMode:pathEncoding:) instead.

```APIDOC
## [Deprecated] Archive.init?(data:accessMode:preferredEncoding:)

### Description
Deprecated failable initializer that creates an Archive from in-memory data. Returns nil instead of throwing. Use the throwing initializer instead.

### Method
Initializer

### Endpoint
Archive.init?(data: Data = Data(), accessMode: AccessMode, preferredEncoding: String.Encoding? = nil)

### Parameters
#### Parameters
- **data** (Data) - Optional - The archive data. Defaults to empty Data.
- **accessMode** (AccessMode) - Required - The access mode (read, create, update).
- **preferredEncoding** (String.Encoding?) - Optional - The preferred encoding for path names. Maps to pathEncoding in the replacement.

### Replacement
Archive(data:accessMode:pathEncoding:)

### Deprecation Message
Please use the throwing initializer.

```

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

### Create in-memory ZIP archive with Archive(accessMode: .create)

Source: https://github.com/weichsel/zipfoundation/blob/development/README.md

Creates an in-memory ZIP archive using the `Archive(accessMode: .create)` initializer, adds a text entry, and retrieves the archive data. The `data` parameter is omitted for creation; the provider closure supplies the entry's content.

```swift
let string = "Some string!"
let archive = try Archive(accessMode: .create)
guard let data = string.data(using: .utf8) else { return }
try archive.addEntry(with: "inMemory.txt", type: .file, uncompressedSize: Int64(data.count), bufferSize: 4, provider: { (position, size) -> Data in
    return data.subdata(in: Data.Index(position)..<Int(position)+size)
})
let archiveData = archive.data
```

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

### Archive init(data:accessMode:pathEncoding:)

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/archive.md

Initializer for an in-memory Archive. The `data` parameter provides the backing data; for `.create` it can be omitted (defaults to `Data()`). The archive's `url` is `memory://` and I/O is served by `Archive.MemoryFile`. Throws the same errors as the URL initializer plus `MemoryFileError.invalidMemoryFile` if `funopen`/`fopencookie` fails.

```swift
public init(data: Data = Data(), accessMode mode: AccessMode, pathEncoding: String.Encoding? = nil) throws
```

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

### Create in-memory archive and add entry

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/archive.md

Creates an in-memory archive, adds a text entry using a provider closure, and retrieves the finished archive data. The `bufferSize` is set to 4 and the provider returns a subdata slice for the requested position and size.

```swift
let archive = try Archive(accessMode: .create) // data omitted → Data()
let string = "Some string!"
guard let data = string.data(using: .utf8) else { return }
try archive.addEntry(with: "inMemory.txt", type: .file, uncompressedSize: Int64(data.count),
                     bufferSize: 4, provider: { (position, size) -> Data in
    return data.subdata(in: Data.Index(position)..<Int(position)+size)
})
let archiveData = archive.data // Data? — the finished in-memory archive
```

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

### Get total unit count for reading an entry

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/archive.md

Returns the total unit count for reading an entry: Int64(entry.uncompressedSize) for .file/.symlink, and 1 (defaultDirectoryUnitCount) for .directory.

```swift
public func totalUnitCountForReading(_ entry: Entry) -> Int64
```

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

### zipItem(at:to:shouldKeepParent:compressionMethod:progress:)

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/filemanager-zip.md

Documentation for the FileManager extension method zipItem(at:to:shouldKeepParent:compressionMethod:progress:) that creates a ZIP archive from a file or directory.

```APIDOC
## `zipItem(at:to:shouldKeepParent:compressionMethod:progress:)`

### Description
Creates a ZIP archive at the destination URL from the file or directory at the source URL. This is the recommended high-level entry point for whole-item zip operations.

### Method
`zipItem(at:to:shouldKeepParent:compressionMethod:progress:)`

### Signature
```swift
public func zipItem(at sourceURL: URL, to destinationURL: URL,
                    shouldKeepParent: Bool = true, compressionMethod: CompressionMethod = .none,
                    progress: Progress? = nil) throws
```

### Parameters
- **sourceURL** (`URL`) - Required - File URL pointing to an existing file or directory.
- **destinationURL** (`URL`) - Required - File URL identifying the destination of the zip operation. Must not already exist.
- **shouldKeepParent** (`Bool`) - Optional - Default: `true`. When the source is a directory, use the directory name (`sourceURL.lastPathComponent`) as the root element inside the archive. If `false`, the directory's contents are placed at the archive root.
- **compressionMethod** (`CompressionMethod`) - Optional - Default: `.none`. Compression applied to all entries.
- **progress** (`Progress?`) - Optional - Default: `nil`. Optional progress object. For directories a hierarchy of child `Progress` objects is created (one per item).

### Behavior
- Fails with `CocoaError(.fileReadNoSuchFile, NSFilePathErrorKey: sourceURL.path)` if the source item does not exist (checked via `checkResourceIsReachable()` so broken symlinks are treated as existing).
- Fails with `CocoaError(.fileWriteFileExists, NSFilePathErrorKey: destinationURL.path)` if the destination already exists.
- Creates the destination archive with `Archive(url:accessMode: .create)`.
- **Directory source:** enumerates subpaths (`subpathsOfDirectory(atPath:)`); when `shouldKeepParent` is true it also appends `""` so a root directory entry preserving the directory's file attributes is emitted. Progress total unit count is the sum of `archive.totalUnitCountForAddingItem(at:)` for every item. Each item is added with `archive.addEntry(with:relativeTo:compressionMethod:progress:)`.
- **File (or symlink) source:** sets `progress.totalUnitCount` to `totalUnitCountForAddingItem(at: sourceURL)` and adds `sourceURL.lastPathComponent` relative to `sourceURL.deletingLastPathComponent()`.

### Throws
- `CocoaError` cases above; `Archive.ArchiveError` and `POSIXError` from the underlying `Archive` initializer / `addEntry` calls; `CocoaError(.fileReadNoSuchFile)` from zipItem's own guards.

### Example — zip a directory tree with deflate compression
```swift
let fileManager = FileManager()
let currentWorkingPath = fileManager.currentDirectoryPath
var sourceURL = URL(fileURLWithPath: currentWorkingPath)
sourceURL.appendPathComponent("folder")
var destinationURL = URL(fileURLWithPath: currentWorkingPath)
destinationURL.appendPathComponent("archive.zip")
let progress = Progress(totalUnitCount: 0)
try fileManager.zipItem(at: sourceURL, to: destinationURL,
                        compressionMethod: .deflate, progress: progress)
```

### Example — zip a single file and handle errors
```swift
do {
    try fileManager.zipItem(at: fileURL, to: archiveURL)
} catch let error as CocoaError {
    switch error.code {
    case .fileWriteFileExists:
        print("Destination archive already exists.")
    case .fileReadNoSuchFile:
        print("Source item does not exist.")
    default:
        print("Zip failed: \(error)")
    }
} catch {
    print("Zip failed: \(error)")
}
```
```

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

### Get total unit count for adding an item

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/archive.md

Returns the total unit count for adding an item at a URL: Int64(FileManager.fileSizeForItem(at:)) for .file/.symlink, defaultDirectoryUnitCount for .directory, and -1 when the type cannot be determined.

```swift
public func totalUnitCountForAddingItem(at url: URL) -> Int64
```

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

### path(using:) method

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/entry.md

Returns the entry's path within the archive using the specified encoding. The encoding is used to decode the file-name bytes.

```swift
/// Returns the `path` of the receiver within a ZIP `Archive` using a given encoding.
public func path(using encoding: String.Encoding) -> String
```

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

### Entry.path(using:)

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/entry.md

Returns the entry's path within the ZIP archive decoded using the specified string encoding.

```APIDOC
## Entry.path(using:)

### Description
Returns the path of the receiver within a ZIP archive using a given encoding.

### Method
path(using:)

### Parameters
- **encoding** (String.Encoding) - Required - Encoding used to decode the entry's file-name bytes.

### Returns
String - The entry path decoded with the given encoding (e.g. .utf8 or .codepage437).
```

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

### Data.crc32(checksum:)

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/data-compression.md

Calculates the CRC32 checksum of the receiver. The checksum parameter is the starting seed; pass 0 for the initial run or a running checksum to continue a chained calculation. Returns the running CRC32 of the receiver's bytes combined with the seed.

```APIDOC
## Data.crc32(checksum:)

### Description
Calculate the `CRC32` checksum of the receiver.

### Method
`public func crc32(checksum: CRC32) -> CRC32`

### Parameters
- **checksum** (`CRC32`) - Required - Starting seed — pass `0` for the initial run, or a running checksum to continue a chained calculation.

### Returns
The checksum calculated from the bytes of the receiver and the starting seed.

### Implementation Notes
When `zlib` is available (`#if canImport(zlib)`) it delegates to `zlib.crc32`; otherwise it uses the internal lookup-table implementation `Data.builtInCRC32(checksum:)` (256-entry `crcTable` in `Data+Compression.swift`).

### Example
```swift
let data = Data("hello".utf8)
let checksum = data.crc32(checksum: 0) // chained: data1.crc32(checksum: data2.crc32(checksum: 0))
```
```

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

### Data.crc32(checksum:) method signature

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/data-compression.md

Calculates the CRC32 checksum of the receiver's bytes combined with a starting seed. Pass 0 for the initial run or a running checksum to continue a chained calculation. Delegates to zlib.crc32 when available, otherwise uses the internal lookup-table implementation.

```swift
/// Calculate the `CRC32` checksum of the receiver.
///
/// - Parameter checksum: The starting seed.
/// - Returns: The checksum calculated from the bytes of the receiver and the starting seed.
public func crc32(checksum: CRC32) -> CRC32
```

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

### Add an entry from a file using addEntry(with:relativeTo:)

Source: https://github.com/weichsel/zipfoundation/blob/development/README.md

Adds an existing file to an archive opened with .update access mode. The relative path and base URL must form an absolute file URL pointing to the file to add.

```swift
let fileManager = FileManager()
let currentWorkingPath = fileManager.currentDirectoryPath
var archiveURL = URL(fileURLWithPath: currentWorkingPath)
archiveURL.appendPathComponent("archive.zip")
let archive = try Archive(url: archiveURL, accessMode: .update)
var fileURL = URL(fileURLWithPath: currentWorkingPath)
fileURL.appendPathComponent("file.txt")
do {
    try archive.addEntry(with: fileURL.lastPathComponent, relativeTo: fileURL.deletingLastPathComponent())
} catch {
    print("Adding entry to ZIP archive failed with error:\(error)")
}
```

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

### Swift Package Manager Package.swift configuration

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/configuration.md

Configures targets for ZIPFoundation, using libcompression on Apple platforms and a system zlib library on others.

```swift
// swift-tools-version:5.0
import PackageDescription

#if canImport(Compression)
let targets: [Target] = [ ... ]           // .target(name: "ZIPFoundation"), tests only
#else
let targets: [Target] = [
    .systemLibrary(name: "CZLib", pkgConfig: "zlib",
                   providers: [.brew(["zlib"]), .apt(["zlib"])]),
    .target(name: "ZIPFoundation", dependencies: ["CZLib"],
            cSettings: [.define("_GNU_SOURCE", to: "1")],
            linkerSettings: [.linkedLibrary("z")]),
    ...
]
#endif
```

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

### Add ZIPFoundation via Carthage

Source: https://github.com/weichsel/zipfoundation/blob/development/README.md

Add ZIPFoundation to your Cartfile and fetch its sources with Carthage. After fetching, drag ZIPFoundation.xcodeproj into your Xcode project.

```ogdl
github "weichsel/ZIPFoundation" ~> 0.9
```

```bash
carthage update --no-build
```

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

### Archive init(url:accessMode:pathEncoding:)

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/archive.md

Initializer for an Archive backed by a file URL. The `pathEncoding` parameter overrides the encoding used when decoding entry paths; paths added with `addEntry` are always UTF-8 encoded. Throws `POSIXError` if `fopen` fails, or `Archive.ArchiveError.missingEndOfCentralDirectoryRecord` if no End of Central Directory Record is found.

```swift
public init(url: URL, accessMode mode: AccessMode, pathEncoding: String.Encoding? = nil) throws
```

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

### Create new archive with error handling

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/archive.md

Creates a new archive at `newArchiveURL` and handles the case where a file already exists at the destination by catching `CocoaError` with code `.fileWriteFileExists`. Other errors are printed.

```swift
do {
    let archive = try Archive(url: newArchiveURL, accessMode: .create)
    // ... add entries ...
} catch let error as CocoaError where error.code == .fileWriteFileExists {
    print("A file already exists at the destination.")
} catch {
    print("Could not create archive: \(error)")
}
```

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

### Iterating an Archive and Reading Entry Metadata

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/entry.md

Creates an archive in read mode and iterates entries, printing path, type, compression info, sizes, and CRC32. Skips directories.

```Swift
import ZIPFoundation

let archive = try Archive(url: archiveURL, accessMode: .read)
for entry in archive {
    print("\(entry.path) — \(entry.type) — " +
          "compressed: \(entry.isCompressed), \(entry.compressedSize)/\(entry.uncompressedSize) bytes")
    if entry.type == .directory { continue }
    let expected = String(format: "%08X", entry.checksum)
    print("crc32: \(expected)")
}
```

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

### Add entry from memory with provider closure

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/archive.md

Adds an entry from an in-memory string. The provider closure is called repeatedly until the uncompressedSize bytes are provided; with bufferSize 4 and a 12-byte string it is called 3 times. Uses try? so errors are ignored.

```swift
let string = "abcdefghijkl"
guard let data = string.data(using: .utf8) else { return }
try? archive.addEntry(with: "fromMemory.txt", type: .file, uncompressedSize: Int64(data.count),
                      bufferSize: 4, provider: { (position, size) -> Data in
    // Called until the entry data is exhausted (3x in this case).
    return data.subdata(in: Data.Index(position)..<Int(position)+size)
})
```

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

### Testing Entry Type Before Extraction

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/entry.md

Looks up an entry by path and switches on its type to extract appropriately: directories create the directory, symlinks validate the link target via symlinksValidWithin, and files extract with optional CRC check and progress.

```Swift
guard let entry = archive["folder/"] else { return }
switch entry.type {
case .directory:
    try archive.extract(entry, to: destinationURL) // creates the directory
case .symlink:
    // Extraction validates the link target against symlinksValidWithin
    try archive.extract(entry, to: destinationURL, symlinksValidWithin: URL.rootFS)
case .file:
    try archive.extract(entry, to: destinationURL, skipCRC32: false, progress: progress)
}
```

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

### addEntry(with:type:uncompressedSize:modificationDate:permissions:compressionMethod:bufferSize:progress:provider:)

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/archive.md

Adds a new entry to the ZIP archive. This method accepts a path, entry type, uncompressed size, and a provider closure that supplies the data. It supports optional modification date, permissions, compression method, buffer size, and progress reporting.

```APIDOC
## addEntry(with:type:uncompressedSize:modificationDate:permissions:compressionMethod:bufferSize:progress:provider:)

### Description
Adds a new entry to the ZIP archive. The entry can be a file, directory, or symlink. The data for the entry is provided via a closure that is called repeatedly until the specified uncompressed size is reached.

### Method
addEntry

### Signature
public func addEntry(with path: String, type: Entry.EntryType, uncompressedSize: Int64, modificationDate: Date = Date(), permissions: UInt16? = nil, compressionMethod: CompressionMethod = .none, bufferSize: Int = defaultWriteChunkSize, progress: Progress? = nil, provider: Provider) throws

### Parameters
- **path** (String) - Required - Path identifying the Entry within the archive.
- **type** (Entry.EntryType) - Required - Entry type (.file, .directory, .symlink).
- **uncompressedSize** (Int64) - Required - Uncompressed size of the data provided by provider.
- **modificationDate** (Date) - Optional - Default: Date() - Stored as MS-DOS date/time (clamped to 1980-2099).
- **permissions** (UInt16?) - Optional - Default: nil - POSIX permissions; defaults to defaultFilePermissions/defaultDirectoryPermissions by type.
- **compressionMethod** (CompressionMethod) - Optional - Default: .none - Ignored (.none) for directories and symlinks.
- **bufferSize** (Int) - Optional - Default: defaultWriteChunkSize - Max write/compression buffer size.
- **progress** (Progress?) - Optional - Default: nil - totalUnitCount = 1 (defaultDirectoryUnitCount) for directories, else uncompressedSize.
- **provider** (Provider) - Required - Closure (position: Int64, size: Int) throws -> Data called until uncompressedSize bytes are provided.

### Throws
- unwritableArchive (when archive is in .read mode)
- invalidCentralDirectoryOffset
- invalidCentralDirectorySize
- invalidCentralDirectoryEntryCount (ZIP64 arithmetic overflows)
- cancelledOperation (rollback performed)

### Example
```swift
let string = "abcdefghijkl"
guard let data = string.data(using: .utf8) else { return }
try? archive.addEntry(with: "fromMemory.txt", type: .file, uncompressedSize: Int64(data.count),
                      bufferSize: 4, provider: { (position, size) -> Data in
    // Called until the entry data is exhausted (3x in this case).
    return data.subdata(in: Data.Index(position)..<Int(position)+size)
})
```

```

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

### Data.compress(size:bufferSize:provider:consumer:)

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/data-compression.md

Compresses data supplied by a provider closure and delivers the compressed output to a consumer closure. Returns the CRC32 checksum of the uncompressed input. Throws a `Data.CompressionError` on failure.

```APIDOC
## Data.compress(size:bufferSize:provider:consumer:)

### Description
Compresses data from a provider closure and sends the compressed output to a consumer closure. Returns the CRC32 checksum of the uncompressed input.

### Method
`public static func compress(size:bufferSize:provider:consumer:)`

### Signature
```swift
public static func compress(size: Int64, bufferSize: Int, provider: Provider, consumer: Consumer) throws -> CRC32
```

### Parameters
- `size` (Int64) - Required - The uncompressed size of the data to be compressed.
- `bufferSize` (Int) - Required - The maximum size of the compression buffer.
- `provider` (Provider) - Required - Closure `(position: Int64, size: Int) throws -> Data` supplying the uncompressed input.
- `consumer` (Consumer) - Required - Closure receiving the compressed output chunks.

### Returns
The CRC32 checksum of the uncompressed input content.

### Throws
- `Data.CompressionError.invalidStream` - when `compression_stream_init` fails (Apple) or `deflateInit2_` returns non-`Z_OK` (zlib).
- `Data.CompressionError.corruptedData` - when compression stream error occurs (Apple `COMPRESSION_STATUS_*` other than OK/END; zlib `deflate` result `< Z_OK`). Errors thrown by `provider`/`consumer` also propagate.

### Example
```swift
let input = Data("hello world, hello world, ...".utf8)
let compressed = try Data.compress(size: Int64(input.count), bufferSize: 8 * 1024,
    provider: { position, size in
        let start = Int(position)
        return input.subdata(in: start..<min(start + size, input.count))
    },
    consumer: { chunk in compressedBuffer.append(chunk) })
```
```

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

### addEntry(with:fileURL:compressionMethod:bufferSize:progress:)

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/archive.md

Adds an entry to the archive from an absolute file URL. Supports files, directories, and symlinks, with automatic handling of directory and symlink specifics.

```APIDOC
## addEntry(with:fileURL:compressionMethod:bufferSize:progress:)

### Description
Adds an entry to the archive from an absolute file URL. Supports files, directories, and symlinks, with automatic handling of directory and symlink specifics.

### Method
addEntry(with:fileURL:compressionMethod:bufferSize:progress:)

### Parameters
- **path** (String) - Required - Path identifying the Entry within the archive.
- **fileURL** (URL) - Required - Absolute file URL of the resource to add (file, symlink or directory anywhere on the filesystem).
- **compressionMethod** (CompressionMethod) - Optional - Default: .none - Compression to apply.
- **bufferSize** (Int) - Optional - Default: defaultWriteChunkSize - Max write/compression buffer size.
- **progress** (Progress?) - Optional - Default: nil - Optional progress/cancellation object.

### Throws
- **CocoaError(.fileReadNoSuchFile)** - Thrown when fileURL does not exist.
- **CocoaError(.fileReadNoPermission)** - Thrown when item exists, is not a symlink, and is unreadable.
- **ArchiveError.unwritableArchive** - Thrown when archive is in .read mode.
- **POSIXError** - Thrown when fopen of the source file fails.
- **ArchiveError.invalidCentralDirectoryOffset** / **cancelledOperation** / **ZIP64 overflow errors** - Thrown on failures during the underlying write sequence.

### Example
```swift
let archive = try Archive(url: archiveURL, accessMode: .update)
try archive.addEntry(with: "someFile.txt", fileURL: someAbsoluteFileURL, compressionMethod: .deflate)
```
```

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

### addEntry(with:relativeTo:compressionMethod:bufferSize:progress:)

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/archive.md

Adds an entry to the archive using a path relative to a base URL. The base URL and path are combined to form the file URL of the resource to add.

```APIDOC
## addEntry(with:relativeTo:compressionMethod:bufferSize:progress:)

### Description
Adds an entry to the archive using a path relative to a base URL. The base URL and path are combined to form the file URL of the resource to add.

### Method
addEntry(with:relativeTo:compressionMethod:bufferSize:progress:)

### Parameters
- **path** (String) - Required - Path identifying the Entry within the archive.
- **baseURL** (URL) - Required - Base URL of the resource; baseURL + path must form a fully qualified file URL.
- **compressionMethod** (CompressionMethod) - Optional - Default: .none - Compression applied to the entry.
- **bufferSize** (Int) - Optional - Default: defaultWriteChunkSize - Max write/compression buffer size.
- **progress** (Progress?) - Optional - Default: nil - Optional progress/cancellation object.

### Throws
- **ArchiveError.unwritableArchive** - Thrown when self.accessMode == .read.

### Example
```swift
let archive = try Archive(url: archiveURL, accessMode: .update)
try archive.addEntry(with: "someFile.txt", relativeTo: baseURL, compressionMethod: .deflate)
```
```

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

### Archive.addEntry (deprecated) - with uncompressedSize and provider

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/deprecated-api.md

Adds an entry with a custom provider. Deprecated: use Int64 for uncompressedSize and provider position, Int for bufferSize.

```APIDOC
## `Archive.addEntry` (deprecated)

### Description
Adds an entry with a custom provider. Deprecated: use `Int64` for `uncompressedSize` and provider `position`. `Int` for `bufferSize`.

### Method
`func addEntry(with path: String, type: Entry.EntryType, uncompressedSize: UInt32, modificationDate: Date = Date(), permissions: UInt16? = nil, compressionMethod: CompressionMethod = .none, bufferSize: Int = defaultWriteChunkSize, progress: Progress? = nil, provider: (_ position: Int, _ size: Int) throws -> Data) throws`

### Parameters
- **path** (String) - Required - The path of the entry in the archive.
- **type** (Entry.EntryType) - Required - The type of the entry.
- **uncompressedSize** (UInt32) - Required - The uncompressed size.
- **modificationDate** (Date) - Optional - Default `Date()`.
- **permissions** (UInt16?) - Optional - File permissions.
- **compressionMethod** (CompressionMethod) - Optional - Default `.none`.
- **bufferSize** (Int) - Optional - Default `defaultWriteChunkSize`.
- **progress** (Progress?) - Optional - Progress object.
- **provider** (closure) - Required - A closure that provides data at a given position and size.

### Deprecation
Please use `Int64` for `uncompressedSize` and provider `position`. `Int` for `bufferSize`.
```

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

### Use Progress with archive.extract

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/archive.md

Shows how to pass a Progress object to extract; the totalUnitCount is set internally by the archive.

```swift
let progress = Progress(totalUnitCount: 0)
try archive.extract(entry, to: destinationURL, progress: progress) // totalUnitCount set internally
```

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

### Entry.uncompressedSize

Source: https://github.com/weichsel/zipfoundation/blob/development/_autodocs/api-reference/entry.md

Returns the size of the entry's uncompressed data, with ZIP64 and data descriptor precedence.

```APIDOC
## Entry.uncompressedSize

### Description
Returns the size of the entry's uncompressed data, with the same ZIP64/descriptor precedence as compressedSize.

### Returns
UInt64 - The uncompressed size of the entry.
```
Tokens:
Raw