106 lines
13 KiB
HTML
106 lines
13 KiB
HTML
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="API documentation for the Rust `flate2` crate."><meta name="keywords" content="rust, rustlang, rust-lang, flate2"><title>flate2 - Rust</title><link rel="stylesheet" type="text/css" href="../normalize.css"><link rel="stylesheet" type="text/css" href="../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" type="text/css" href="../dark.css"><link rel="stylesheet" type="text/css" href="../light.css" id="themeStyle"><script src="../storage.js"></script><noscript><link rel="stylesheet" href="../noscript.css"></noscript><link rel="shortcut icon" href="../favicon.ico"><style type="text/css">#crate-search{background-image:url("../down-arrow.svg");}</style></head><body class="rustdoc mod"><!--[if lte IE 8]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="sidebar"><div class="sidebar-menu">☰</div><a href='../flate2/index.html'><div class='logo-container'><img src='../rust-logo.png' alt='logo'></div></a><p class='location'>Crate flate2</p><div class="sidebar-elems"><a id='all-types' href='all.html'><p>See all flate2's items</p></a><div class="block items"><ul><li><a href="#modules">Modules</a></li><li><a href="#structs">Structs</a></li><li><a href="#enums">Enums</a></li></ul></div><p class='location'></p><script>window.sidebarCurrent = {name: 'flate2', ty: 'mod', relpath: '../'};</script></div></nav><div class="theme-picker"><button id="theme-picker" aria-label="Pick another theme!"><img src="../brush.svg" width="18" alt="Pick another theme!"></button><div id="theme-choices"></div></div><script src="../theme.js"></script><nav class="sub"><form class="search-form"><div class="search-container"><div><select id="crate-search"><option value="All crates">All crates</option></select><input class="search-input" name="search" disabled autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"></div><a id="settings-menu" href="../settings.html"><img src="../wheel.svg" width="18" alt="Change settings"></a></div></form></nav><section id="main" class="content"><h1 class='fqn'><span class='out-of-band'><span id='render-detail'><a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class='inner'>−</span>]</a></span><a class='srclink' href='../src/flate2/lib.rs.html#1-234' title='goto source code'>[src]</a></span><span class='in-band'>Crate <a class="mod" href=''>flate2</a></span></h1><div class='docblock'><p>A DEFLATE-based stream compression/decompression library</p>
|
||
<p>This library provides support for compression and decompression of
|
||
DEFLATE-based streams:</p>
|
||
<ul>
|
||
<li>the DEFLATE format itself</li>
|
||
<li>the zlib format</li>
|
||
<li>gzip</li>
|
||
</ul>
|
||
<p>These three formats are all closely related and largely only differ in their
|
||
headers/footers. This crate has three types in each submodule for dealing
|
||
with these three formats.</p>
|
||
<h1 id="implementation" class="section-header"><a href="#implementation">Implementation</a></h1>
|
||
<p>In addition to supporting three formats, this crate supports three different
|
||
backends, controlled through this crate's features:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>default</code>, or <code>rust_backend</code> - this implementation uses the <code>miniz_oxide</code>
|
||
crate which is a port of <code>miniz.c</code> (below) to Rust. This feature does not
|
||
require a C compiler and only requires Rust code.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>miniz-sys</code> - when enabled this feature will enable this crate to instead
|
||
use <code>miniz.c</code>, distributed with <code>miniz-sys</code>, to implement
|
||
compression/decompression.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zlib</code> - finally, this feature will enable linking against the <code>libz</code>
|
||
library, typically found on most Linux systems by default. If the library
|
||
isn't found to already be on the system it will be compiled from source
|
||
(this is a C library).</p>
|
||
</li>
|
||
</ul>
|
||
<p>There's various tradeoffs associated with each implementation, but in
|
||
general you probably won't have to tweak the defaults. The default choice is
|
||
selected to avoid the need for a C compiler at build time. The <code>miniz-sys</code>
|
||
feature is largely a historical artifact at this point and is unlikely to be
|
||
needed, and <code>zlib</code> is often useful if you're already using <code>zlib</code> for other
|
||
C dependencies. The compression ratios and performance of each of these
|
||
feature should be roughly comparable, but you'll likely want to run your own
|
||
tests if you're curious about the performance.</p>
|
||
<h1 id="organization" class="section-header"><a href="#organization">Organization</a></h1>
|
||
<p>This crate consists mainly of three modules, <a href="read/index.html"><code>read</code></a>, <a href="write/index.html"><code>write</code></a>, and
|
||
<a href="bufread/index.html"><code>bufread</code></a>. Each module contains a number of types used to encode and
|
||
decode various streams of data.</p>
|
||
<p>All types in the <a href="write/index.html"><code>write</code></a> module work on instances of <a href="https://doc.rust-lang.org/std/io/trait.Write.html"><code>Write</code></a>,
|
||
whereas all types in the <a href="read/index.html"><code>read</code></a> module work on instances of
|
||
<a href="https://doc.rust-lang.org/std/io/trait.Read.html"><code>Read</code></a> and <a href="bufread/index.html"><code>bufread</code></a> works with <a href="https://doc.rust-lang.org/std/io/trait.BufRead.html"><code>BufRead</code></a>. If you
|
||
are decoding directly from a <code>&[u8]</code>, use the <a href="bufread/index.html"><code>bufread</code></a> types.</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">flate2</span>::<span class="ident">write</span>::<span class="ident">GzEncoder</span>;
|
||
<span class="kw">use</span> <span class="ident">flate2</span>::<span class="ident">Compression</span>;
|
||
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>;
|
||
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">io</span>::<span class="ident">prelude</span>::<span class="kw-2">*</span>;
|
||
|
||
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">encoder</span> <span class="op">=</span> <span class="ident">GzEncoder</span>::<span class="ident">new</span>(<span class="ident">Vec</span>::<span class="ident">new</span>(), <span class="ident">Compression</span>::<span class="ident">default</span>());
|
||
<span class="ident">encoder</span>.<span class="ident">write_all</span>(<span class="string">b"Example"</span>)<span class="question-mark">?</span>;</pre></div>
|
||
<p>Other various types are provided at the top-level of the crate for
|
||
management and dealing with encoders/decoders. Also note that types which
|
||
operate over a specific trait often implement the mirroring trait as well.
|
||
For example a <code>flate2::read::DeflateDecoder<T></code> <em>also</em> implements the
|
||
<code>Write</code> trait if <code>T: Write</code>. That is, the "dual trait" is forwarded directly
|
||
to the underlying object if available.</p>
|
||
<h1 id="async-io" class="section-header"><a href="#async-io">Async I/O</a></h1>
|
||
<p>This crate optionally can support async I/O streams with the <a href="https://tokio.rs/">Tokio stack</a> via
|
||
the <code>tokio</code> feature of this crate:</p>
|
||
<pre><code class="language-toml">flate2 = { version = "0.2", features = ["tokio"] }
|
||
</code></pre>
|
||
<p>All methods are internally capable of working with streams that may return
|
||
<a href="https://doc.rust-lang.org/std/io/enum.ErrorKind.html"><code>ErrorKind::WouldBlock</code></a> when they're not ready to perform the particular
|
||
operation.</p>
|
||
<p>Note that care needs to be taken when using these objects, however. The
|
||
Tokio runtime, in particular, requires that data is fully flushed before
|
||
dropping streams. For compatibility with blocking streams all streams are
|
||
flushed/written when they are dropped, and this is not always a suitable
|
||
time to perform I/O. If I/O streams are flushed before drop, however, then
|
||
these operations will be a noop.</p>
|
||
</div><h2 id='modules' class='section-header'><a href="#modules">Modules</a></h2>
|
||
<table><tr class='module-item'><td><a class="mod" href="bufread/index.html" title='flate2::bufread mod'>bufread</a></td><td class='docblock-short'><p>Types which operate over <a href="https://doc.rust-lang.org/std/io/trait.BufRead.html"><code>BufRead</code></a> streams, both encoders and decoders for
|
||
various formats.</p>
|
||
</td></tr><tr class='module-item'><td><a class="mod" href="read/index.html" title='flate2::read mod'>read</a></td><td class='docblock-short'><p>Types which operate over <a href="https://doc.rust-lang.org/std/io/trait.Read.html"><code>Read</code></a> streams, both encoders and decoders for
|
||
various formats.</p>
|
||
</td></tr><tr class='module-item'><td><a class="mod" href="write/index.html" title='flate2::write mod'>write</a></td><td class='docblock-short'><p>Types which operate over <a href="https://doc.rust-lang.org/std/io/trait.Write.html"><code>Write</code></a> streams, both encoders and decoders for
|
||
various formats.</p>
|
||
</td></tr></table><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
|
||
<table><tr class='module-item'><td><a class="struct" href="struct.Compress.html" title='flate2::Compress struct'>Compress</a></td><td class='docblock-short'><p>Raw in-memory compression stream for blocks of data.</p>
|
||
</td></tr><tr class='module-item'><td><a class="struct" href="struct.CompressError.html" title='flate2::CompressError struct'>CompressError</a></td><td class='docblock-short'><p>Error returned when a compression object is used incorrectly or otherwise
|
||
generates an error.</p>
|
||
</td></tr><tr class='module-item'><td><a class="struct" href="struct.Compression.html" title='flate2::Compression struct'>Compression</a></td><td class='docblock-short'><p>When compressing data, the compression level can be specified by a value in
|
||
this enum.</p>
|
||
</td></tr><tr class='module-item'><td><a class="struct" href="struct.Crc.html" title='flate2::Crc struct'>Crc</a></td><td class='docblock-short'><p>The CRC calculated by a <a href="struct.CrcReader.html"><code>CrcReader</code></a>.</p>
|
||
</td></tr><tr class='module-item'><td><a class="struct" href="struct.CrcReader.html" title='flate2::CrcReader struct'>CrcReader</a></td><td class='docblock-short'><p>A wrapper around a <a href="https://doc.rust-lang.org/std/io/trait.Read.html"><code>Read</code></a> that calculates the CRC.</p>
|
||
</td></tr><tr class='module-item'><td><a class="struct" href="struct.CrcWriter.html" title='flate2::CrcWriter struct'>CrcWriter</a></td><td class='docblock-short'><p>A wrapper around a <a href="https://doc.rust-lang.org/std/io/trait.Write.html"><code>Write</code></a> that calculates the CRC.</p>
|
||
</td></tr><tr class='module-item'><td><a class="struct" href="struct.Decompress.html" title='flate2::Decompress struct'>Decompress</a></td><td class='docblock-short'><p>Raw in-memory decompression stream for blocks of data.</p>
|
||
</td></tr><tr class='module-item'><td><a class="struct" href="struct.DecompressError.html" title='flate2::DecompressError struct'>DecompressError</a></td><td class='docblock-short'><p>Error returned when a decompression object finds that the input stream of
|
||
bytes was not a valid input stream of bytes.</p>
|
||
</td></tr><tr class='module-item'><td><a class="struct" href="struct.GzBuilder.html" title='flate2::GzBuilder struct'>GzBuilder</a></td><td class='docblock-short'><p>A builder structure to create a new gzip Encoder.</p>
|
||
</td></tr><tr class='module-item'><td><a class="struct" href="struct.GzHeader.html" title='flate2::GzHeader struct'>GzHeader</a></td><td class='docblock-short'><p>A structure representing the header of a gzip stream.</p>
|
||
</td></tr></table><h2 id='enums' class='section-header'><a href="#enums">Enums</a></h2>
|
||
<table><tr class='module-item'><td><a class="enum" href="enum.FlushCompress.html" title='flate2::FlushCompress enum'>FlushCompress</a></td><td class='docblock-short'><p>Values which indicate the form of flushing to be used when compressing
|
||
in-memory data.</p>
|
||
</td></tr><tr class='module-item'><td><a class="enum" href="enum.FlushDecompress.html" title='flate2::FlushDecompress enum'>FlushDecompress</a></td><td class='docblock-short'><p>Values which indicate the form of flushing to be used when
|
||
decompressing in-memory data.</p>
|
||
</td></tr><tr class='module-item'><td><a class="enum" href="enum.Status.html" title='flate2::Status enum'>Status</a></td><td class='docblock-short'><p>Possible status results of compressing some data or successfully
|
||
decompressing a block of data.</p>
|
||
</td></tr></table></section><section id="search" class="content hidden"></section><section class="footer"></section><script>window.rootPath = "../";window.currentCrate = "flate2";</script><script src="../aliases.js"></script><script src="../main.js"></script><script defer src="../search-index.js"></script></body></html> |