Timofey SolomkoSWCompression
A framework which contains implementations of (de)compression algorithms.
Developed with Swift.
Why have you made this framework?
There are a couple of reasons for this.
The main reason is that it is very educational and somewhat fun.
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.
And here comes SWCompression: no Objective-C, pure Swift.
Features
- (De)compression algorithms:
- LZMA/LZMA2
- Deflate
- BZip2
- Archives:
- XZ
- GZip
- Zlib
- Platform independent.
- Swift only.
By the way, it seems like GZip, Deflate and Zlib implementations are specification compliant.
Installation
SWCompression can be integrated into your project either using CocoaPods, Carthage or Swift Package Manager.
CocoaPods
Add to your Podfile pod 'SWCompression'.
There are several sub-podspecs in case you need only parts of framework's functionality. Available subspecs:
- SWCompression/LZMA
- SWCompression/XZ
- SWCompression/Deflate
- SWCompression/Gzip
- SWCompression/Zlib
- SWCompression/BZip2
You can add some or all of them instead of pod 'SWCompression'
Also, do not forget to include use_frameworks! line in your Podfile.
To complete installation, run pod install.
Note: 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.
Carthage
Add to your Cartfile github "tsolomko/SWCompression".
Then run carthage update.
Finally, drag and drop SWCompression.framework from Carthage/Build folder into the "Embedded Binaries" section on your targets' "General" tab.
Swift Package Manager
Add to you package dependecies .Package(url: "https://github.com/tsolomko/SWCompression.git"), for example like this:
import PackageDescription
let package = Package(
name: "PackageName",
dependencies: [
.Package(url: "https://github.com/tsolomko/SWCompression.git", majorVersion: 2)
]
)
More info about SPM you can find at Swift Package Manager's Documentation.
Usage
Basics
If you'd like to decompress "deflated" data just use:
let data = try! Data(contentsOf: URL(fileURLWithPath: "path/to/file"),
options: .mappedIfSafe)
let decompressedData = try? Deflate.decompress(compressedData: data)
Note: It is highly recommended to specify Data.ReadingOptions.mappedIfSafe,
especially if you are working with large files,
so you don't run out of system memory.
However, it is unlikely that you will encounter deflated data outside of any archive. So, in case of GZip archive you should use:
let decompressedData = try? GzipArchive.unarchive(archiveData: data)
One final note: every unarchive/decompress function can throw an error and you are responsible for handling them.
Documentation
Every function or class of public API of SWCompression is documented. This documentation can be found at its own website.
Handling Errors
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 XZError.WrongMagic) exist for diagnostic purposes.
Thus, you only need to handle the most common type of error for your archive/algorithm. For example:
do {
let data = try Data(contentsOf: URL(fileURLWithPath: "path/to/file"),
options: .mappedIfSafe)
let decompressedData = XZArchive.unarchive(archiveData: data)
} catch let error as XZError {
<handle XZ related error here>
} catch let error {
<handle all other errors here>
}
Sophisticated example
There is a small program, swcomp, which uses SWCompression for unarchiving several types of archives.
Why is it so slow?
Version 2.0 came with a great performance improvement. Just look at the test results at 'Tests/Test Result'. So if it's slow the first thing you should do is to make sure you are using version >= 2.0.
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 significantly worse. You can once again check test results if you want to convince yourself that this is the case.
Finally, SWCompression's code is not as optimized as original C/C++ versions of corresponding algorithms, so some difference in speed is expected.
To sum up, it is highly recommended to build SWCompression with 'Release' configuration and use the latest version (at least 2.0).
Future plans
- Tar unarchiving.
- Deflate compression.
- BZip2 compression.
- Something else...