Archive

public final class Archive : Sequence

A sequence of uncompressed or compressed ZIP entries.

You use an Archive to create, read or update ZIP files. To read an existing ZIP file, you have to pass in an existing file URL and AccessMode.read:

var archiveURL = URL(fileURLWithPath: "/path/file.zip")
var archive = Archive(url: archiveURL, accessMode: .read)

An Archive is a sequence of entries. You can iterate over an archive using a for-in loop to get access to individual Entry objects:

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

Each Entry in an Archive is represented by its path. You can use path to retrieve the corresponding Entry from an Archive via subscripting:

let entry = archive['/path/file.txt']

To create a new Archive, pass in a non-existing file URL and AccessMode.create. To modify an existing Archive use AccessMode.update:

var archiveURL = URL(fileURLWithPath: "/path/file.zip")
var archive = Archive(url: archiveURL, accessMode: .update)
try archive?.addEntry("test.txt", relativeTo: baseURL, compressionMethod: .deflate)

ArchiveError
An error that occurs during reading, creating or updating a ZIP file.
See more
Declaration
Swift

public enum ArchiveError : Error
AccessMode
The access mode for an Archive.
See more
Declaration
Swift

public enum AccessMode : UInt
url
URL of an Archive’s backing file.
Declaration
Swift

public let url: URL
accessMode
Access mode for an archive file.
Declaration
Swift

public let accessMode: AccessMode


                    
                    
                    init(url:accessMode:preferredEncoding:)

Initializes a new ZIP Archive.

You can use this initalizer to create new archive files or to read and update existing ones. The mode parameter indicates the intended usage of the archive: .read, .create or .update.

Note

The file URL must point to an existing file for AccessMode.read.
The file URL must point to a non-existing file for AccessMode.create.
The file URL must point to an existing file for AccessMode.update.

Declaration

Swift

public init?(url: URL, accessMode mode: AccessMode, preferredEncoding: String.Encoding? = nil)

Parameters

`url`	File URL to the receivers backing file.
`mode`	Access mode of the receiver.
`preferredEncoding`	Encoding for entry paths. Overrides the encoding specified in the archive. This encoding is only used when decoding paths from the receiver. Paths of entries added with `addEntry` are always UTF-8 encoded.

Return Value

An archive initialized with a backing file at the passed in file URL and the given access mode or nil if the following criteria are not met:


                    
                    
                    init(data:accessMode:preferredEncoding:)

Initializes a new in-memory ZIP Archive.

You can use this initalizer to create new in-memory archive files or to read and update existing ones.

Note

The backing data must contain a valid ZIP archive for AccessMode.read and AccessMode.update.
The backing data must be empty (or omitted) for AccessMode.create.

Declaration

Swift

public init?(data: Data = Data(), accessMode mode: AccessMode, preferredEncoding: String.Encoding? = nil)

Parameters

`data`	`Data` object used as backing for in-memory archives.
`mode`	Access mode of the receiver.
`preferredEncoding`	Encoding for entry paths. Overrides the encoding specified in the archive. This encoding is only used when decoding paths from the receiver. Paths of entries added with `addEntry` are always UTF-8 encoded.

Return Value

An in-memory archive initialized with passed in backing data.


                    
                    
                    makeIterator()

Declaration

Swift

public func makeIterator() -> AnyIterator<Entry>


                    
                    
                    subscript(_:)

Retrieve the ZIP Entry with the given path from the receiver.

Note

The ZIP file format specification does not enforce unique paths for entries. Therefore an archive can contain multiple entries with the same path. This method always returns the first Entry with the given path.

Declaration

Swift

public subscript(path: String) -> Entry? { get }

Parameters


                                path

A relative file path identifying the corresponding Entry.

Return Value

An Entry with the given path. Otherwise, nil.

data
Returns a Data object containing a representation of the receiver.
Declaration
Swift

public var data: Data? { get }


                    
                    
                    totalUnitCountForRemoving(_:)

The number of the work units that have to be performed when removing entry from the receiver.

Declaration

Swift

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

Parameters


                                entry

The entry that will be removed.

Return Value

The number of the work units.


                    
                    
                    totalUnitCountForReading(_:)

The number of the work units that have to be performed when reading entry from the receiver.

Declaration

Swift

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

Parameters


                                entry

The entry that will be read.

Return Value

The number of the work units.


                    
                    
                    totalUnitCountForAddingItem(at:)

The number of the work units that have to be performed when adding the file at url to the receiver.

Declaration

Swift

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

Parameters


                                entry

The entry that will be removed.

Return Value

The number of the work units.


                    
                    
                    extract(_:to:bufferSize:skipCRC32:progress:)

Read a ZIP Entry from the receiver and write it to url.

Throws

An error if the destination file cannot be written or the entry contains malformed content.

