mirror of
https://github.com/tsolomko/SWCompression.git
synced 2026-06-23 14:56:41 +00:00
Timofey Solomko
354 lines
18 KiB
HTML
354 lines
18 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="Classes.html">Classes</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/GzipArchive.html">GzipArchive</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>
|
||
<li class="nav-group-task">
|
||
<a class="nav-group-task-link" href="Classes/XZArchive.html">XZArchive</a>
|
||
</li>
|
||
<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/ZlibArchive.html">ZlibArchive</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="nav-group-name">
|
||
<a class="nav-group-name-link" href="Enums.html">Enums</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/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/DecompressionAlgorithm.html">DecompressionAlgorithm</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="nav-group-name">
|
||
<a class="nav-group-name-link" href="Structs.html">Structs</a>
|
||
<ul class="nav-group-tasks">
|
||
<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="Structs/ZipEntry.html">ZipEntry</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>
|
||
</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-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.</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 (complying to ISO/IEC 21320 standard)</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>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>
|
||
</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>
|
||
|
||
<p><em>Note:</em> Actually, there is one more subspec (SWCompression/Common) but it does not contain any end-user functions. It is included in every other subspec and should not be specified directly in Podfile.</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">2</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='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">compressedData</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 unarchive/decompress 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">archiveData</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='why-is-it-so-slow' class='heading'>Why is it so slow?</h2>
|
||
|
||
<p>Version 2.0 came with a great performance improvement.
|
||
Just look at the test results in ‘Tests/Test Result’.
|
||
So if it’s slow the first thing you should do is to make sure you are using version >= 2.0.</p>
|
||
|
||
<p>Is it still slow?
|
||
Maybe you are compiling SWCompression not for ‘Release’ but with ‘Debug’ build configuration?
|
||
For some reason, when framework is built for ‘Debug’ its performance <strong>significantly</strong> worse.
|
||
You can once again check test results if you want to convince yourself that this is the case.</p>
|
||
|
||
<p>Finally, SWCompression’s code is not as optimized as original C/C++ versions of corresponding algorithms,
|
||
so some difference in speed is expected.</p>
|
||
|
||
<p>To sum up, it is <strong>highly recommended</strong> to build SWCompression with ‘Release’ configuration and use the latest version (at least 2.0).</p>
|
||
<h2 id='future-plans' class='heading'>Future plans</h2>
|
||
|
||
<ul>
|
||
<li>Tar unarchiving.</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>
|
||
</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.0</a>, a <a class="link" href="http://realm.io" target="_blank" rel="external">Realm</a> project.</p>
|
||
</section>
|
||
</body>
|
||
</div>
|
||
</html>
|