zlib.html

来自「perl教程」· HTML 代码 · 共 956 行 · 第 1/4 页

<dd>
<p>Sets the initial size for the deflation buffer. If the buffer has to be
reallocated to increase the size, it will grow in increments of
<strong>Bufsize</strong>.</p>
</dd>
<dd>
<p>The default is 4096.</p>
</dd>
</li>
</dl>
<p>Here is an example of using the <strong>deflateInit</strong> optional parameter list
to override the default buffer size and compression level. All other
options will take their default values.</p>
<pre>
    <span class="variable">deflateInit</span><span class="operator">(</span> <span class="string">-Bufsize</span> <span class="operator">=&gt;</span> <span class="number">300</span><span class="operator">,</span> 
                 <span class="string">-Level</span> <span class="operator">=&gt;</span> <span class="variable">Z_BEST_SPEED</span>  <span class="operator">)</span> <span class="operator">;</span>
</pre>
<p>
</p>
<h2><a name="__out___status_____d_deflate__buffer_"><strong>($out, $status) = $d-&gt;deflate($buffer)</strong></a></h2>
<p>Deflates the contents of <strong>$buffer</strong>. The buffer can either be a scalar
or a scalar reference.  When finished, <strong>$buffer</strong> will be
completely processed (assuming there were no errors). If the deflation
was successful it returns the deflated output, <strong>$out</strong>, and a status
value, <strong>$status</strong>, of <code>Z_OK</code>.</p>
<p>On error, <strong>$out</strong> will be <em>undef</em> and <strong>$status</strong> will contain the
<em>zlib</em> error code.</p>
<p>In a scalar context <strong>deflate</strong> will return <strong>$out</strong> only.</p>
<p>As with the <em>deflate</em> function in <em>zlib</em>, it is not necessarily the
case that any output will be produced by this method. So don't rely on
the fact that <strong>$out</strong> is empty for an error test.</p>
<p>
</p>
<h2><a name="__out___status_____d_flush__flush_type__"><strong>($out, $status) = $d-&gt;flush([flush_type])</strong></a></h2>
<p>Typically used to finish the deflation. Any pending output will be
returned via <strong>$out</strong>.
<strong>$status</strong> will have a value <code>Z_OK</code> if successful.</p>
<p>In a scalar context <strong>flush</strong> will return <strong>$out</strong> only.</p>
<p>Note that flushing can seriously degrade the compression ratio, so it
should only be used to terminate a decompression (using <code>Z_FINISH</code>) or
when you want to create a <em>full flush point</em> (using <code>Z_FULL_FLUSH</code>).</p>
<p>By default the <code>flush_type</code> used is <code>Z_FINISH</code>. Other valid values
for <code>flush_type</code> are <code>Z_NO_FLUSH</code>, <code>Z_PARTIAL_FLUSH</code>, <code>Z_SYNC_FLUSH</code>
and <code>Z_FULL_FLUSH</code>. It is strongly recommended that you only set the
<code>flush_type</code> parameter if you fully understand the implications of
what it does. See the <code>zlib</code> documentation for details.</p>
<p>
</p>
<h2><a name="_status____d_deflateparams__opt__"><strong>$status = $d-&gt;deflateParams([OPT])</strong></a></h2>
<p>Change settings for the deflate stream <code>$d</code>.</p>
<p>The list of the valid options is shown below. Options not specified
will remain unchanged.</p>
<dl>
<dt><strong><strong>-Level</strong></strong>

<dd>
<p>Defines the compression level. Valid values are 0 through 9,
<code>Z_NO_COMPRESSION</code>, <code>Z_BEST_SPEED</code>, <code>Z_BEST_COMPRESSION</code>, and
<code>Z_DEFAULT_COMPRESSION</code>.</p>
</dd>
</li>
<dt><strong><strong>-Strategy</strong></strong>

