← Index
NYTProf Performance Profile   « block view • line view • sub view »
For 05.Domain_and_Item.t
  Run on Tue May 4 17:21:41 2010
Reported on Tue May 4 17:22:23 2010

File /usr/local/lib/perl5/5.10.1/darwin-2level/Compress/Raw/Zlib.pm
Statements Executed 91
Statement Execution Time 4.11ms
Subroutines — ordered by exclusive time
Calls P F Exclusive
Time
Inclusive
Time
Subroutine
11129µs262µsCompress::Raw::Zlib::::BEGIN@6 Compress::Raw::Zlib::BEGIN@6
11123µs132µsCompress::Raw::Zlib::::BEGIN@70 Compress::Raw::Zlib::BEGIN@70
11121µs44µsCompress::Raw::Zlib::::BEGIN@12 Compress::Raw::Zlib::BEGIN@12
11119µs96µsCompress::Raw::Zlib::::BEGIN@71 Compress::Raw::Zlib::BEGIN@71
11118µs26µsCompress::Raw::Zlib::::BEGIN@13 Compress::Raw::Zlib::BEGIN@13
11117µs58µsCompress::Raw::Zlib::::BEGIN@78 Compress::Raw::Zlib::BEGIN@78
11117µs107µsCompress::Raw::Zlib::::BEGIN@7 Compress::Raw::Zlib::BEGIN@7
11114µs21µsCompress::Raw::Zlib::::BEGIN@11 Compress::Raw::Zlib::BEGIN@11
11112µs61µsCompress::Raw::Zlib::::BEGIN@85 Compress::Raw::Zlib::BEGIN@85
11112µs52µsCompress::Raw::Zlib::::BEGIN@87 Compress::Raw::Zlib::BEGIN@87
11111µs54µsCompress::Raw::Zlib::::BEGIN@101 Compress::Raw::Zlib::BEGIN@101
11111µs49µsCompress::Raw::Zlib::::BEGIN@104 Compress::Raw::Zlib::BEGIN@104
11111µs53µsCompress::Raw::Zlib::::BEGIN@106 Compress::Raw::Zlib::BEGIN@106
11111µs53µsCompress::Raw::Zlib::::BEGIN@102 Compress::Raw::Zlib::BEGIN@102
11110µs51µsCompress::Raw::Zlib::::BEGIN@83 Compress::Raw::Zlib::BEGIN@83
11110µs51µsCompress::Raw::Zlib::::BEGIN@108 Compress::Raw::Zlib::BEGIN@108
11110µs52µsCompress::Raw::Zlib::::BEGIN@86 Compress::Raw::Zlib::BEGIN@86
11110µs49µsCompress::Raw::Zlib::::BEGIN@84 Compress::Raw::Zlib::BEGIN@84
1119µs44µsCompress::Raw::Zlib::::BEGIN@105 Compress::Raw::Zlib::BEGIN@105
1119µs47µsCompress::Raw::Zlib::::BEGIN@110 Compress::Raw::Zlib::BEGIN@110
1118µs36µsCompress::Raw::Zlib::::BEGIN@103 Compress::Raw::Zlib::BEGIN@103
1117µs39µsCompress::Raw::Zlib::::BEGIN@111 Compress::Raw::Zlib::BEGIN@111
1117µs32µsCompress::Raw::Zlib::::BEGIN@113 Compress::Raw::Zlib::BEGIN@113
1116µs42µsCompress::Raw::Zlib::::BEGIN@112 Compress::Raw::Zlib::BEGIN@112
1116µs32µsCompress::Raw::Zlib::::BEGIN@115 Compress::Raw::Zlib::BEGIN@115
1116µs32µsCompress::Raw::Zlib::::BEGIN@114 Compress::Raw::Zlib::BEGIN@114
0000s0sCompress::Raw::Zlib::::AUTOLOAD Compress::Raw::Zlib::AUTOLOAD
0000s0sCompress::Raw::Zlib::Deflate::::new Compress::Raw::Zlib::Deflate::new
0000s0sCompress::Raw::Zlib::Inflate::::new Compress::Raw::Zlib::Inflate::new
0000s0sCompress::Raw::Zlib::InflateScan::::new Compress::Raw::Zlib::InflateScan::new
0000s0sCompress::Raw::Zlib::Parameters::::_checkType Compress::Raw::Zlib::Parameters::_checkType
0000s0sCompress::Raw::Zlib::Parameters::::new Compress::Raw::Zlib::Parameters::new
0000s0sCompress::Raw::Zlib::Parameters::::parse Compress::Raw::Zlib::Parameters::parse
0000s0sCompress::Raw::Zlib::Parameters::::parsed Compress::Raw::Zlib::Parameters::parsed
0000s0sCompress::Raw::Zlib::Parameters::::setError Compress::Raw::Zlib::Parameters::setError
0000s0sCompress::Raw::Zlib::Parameters::::value Compress::Raw::Zlib::Parameters::value
0000s0sCompress::Raw::Zlib::::ParseParameters Compress::Raw::Zlib::ParseParameters
0000s0sCompress::Raw::Zlib::::__ANON__[:79] Compress::Raw::Zlib::__ANON__[:79]
0000s0sCompress::Raw::Zlib::deflateStream::::deflateParams Compress::Raw::Zlib::deflateStream::deflateParams
0000s0sCompress::Raw::Zlib::inflateScanStream::::createDeflateStreamCompress::Raw::Zlib::inflateScanStream::createDeflateStream
0000s0sCompress::Raw::Zlib::inflateScanStream::::inflateCompress::Raw::Zlib::inflateScanStream::inflate
Call graph for these subroutines as a Graphviz dot language file.
Line State
ments
Time
on line
Calls Time
in subs
Code
1
2package Compress::Raw::Zlib;
3
4129µsrequire 5.004 ;
51700nsrequire Exporter;
6352µs2496µs
# spent 262µs (29+233) within Compress::Raw::Zlib::BEGIN@6 which was called # once (29µs+233µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 6
use AutoLoader;
# spent 262µs making 1 call to Compress::Raw::Zlib::BEGIN@6 # spent 233µs making 1 call to AutoLoader::import
7348µs2196µs
# spent 107µs (17+90) within Compress::Raw::Zlib::BEGIN@7 which was called # once (17µs+90µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 7
use Carp ;
# spent 107µs making 1 call to Compress::Raw::Zlib::BEGIN@7 # spent 90µs making 1 call to Exporter::import
8
9#use Parse::Parameters;
10
11345µs227µs
# spent 21µs (14+6) within Compress::Raw::Zlib::BEGIN@11 which was called # once (14µs+6µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 11
use strict ;
# spent 21µs making 1 call to Compress::Raw::Zlib::BEGIN@11 # spent 6µs making 1 call to strict::import
12372µs267µs
# spent 44µs (21+23) within Compress::Raw::Zlib::BEGIN@12 which was called # once (21µs+23µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 12
use warnings ;
# spent 44µs making 1 call to Compress::Raw::Zlib::BEGIN@12 # spent 23µs making 1 call to warnings::import
133404µs234µs
# spent 26µs (18+8) within Compress::Raw::Zlib::BEGIN@13 which was called # once (18µs+8µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 13
use bytes ;
# spent 26µs making 1 call to Compress::Raw::Zlib::BEGIN@13 # spent 8µs making 1 call to bytes::import
1411µsour ($VERSION, $XS_VERSION, @ISA, @EXPORT, $AUTOLOAD);
15
161500ns$VERSION = '2.020';
171200ns$XS_VERSION = $VERSION;
18122µs$VERSION = eval $VERSION;
19
20110µs@ISA = qw(Exporter);
21# Items to export into callers namespace by default. Note: do not export
22# names by default without a very good reason. Use EXPORT_OK instead.
23# Do not simply export all your public functions/methods/constants.
2417µs@EXPORT = qw(
25 adler32 crc32
26
27 ZLIB_VERSION
28 ZLIB_VERNUM
29
30 DEF_WBITS
31 OS_CODE
32
33 MAX_MEM_LEVEL
34 MAX_WBITS
35
36 Z_ASCII
37 Z_BEST_COMPRESSION
38 Z_BEST_SPEED
39 Z_BINARY
40 Z_BLOCK
41 Z_BUF_ERROR
42 Z_DATA_ERROR
43 Z_DEFAULT_COMPRESSION
44 Z_DEFAULT_STRATEGY
45 Z_DEFLATED
46 Z_ERRNO
47 Z_FILTERED
48 Z_FIXED
49 Z_FINISH
50 Z_FULL_FLUSH
51 Z_HUFFMAN_ONLY
52 Z_MEM_ERROR
53 Z_NEED_DICT
54 Z_NO_COMPRESSION
55 Z_NO_FLUSH
56 Z_NULL
57 Z_OK
58 Z_PARTIAL_FLUSH
59 Z_RLE
60 Z_STREAM_END
61 Z_STREAM_ERROR
62 Z_SYNC_FLUSH
63 Z_UNKNOWN
64 Z_VERSION_ERROR
65
66 WANT_GZIP
67 WANT_GZIP_OR_ZLIB
68);
69
70382µs2241µs
# spent 132µs (23+109) within Compress::Raw::Zlib::BEGIN@70 which was called # once (23µs+109µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 70
use constant WANT_GZIP => 16;
# spent 132µs making 1 call to Compress::Raw::Zlib::BEGIN@70 # spent 109µs making 1 call to constant::import
713220µs2174µs
# spent 96µs (19+77) within Compress::Raw::Zlib::BEGIN@71 which was called # once (19µs+77µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 71
use constant WANT_GZIP_OR_ZLIB => 32;
# spent 96µs making 1 call to Compress::Raw::Zlib::BEGIN@71 # spent 78µs making 1 call to constant::import
72
73sub AUTOLOAD {
74 my($constname);
75 ($constname = $AUTOLOAD) =~ s/.*:://;
76 my ($error, $val) = constant($constname);
77 Carp::croak $error if $error;
783131µs299µs
# spent 58µs (17+41) within Compress::Raw::Zlib::BEGIN@78 which was called # once (17µs+41µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 78
no strict 'refs';
# spent 58µs making 1 call to Compress::Raw::Zlib::BEGIN@78 # spent 41µs making 1 call to strict::unimport
79 *{$AUTOLOAD} = sub { $val };
80 goto &{$AUTOLOAD};
81}
82
83338µs292µs
# spent 51µs (10+41) within Compress::Raw::Zlib::BEGIN@83 which was called # once (10µs+41µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 83
use constant FLAG_APPEND => 1 ;
# spent 51µs making 1 call to Compress::Raw::Zlib::BEGIN@83 # spent 41µs making 1 call to constant::import
84340µs287µs
# spent 49µs (10+39) within Compress::Raw::Zlib::BEGIN@84 which was called # once (10µs+39µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 84
use constant FLAG_CRC => 2 ;
# spent 49µs making 1 call to Compress::Raw::Zlib::BEGIN@84 # spent 39µs making 1 call to constant::import
85338µs2109µs
# spent 61µs (12+48) within Compress::Raw::Zlib::BEGIN@85 which was called # once (12µs+48µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 85
use constant FLAG_ADLER => 4 ;
# spent 61µs making 1 call to Compress::Raw::Zlib::BEGIN@85 # spent 48µs making 1 call to constant::import
86340µs293µs
# spent 52µs (10+41) within Compress::Raw::Zlib::BEGIN@86 which was called # once (10µs+41µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 86
use constant FLAG_CONSUME_INPUT => 8 ;
# spent 52µs making 1 call to Compress::Raw::Zlib::BEGIN@86 # spent 41µs making 1 call to constant::import
873102µs293µs
# spent 52µs (12+41) within Compress::Raw::Zlib::BEGIN@87 which was called # once (12µs+41µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 87
use constant FLAG_LIMIT_OUTPUT => 16 ;
# spent 52µs making 1 call to Compress::Raw::Zlib::BEGIN@87 # spent 41µs making 1 call to constant::import
88
89eval {
901600ns require XSLoader;
911430µs1422µs XSLoader::load('Compress::Raw::Zlib', $XS_VERSION);
# spent 422µs making 1 call to XSLoader::load
9211µs 1;
93}
941600nsor do {
95 require DynaLoader;
96 local @ISA = qw(DynaLoader);
97 bootstrap Compress::Raw::Zlib $XS_VERSION ;
98};
99
100
101340µs296µs
# spent 54µs (11+42) within Compress::Raw::Zlib::BEGIN@101 which was called # once (11µs+42µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 101
use constant Parse_any => 0x01;
# spent 54µs making 1 call to Compress::Raw::Zlib::BEGIN@101 # spent 42µs making 1 call to constant::import
102335µs295µs
# spent 53µs (11+42) within Compress::Raw::Zlib::BEGIN@102 which was called # once (11µs+42µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 102
use constant Parse_unsigned => 0x02;
# spent 53µs making 1 call to Compress::Raw::Zlib::BEGIN@102 # spent 42µs making 1 call to constant::import
103340µs265µs
# spent 36µs (8+28) within Compress::Raw::Zlib::BEGIN@103 which was called # once (8µs+28µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 103
use constant Parse_signed => 0x04;
# spent 36µs making 1 call to Compress::Raw::Zlib::BEGIN@103 # spent 28µs making 1 call to constant::import
104340µs287µs
# spent 49µs (11+38) within Compress::Raw::Zlib::BEGIN@104 which was called # once (11µs+38µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 104
use constant Parse_boolean => 0x08;
# spent 49µs making 1 call to Compress::Raw::Zlib::BEGIN@104 # spent 38µs making 1 call to constant::import
105340µs279µs
# spent 44µs (9+35) within Compress::Raw::Zlib::BEGIN@105 which was called # once (9µs+35µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 105
use constant Parse_string => 0x10;
# spent 44µs making 1 call to Compress::Raw::Zlib::BEGIN@105 # spent 35µs making 1 call to constant::import
106339µs296µs
# spent 53µs (11+42) within Compress::Raw::Zlib::BEGIN@106 which was called # once (11µs+42µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 106
use constant Parse_custom => 0x12;
# spent 53µs making 1 call to Compress::Raw::Zlib::BEGIN@106 # spent 42µs making 1 call to constant::import
107
108336µs292µs
# spent 51µs (10+41) within Compress::Raw::Zlib::BEGIN@108 which was called # once (10µs+41µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 108
use constant Parse_store_ref => 0x100 ;
# spent 51µs making 1 call to Compress::Raw::Zlib::BEGIN@108 # spent 41µs making 1 call to constant::import
109
110327µs285µs
# spent 47µs (9+38) within Compress::Raw::Zlib::BEGIN@110 which was called # once (9µs+38µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 110
use constant OFF_PARSED => 0 ;
# spent 47µs making 1 call to Compress::Raw::Zlib::BEGIN@110 # spent 38µs making 1 call to constant::import
111327µs270µs
# spent 39µs (7+31) within Compress::Raw::Zlib::BEGIN@111 which was called # once (7µs+31µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 111
use constant OFF_TYPE => 1 ;
# spent 39µs making 1 call to Compress::Raw::Zlib::BEGIN@111 # spent 31µs making 1 call to constant::import
112325µs276µs
# spent 42µs (6+35) within Compress::Raw::Zlib::BEGIN@112 which was called # once (6µs+35µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 112
use constant OFF_DEFAULT => 2 ;
# spent 42µs making 1 call to Compress::Raw::Zlib::BEGIN@112 # spent 35µs making 1 call to constant::import
113324µs257µs
# spent 32µs (7+25) within Compress::Raw::Zlib::BEGIN@113 which was called # once (7µs+25µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 113
use constant OFF_FIXED => 3 ;
# spent 32µs making 1 call to Compress::Raw::Zlib::BEGIN@113 # spent 25µs making 1 call to constant::import
114324µs257µs
# spent 32µs (6+25) within Compress::Raw::Zlib::BEGIN@114 which was called # once (6µs+25µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 114
use constant OFF_FIRST_ONLY => 4 ;
# spent 32µs making 1 call to Compress::Raw::Zlib::BEGIN@114 # spent 25µs making 1 call to constant::import
11531.88ms257µs
# spent 32µs (6+25) within Compress::Raw::Zlib::BEGIN@115 which was called # once (6µs+25µs) by IO::Uncompress::RawInflate::BEGIN@8 at line 115
use constant OFF_STICKY => 5 ;
# spent 32µs making 1 call to Compress::Raw::Zlib::BEGIN@115 # spent 25µs making 1 call to constant::import
116
117
118
119sub ParseParameters
120{
121 my $level = shift || 0 ;
122
123 my $sub = (caller($level + 1))[3] ;
124 #local $Carp::CarpLevel = 1 ;
125 my $p = new Compress::Raw::Zlib::Parameters() ;
126 $p->parse(@_)
127 or croak "$sub: $p->{Error}" ;
128
129 return $p;
130}
131
132
133sub Compress::Raw::Zlib::Parameters::new
134{
135 my $class = shift ;
136
137 my $obj = { Error => '',
138 Got => {},
139 } ;
140
141 #return bless $obj, ref($class) || $class || __PACKAGE__ ;
142 return bless $obj, 'Compress::Raw::Zlib::Parameters' ;
143}
144
145sub Compress::Raw::Zlib::Parameters::setError
146{
147 my $self = shift ;
148 my $error = shift ;
149 my $retval = @_ ? shift : undef ;
150
151 $self->{Error} = $error ;
152 return $retval;
153}
154
155#sub getError
156#{
157# my $self = shift ;
158# return $self->{Error} ;
159#}
160
161sub Compress::Raw::Zlib::Parameters::parse
162{
163 my $self = shift ;
164
165 my $default = shift ;
166
167 my $got = $self->{Got} ;
168 my $firstTime = keys %{ $got } == 0 ;
169
170 my (@Bad) ;
171 my @entered = () ;
172
173 # Allow the options to be passed as a hash reference or
174 # as the complete hash.
175 if (@_ == 0) {
176 @entered = () ;
177 }
178 elsif (@_ == 1) {
179 my $href = $_[0] ;
180 return $self->setError("Expected even number of parameters, got 1")
181 if ! defined $href or ! ref $href or ref $href ne "HASH" ;
182
183 foreach my $key (keys %$href) {
184 push @entered, $key ;
185 push @entered, \$href->{$key} ;
186 }
187 }
188 else {
189 my $count = @_;
190 return $self->setError("Expected even number of parameters, got $count")
191 if $count % 2 != 0 ;
192
193 for my $i (0.. $count / 2 - 1) {
194 push @entered, $_[2* $i] ;
195 push @entered, \$_[2* $i+1] ;
196 }
197 }
198
199
200 while (my ($key, $v) = each %$default)
201 {
202 croak "need 4 params [@$v]"
203 if @$v != 4 ;
204
205 my ($first_only, $sticky, $type, $value) = @$v ;
206 my $x ;
207 $self->_checkType($key, \$value, $type, 0, \$x)
208 or return undef ;
209
210 $key = lc $key;
211
212 if ($firstTime || ! $sticky) {
213 $got->{$key} = [0, $type, $value, $x, $first_only, $sticky] ;
214 }
215
216 $got->{$key}[OFF_PARSED] = 0 ;
217 }
218
219 for my $i (0.. @entered / 2 - 1) {
220 my $key = $entered[2* $i] ;
221 my $value = $entered[2* $i+1] ;
222
223 #print "Key [$key] Value [$value]" ;
224 #print defined $$value ? "[$$value]\n" : "[undef]\n";
225
226 $key =~ s/^-// ;
227 my $canonkey = lc $key;
228
229 if ($got->{$canonkey} && ($firstTime ||
230 ! $got->{$canonkey}[OFF_FIRST_ONLY] ))
231 {
232 my $type = $got->{$canonkey}[OFF_TYPE] ;
233 my $s ;
234 $self->_checkType($key, $value, $type, 1, \$s)
235 or return undef ;
236 #$value = $$value unless $type & Parse_store_ref ;
237 $value = $$value ;
238 $got->{$canonkey} = [1, $type, $value, $s] ;
239 }
240 else
241 { push (@Bad, $key) }
242 }
243
244 if (@Bad) {
245 my ($bad) = join(", ", @Bad) ;
246 return $self->setError("unknown key value(s) @Bad") ;
247 }
248
249 return 1;
250}
251
252sub Compress::Raw::Zlib::Parameters::_checkType
253{
254 my $self = shift ;
255
256 my $key = shift ;
257 my $value = shift ;
258 my $type = shift ;
259 my $validate = shift ;
260 my $output = shift;
261
262 #local $Carp::CarpLevel = $level ;
263 #print "PARSE $type $key $value $validate $sub\n" ;
264 if ( $type & Parse_store_ref)
265 {
266 #$value = $$value
267 # if ref ${ $value } ;
268
269 $$output = $value ;
270 return 1;
271 }
272
273 $value = $$value ;
274
275 if ($type & Parse_any)
276 {
277 $$output = $value ;
278 return 1;
279 }
280 elsif ($type & Parse_unsigned)
281 {
282 return $self->setError("Parameter '$key' must be an unsigned int, got 'undef'")
283 if $validate && ! defined $value ;
284 return $self->setError("Parameter '$key' must be an unsigned int, got '$value'")
285 if $validate && $value !~ /^\d+$/;
286
287 $$output = defined $value ? $value : 0 ;
288 return 1;
289 }
290 elsif ($type & Parse_signed)
291 {
292 return $self->setError("Parameter '$key' must be a signed int, got 'undef'")
293 if $validate && ! defined $value ;
294 return $self->setError("Parameter '$key' must be a signed int, got '$value'")
295 if $validate && $value !~ /^-?\d+$/;
296
297 $$output = defined $value ? $value : 0 ;
298 return 1 ;
299 }
300 elsif ($type & Parse_boolean)
301 {
302 return $self->setError("Parameter '$key' must be an int, got '$value'")
303 if $validate && defined $value && $value !~ /^\d*$/;
304 $$output = defined $value ? $value != 0 : 0 ;
305 return 1;
306 }
307 elsif ($type & Parse_string)
308 {
309 $$output = defined $value ? $value : "" ;
310 return 1;
311 }
312
313 $$output = $value ;
314 return 1;
315}
316
317
318
319sub Compress::Raw::Zlib::Parameters::parsed
320{
321 my $self = shift ;
322 my $name = shift ;
323
324 return $self->{Got}{lc $name}[OFF_PARSED] ;
325}
326
327sub Compress::Raw::Zlib::Parameters::value
328{
329 my $self = shift ;
330 my $name = shift ;
331
332 if (@_)
333 {
334 $self->{Got}{lc $name}[OFF_PARSED] = 1;
335 $self->{Got}{lc $name}[OFF_DEFAULT] = $_[0] ;
336 $self->{Got}{lc $name}[OFF_FIXED] = $_[0] ;
337 }
338
339 return $self->{Got}{lc $name}[OFF_FIXED] ;
340}
341
342sub Compress::Raw::Zlib::Deflate::new
343{
344 my $pkg = shift ;
345 my ($got) = ParseParameters(0,
346 {
347 'AppendOutput' => [1, 1, Parse_boolean, 0],
348 'CRC32' => [1, 1, Parse_boolean, 0],
349 'ADLER32' => [1, 1, Parse_boolean, 0],
350 'Bufsize' => [1, 1, Parse_unsigned, 4096],
351
352 'Level' => [1, 1, Parse_signed, Z_DEFAULT_COMPRESSION()],
353 'Method' => [1, 1, Parse_unsigned, Z_DEFLATED()],
354 'WindowBits' => [1, 1, Parse_signed, MAX_WBITS()],
355 'MemLevel' => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()],
356 'Strategy' => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()],
357 'Dictionary' => [1, 1, Parse_any, ""],
358 }, @_) ;
359
360
361 croak "Compress::Raw::Zlib::Deflate::new: Bufsize must be >= 1, you specified " .
362 $got->value('Bufsize')
363 unless $got->value('Bufsize') >= 1;
364
365 my $flags = 0 ;
366 $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
367 $flags |= FLAG_CRC if $got->value('CRC32') ;
368 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
369
370 my $windowBits = $got->value('WindowBits');
371 $windowBits += MAX_WBITS()
372 if ($windowBits & MAX_WBITS()) == 0 ;
373
374 _deflateInit($flags,
375 $got->value('Level'),
376 $got->value('Method'),
377 $windowBits,
378 $got->value('MemLevel'),
379 $got->value('Strategy'),
380 $got->value('Bufsize'),
381 $got->value('Dictionary')) ;
382
383}
384
385sub Compress::Raw::Zlib::Inflate::new
386{
387 my $pkg = shift ;
388 my ($got) = ParseParameters(0,
389 {
390 'AppendOutput' => [1, 1, Parse_boolean, 0],
391 'LimitOutput' => [1, 1, Parse_boolean, 0],
392 'CRC32' => [1, 1, Parse_boolean, 0],
393 'ADLER32' => [1, 1, Parse_boolean, 0],
394 'ConsumeInput' => [1, 1, Parse_boolean, 1],
395 'Bufsize' => [1, 1, Parse_unsigned, 4096],
396
397 'WindowBits' => [1, 1, Parse_signed, MAX_WBITS()],
398 'Dictionary' => [1, 1, Parse_any, ""],
399 }, @_) ;
400
401
402 croak "Compress::Raw::Zlib::Inflate::new: Bufsize must be >= 1, you specified " .
403 $got->value('Bufsize')
404 unless $got->value('Bufsize') >= 1;
405
406 my $flags = 0 ;
407 $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
408 $flags |= FLAG_CRC if $got->value('CRC32') ;
409 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
410 $flags |= FLAG_CONSUME_INPUT if $got->value('ConsumeInput') ;
411 $flags |= FLAG_LIMIT_OUTPUT if $got->value('LimitOutput') ;
412
413
414 my $windowBits = $got->value('WindowBits');
415 $windowBits += MAX_WBITS()
416 if ($windowBits & MAX_WBITS()) == 0 ;
417
418 _inflateInit($flags, $windowBits, $got->value('Bufsize'),
419 $got->value('Dictionary')) ;
420}
421
422sub Compress::Raw::Zlib::InflateScan::new
423{
424 my $pkg = shift ;
425 my ($got) = ParseParameters(0,
426 {
427 'CRC32' => [1, 1, Parse_boolean, 0],
428 'ADLER32' => [1, 1, Parse_boolean, 0],
429 'Bufsize' => [1, 1, Parse_unsigned, 4096],
430
431 'WindowBits' => [1, 1, Parse_signed, -MAX_WBITS()],
432 'Dictionary' => [1, 1, Parse_any, ""],
433 }, @_) ;
434
435
436 croak "Compress::Raw::Zlib::InflateScan::new: Bufsize must be >= 1, you specified " .
437 $got->value('Bufsize')
438 unless $got->value('Bufsize') >= 1;
439
440 my $flags = 0 ;
441 #$flags |= FLAG_APPEND if $got->value('AppendOutput') ;
442 $flags |= FLAG_CRC if $got->value('CRC32') ;
443 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
444 #$flags |= FLAG_CONSUME_INPUT if $got->value('ConsumeInput') ;
445
446 _inflateScanInit($flags, $got->value('WindowBits'), $got->value('Bufsize'),
447 '') ;
448}
449
450sub Compress::Raw::Zlib::inflateScanStream::createDeflateStream
451{
452 my $pkg = shift ;
453 my ($got) = ParseParameters(0,
454 {
455 'AppendOutput' => [1, 1, Parse_boolean, 0],
456 'CRC32' => [1, 1, Parse_boolean, 0],
457 'ADLER32' => [1, 1, Parse_boolean, 0],
458 'Bufsize' => [1, 1, Parse_unsigned, 4096],
459
460 'Level' => [1, 1, Parse_signed, Z_DEFAULT_COMPRESSION()],
461 'Method' => [1, 1, Parse_unsigned, Z_DEFLATED()],
462 'WindowBits' => [1, 1, Parse_signed, - MAX_WBITS()],
463 'MemLevel' => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()],
464 'Strategy' => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()],
465 }, @_) ;
466
467 croak "Compress::Raw::Zlib::InflateScan::createDeflateStream: Bufsize must be >= 1, you specified " .
468 $got->value('Bufsize')
469 unless $got->value('Bufsize') >= 1;
470
471 my $flags = 0 ;
472 $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
473 $flags |= FLAG_CRC if $got->value('CRC32') ;
474 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
475
476 $pkg->_createDeflateStream($flags,
477 $got->value('Level'),
478 $got->value('Method'),
479 $got->value('WindowBits'),
480 $got->value('MemLevel'),
481 $got->value('Strategy'),
482 $got->value('Bufsize'),
483 ) ;
484
485}
486
487sub Compress::Raw::Zlib::inflateScanStream::inflate
488{
489 my $self = shift ;
490 my $buffer = $_[1];
491 my $eof = $_[2];
492
493 my $status = $self->scan(@_);
494
495 if ($status == Z_OK() && $_[2]) {
496 my $byte = ' ';
497
498 $status = $self->scan(\$byte, $_[1]) ;
499 }
500
501 return $status ;
502}
503
504sub Compress::Raw::Zlib::deflateStream::deflateParams
505{
506 my $self = shift ;
507 my ($got) = ParseParameters(0, {
508 'Level' => [1, 1, Parse_signed, undef],
509 'Strategy' => [1, 1, Parse_unsigned, undef],
510 'Bufsize' => [1, 1, Parse_unsigned, undef],
511 },
512 @_) ;
513
514 croak "Compress::Raw::Zlib::deflateParams needs Level and/or Strategy"
515 unless $got->parsed('Level') + $got->parsed('Strategy') +
516 $got->parsed('Bufsize');
517
518 croak "Compress::Raw::Zlib::Inflate::deflateParams: Bufsize must be >= 1, you specified " .
519 $got->value('Bufsize')
520 if $got->parsed('Bufsize') && $got->value('Bufsize') <= 1;
521
522 my $flags = 0;
523 $flags |= 1 if $got->parsed('Level') ;
524 $flags |= 2 if $got->parsed('Strategy') ;
525 $flags |= 4 if $got->parsed('Bufsize') ;
526
527 $self->_deflateParams($flags, $got->value('Level'),
528 $got->value('Strategy'), $got->value('Bufsize'));
529
530}
531
532
533# Autoload methods go after __END__, and are processed by the autosplit program.
534
535124µs1;
536__END__
537
538
539=head1 NAME
540
541Compress::Raw::Zlib - Low-Level Interface to zlib compression library
542
543=head1 SYNOPSIS
544
545 use Compress::Raw::Zlib ;
546
547 ($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) ;
548 $status = $d->deflate($input, $output) ;
549 $status = $d->flush($output [, $flush_type]) ;
550 $d->deflateReset() ;
551 $d->deflateParams(OPTS) ;
552 $d->deflateTune(OPTS) ;
553 $d->dict_adler() ;
554 $d->crc32() ;
555 $d->adler32() ;
556 $d->total_in() ;
557 $d->total_out() ;
558 $d->msg() ;
559 $d->get_Strategy();
560 $d->get_Level();
561 $d->get_BufSize();
562
563 ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) ;
564 $status = $i->inflate($input, $output [, $eof]) ;
565 $status = $i->inflateSync($input) ;
566 $i->dict_adler() ;
567 $d->crc32() ;
568 $d->adler32() ;
569 $i->total_in() ;
570 $i->total_out() ;
571 $i->msg() ;
572 $d->get_BufSize();
573
574 $crc = adler32($buffer [,$crc]) ;
575 $crc = crc32($buffer [,$crc]) ;
576
577 $crc = adler32_combine($crc1, $crc2, $len2)l
578 $crc = crc32_combine($adler1, $adler2, $len2)
579
580 my $version = Compress::Raw::Zlib::zlib_version();
581
582=head1 DESCRIPTION
583
584The I<Compress::Raw::Zlib> module provides a Perl interface to the I<zlib>
585compression library (see L</AUTHOR> for details about where to get
586I<zlib>).
587
588=head1 Compress::Raw::Zlib::Deflate
589
590This section defines an interface that allows in-memory compression using
591the I<deflate> interface provided by zlib.
592
593Here is a definition of the interface available:
594
595=head2 B<($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) >
596
597Initialises a deflation object.
598
599If you are familiar with the I<zlib> library, it combines the
600features of the I<zlib> functions C<deflateInit>, C<deflateInit2>
601and C<deflateSetDictionary>.
602
603If successful, it will return the initialised deflation object, C<$d>
604and a C<$status> of C<Z_OK> in a list context. In scalar context it
605returns the deflation object, C<$d>, only.
606
607If not successful, the returned deflation object, C<$d>, will be
608I<undef> and C<$status> will hold the a I<zlib> error code.
609
610The function optionally takes a number of named options specified as
611C<< Name => value >> pairs. This allows individual options to be
612tailored without having to specify them all in the parameter list.
613
614For backward compatibility, it is also possible to pass the parameters
615as a reference to a hash containing the name=>value pairs.
616
617Below is a list of the valid options:
618
619=over 5
620
621=item B<-Level>
622
623Defines the compression level. Valid values are 0 through 9,
624C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
625C<Z_DEFAULT_COMPRESSION>.
626
627The default is C<Z_DEFAULT_COMPRESSION>.
628
629=item B<-Method>
630
631Defines the compression method. The only valid value at present (and
632the default) is Z_DEFLATED.
633
634=item B<-WindowBits>
635
636To compress an RFC 1950 data stream, set C<WindowBits> to a positive
637number between 8 and 15.
638
639To compress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
640
641To compress an RFC 1952 data stream (i.e. gzip), set C<WindowBits> to
642C<WANT_GZIP>.
643
644For a definition of the meaning and valid values for C<WindowBits>
645refer to the I<zlib> documentation for I<deflateInit2>.
646
647Defaults to C<MAX_WBITS>.
648
649=item B<-MemLevel>
650
651For a definition of the meaning and valid values for C<MemLevel>
652refer to the I<zlib> documentation for I<deflateInit2>.
653
654Defaults to MAX_MEM_LEVEL.
655
656=item B<-Strategy>
657
658Defines the strategy used to tune the compression. The valid values are
659C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED>, C<Z_RLE>, C<Z_FIXED> and
660C<Z_HUFFMAN_ONLY>.
661
662The default is Z_DEFAULT_STRATEGY.
663
664=item B<-Dictionary>
665
666When a dictionary is specified I<Compress::Raw::Zlib> will automatically
667call C<deflateSetDictionary> directly after calling C<deflateInit>. The
668Adler32 value for the dictionary can be obtained by calling the method
669C<$d-E<gt>dict_adler()>.
670
671The default is no dictionary.
672
673=item B<-Bufsize>
674
675Sets the initial size for the output buffer used by the C<$d-E<gt>deflate>
676and C<$d-E<gt>flush> methods. If the buffer has to be
677reallocated to increase the size, it will grow in increments of
678C<Bufsize>.
679
680The default buffer size is 4096.
681
682=item B<-AppendOutput>
683
684This option controls how data is written to the output buffer by the
685C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods.
686
687If the C<AppendOutput> option is set to false, the output buffers in the
688C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods will be truncated before
689uncompressed data is written to them.
690
691If the option is set to true, uncompressed data will be appended to the
692output buffer in the C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods.
693
694This option defaults to false.
695
696=item B<-CRC32>
697
698If set to true, a crc32 checksum of the uncompressed data will be
699calculated. Use the C<$d-E<gt>crc32> method to retrieve this value.
700
701This option defaults to false.
702
703=item B<-ADLER32>
704
705If set to true, an adler32 checksum of the uncompressed data will be
706calculated. Use the C<$d-E<gt>adler32> method to retrieve this value.
707
708This option defaults to false.
709
710=back
711
712Here is an example of using the C<Compress::Raw::Zlib::Deflate> optional
713parameter list to override the default buffer size and compression
714level. All other options will take their default values.
715
716 my $d = new Compress::Raw::Zlib::Deflate ( -Bufsize => 300,
717 -Level => Z_BEST_SPEED ) ;
718
719=head2 B<$status = $d-E<gt>deflate($input, $output)>
720
721Deflates the contents of C<$input> and writes the compressed data to
722C<$output>.
723
724The C<$input> and C<$output> parameters can be either scalars or scalar
725references.
726
727When finished, C<$input> will be completely processed (assuming there
728were no errors). If the deflation was successful it writes the deflated
729data to C<$output> and returns a status value of C<Z_OK>.
730
731On error, it returns a I<zlib> error code.
732
733If the C<AppendOutput> option is set to true in the constructor for
734the C<$d> object, the compressed data will be appended to C<$output>. If
735it is false, C<$output> will be truncated before any compressed data is
736written to it.
737
738B<Note>: This method will not necessarily write compressed data to
739C<$output> every time it is called. So do not assume that there has been
740an error if the contents of C<$output> is empty on returning from
741this method. As long as the return code from the method is C<Z_OK>,
742the deflate has succeeded.
743
744=head2 B<$status = $d-E<gt>flush($output [, $flush_type]) >
745
746Typically used to finish the deflation. Any pending output will be
747written to C<$output>.
748
749Returns C<Z_OK> if successful.
750
751Note that flushing can seriously degrade the compression ratio, so it
752should only be used to terminate a decompression (using C<Z_FINISH>) or
753when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
754
755By default the C<flush_type> used is C<Z_FINISH>. Other valid values
756for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
757and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
758C<flush_type> parameter if you fully understand the implications of
759what it does. See the C<zlib> documentation for details.
760
761If the C<AppendOutput> option is set to true in the constructor for
762the C<$d> object, the compressed data will be appended to C<$output>. If
763it is false, C<$output> will be truncated before any compressed data is
764written to it.
765
766=head2 B<$status = $d-E<gt>deflateReset() >
767
768This method will reset the deflation object C<$d>. It can be used when you
769are compressing multiple data streams and want to use the same object to
770compress each of them. It should only be used once the previous data stream
771has been flushed successfully, i.e. a call to C<< $d->flush(Z_FINISH) >> has
772returned C<Z_OK>.
773
774Returns C<Z_OK> if successful.
775
776=head2 B<$status = $d-E<gt>deflateParams([OPT])>
777
778Change settings for the deflate object C<$d>.
779
780The list of the valid options is shown below. Options not specified
781will remain unchanged.
782
783=over 5
784
785=item B<-Level>
786
787Defines the compression level. Valid values are 0 through 9,
788C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
789C<Z_DEFAULT_COMPRESSION>.
790
791=item B<-Strategy>
792
793Defines the strategy used to tune the compression. The valid values are
794C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
795
796=item B<-BufSize>
797
798Sets the initial size for the output buffer used by the C<$d-E<gt>deflate>
799and C<$d-E<gt>flush> methods. If the buffer has to be
800reallocated to increase the size, it will grow in increments of
801C<Bufsize>.
802
803=back
804
805=head2 B<$status = $d-E<gt>deflateTune($good_length, $max_lazy, $nice_length, $max_chain)>
806
807Tune the internal settings for the deflate object C<$d>. This option is
808only available if you are running zlib 1.2.2.3 or better.
809
810Refer to the documentation in zlib.h for instructions on how to fly
811C<deflateTune>.
812
813=head2 B<$d-E<gt>dict_adler()>
814
815Returns the adler32 value for the dictionary.
816
817=head2 B<$d-E<gt>crc32()>
818
819Returns the crc32 value for the uncompressed data to date.
820
821If the C<CRC32> option is not enabled in the constructor for this object,
822this method will always return 0;
823
824=head2 B<$d-E<gt>adler32()>
825
826Returns the adler32 value for the uncompressed data to date.
827
828=head2 B<$d-E<gt>msg()>
829
830Returns the last error message generated by zlib.
831
832=head2 B<$d-E<gt>total_in()>
833
834Returns the total number of bytes uncompressed bytes input to deflate.
835
836=head2 B<$d-E<gt>total_out()>
837
838Returns the total number of compressed bytes output from deflate.
839
840=head2 B<$d-E<gt>get_Strategy()>
841
842Returns the deflation strategy currently used. Valid values are
843C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
844
845=head2 B<$d-E<gt>get_Level()>
846
847Returns the compression level being used.
848
849=head2 B<$d-E<gt>get_BufSize()>
850
851Returns the buffer size used to carry out the compression.
852
853=head2 Example
854
855Here is a trivial example of using C<deflate>. It simply reads standard
856input, deflates it and writes it to standard output.
857
858 use strict ;
859 use warnings ;
860
861 use Compress::Raw::Zlib ;
862
863 binmode STDIN;
864 binmode STDOUT;
865 my $x = new Compress::Raw::Zlib::Deflate
866 or die "Cannot create a deflation stream\n" ;
867
868 my ($output, $status) ;
869 while (<>)
870 {
871 $status = $x->deflate($_, $output) ;
872
873 $status == Z_OK
874 or die "deflation failed\n" ;
875
876 print $output ;
877 }
878
879 $status = $x->flush($output) ;
880
881 $status == Z_OK
882 or die "deflation failed\n" ;
883
884 print $output ;
885
886=head1 Compress::Raw::Zlib::Inflate
887
888This section defines an interface that allows in-memory uncompression using
889the I<inflate> interface provided by zlib.
890
891Here is a definition of the interface:
892
893=head2 B< ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) >
894
895Initialises an inflation object.
896
897In a list context it returns the inflation object, C<$i>, and the
898I<zlib> status code (C<$status>). In a scalar context it returns the
899inflation object only.
900
901If successful, C<$i> will hold the inflation object and C<$status> will
902be C<Z_OK>.
903
904If not successful, C<$i> will be I<undef> and C<$status> will hold the
905I<zlib> error code.
906
907The function optionally takes a number of named options specified as
908C<< -Name => value >> pairs. This allows individual options to be
909tailored without having to specify them all in the parameter list.
910
911For backward compatibility, it is also possible to pass the parameters
912as a reference to a hash containing the C<< name=>value >> pairs.
913
914Here is a list of the valid options:
915
916=over 5
917
918=item B<-WindowBits>
919
920To uncompress an RFC 1950 data stream, set C<WindowBits> to a positive
921number between 8 and 15.
922
923To uncompress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
924
925To uncompress an RFC 1952 data stream (i.e. gzip), set C<WindowBits> to
926C<WANT_GZIP>.
927
928To auto-detect and uncompress an RFC 1950 or RFC 1952 data stream (i.e.
929gzip), set C<WindowBits> to C<WANT_GZIP_OR_ZLIB>.
930
931For a full definition of the meaning and valid values for C<WindowBits>
932refer to the I<zlib> documentation for I<inflateInit2>.
933
934Defaults to C<MAX_WBITS>.
935
936=item B<-Bufsize>
937
938Sets the initial size for the output buffer used by the C<$i-E<gt>inflate>
939method. If the output buffer in this method has to be reallocated to
940increase the size, it will grow in increments of C<Bufsize>.
941
942Default is 4096.
943
944=item B<-Dictionary>
945
946The default is no dictionary.
947
948=item B<-AppendOutput>
949
950This option controls how data is written to the output buffer by the
951C<$i-E<gt>inflate> method.
952
953If the option is set to false, the output buffer in the C<$i-E<gt>inflate>
954method will be truncated before uncompressed data is written to it.
955
956If the option is set to true, uncompressed data will be appended to the
957output buffer by the C<$i-E<gt>inflate> method.
958
959This option defaults to false.
960
961=item B<-CRC32>
962
963If set to true, a crc32 checksum of the uncompressed data will be
964calculated. Use the C<$i-E<gt>crc32> method to retrieve this value.
965
966This option defaults to false.
967
968=item B<-ADLER32>
969
970If set to true, an adler32 checksum of the uncompressed data will be
971calculated. Use the C<$i-E<gt>adler32> method to retrieve this value.
972
973This option defaults to false.
974
975=item B<-ConsumeInput>
976
977If set to true, this option will remove compressed data from the input
978buffer of the C<< $i->inflate >> method as the inflate progresses.
979
980This option can be useful when you are processing compressed data that is
981embedded in another file/buffer. In this case the data that immediately
982follows the compressed stream will be left in the input buffer.
983
984This option defaults to true.
985
986=item B<-LimitOutput>
987
988The C<LimitOutput> option changes the behavior of the C<< $i->inflate >>
989method so that the amount of memory used by the output buffer can be
990limited.
991
992When C<LimitOutput> is used the size of the output buffer used will either
993be the value of the C<Bufsize> option or the amount of memory already
994allocated to C<$output>, whichever is larger. Predicting the output size
995available is tricky, so don't rely on getting an exact output buffer size.
996
997When C<LimitOutout> is not specified C<< $i->inflate >> will use as much
998memory as it takes to write all the uncompressed data it creates by
999uncompressing the input buffer.
1000
1001If C<LimitOutput> is enabled, the C<ConsumeInput> option will also be
1002enabled.
1003
1004This option defaults to false.
1005
1006See L</The LimitOutput option> for a discussion on why C<LimitOutput> is
1007needed and how to use it.
1008
1009=back
1010
1011Here is an example of using an optional parameter to override the default
1012buffer size.
1013
1014 my ($i, $status) = new Compress::Raw::Zlib::Inflate( -Bufsize => 300 ) ;
1015
1016=head2 B< $status = $i-E<gt>inflate($input, $output [,$eof]) >
1017
1018Inflates the complete contents of C<$input> and writes the uncompressed
1019data to C<$output>. The C<$input> and C<$output> parameters can either be
1020scalars or scalar references.
1021
1022Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
1023compressed data has been successfully reached.
1024
1025If not successful C<$status> will hold the I<zlib> error code.
1026
1027If the C<ConsumeInput> option has been set to true when the
1028C<Compress::Raw::Zlib::Inflate> object is created, the C<$input> parameter
1029is modified by C<inflate>. On completion it will contain what remains
1030of the input buffer after inflation. In practice, this means that when
1031the return status is C<Z_OK> the C<$input> parameter will contain an
1032empty string, and when the return status is C<Z_STREAM_END> the C<$input>
1033parameter will contains what (if anything) was stored in the input buffer
1034after the deflated data stream.
1035
1036This feature is useful when processing a file format that encapsulates
1037a compressed data stream (e.g. gzip, zip) and there is useful data
1038immediately after the deflation stream.
1039
1040If the C<AppendOutput> option is set to true in the constructor for
1041this object, the uncompressed data will be appended to C<$output>. If
1042it is false, C<$output> will be truncated before any uncompressed data
1043is written to it.
1044
1045The C<$eof> parameter needs a bit of explanation.
1046
1047Prior to version 1.2.0, zlib assumed that there was at least one trailing
1048byte immediately after the compressed data stream when it was carrying out
1049decompression. This normally isn't a problem because the majority of zlib
1050applications guarantee that there will be data directly after the
1051compressed data stream. For example, both gzip (RFC 1950) and zip both
1052define trailing data that follows the compressed data stream.
1053
1054The C<$eof> parameter only needs to be used if B<all> of the following
1055conditions apply
1056
1057=over 5
1058
1059=item 1
1060
1061You are either using a copy of zlib that is older than version 1.2.0 or you
1062want your application code to be able to run with as many different
1063versions of zlib as possible.
1064
1065=item 2
1066
1067You have set the C<WindowBits> parameter to C<-MAX_WBITS> in the constructor
1068for this object, i.e. you are uncompressing a raw deflated data stream
1069(RFC 1951).
1070
1071=item 3
1072
1073There is no data immediately after the compressed data stream.
1074
1075=back
1076
1077If B<all> of these are the case, then you need to set the C<$eof> parameter
1078to true on the final call (and only the final call) to C<$i-E<gt>inflate>.
1079
1080If you have built this module with zlib >= 1.2.0, the C<$eof> parameter is
1081ignored. You can still set it if you want, but it won't be used behind the
1082scenes.
1083
1084=head2 B<$status = $i-E<gt>inflateSync($input)>
1085
1086This method can be used to attempt to recover good data from a compressed
1087data stream that is partially corrupt.
1088It scans C<$input> until it reaches either a I<full flush point> or the
1089end of the buffer.
1090
1091If a I<full flush point> is found, C<Z_OK> is returned and C<$input>
1092will be have all data up to the flush point removed. This data can then be
1093passed to the C<$i-E<gt>inflate> method to be uncompressed.
1094
1095Any other return code means that a flush point was not found. If more
1096data is available, C<inflateSync> can be called repeatedly with more
1097compressed data until the flush point is found.
1098
1099Note I<full flush points> are not present by default in compressed
1100data streams. They must have been added explicitly when the data stream
1101was created by calling C<Compress::Deflate::flush> with C<Z_FULL_FLUSH>.
1102
1103=head2 B<$i-E<gt>dict_adler()>
1104
1105Returns the adler32 value for the dictionary.
1106
1107=head2 B<$i-E<gt>crc32()>
1108
1109Returns the crc32 value for the uncompressed data to date.
1110
1111If the C<CRC32> option is not enabled in the constructor for this object,
1112this method will always return 0;
1113
1114=head2 B<$i-E<gt>adler32()>
1115
1116Returns the adler32 value for the uncompressed data to date.
1117
1118If the C<ADLER32> option is not enabled in the constructor for this object,
1119this method will always return 0;
1120
1121=head2 B<$i-E<gt>msg()>
1122
1123Returns the last error message generated by zlib.
1124
1125=head2 B<$i-E<gt>total_in()>
1126
1127Returns the total number of bytes compressed bytes input to inflate.
1128
1129=head2 B<$i-E<gt>total_out()>
1130
1131Returns the total number of uncompressed bytes output from inflate.
1132
1133=head2 B<$d-E<gt>get_BufSize()>
1134
1135Returns the buffer size used to carry out the decompression.
1136
1137=head2 Examples
1138
1139Here is an example of using C<inflate>.
1140
1141 use strict ;
1142 use warnings ;
1143
1144 use Compress::Raw::Zlib;
1145
1146 my $x = new Compress::Raw::Zlib::Inflate()
1147 or die "Cannot create a inflation stream\n" ;
1148
1149 my $input = '' ;
1150 binmode STDIN;
1151 binmode STDOUT;
1152
1153 my ($output, $status) ;
1154 while (read(STDIN, $input, 4096))
1155 {
1156 $status = $x->inflate($input, $output) ;
1157
1158 print $output ;
1159
1160 last if $status != Z_OK ;
1161 }
1162
1163 die "inflation failed\n"
1164 unless $status == Z_STREAM_END ;
1165
1166The next example show how to use the C<LimitOutput> option. Notice the use
1167of two nested loops in this case. The outer loop reads the data from the
1168input source - STDIN and the inner loop repeatedly calls C<inflate> until
1169C<$input> is exhausted, we get an error, or the end of the stream is
1170reached. One point worth remembering is by using the C<LimitOutput> option
1171you also get C<ConsumeInput> set as well - this makes the code below much
1172simpler.
1173
1174 use strict ;
1175 use warnings ;
1176
1177 use Compress::Raw::Zlib;
1178
1179 my $x = new Compress::Raw::Zlib::Inflate(LimitOutput => 1)
1180 or die "Cannot create a inflation stream\n" ;
1181
1182 my $input = '' ;
1183 binmode STDIN;
1184 binmode STDOUT;
1185
1186 my ($output, $status) ;
1187
1188 OUTER:
1189 while (read(STDIN, $input, 4096))
1190 {
1191 do
1192 {
1193 $status = $x->inflate($input, $output) ;
1194
1195 print $output ;
1196
1197 last OUTER
1198 unless $status == Z_OK || $status == Z_BUF_ERROR ;
1199 }
1200 while ($status == Z_OK && length $input);
1201 }
1202
1203 die "inflation failed\n"
1204 unless $status == Z_STREAM_END ;
1205
1206=head1 CHECKSUM FUNCTIONS
1207
1208Two functions are provided by I<zlib> to calculate checksums. For the
1209Perl interface, the order of the two parameters in both functions has
1210been reversed. This allows both running checksums and one off
1211calculations to be done.
1212
1213 $crc = adler32($buffer [,$crc]) ;
1214 $crc = crc32($buffer [,$crc]) ;
1215
1216The buffer parameters can either be a scalar or a scalar reference.
1217
1218If the $crc parameters is C<undef>, the crc value will be reset.
1219
1220If you have built this module with zlib 1.2.3 or better, two more
1221CRC-related functions are available.
1222
1223 $crc = adler32_combine($crc1, $crc2, $len2)l
1224 $crc = crc32_combine($adler1, $adler2, $len2)
1225
1226These functions allow checksums to be merged.
1227
1228=head1 Misc
1229
1230=head2 my $version = Compress::Raw::Zlib::zlib_version();
1231
1232Returns the version of the zlib library.
1233
1234=head1 The LimitOutput option.
1235
1236By default C<< $i->inflate($input, $output) >> will uncompress I<all> data
1237in C<$input> and write I<all> of the uncompressed data it has generated to
1238C<$output>. This makes the interface to C<inflate> much simpler - if the
1239method has uncompressed C<$input> successfully I<all> compressed data in
1240C<$input> will have been dealt with. So if you are reading from an input
1241source and uncompressing as you go the code will look something like this
1242
1243 use strict ;
1244 use warnings ;
1245
1246 use Compress::Raw::Zlib;
1247
1248 my $x = new Compress::Raw::Zlib::Inflate()
1249 or die "Cannot create a inflation stream\n" ;
1250
1251 my $input = '' ;
1252
1253 my ($output, $status) ;
1254 while (read(STDIN, $input, 4096))
1255 {
1256 $status = $x->inflate($input, $output) ;
1257
1258 print $output ;
1259
1260 last if $status != Z_OK ;
1261 }
1262
1263 die "inflation failed\n"
1264 unless $status == Z_STREAM_END ;
1265
1266The points to note are
1267
1268=over 5
1269
1270=item *
1271
1272The main processing loop in the code handles reading of compressed data
1273from STDIN.
1274
1275=item *
1276
1277The status code returned from C<inflate> will only trigger termination of
1278the main processing loop if it isn't C<Z_OK>. When C<LimitOutput> has not
1279been used the C<Z_OK> status means means that the end of the compressed
1280data stream has been reached or there has been an error in uncompression.
1281
1282=item *
1283
1284After the call to C<inflate> I<all> of the uncompressed data in C<$input>
1285will have been processed. This means the subsequent call to C<read> can
1286overwrite it's contents without any problem.
1287
1288=back
1289
1290For most use-cases the behavior described above is acceptable (this module
1291and it's predecessor, C<Compress::Zlib>, have used it for over 10 years
1292without an issue), but in a few very specific use-cases the amount of
1293memory required for C<$output> can prohibitively large. For example, if the
1294compressed data stream contains the same pattern repeated thousands of
1295times, a relatively small compressed data stream can uncompress into
1296hundreds of megabytes. Remember C<inflate> will keep allocating memory
1297until I<all> the uncompressed data has been written to the output buffer -
1298the size of C<$output> is unbounded.
1299
1300The C<LimitOutput> option is designed to help with this use-case.
1301
1302The main difference in your code when using C<LimitOutput> is having to
1303deal with cases where the C<$input> parameter still contains some
1304uncompressed data that C<inflate> hasn't processed yet. The status code
1305returned from C<inflate> will be C<Z_OK> if uncompression took place and
1306C<Z_BUF_ERROR> if the output buffer is full.
1307
1308Below is typical code that shows how to use C<LimitOutput>.
1309
1310 use strict ;
1311 use warnings ;
1312
1313 use Compress::Raw::Zlib;
1314
1315 my $x = new Compress::Raw::Zlib::Inflate(LimitOutput => 1)
1316 or die "Cannot create a inflation stream\n" ;
1317
1318 my $input = '' ;
1319 binmode STDIN;
1320 binmode STDOUT;
1321
1322 my ($output, $status) ;
1323
1324 OUTER:
1325 while (read(STDIN, $input, 4096))
1326 {
1327 do
1328 {
1329 $status = $x->inflate($input, $output) ;
1330
1331 print $output ;
1332
1333 last OUTER
1334 unless $status == Z_OK || $status == Z_BUF_ERROR ;
1335 }
1336 while ($status == Z_OK && length $input);
1337 }
1338
1339 die "inflation failed\n"
1340 unless $status == Z_STREAM_END ;
1341
1342Points to note this time:
1343
1344=over 5
1345
1346=item *
1347
1348There are now two nested loops in the code: the outer loop for reading the
1349compressed data from STDIN, as before; and the inner loop to carry out the
1350uncompression.
1351
1352=item *
1353
1354There are two exit points from the inner uncompression loop.
1355
1356Firstly when C<inflate> has returned a status other than C<Z_OK> or
1357C<Z_BUF_ERROR>. This means that either the end of the compressed data
1358stream has been reached (C<Z_STREAM_END>) or there is an error in the
1359compressed data. In either of these cases there is no point in continuing
1360with reading the compressed data, so both loops are terminated.
1361
1362The second exit point tests if there is any data left in the input buffer,
1363C<$input> - remember that the C<ConsumeInput> option is automatically
1364enabled when C<LimitOutput> is used. When the input buffer has been
1365exhausted, the outer loop can run again and overwrite a now empty
1366C<$input>.
1367
1368=back
1369
1370=head1 ACCESSING ZIP FILES
1371
1372Although it is possible (with some effort on your part) to use this module
1373to access .zip files, there are other perl modules available that will
1374do all the hard work for you. Check out C<Archive::Zip>,
1375C<IO::Compress::Zip> and C<IO::Uncompress::Unzip>.
1376
1377=head1 CONSTANTS
1378
1379All the I<zlib> constants are automatically imported when you make use
1380of I<Compress::Raw::Zlib>.
1381
1382=head1 SEE ALSO
1383
1384L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1385
1386L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1387
1388L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1389L<Archive::Tar|Archive::Tar>,
1390L<IO::Zlib|IO::Zlib>
1391
1392For RFC 1950, 1951 and 1952 see
1393F<http://www.faqs.org/rfcs/rfc1950.html>,
1394F<http://www.faqs.org/rfcs/rfc1951.html> and
1395F<http://www.faqs.org/rfcs/rfc1952.html>
1396
1397The I<zlib> compression library was written by Jean-loup Gailly
1398F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1399
1400The primary site for the I<zlib> compression library is
1401F<http://www.zlib.org>.
1402
1403The primary site for gzip is F<http://www.gzip.org>.
1404
1405=head1 AUTHOR
1406
1407This module was written by Paul Marquess, F<pmqs@cpan.org>.
1408
1409=head1 MODIFICATION HISTORY
1410
1411See the Changes file.
1412
1413=head1 COPYRIGHT AND LICENSE
1414
1415Copyright (c) 2005-2009 Paul Marquess. All rights reserved.
1416
1417This program is free software; you can redistribute it and/or
1418modify it under the same terms as Perl itself.
1419