Declaration

Swift

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

Parameters

`entry`	The ZIP `Entry` to read.
`url`	The destination file URL.
`bufferSize`	The maximum size of the read buffer and the decompression buffer (if needed).
`skipCRC32`	Optional flag to skip calculation of the CRC32 checksum to improve performance.
`progress`	A progress object that can be used to track or cancel the extract operation.

Return Value

The checksum of the processed content or 0 if the skipCRC32 flag was set to true.


                    
                    
                    extract(_:bufferSize:skipCRC32:progress:consumer:)

Read a ZIP Entry from the receiver and forward its contents to a Consumer closure.

Throws

An error if the destination file cannot be written or the entry contains malformed content.

Declaration

Swift

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

Parameters

`entry`	The ZIP `Entry` to read.
`bufferSize`	The maximum size of the read buffer and the decompression buffer (if needed).
`skipCRC32`	Optional flag to skip calculation of the CRC32 checksum to improve performance.
`progress`	A progress object that can be used to track or cancel the extract operation.
`consumer`	A closure that consumes contents of `Entry` as `Data` chunks.

Return Value

The checksum of the processed content or 0 if the skipCRC32 flag was set to true..


                    
                    
                    extract(_:to:bufferSize:skipCRC32:progress:)

Declaration

Swift

func extract(_ entry: Entry, to url: URL, bufferSize: UInt32, skipCRC32: Bool = false,
             progress: Progress? = nil) throws -> CRC32


                    
                    
                    extract(_:bufferSize:skipCRC32:progress:consumer:)

Declaration

Swift

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


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

Write files, directories or symlinks to the receiver.

Throws

An error if the source file cannot be read or the receiver is not writable.

Declaration

Swift

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

Parameters

`path`	The path that is used to identify an `Entry` within the `Archive` file.
`baseURL`	The base URL of the resource to add. The `baseURL` combined with `path` must form a fully qualified file URL.
`compressionMethod`	Indicates the `CompressionMethod` that should be applied to `Entry`. By default, no compression will be applied.
`bufferSize`	The maximum size of the write buffer and the compression buffer (if needed).
`progress`	A progress object that can be used to track or cancel the add operation.


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

Write files, directories or symlinks to the receiver.

Throws

An error if the source file cannot be read or the receiver is not writable.

Declaration

Swift

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

Parameters

`path`	The path that is used to identify an `Entry` within the `Archive` file.
`fileURL`	An absolute file URL referring to the resource to add.
`compressionMethod`	Indicates the `CompressionMethod` that should be applied to `Entry`. By default, no compression will be applied.
`bufferSize`	The maximum size of the write buffer and the compression buffer (if needed).
`progress`	A progress object that can be used to track or cancel the add operation.


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

Write files, directories or symlinks to the receiver.

Throws

An error if the source data is invalid or the receiver is not writable.

Declaration

Swift

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`	The path that is used to identify an `Entry` within the `Archive` file.
`type`	Indicates the `Entry.EntryType` of the added content.
`uncompressedSize`	The uncompressed size of the data that is going to be added with `provider`.
`modificationDate`	A `Date` describing the file modification date of the `Entry`. Default is the current `Date`.
`permissions`	POSIX file permissions for the `Entry`. Default is `0`o`644` for files and symlinks and `0`o`755` for directories.
`compressionMethod`	Indicates the `CompressionMethod` that should be applied to `Entry`. By default, no compression will be applied.
`bufferSize`	The maximum size of the write buffer and the compression buffer (if needed).
`progress`	A progress object that can be used to track or cancel the add operation.
`provider`	A closure that accepts a position and a chunk size. Returns a `Data` chunk.


                    
                    
                    remove(_:bufferSize:progress:)

Remove a ZIP Entry from the receiver.

Throws

An error if the Entry is malformed or the receiver is not writable.

Declaration

Swift

public func remove(_ entry: Entry, bufferSize: Int = defaultReadChunkSize, progress: Progress? = nil) throws

Parameters

`entry`	The `Entry` to remove.
`bufferSize`	The maximum size for the read and write buffers used during removal.
`progress`	A progress object that can be used to track or cancel the remove operation.


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

Declaration

Swift

func addEntry(with path: String, relativeTo baseURL: URL,
              compressionMethod: CompressionMethod = .none,
              bufferSize: UInt32, progress: Progress? = nil) throws


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

Declaration

Swift

func addEntry(with path: String, fileURL: URL, compressionMethod: CompressionMethod = .none,
              bufferSize: UInt32, progress: Progress? = nil) throws


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

Declaration

Swift

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


                    
                    
                    remove(_:bufferSize:progress:)

Declaration

Swift

func remove(_ entry: Entry, bufferSize: UInt32, progress: Progress? = nil) throws