mirror of
https://github.com/tsolomko/SWCompression.git
synced 2026-06-23 14:56:41 +00:00
Timofey Solomko
413 lines
22 KiB
HTML
413 lines
22 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<title>SWCompression Reference</title>
|
||
<link rel="stylesheet" type="text/css" href="css/jazzy.css" />
|
||
<link rel="stylesheet" type="text/css" href="css/highlight.css" />
|
||
<meta charset="utf-8">
|
||
<script src="js/jquery.min.js" defer></script>
|
||
<script src="js/jazzy.js" defer></script>
|
||
|
||
<script src="js/lunr.min.js" defer></script>
|
||
<script src="js/typeahead.jquery.js" defer></script>
|
||
<script src="js/jazzy.search.js" defer></script>
|
||
</head>
|
||
<body>
|
||
|
||
|
||
<a title="SWCompression Reference"></a>
|
||
|
||
<header class="header">
|
||
<p class="header-col header-col--primary">
|
||
<a class="header-link" href="index.html">
|
||
SWCompression Docs
|
||
</a>
|
||
(100% documented)
|
||
</p>
|
||
|
||
<p class="header-col--secondary">
|
||
<form role="search" action="search.json">
|
||
<input type="text" placeholder="Search documentation" data-typeahead>
|
||
</form>
|
||
</p>
|
||
|
||
<p class="header-col header-col--secondary">
|
||
<a class="header-link" href="https://github.com/tsolomko/SWCompression">
|
||
<img class="header-icon" src="img/gh.png"/>
|
||
View on GitHub
|
||
</a>
|
||
</p>
|
||
|
||
</header>
|
||
|
||
<p class="breadcrumbs">
|
||
<a class="breadcrumb" href="index.html">SWCompression Reference</a>
|
||
<img class="carat" src="img/carat.png" />
|
||
SWCompression Reference
|
||
</p>
|
||
|
||
<div class="content-wrapper">
|
||
<nav class="navigation">
|
||
<ul class="nav-groups">
|
||
<li class="nav-group-name">
|
||
<a class="nav-group-name-link" href="Compression.html">Compression</a>
|
||
<ul class="nav-group-tasks">
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Classes/BZip2.html">BZip2</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Classes/Deflate.html">Deflate</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Classes/LZMA.html">LZMA</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Classes/LZMA2.html">LZMA2</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="nav-group-name">
|
||
<a class="nav-group-name-link" href="Archives.html">Archives</a>
|
||
<ul class="nav-group-tasks">
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Classes/GzipArchive.html">GzipArchive</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Classes/GzipArchive/Member.html">– Member</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Structs/GzipHeader.html">GzipHeader</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Structs/GzipHeader/CompressionMethod.html">– CompressionMethod</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Structs/GzipHeader/FileSystemType.html">– FileSystemType</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Classes/ZlibArchive.html">ZlibArchive</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Structs/ZlibHeader.html">ZlibHeader</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Structs/ZlibHeader/CompressionMethod.html">– CompressionMethod</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Structs/ZlibHeader/CompressionLevel.html">– CompressionLevel</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Classes/XZArchive.html">XZArchive</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="nav-group-name">
|
||
<a class="nav-group-name-link" href="Containers.html">Containers</a>
|
||
<ul class="nav-group-tasks">
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Classes/ZipContainer.html">ZipContainer</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Classes/ZipEntry.html">ZipEntry</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Classes/TarContainer.html">TarContainer</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Classes/TarEntry.html">TarEntry</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Classes/TarEntry/EntryType.html">– EntryType</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="nav-group-name">
|
||
<a class="nav-group-name-link" href="Errors.html">Errors</a>
|
||
<ul class="nav-group-tasks">
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Enums/BZip2Error.html">BZip2Error</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Enums/DeflateError.html">DeflateError</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Enums/GzipError.html">GzipError</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Enums/LZMA2Error.html">LZMA2Error</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Enums/LZMAError.html">LZMAError</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Enums/TarError.html">TarError</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Enums/XZError.html">XZError</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Enums/ZipError.html">ZipError</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Enums/ZlibError.html">ZlibError</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="nav-group-name">
|
||
<a class="nav-group-name-link" href="Protocols.html">Protocols</a>
|
||
<ul class="nav-group-tasks">
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Protocols/Archive.html">Archive</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Protocols/Container.html">Container</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Protocols/ContainerEntry.html">ContainerEntry</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Protocols/DecompressionAlgorithm.html">DecompressionAlgorithm</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</nav>
|
||
<article class="main-content">
|
||
|
||
<section class="section">
|
||
<div class="section-content">
|
||
|
||
<h1 id='swcompression' class='heading'>SWCompression</h1>
|
||
|
||
<p><a href="https://raw.githubusercontent.com/tsolomko/SWCompression/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-lightgrey.svg" alt="GitHub license"></a>
|
||
<a href="https://cocoapods.org/pods/SWCompression"><img src="https://img.shields.io/cocoapods/p/SWCompression.svg" alt="CocoaPods"></a>
|
||
<a href="https://developer.apple.com/swift/"><img src="https://img.shields.io/badge/Swift-3.1.1-lightgrey.svg" alt="Swift 3"></a>
|
||
<a href="https://travis-ci.org/tsolomko/SWCompression"><img src="https://travis-ci.org/tsolomko/SWCompression.svg?branch=develop" alt="Build Status"></a>
|
||
<a href="https://codecov.io/gh/tsolomko/SWCompression"><img src="https://codecov.io/gh/tsolomko/SWCompression/branch/develop/graph/badge.svg" alt="codecov"></a></p>
|
||
|
||
<p><a href="https://cocoapods.org/pods/SWCompression"><img src="https://img.shields.io/cocoapods/v/SWCompression.svg" alt="CocoaPods"></a>
|
||
<a href="https://github.com/Carthage/Carthage"><img src="https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat" alt="Carthage compatible"></a></p>
|
||
|
||
<p>A framework which contains implementations of (de)compression algorithms and functions which parse various archives and containers.</p>
|
||
|
||
<p><strong>Developed with Swift.</strong></p>
|
||
<h2 id='why-have-you-made-this-framework' class='heading'>Why have you made this framework?</h2>
|
||
|
||
<p>There are a couple of reasons for this.</p>
|
||
|
||
<p>The main reason is that it is very educational and somewhat fun.</p>
|
||
|
||
<p>Secondly, if you are a Swift developer and you want to compress/decompress something in your project
|
||
you have to use either wrapper around system libraries (which is probably written in Objective-C)
|
||
or you have to use built-in Compression framework.
|
||
You might think that last option is what you need, but, frankly
|
||
that framework has a bit complicated API and somewhat questionable choice of supported compression algorithms.
|
||
And yes, it is also in Objective-C.</p>
|
||
|
||
<p>And here comes SWCompression: no Objective-C, pure Swift.</p>
|
||
<h2 id='features' class='heading'>Features</h2>
|
||
|
||
<ul>
|
||
<li>Containers:
|
||
|
||
<ul>
|
||
<li>ZIP</li>
|
||
<li>TAR</li>
|
||
</ul></li>
|
||
<li>Decompression algorithms:
|
||
|
||
<ul>
|
||
<li>LZMA/LZMA2</li>
|
||
<li>Deflate</li>
|
||
<li>BZip2</li>
|
||
</ul></li>
|
||
<li>Compression algorithms:
|
||
|
||
<ul>
|
||
<li>Deflate</li>
|
||
</ul></li>
|
||
<li>Archives:
|
||
|
||
<ul>
|
||
<li>XZ</li>
|
||
<li>GZip</li>
|
||
<li>Zlib</li>
|
||
</ul></li>
|
||
<li>Platform independent.</li>
|
||
<li><em>Written with Swift only.</em></li>
|
||
</ul>
|
||
|
||
<p>By the way, it seems like GZip, Deflate and Zlib implementations are <strong>specification compliant</strong>.</p>
|
||
<h2 id='installation' class='heading'>Installation</h2>
|
||
|
||
<p>SWCompression can be integrated into your project either using CocoaPods, Carthage or Swift Package Manager.</p>
|
||
<h5 id='cocoapods' class='heading'>CocoaPods</h5>
|
||
|
||
<p>Add to your Podfile <code>pod 'SWCompression'</code>.</p>
|
||
|
||
<p>There are several sub-podspecs in case you need only parts of framework’s functionality.
|
||
Available subspecs:</p>
|
||
|
||
<ul>
|
||
<li>SWCompression/LZMA</li>
|
||
<li>SWCompression/XZ</li>
|
||
<li>SWCompression/Deflate</li>
|
||
<li>SWCompression/Gzip</li>
|
||
<li>SWCompression/Zlib</li>
|
||
<li>SWCompression/BZip2</li>
|
||
<li>SWCompression/ZIP</li>
|
||
<li>SWCompression/TAR</li>
|
||
</ul>
|
||
|
||
<p>You can add some or all of them instead of <code>pod 'SWCompression'</code></p>
|
||
|
||
<p>Also, do not forget to include <code>use_frameworks!</code> line in your Podfile.</p>
|
||
|
||
<p>To complete installation, run <code>pod install</code>.</p>
|
||
<h5 id='carthage' class='heading'>Carthage</h5>
|
||
|
||
<p>Add to your Cartfile <code>github "tsolomko/SWCompression"</code>.</p>
|
||
|
||
<p>Then run <code>carthage update</code>.</p>
|
||
|
||
<p>Finally, drag and drop <code>SWCompression.framework</code> from <code>Carthage/Build</code> folder into the <q>Embedded Binaries</q> section on your targets’ <q>General</q> tab.</p>
|
||
<h5 id='swift-package-manager' class='heading'>Swift Package Manager</h5>
|
||
|
||
<p>Add to you package dependecies <code>.Package(url: "https://github.com/tsolomko/SWCompression.git")</code>, for example like this:</p>
|
||
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">PackageDescription</span>
|
||
|
||
<span class="k">let</span> <span class="nv">package</span> <span class="o">=</span> <span class="kt">Package</span><span class="p">(</span>
|
||
<span class="nv">name</span><span class="p">:</span> <span class="s">"PackageName"</span><span class="p">,</span>
|
||
<span class="nv">dependencies</span><span class="p">:</span> <span class="p">[</span>
|
||
<span class="o">.</span><span class="kt">Package</span><span class="p">(</span><span class="nv">url</span><span class="p">:</span> <span class="s">"https://github.com/tsolomko/SWCompression.git"</span><span class="p">,</span> <span class="nv">majorVersion</span><span class="p">:</span> <span class="mi">3</span><span class="p">)</span>
|
||
<span class="p">]</span>
|
||
<span class="p">)</span>
|
||
</code></pre>
|
||
|
||
<p>More info about SPM you can find at <a href="https://github.com/apple/swift-package-manager/tree/master/Documentation">Swift Package Manager’s Documentation</a>.</p>
|
||
<h2 id='swcompression-zip-and-compression-methods' class='heading'>SWCompression/ZIP and compression methods</h2>
|
||
|
||
<p>Deflate is a default compression method of ZIP containers.</p>
|
||
|
||
<p>This means, that if you use CocoaPods, when installing SWCompression/ZIP it will install SWCompression/Deflate as a dependency.</p>
|
||
|
||
<p>However, ZIP containers can also support LZMA and BZip2.
|
||
So if you want to enable them in your Pods configuration you need to include SWCompression/LZMA and/or SWCompression/Deflate.</p>
|
||
|
||
<p>If you use Carthage or Swift Package Manager you always have the full package,
|
||
and ZIP will be built with both BZip2 and LZMA support.</p>
|
||
<h2 id='usage' class='heading'>Usage</h2>
|
||
<h4 id='basics' class='heading'>Basics</h4>
|
||
|
||
<p>If you’d like to decompress <q>deflated</q> data just use:</p>
|
||
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">data</span> <span class="o">=</span> <span class="k">try!</span> <span class="kt">Data</span><span class="p">(</span><span class="nv">contentsOf</span><span class="p">:</span> <span class="kt">URL</span><span class="p">(</span><span class="nv">fileURLWithPath</span><span class="p">:</span> <span class="s">"path/to/file"</span><span class="p">),</span>
|
||
<span class="nv">options</span><span class="p">:</span> <span class="o">.</span><span class="n">mappedIfSafe</span><span class="p">)</span>
|
||
<span class="k">let</span> <span class="nv">decompressedData</span> <span class="o">=</span> <span class="k">try</span><span class="p">?</span> <span class="kt">Deflate</span><span class="o">.</span><span class="nf">decompress</span><span class="p">(</span><span class="nv">data</span><span class="p">:</span> <span class="n">data</span><span class="p">)</span>
|
||
</code></pre>
|
||
|
||
<p><em>Note:</em> It is <strong>highly recommended</strong> to specify <code>Data.ReadingOptions.mappedIfSafe</code>,
|
||
especially if you are working with large files, so you don’t run out of system memory.</p>
|
||
|
||
<p>However, it is unlikely that you will encounter deflated data outside of any archive.
|
||
So, in case of GZip archive you should use:</p>
|
||
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">decompressedData</span> <span class="o">=</span> <span class="k">try</span><span class="p">?</span> <span class="kt">GzipArchive</span><span class="o">.</span><span class="nf">unarchive</span><span class="p">(</span><span class="nv">archiveData</span><span class="p">:</span> <span class="n">data</span><span class="p">)</span>
|
||
</code></pre>
|
||
|
||
<p>One final note: every SWCompression function can throw an error and
|
||
you are responsible for handling them.</p>
|
||
<h4 id='documentation' class='heading'>Documentation</h4>
|
||
|
||
<p>Every function or class of public API of SWCompression is documented.
|
||
This documentation can be found at its own <a href="http://tsolomko.github.io/SWCompression">website</a>.</p>
|
||
<h4 id='handling-errors' class='heading'>Handling Errors</h4>
|
||
|
||
<p>If you look at list of available error types and their cases, you may be frightened by their number.
|
||
However, most of these cases (such as <code>XZError.WrongMagic</code>) exist for diagnostic purposes.</p>
|
||
|
||
<p>Thus, you only need to handle the most common type of error for your archive/algorithm.
|
||
For example:</p>
|
||
<pre class="highlight swift"><code><span class="k">do</span> <span class="p">{</span>
|
||
<span class="k">let</span> <span class="nv">data</span> <span class="o">=</span> <span class="k">try</span> <span class="kt">Data</span><span class="p">(</span><span class="nv">contentsOf</span><span class="p">:</span> <span class="kt">URL</span><span class="p">(</span><span class="nv">fileURLWithPath</span><span class="p">:</span> <span class="s">"path/to/file"</span><span class="p">),</span>
|
||
<span class="nv">options</span><span class="p">:</span> <span class="o">.</span><span class="n">mappedIfSafe</span><span class="p">)</span>
|
||
<span class="k">let</span> <span class="nv">decompressedData</span> <span class="o">=</span> <span class="kt">XZArchive</span><span class="o">.</span><span class="nf">unarchive</span><span class="p">(</span><span class="nv">archive</span><span class="p">:</span> <span class="n">data</span><span class="p">)</span>
|
||
<span class="p">}</span> <span class="k">catch</span> <span class="k">let</span> <span class="nv">error</span> <span class="k">as</span> <span class="kt">XZError</span> <span class="p">{</span>
|
||
<span class="o"><</span><span class="n">handle</span> <span class="kt">XZ</span> <span class="n">related</span> <span class="n">error</span> <span class="n">here</span><span class="o">></span>
|
||
<span class="p">}</span> <span class="k">catch</span> <span class="k">let</span> <span class="nv">error</span> <span class="p">{</span>
|
||
<span class="o"><</span><span class="n">handle</span> <span class="n">all</span> <span class="n">other</span> <span class="n">errors</span> <span class="n">here</span><span class="o">></span>
|
||
<span class="p">}</span>
|
||
</code></pre>
|
||
<h4 id='sophisticated-example' class='heading'>Sophisticated example</h4>
|
||
|
||
<p>There is a small program, <a href="https://github.com/tsolomko/swcomp">swcomp</a>,
|
||
which uses SWCompression for unarchiving several types of archives.</p>
|
||
<h2 id='performace' class='heading'>Performace</h2>
|
||
|
||
<p><strong>TL;DR</strong> Constantly trying to improve performance;
|
||
use whole module optimizations, which are enabled by default for Release configurations.</p>
|
||
|
||
<p>Further thoughts, details and notes about performance you can read in a <a href="Performance.md">separate document</a>.</p>
|
||
|
||
<p><a href="Tests/Results.md">Tests Results</a> document contains results of performance testing of various algorithms.</p>
|
||
<h2 id='running-tests-locally' class='heading'>Running tests locally</h2>
|
||
|
||
<p>If you want to run tests locally you need to clone this repository and do some additional steps:</p>
|
||
<pre class="highlight shell"><code><span class="gp">$ </span>git submodule update --init --recursive
|
||
<span class="gp">$ </span><span class="nb">cd </span>Tests/Test<span class="se">\ </span>Files
|
||
<span class="gp">$ </span>git lfs pull
|
||
</code></pre>
|
||
|
||
<p>These commands fetch example archives and other files which are used for testing.
|
||
These files are stored in a <a href="https://github.com/tsolomko/SWCompression-Test-Files">separate repository</a>.
|
||
Git LFS is also used for storing them which basically is the reason for having them in other repository.
|
||
Otherwise, using Swift Package Manager to install SWCompression is a bit challenging
|
||
(requires installing git-lfs <em>locally</em> with <code>--skip-smudge</code> option to solve the problem).</p>
|
||
<h2 id='known-issues' class='heading'>Known issues</h2>
|
||
|
||
<ul>
|
||
<li><code>wrongCRC</code> and <code>wrongCheck</code> errors for XZ and GZip multi-member archives
|
||
contain only last member’s data as their associated value instead of all successfully processed members.</li>
|
||
</ul>
|
||
|
||
<p>Comment: Philosophy for such errors is that by the time these errors are thrown,
|
||
decompression was already performed, so we can still provide the result of decompression to the caller.
|
||
It is intended to fix this problem, but solution requires backwards-incompatible API changes so it is delayed until 4.0 release.</p>
|
||
<h2 id='future-plans' class='heading'>Future plans</h2>
|
||
|
||
<ul>
|
||
<li>Better Deflate compression.</li>
|
||
<li>7zip containers.</li>
|
||
<li>BZip2 compression.</li>
|
||
<li>Something else…</li>
|
||
</ul>
|
||
<h2 id='references' class='heading'>References</h2>
|
||
|
||
<ul>
|
||
<li><a href="http://www.paul.sladen.org/projects/pyflate/">pyflate</a></li>
|
||
<li><a href="https://www.ietf.org/rfc/rfc1951.txt">Deflate specification</a></li>
|
||
<li><a href="https://www.ietf.org/rfc/rfc1952.txt">GZip specification</a></li>
|
||
<li><a href="https://www.ietf.org/rfc/rfc1950.txt">Zlib specfication</a></li>
|
||
<li><a href="http://www.7-zip.org/sdk.html">LZMA SDK and specification</a></li>
|
||
<li><a href="http://tukaani.org/xz/xz-file-format-1.0.4.txt">XZ specification</a></li>
|
||
<li><a href="https://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Markov_chain_algorithm">Wikipedia article about LZMA</a></li>
|
||
<li><a href="http://www.pkware.com/appnote">.ZIP Application Note</a></li>
|
||
<li><a href="http://www.iso.org/iso/catalogue_detail.htm?csnumber=60101">ISO/IEC 21320-1</a></li>
|
||
<li><a href="https://opensource.apple.com/source/zip/zip-6/unzip/unzip/proginfo/extra.fld">List of defined ZIP extra fields</a></li>
|
||
<li><a href="https://en.wikipedia.org/wiki/Tar_(computing)">Wikipedia article about TAR</a></li>
|
||
<li><a href="http://pubs.opengroup.org/onlinepubs/9699919799/utilities/pax.html">Pax specification</a></li>
|
||
<li><a href="https://www.gnu.org/software/tar/manual/html_node/Standard.html">Basic TAR specification</a></li>
|
||
</ul>
|
||
|
||
</div>
|
||
</section>
|
||
|
||
|
||
</article>
|
||
</div>
|
||
<section class="footer">
|
||
<p>© 2017 Timofey Solomko</p>
|
||
<p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.8.3</a>, a <a class="link" href="http://realm.io" target="_blank" rel="external">Realm</a> project.</p>
|
||
</section>
|
||
</body>
|
||
</div>
|
||
</html>
|