<dd>
<p>Defines the strategy used to tune the compression. The valid values are
<code>Z_DEFAULT_STRATEGY</code>, <code>Z_FILTERED</code> and <code>Z_HUFFMAN_ONLY</code>.</p>
</dd>
</li>
</dl>
<p>
</p>
<h2><a name="_d_dict_adler__"><strong>$d-&gt;dict_adler()</strong></a></h2>
<p>Returns the adler32 value for the dictionary.</p>
<p>
</p>
<h2><a name="_d_msg__"><strong>$d-&gt;msg()</strong></a></h2>
<p>Returns the last error message generated by zlib.</p>
<p>
</p>
<h2><a name="_d_total_in__"><strong>$d-&gt;total_in()</strong></a></h2>
<p>Returns the total number of bytes uncompressed bytes input to deflate.</p>
<p>
</p>
<h2><a name="_d_total_out__"><strong>$d-&gt;total_out()</strong></a></h2>
<p>Returns the total number of compressed bytes output from deflate.</p>
<p>
</p>
<h2><a name="example">Example</a></h2>
<p>Here is a trivial example of using <strong>deflate</strong>. It simply reads standard
input, deflates it and writes it to standard output.</p>
<pre>
    <span class="keyword">use</span> <span class="variable">strict</span> <span class="operator">;</span>
    <span class="keyword">use</span> <span class="variable">warnings</span> <span class="operator">;</span>
</pre>
<pre>
    <span class="keyword">use</span> <span class="variable">Compress::Zlib</span> <span class="operator">;</span>
</pre>
<pre>
    <span class="keyword">binmode</span> <span class="variable">STDIN</span><span class="operator">;</span>
    <span class="keyword">binmode</span> <span class="variable">STDOUT</span><span class="operator">;</span>
    <span class="keyword">my</span> <span class="variable">$x</span> <span class="operator">=</span> <span class="variable">deflateInit</span><span class="operator">()</span>
       <span class="keyword">or</span> <span class="keyword">die</span> <span class="string">"Cannot create a deflation stream\n"</span> <span class="operator">;</span>
</pre>
<pre>
    <span class="keyword">my</span> <span class="operator">(</span><span class="variable">$output</span><span class="operator">,</span> <span class="variable">$status</span><span class="operator">)</span> <span class="operator">;</span>
    <span class="keyword">while</span> <span class="operator">(&lt;&gt;)</span>
    <span class="operator">{</span>
        <span class="operator">(</span><span class="variable">$output</span><span class="operator">,</span> <span class="variable">$status</span><span class="operator">)</span> <span class="operator">=</span> <span class="variable">$x</span><span class="operator">-&gt;</span><span class="variable">deflate</span><span class="operator">(</span><span class="variable">$_</span><span class="operator">)</span> <span class="operator">;</span>
    
        <span class="variable">$status</span> <span class="operator">==</span> <span class="variable">Z_OK</span>
            <span class="keyword">or</span> <span class="keyword">die</span> <span class="string">"deflation failed\n"</span> <span class="operator">;</span>
    
        <span class="keyword">print</span> <span class="variable">$output</span> <span class="operator">;</span>
    <span class="operator">}</span>
    
    <span class="operator">(</span><span class="variable">$output</span><span class="operator">,</span> <span class="variable">$status</span><span class="operator">)</span> <span class="operator">=</span> <span class="variable">$x</span><span class="operator">-&gt;</span><span class="variable">flush</span><span class="operator">()</span> <span class="operator">;</span>
    
    <span class="variable">$status</span> <span class="operator">==</span> <span class="variable">Z_OK</span>
        <span class="keyword">or</span> <span class="keyword">die</span> <span class="string">"deflation failed\n"</span> <span class="operator">;</span>
    
    <span class="keyword">print</span> <span class="variable">$output</span> <span class="operator">;</span>
</pre>
<p>
</p>
<hr />
<h1><a name="inflate">INFLATE</a></h1>
<p>Here is a definition of the interface:</p>
<p>
</p>
<h2><a name="__i___status____inflateinit__"><strong>($i, $status) = inflateInit()</strong></a></h2>
<p>Initialises an inflation stream.</p>
<p>In a list context it returns the inflation stream, <strong>$i</strong>, and the
<em>zlib</em> status code (<strong>$status</strong>). In a scalar context it returns the
inflation stream only.</p>
<p>If successful, <strong>$i</strong> will hold the inflation stream and <strong>$status</strong> will
be <code>Z_OK</code>.</p>
<p>If not successful, <strong>$i</strong> will be <em>undef</em> and <strong>$status</strong> will hold the
<em>zlib</em> error code.</p>
<p>The function optionally takes a number of named options specified as
<code>-Name=&gt;value</code> pairs. This allows individual options to be
tailored without having to specify them all in the parameter list.</p>
<pre>

For backward compatibility, it is also possible to pass the parameters
as a reference to a hash containing the name=&gt;value pairs.</pre>
<pre>

The function takes one optional parameter, a reference to a hash.  The
contents of the hash allow the deflation interface to be tailored.</pre>
<pre>

Here is a list of the valid options:</pre>
<dl>
<dt><strong><strong>-WindowBits</strong></strong>

<dd>
<p>For a definition of the meaning and valid values for <strong>WindowBits</strong>
refer to the <em>zlib</em> documentation for <em>inflateInit2</em>.</p>
</dd>
<dd>
<p>Defaults to <code>-WindowBits =&gt;MAX_WBITS</code>.</p>
</dd>
</li>
<dt><strong><strong>-Bufsize</strong></strong>

<dd>
<p>Sets the initial size for the inflation buffer. If the buffer has to be
reallocated to increase the size, it will grow in increments of
<strong>Bufsize</strong>.</p>
</dd>
<dd>
<p>Default is 4096.</p>
</dd>
</li>
<dt><strong><strong>-Dictionary</strong></strong>

<dd>
<p>The default is no dictionary.</p>
</dd>
</li>
</dl>
<p>Here is an example of using the <strong>inflateInit</strong> optional parameter to
override the default buffer size.</p>
<pre>
    <span class="variable">inflateInit</span><span class="operator">(</span> <span class="string">-Bufsize</span> <span class="operator">=&gt;</span> <span class="number">300</span> <span class="operator">)</span> <span class="operator">;</span>
</pre>
<p>
</p>
<h2><a name="__out___status_____i_inflate__buffer_"><strong>($out, $status) = $i-&gt;inflate($buffer)</strong></a></h2>
<p>Inflates the complete contents of <strong>$buffer</strong>. The buffer can either be
a scalar or a scalar reference.</p>
<p>Returns <code>Z_OK</code> if successful and <code>Z_STREAM_END</code> if the end of the
compressed data has been successfully reached. 
If not successful, <strong>$out</strong> will be <em>undef</em> and <strong>$status</strong> will hold
the <em>zlib</em> error code.</p>
<p>The <code>$buffer</code> parameter is modified by <code>inflate</code>. On completion it
will contain what remains of the input buffer after inflation. This
means that <code>$buffer</code> will be an empty string when the return status is
<code>Z_OK</code>. When the return status is <code>Z_STREAM_END</code> the <code>$buffer</code>
parameter will contains what (if anything) was stored in the input
buffer after the deflated data stream.</p>
<p>This feature is useful when processing a file format that encapsulates
a  compressed data stream (e.g. gzip, zip).</p>
<p>
</p>
<h2><a name="_status____i_inflatesync__buffer_"><strong>$status = $i-&gt;inflateSync($buffer)</strong></a></h2>
<p>Scans <code>$buffer</code> until it reaches either a <em>full flush point</em> or the
end of the buffer.</p>
<p>If a <em>full flush point</em> is found, <code>Z_OK</code> is returned and <code>$buffer</code>
will be have all data up to the flush point removed. This can then be
passed to the <code>deflate</code> method.</p>
<p>Any other return code means that a flush point was not found. If more
data is available, <code>inflateSync</code> can be called repeatedly with more
compressed data until the flush point is found.</p>
<p>
</p>
<h2><a name="_i_dict_adler__"><strong>$i-&gt;dict_adler()</strong></a></h2>
<p>Returns the adler32 value for the dictionary.</p>
<p>
</p>
<h2><a name="_i_msg__"><strong>$i-&gt;msg()</strong></a></h2>
<p>Returns the last error message generated by zlib.</p>
<p>
</p>
<h2><a name="_i_total_in__"><strong>$i-&gt;total_in()</strong></a></h2>
<p>Returns the total number of bytes compressed bytes input to inflate.</p>
<p>
</p>
<h2><a name="_i_total_out__"><strong>$i-&gt;total_out()</strong></a></h2>
<p>Returns the total number of uncompressed bytes output from inflate.</p>
<p>
</p>
<h2><a name="example">Example</a></h2>
<p>Here is an example of using <strong>inflate</strong>.</p>
<pre>
    <span class="keyword">use</span> <span class="variable">strict</span> <span class="operator">;</span>
    <span class="keyword">use</span> <span class="variable">warnings</span> <span class="operator">;</span>