← Index
NYTProf Performance Profile   « block view • line view • sub view »
For ddd2.pl
  Run on Tue May 25 16:52:24 2010
Reported on Tue May 25 16:56:45 2010

File /project/perl/lib/Compress/Raw/Zlib.pm
Statements Executed 82
Statement Execution Time 7.89ms
Subroutines — ordered by exclusive time
Calls P F Exclusive
Time
Inclusive
Time
Subroutine
0000s0sCompress::Raw::Zlib::::AUTOLOAD Compress::Raw::Zlib::AUTOLOAD
0000s0sCompress::Raw::Zlib::::BEGIN Compress::Raw::Zlib::BEGIN
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__[:74] Compress::Raw::Zlib::__ANON__[:74]
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
415µsrequire 5.004 ;
517µsrequire Exporter;
63100µs1393µsuse AutoLoader;
# spent 393µs making 1 call to AutoLoader::import
7398µs1248µsuse Carp ;
# spent 248µs making 1 call to Exporter::import
8
9#use Parse::Parameters;
10
11376µs122µsuse strict ;
# spent 22µs making 1 call to strict::import
12383µs1111µsuse warnings ;
# spent 111µs making 1 call to warnings::import
133413µs114µsuse bytes ;
# spent 14µs making 1 call to bytes::import
1415µsour ($VERSION, $XS_VERSION, @ISA, @EXPORT, $AUTOLOAD);
15
1619µs$VERSION = '2.005';
1715µs$XS_VERSION = $VERSION;
18167µs$VERSION = eval $VERSION;
19
2019µ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.
24122µ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
67
68sub AUTOLOAD {
69 my($constname);
70 ($constname = $AUTOLOAD) =~ s/.*:://;
71 my ($error, $val) = constant($constname);
72 Carp::croak $error if $error;
733314µs1100µs no strict 'refs';
# spent 100µs making 1 call to strict::unimport
74 *{$AUTOLOAD} = sub { $val };
75 goto &{$AUTOLOAD};
76}
77
783103µs1195µsuse constant FLAG_APPEND => 1 ;
# spent 195µs making 1 call to constant::import
793119µs1186µsuse constant FLAG_CRC => 2 ;
# spent 186µs making 1 call to constant::import
80395µs1178µsuse constant FLAG_ADLER => 4 ;
# spent 178µs making 1 call to constant::import
813206µs1176µsuse constant FLAG_CONSUME_INPUT => 8 ;
# spent 176µs making 1 call to constant::import
82
83eval {
8415µs require XSLoader;
851822µs1792µs XSLoader::load('Compress::Raw::Zlib', $XS_VERSION);
# spent 792µs making 1 call to XSLoader::load
8617µs 1;
87}
88110µsor do {
89 require DynaLoader;
90 local @ISA = qw(DynaLoader);
91 bootstrap Compress::Raw::Zlib $XS_VERSION ;
92};
93
94
95397µs1184µsuse constant Parse_any => 0x01;
# spent 184µs making 1 call to constant::import
96391µs1183µsuse constant Parse_unsigned => 0x02;
# spent 183µs making 1 call to constant::import
973104µs1178µsuse constant Parse_signed => 0x04;
# spent 178µs making 1 call to constant::import
98396µs1183µsuse constant Parse_boolean => 0x08;
# spent 183µs making 1 call to constant::import
993107µs1178µsuse constant Parse_string => 0x10;
# spent 178µs making 1 call to constant::import
100395µs1173µsuse constant Parse_custom => 0x12;
# spent 173µs making 1 call to constant::import
101
102392µs1170µsuse constant Parse_store_ref => 0x100 ;
# spent 170µs making 1 call to constant::import
103
104397µs1193µsuse constant OFF_PARSED => 0 ;
# spent 193µs making 1 call to constant::import
105392µs1171µsuse constant OFF_TYPE => 1 ;
# spent 171µs making 1 call to constant::import
1063100µs1192µsuse constant OFF_DEFAULT => 2 ;
# spent 192µs making 1 call to constant::import
107393µs1177µsuse constant OFF_FIXED => 3 ;
# spent 177µs making 1 call to constant::import
1083107µs1172µsuse constant OFF_FIRST_ONLY => 4 ;
# spent 172µs making 1 call to constant::import
10934.10ms1178µsuse constant OFF_STICKY => 5 ;
# spent 178µs making 1 call to constant::import
110
111
112
113sub ParseParameters
114{
115 my $level = shift || 0 ;
116
117 my $sub = (caller($level + 1))[3] ;
118 #local $Carp::CarpLevel = 1 ;
119 my $p = new Compress::Raw::Zlib::Parameters() ;
120 $p->parse(@_)
121 or croak "$sub: $p->{Error}" ;
122
123 return $p;
124}
125
126
127sub Compress::Raw::Zlib::Parameters::new
128{
129 my $class = shift ;
130
131 my $obj = { Error => '',
132 Got => {},
133 } ;
134
135 #return bless $obj, ref($class) || $class || __PACKAGE__ ;
136 return bless $obj, 'Compress::Raw::Zlib::Parameters' ;
137}
138
139sub Compress::Raw::Zlib::Parameters::setError
140{
141 my $self = shift ;
142 my $error = shift ;
143 my $retval = @_ ? shift : undef ;
144
145 $self->{Error} = $error ;
146 return $retval;
147}
148
149#sub getError
150#{
151# my $self = shift ;
152# return $self->{Error} ;
153#}
154
155sub Compress::Raw::Zlib::Parameters::parse
156{
157 my $self = shift ;
158
159 my $default = shift ;
160
161 my $got = $self->{Got} ;
162 my $firstTime = keys %{ $got } == 0 ;
163
164 my (@Bad) ;
165 my @entered = () ;
166
167 # Allow the options to be passed as a hash reference or
168 # as the complete hash.
169 if (@_ == 0) {
170 @entered = () ;
171 }
172 elsif (@_ == 1) {
173 my $href = $_[0] ;
174 return $self->setError("Expected even number of parameters, got 1")
175 if ! defined $href or ! ref $href or ref $href ne "HASH" ;
176
177 foreach my $key (keys %$href) {
178 push @entered, $key ;
179 push @entered, \$href->{$key} ;
180 }
181 }
182 else {
183 my $count = @_;
184 return $self->setError("Expected even number of parameters, got $count")
185 if $count % 2 != 0 ;
186
187 for my $i (0.. $count / 2 - 1) {
188 push @entered, $_[2* $i] ;
189 push @entered, \$_[2* $i+1] ;
190 }
191 }
192
193
194 while (my ($key, $v) = each %$default)
195 {
196 croak "need 4 params [@$v]"
197 if @$v != 4 ;
198
199 my ($first_only, $sticky, $type, $value) = @$v ;
200 my $x ;
201 $self->_checkType($key, \$value, $type, 0, \$x)
202 or return undef ;
203
204 $key = lc $key;
205
206 if ($firstTime || ! $sticky) {
207 $got->{$key} = [0, $type, $value, $x, $first_only, $sticky] ;
208 }
209
210 $got->{$key}[OFF_PARSED] = 0 ;
211 }
212
213 for my $i (0.. @entered / 2 - 1) {
214 my $key = $entered[2* $i] ;
215 my $value = $entered[2* $i+1] ;
216
217 #print "Key [$key] Value [$value]" ;
218 #print defined $$value ? "[$$value]\n" : "[undef]\n";
219
220 $key =~ s/^-// ;
221 my $canonkey = lc $key;
222
223 if ($got->{$canonkey} && ($firstTime ||
224 ! $got->{$canonkey}[OFF_FIRST_ONLY] ))
225 {
226 my $type = $got->{$canonkey}[OFF_TYPE] ;
227 my $s ;
228 $self->_checkType($key, $value, $type, 1, \$s)
229 or return undef ;
230 #$value = $$value unless $type & Parse_store_ref ;
231 $value = $$value ;
232 $got->{$canonkey} = [1, $type, $value, $s] ;
233 }
234 else
235 { push (@Bad, $key) }
236 }
237
238 if (@Bad) {
239 my ($bad) = join(", ", @Bad) ;
240 return $self->setError("unknown key value(s) @Bad") ;
241 }
242
243 return 1;
244}
245
246sub Compress::Raw::Zlib::Parameters::_checkType
247{
248 my $self = shift ;
249
250 my $key = shift ;
251 my $value = shift ;
252 my $type = shift ;
253 my $validate = shift ;
254 my $output = shift;
255
256 #local $Carp::CarpLevel = $level ;
257 #print "PARSE $type $key $value $validate $sub\n" ;
258 if ( $type & Parse_store_ref)
259 {
260 #$value = $$value
261 # if ref ${ $value } ;
262
263 $$output = $value ;
264 return 1;
265 }
266
267 $value = $$value ;
268
269 if ($type & Parse_any)
270 {
271 $$output = $value ;
272 return 1;
273 }
274 elsif ($type & Parse_unsigned)
275 {
276 return $self->setError("Parameter '$key' must be an unsigned int, got 'undef'")
277 if $validate && ! defined $value ;
278 return $self->setError("Parameter '$key' must be an unsigned int, got '$value'")
279 if $validate && $value !~ /^\d+$/;
280
281 $$output = defined $value ? $value : 0 ;
282 return 1;
283 }
284 elsif ($type & Parse_signed)
285 {
286 return $self->setError("Parameter '$key' must be a signed int, got 'undef'")
287 if $validate && ! defined $value ;
288 return $self->setError("Parameter '$key' must be a signed int, got '$value'")
289 if $validate && $value !~ /^-?\d+$/;
290
291 $$output = defined $value ? $value : 0 ;
292 return 1 ;
293 }
294 elsif ($type & Parse_boolean)
295 {
296 return $self->setError("Parameter '$key' must be an int, got '$value'")
297 if $validate && defined $value && $value !~ /^\d*$/;
298 $$output = defined $value ? $value != 0 : 0 ;
299 return 1;
300 }
301 elsif ($type & Parse_string)
302 {
303 $$output = defined $value ? $value : "" ;
304 return 1;
305 }
306
307 $$output = $value ;
308 return 1;
309}
310
311
312
313sub Compress::Raw::Zlib::Parameters::parsed
314{
315 my $self = shift ;
316 my $name = shift ;
317
318 return $self->{Got}{lc $name}[OFF_PARSED] ;
319}
320
321sub Compress::Raw::Zlib::Parameters::value
322{
323 my $self = shift ;
324 my $name = shift ;
325
326 if (@_)
327 {
328 $self->{Got}{lc $name}[OFF_PARSED] = 1;
329 $self->{Got}{lc $name}[OFF_DEFAULT] = $_[0] ;
330 $self->{Got}{lc $name}[OFF_FIXED] = $_[0] ;
331 }
332
333 return $self->{Got}{lc $name}[OFF_FIXED] ;
334}
335
336sub Compress::Raw::Zlib::Deflate::new
337{
338 my $pkg = shift ;
339 my ($got) = ParseParameters(0,
340 {
341 'AppendOutput' => [1, 1, Parse_boolean, 0],
342 'CRC32' => [1, 1, Parse_boolean, 0],
343 'ADLER32' => [1, 1, Parse_boolean, 0],
344 'Bufsize' => [1, 1, Parse_unsigned, 4096],
345
346 'Level' => [1, 1, Parse_signed, Z_DEFAULT_COMPRESSION()],
347 'Method' => [1, 1, Parse_unsigned, Z_DEFLATED()],
348 'WindowBits' => [1, 1, Parse_signed, MAX_WBITS()],
349 'MemLevel' => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()],
350 'Strategy' => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()],
351 'Dictionary' => [1, 1, Parse_any, ""],
352 }, @_) ;
353
354
355 croak "Compress::Raw::Zlib::Deflate::new: Bufsize must be >= 1, you specified " .
356 $got->value('Bufsize')
357 unless $got->value('Bufsize') >= 1;
358
359 my $flags = 0 ;
360 $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
361 $flags |= FLAG_CRC if $got->value('CRC32') ;
362 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
363
364 _deflateInit($flags,
365 $got->value('Level'),
366 $got->value('Method'),
367 $got->value('WindowBits'),
368 $got->value('MemLevel'),
369 $got->value('Strategy'),
370 $got->value('Bufsize'),
371 $got->value('Dictionary')) ;
372
373}
374
375sub Compress::Raw::Zlib::Inflate::new
376{
377 my $pkg = shift ;
378 my ($got) = ParseParameters(0,
379 {
380 'AppendOutput' => [1, 1, Parse_boolean, 0],
381 'CRC32' => [1, 1, Parse_boolean, 0],
382 'ADLER32' => [1, 1, Parse_boolean, 0],
383 'ConsumeInput' => [1, 1, Parse_boolean, 1],
384 'Bufsize' => [1, 1, Parse_unsigned, 4096],
385
386 'WindowBits' => [1, 1, Parse_signed, MAX_WBITS()],
387 'Dictionary' => [1, 1, Parse_any, ""],
388 }, @_) ;
389
390
391 croak "Compress::Raw::Zlib::Inflate::new: Bufsize must be >= 1, you specified " .
392 $got->value('Bufsize')
393 unless $got->value('Bufsize') >= 1;
394
395 my $flags = 0 ;
396 $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
397 $flags |= FLAG_CRC if $got->value('CRC32') ;
398 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
399 $flags |= FLAG_CONSUME_INPUT if $got->value('ConsumeInput') ;
400
401 _inflateInit($flags, $got->value('WindowBits'), $got->value('Bufsize'),
402 $got->value('Dictionary')) ;
403}
404
405sub Compress::Raw::Zlib::InflateScan::new
406{
407 my $pkg = shift ;
408 my ($got) = ParseParameters(0,
409 {
410 'CRC32' => [1, 1, Parse_boolean, 0],
411 'ADLER32' => [1, 1, Parse_boolean, 0],
412 'Bufsize' => [1, 1, Parse_unsigned, 4096],
413
414 'WindowBits' => [1, 1, Parse_signed, -MAX_WBITS()],
415 'Dictionary' => [1, 1, Parse_any, ""],
416 }, @_) ;
417
418
419 croak "Compress::Raw::Zlib::InflateScan::new: Bufsize must be >= 1, you specified " .
420 $got->value('Bufsize')
421 unless $got->value('Bufsize') >= 1;
422
423 my $flags = 0 ;
424 #$flags |= FLAG_APPEND if $got->value('AppendOutput') ;
425 $flags |= FLAG_CRC if $got->value('CRC32') ;
426 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
427 #$flags |= FLAG_CONSUME_INPUT if $got->value('ConsumeInput') ;
428
429 _inflateScanInit($flags, $got->value('WindowBits'), $got->value('Bufsize'),
430 '') ;
431}
432
433sub Compress::Raw::Zlib::inflateScanStream::createDeflateStream
434{
435 my $pkg = shift ;
436 my ($got) = ParseParameters(0,
437 {
438 'AppendOutput' => [1, 1, Parse_boolean, 0],
439 'CRC32' => [1, 1, Parse_boolean, 0],
440 'ADLER32' => [1, 1, Parse_boolean, 0],
441 'Bufsize' => [1, 1, Parse_unsigned, 4096],
442
443 'Level' => [1, 1, Parse_signed, Z_DEFAULT_COMPRESSION()],
444 'Method' => [1, 1, Parse_unsigned, Z_DEFLATED()],
445 'WindowBits' => [1, 1, Parse_signed, - MAX_WBITS()],
446 'MemLevel' => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()],
447 'Strategy' => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()],
448 }, @_) ;
449
450 croak "Compress::Raw::Zlib::InflateScan::createDeflateStream: Bufsize must be >= 1, you specified " .
451 $got->value('Bufsize')
452 unless $got->value('Bufsize') >= 1;
453
454 my $flags = 0 ;
455 $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
456 $flags |= FLAG_CRC if $got->value('CRC32') ;
457 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
458
459 $pkg->_createDeflateStream($flags,
460 $got->value('Level'),
461 $got->value('Method'),
462 $got->value('WindowBits'),
463 $got->value('MemLevel'),
464 $got->value('Strategy'),
465 $got->value('Bufsize'),
466 ) ;
467
468}
469
470sub Compress::Raw::Zlib::inflateScanStream::inflate
471{
472 my $self = shift ;
473 my $buffer = $_[1];
474 my $eof = $_[2];
475
476 my $status = $self->scan(@_);
477
478 if ($status == Z_OK() && $_[2]) {
479 my $byte = ' ';
480
481 $status = $self->scan(\$byte, $_[1]) ;
482 }
483
484 return $status ;
485}
486
487sub Compress::Raw::Zlib::deflateStream::deflateParams
488{
489 my $self = shift ;
490 my ($got) = ParseParameters(0, {
491 'Level' => [1, 1, Parse_signed, undef],
492 'Strategy' => [1, 1, Parse_unsigned, undef],
493 'Bufsize' => [1, 1, Parse_unsigned, undef],
494 },
495 @_) ;
496
497 croak "Compress::Raw::Zlib::deflateParams needs Level and/or Strategy"
498 unless $got->parsed('Level') + $got->parsed('Strategy') +
499 $got->parsed('Bufsize');
500
501 croak "Compress::Raw::Zlib::Inflate::deflateParams: Bufsize must be >= 1, you specified " .
502 $got->value('Bufsize')
503 if $got->parsed('Bufsize') && $got->value('Bufsize') <= 1;
504
505 my $flags = 0;
506 $flags |= 1 if $got->parsed('Level') ;
507 $flags |= 2 if $got->parsed('Strategy') ;
508 $flags |= 4 if $got->parsed('Bufsize') ;
509
510 $self->_deflateParams($flags, $got->value('Level'),
511 $got->value('Strategy'), $got->value('Bufsize'));
512
513}
514
515
516# Autoload methods go after __END__, and are processed by the autosplit program.
517
518144µs1;
519__END__
520
521
522=head1 NAME
523
524Compress::Raw::Zlib - Low-Level Interface to zlib compression library
525
526=head1 SYNOPSIS
527
528 use Compress::Raw::Zlib ;
529
530 ($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) ;
531 $status = $d->deflate($input, $output) ;
532 $status = $d->flush($output [, $flush_type]) ;
533 $d->deflateParams(OPTS) ;
534 $d->deflateTune(OPTS) ;
535 $d->dict_adler() ;
536 $d->crc32() ;
537 $d->adler32() ;
538 $d->total_in() ;
539 $d->total_out() ;
540 $d->msg() ;
541 $d->get_Strategy();
542 $d->get_Level();
543 $d->get_BufSize();
544
545 ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) ;
546 $status = $i->inflate($input, $output [, $eof]) ;
547 $status = $i->inflateSync($input) ;
548 $i->dict_adler() ;
549 $d->crc32() ;
550 $d->adler32() ;
551 $i->total_in() ;
552 $i->total_out() ;
553 $i->msg() ;
554 $d->get_BufSize();
555
556 $crc = adler32($buffer [,$crc]) ;
557 $crc = crc32($buffer [,$crc]) ;
558
559 $crc = adler32_combine($crc1, $crc2, $len2)l
560 $crc = crc32_combine($adler1, $adler2, $len2)
561
562 ZLIB_VERSION
563 ZLIB_VERNUM
564
565=head1 DESCRIPTION
566
567The I<Compress::Raw::Zlib> module provides a Perl interface to the I<zlib>
568compression library (see L</AUTHOR> for details about where to get
569I<zlib>).
570
571
572
573=head1 Compress::Raw::Zlib::Deflate
574
575This section defines an interface that allows in-memory compression using
576the I<deflate> interface provided by zlib.
577
578Here is a definition of the interface available:
579
580
581=head2 B<($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) >
582
583Initialises a deflation object.
584
585If you are familiar with the I<zlib> library, it combines the
586features of the I<zlib> functions C<deflateInit>, C<deflateInit2>
587and C<deflateSetDictionary>.
588
589If successful, it will return the initialised deflation object, C<$d>
590and a C<$status> of C<Z_OK> in a list context. In scalar context it
591returns the deflation object, C<$d>, only.
592
593If not successful, the returned deflation object, C<$d>, will be
594I<undef> and C<$status> will hold the a I<zlib> error code.
595
596The function optionally takes a number of named options specified as
597C<< Name => value >> pairs. This allows individual options to be
598tailored without having to specify them all in the parameter list.
599
600For backward compatibility, it is also possible to pass the parameters
601as a reference to a hash containing the name=>value pairs.
602
603Below is a list of the valid options:
604
605=over 5
606
607=item B<-Level>
608
609Defines the compression level. Valid values are 0 through 9,
610C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
611C<Z_DEFAULT_COMPRESSION>.
612
613The default is Z_DEFAULT_COMPRESSION.
614
615=item B<-Method>
616
617Defines the compression method. The only valid value at present (and
618the default) is Z_DEFLATED.
619
620=item B<-WindowBits>
621
622For a definition of the meaning and valid values for C<WindowBits>
623refer to the I<zlib> documentation for I<deflateInit2>.
624
625Defaults to MAX_WBITS.
626
627=item B<-MemLevel>
628
629For a definition of the meaning and valid values for C<MemLevel>
630refer to the I<zlib> documentation for I<deflateInit2>.
631
632Defaults to MAX_MEM_LEVEL.
633
634=item B<-Strategy>
635
636Defines the strategy used to tune the compression. The valid values are
637C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED>, C<Z_RLE>, C<Z_FIXED> and
638C<Z_HUFFMAN_ONLY>.
639
640The default is Z_DEFAULT_STRATEGY.
641
642=item B<-Dictionary>
643
644When a dictionary is specified I<Compress::Raw::Zlib> will automatically
645call C<deflateSetDictionary> directly after calling C<deflateInit>. The
646Adler32 value for the dictionary can be obtained by calling the method
647C<$d-E<gt>dict_adler()>.
648
649The default is no dictionary.
650
651=item B<-Bufsize>
652
653Sets the initial size for the output buffer used by the C<$d-E<gt>deflate>
654and C<$d-E<gt>flush> methods. If the buffer has to be
655reallocated to increase the size, it will grow in increments of
656C<Bufsize>.
657
658The default buffer size is 4096.
659
660=item B<-AppendOutput>
661
662This option controls how data is written to the output buffer by the
663C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods.
664
665If the C<AppendOutput> option is set to false, the output buffers in the
666C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods will be truncated before
667uncompressed data is written to them.
668
669If the option is set to true, uncompressed data will be appended to the
670output buffer in the C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods.
671
672This option defaults to false.
673
674=item B<-CRC32>
675
676If set to true, a crc32 checksum of the uncompressed data will be
677calculated. Use the C<$d-E<gt>crc32> method to retrieve this value.
678
679This option defaults to false.
680
681
682=item B<-ADLER32>
683
684If set to true, an adler32 checksum of the uncompressed data will be
685calculated. Use the C<$d-E<gt>adler32> method to retrieve this value.
686
687This option defaults to false.
688
689
690=back
691
692Here is an example of using the C<Compress::Raw::Zlib::Deflate> optional
693parameter list to override the default buffer size and compression
694level. All other options will take their default values.
695
696 my $d = new Compress::Raw::Zlib::Deflate ( -Bufsize => 300,
697 -Level => Z_BEST_SPEED ) ;
698
699
700=head2 B<$status = $d-E<gt>deflate($input, $output)>
701
702Deflates the contents of C<$input> and writes the compressed data to
703C<$output>.
704
705The C<$input> and C<$output> parameters can be either scalars or scalar
706references.
707
708When finished, C<$input> will be completely processed (assuming there
709were no errors). If the deflation was successful it writes the deflated
710data to C<$output> and returns a status value of C<Z_OK>.
711
712On error, it returns a I<zlib> error code.
713
714If the C<AppendOutput> option is set to true in the constructor for
715the C<$d> object, the compressed data will be appended to C<$output>. If
716it is false, C<$output> will be truncated before any compressed data is
717written to it.
718
719B<Note>: This method will not necessarily write compressed data to
720C<$output> every time it is called. So do not assume that there has been
721an error if the contents of C<$output> is empty on returning from
722this method. As long as the return code from the method is C<Z_OK>,
723the deflate has succeeded.
724
725=head2 B<$status = $d-E<gt>flush($output [, $flush_type]) >
726
727Typically used to finish the deflation. Any pending output will be
728written to C<$output>.
729
730Returns C<Z_OK> if successful.
731
732Note that flushing can seriously degrade the compression ratio, so it
733should only be used to terminate a decompression (using C<Z_FINISH>) or
734when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
735
736By default the C<flush_type> used is C<Z_FINISH>. Other valid values
737for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
738and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
739C<flush_type> parameter if you fully understand the implications of
740what it does. See the C<zlib> documentation for details.
741
742If the C<AppendOutput> option is set to true in the constructor for
743the C<$d> object, the compressed data will be appended to C<$output>. If
744it is false, C<$output> will be truncated before any compressed data is
745written to it.
746
747=head2 B<$status = $d-E<gt>deflateParams([OPT])>
748
749Change settings for the deflate object C<$d>.
750
751The list of the valid options is shown below. Options not specified
752will remain unchanged.
753
754
755=over 5
756
757=item B<-Level>
758
759Defines the compression level. Valid values are 0 through 9,
760C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
761C<Z_DEFAULT_COMPRESSION>.
762
763=item B<-Strategy>
764
765Defines the strategy used to tune the compression. The valid values are
766C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
767
768=item B<-BufSize>
769
770Sets the initial size for the output buffer used by the C<$d-E<gt>deflate>
771and C<$d-E<gt>flush> methods. If the buffer has to be
772reallocated to increase the size, it will grow in increments of
773C<Bufsize>.
774
775
776=back
777
778=head2 B<$status = $d-E<gt>deflateTune($good_length, $max_lazy, $nice_length, $max_chain)>
779
780Tune the internal settings for the deflate object C<$d>. This option is
781only available if you are running zlib 1.2.2.3 or better.
782
783Refer to the documentation in zlib.h for instructions on how to fly
784C<deflateTune>.
785
786=head2 B<$d-E<gt>dict_adler()>
787
788Returns the adler32 value for the dictionary.
789
790=head2 B<$d-E<gt>crc32()>
791
792Returns the crc32 value for the uncompressed data to date.
793
794If the C<CRC32> option is not enabled in the constructor for this object,
795this method will always return 0;
796
797=head2 B<$d-E<gt>adler32()>
798
799Returns the adler32 value for the uncompressed data to date.
800
801=head2 B<$d-E<gt>msg()>
802
803Returns the last error message generated by zlib.
804
805=head2 B<$d-E<gt>total_in()>
806
807Returns the total number of bytes uncompressed bytes input to deflate.
808
809=head2 B<$d-E<gt>total_out()>
810
811Returns the total number of compressed bytes output from deflate.
812
813=head2 B<$d-E<gt>get_Strategy()>
814
815Returns the deflation strategy currently used. Valid values are
816C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
817
818
819=head2 B<$d-E<gt>get_Level()>
820
821Returns the compression level being used.
822
823=head2 B<$d-E<gt>get_BufSize()>
824
825Returns the buffer size used to carry out the compression.
826
827=head2 Example
828
829
830Here is a trivial example of using C<deflate>. It simply reads standard
831input, deflates it and writes it to standard output.
832
833 use strict ;
834 use warnings ;
835
836 use Compress::Raw::Zlib ;
837
838 binmode STDIN;
839 binmode STDOUT;
840 my $x = new Compress::Raw::Zlib::Deflate
841 or die "Cannot create a deflation stream\n" ;
842
843 my ($output, $status) ;
844 while (<>)
845 {
846 $status = $x->deflate($_, $output) ;
847
848 $status == Z_OK
849 or die "deflation failed\n" ;
850
851 print $output ;
852 }
853
854 $status = $x->flush($output) ;
855
856 $status == Z_OK
857 or die "deflation failed\n" ;
858
859 print $output ;
860
861=head1 Compress::Raw::Zlib::Inflate
862
863This section defines an interface that allows in-memory uncompression using
864the I<inflate> interface provided by zlib.
865
866Here is a definition of the interface:
867
868
869=head2 B< ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) >
870
871Initialises an inflation object.
872
873In a list context it returns the inflation object, C<$i>, and the
874I<zlib> status code (C<$status>). In a scalar context it returns the
875inflation object only.
876
877If successful, C<$i> will hold the inflation object and C<$status> will
878be C<Z_OK>.
879
880If not successful, C<$i> will be I<undef> and C<$status> will hold the
881I<zlib> error code.
882
883The function optionally takes a number of named options specified as
884C<< -Name => value >> pairs. This allows individual options to be
885tailored without having to specify them all in the parameter list.
886
887For backward compatibility, it is also possible to pass the parameters
888as a reference to a hash containing the C<< name=>value >> pairs.
889
890Here is a list of the valid options:
891
892=over 5
893
894=item B<-WindowBits>
895
896To uncompress an RFC 1950 data stream, set C<WindowBits> to a positive
897number.
898
899To uncompress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
900
901For a full definition of the meaning and valid values for C<WindowBits>
902refer to the I<zlib> documentation for I<inflateInit2>.
903
904Defaults to MAX_WBITS.
905
906=item B<-Bufsize>
907
908Sets the initial size for the output buffer used by the C<$i-E<gt>inflate>
909method. If the output buffer in this method has to be reallocated to
910increase the size, it will grow in increments of C<Bufsize>.
911
912Default is 4096.
913
914=item B<-Dictionary>
915
916The default is no dictionary.
917
918=item B<-AppendOutput>
919
920This option controls how data is written to the output buffer by the
921C<$i-E<gt>inflate> method.
922
923If the option is set to false, the output buffer in the C<$i-E<gt>inflate>
924method will be truncated before uncompressed data is written to it.
925
926If the option is set to true, uncompressed data will be appended to the
927output buffer by the C<$i-E<gt>inflate> method.
928
929This option defaults to false.
930
931
932=item B<-CRC32>
933
934If set to true, a crc32 checksum of the uncompressed data will be
935calculated. Use the C<$i-E<gt>crc32> method to retrieve this value.
936
937This option defaults to false.
938
939=item B<-ADLER32>
940
941If set to true, an adler32 checksum of the uncompressed data will be
942calculated. Use the C<$i-E<gt>adler32> method to retrieve this value.
943
944This option defaults to false.
945
946=item B<-ConsumeInput>
947
948If set to true, this option will remove compressed data from the input
949buffer of the the C< $i-E<gt>inflate > method as the inflate progresses.
950
951This option can be useful when you are processing compressed data that is
952embedded in another file/buffer. In this case the data that immediately
953follows the compressed stream will be left in the input buffer.
954
955This option defaults to true.
956
957=back
958
959Here is an example of using an optional parameter to override the default
960buffer size.
961
962 my ($i, $status) = new Compress::Raw::Zlib::Inflate( -Bufsize => 300 ) ;
963
964=head2 B< $status = $i-E<gt>inflate($input, $output [,$eof]) >
965
966Inflates the complete contents of C<$input> and writes the uncompressed
967data to C<$output>. The C<$input> and C<$output> parameters can either be
968scalars or scalar references.
969
970Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
971compressed data has been successfully reached.
972
973If not successful C<$status> will hold the I<zlib> error code.
974
975If the C<ConsumeInput> option has been set to true when the
976C<Compress::Raw::Zlib::Inflate> object is created, the C<$input> parameter
977is modified by C<inflate>. On completion it will contain what remains
978of the input buffer after inflation. In practice, this means that when
979the return status is C<Z_OK> the C<$input> parameter will contain an
980empty string, and when the return status is C<Z_STREAM_END> the C<$input>
981parameter will contains what (if anything) was stored in the input buffer
982after the deflated data stream.
983
984This feature is useful when processing a file format that encapsulates
985a compressed data stream (e.g. gzip, zip) and there is useful data
986immediately after the deflation stream.
987
988If the C<AppendOutput> option is set to true in the constructor for
989this object, the uncompressed data will be appended to C<$output>. If
990it is false, C<$output> will be truncated before any uncompressed data
991is written to it.
992
993The C<$eof> parameter needs a bit of explanation.
994
995Prior to version 1.2.0, zlib assumed that there was at least one trailing
996byte immediately after the compressed data stream when it was carrying out
997decompression. This normally isn't a problem because the majority of zlib
998applications guarantee that there will be data directly after the
999compressed data stream. For example, both gzip (RFC 1950) and zip both
1000define trailing data that follows the compressed data stream.
1001
1002The C<$eof> parameter only needs to be used if B<all> of the following
1003conditions apply
1004
1005=over 5
1006
1007=item 1
1008
1009You are either using a copy of zlib that is older than version 1.2.0 or you
1010want your application code to be able to run with as many different
1011versions of zlib as possible.
1012
1013=item 2
1014
1015You have set the C<WindowBits> parameter to C<-MAX_WBITS> in the constructor
1016for this object, i.e. you are uncompressing a raw deflated data stream
1017(RFC 1951).
1018
1019=item 3
1020
1021There is no data immediately after the compressed data stream.
1022
1023=back
1024
1025If B<all> of these are the case, then you need to set the C<$eof> parameter
1026to true on the final call (and only the final call) to C<$i-E<gt>inflate>.
1027
1028If you have built this module with zlib >= 1.2.0, the C<$eof> parameter is
1029ignored. You can still set it if you want, but it won't be used behind the
1030scenes.
1031
1032=head2 B<$status = $i-E<gt>inflateSync($input)>
1033
1034This method can be used to attempt to recover good data from a compressed
1035data stream that is partially corrupt.
1036It scans C<$input> until it reaches either a I<full flush point> or the
1037end of the buffer.
1038
1039If a I<full flush point> is found, C<Z_OK> is returned and C<$input>
1040will be have all data up to the flush point removed. This data can then be
1041passed to the C<$i-E<gt>inflate> method to be uncompressed.
1042
1043Any other return code means that a flush point was not found. If more
1044data is available, C<inflateSync> can be called repeatedly with more
1045compressed data until the flush point is found.
1046
1047Note I<full flush points> are not present by default in compressed
1048data streams. They must have been added explicitly when the data stream
1049was created by calling C<Compress::Deflate::flush> with C<Z_FULL_FLUSH>.
1050
1051
1052=head2 B<$i-E<gt>dict_adler()>
1053
1054Returns the adler32 value for the dictionary.
1055
1056=head2 B<$i-E<gt>crc32()>
1057
1058Returns the crc32 value for the uncompressed data to date.
1059
1060If the C<CRC32> option is not enabled in the constructor for this object,
1061this method will always return 0;
1062
1063=head2 B<$i-E<gt>adler32()>
1064
1065Returns the adler32 value for the uncompressed data to date.
1066
1067If the C<ADLER32> option is not enabled in the constructor for this object,
1068this method will always return 0;
1069
1070=head2 B<$i-E<gt>msg()>
1071
1072Returns the last error message generated by zlib.
1073
1074=head2 B<$i-E<gt>total_in()>
1075
1076Returns the total number of bytes compressed bytes input to inflate.
1077
1078=head2 B<$i-E<gt>total_out()>
1079
1080Returns the total number of uncompressed bytes output from inflate.
1081
1082=head2 B<$d-E<gt>get_BufSize()>
1083
1084Returns the buffer size used to carry out the decompression.
1085
1086=head2 Example
1087
1088Here is an example of using C<inflate>.
1089
1090 use strict ;
1091 use warnings ;
1092
1093 use Compress::Raw::Zlib;
1094
1095 my $x = new Compress::Raw::Zlib::Inflate()
1096 or die "Cannot create a inflation stream\n" ;
1097
1098 my $input = '' ;
1099 binmode STDIN;
1100 binmode STDOUT;
1101
1102 my ($output, $status) ;
1103 while (read(STDIN, $input, 4096))
1104 {
1105 $status = $x->inflate(\$input, $output) ;
1106
1107 print $output
1108 if $status == Z_OK or $status == Z_STREAM_END ;
1109
1110 last if $status != Z_OK ;
1111 }
1112
1113 die "inflation failed\n"
1114 unless $status == Z_STREAM_END ;
1115
1116=head1 CHECKSUM FUNCTIONS
1117
1118Two functions are provided by I<zlib> to calculate checksums. For the
1119Perl interface, the order of the two parameters in both functions has
1120been reversed. This allows both running checksums and one off
1121calculations to be done.
1122
1123 $crc = adler32($buffer [,$crc]) ;
1124 $crc = crc32($buffer [,$crc]) ;
1125
1126The buffer parameters can either be a scalar or a scalar reference.
1127
1128If the $crc parameters is C<undef>, the crc value will be reset.
1129
1130If you have built this module with zlib 1.2.3 or better, two more
1131CRC-related functions are available.
1132
1133 $crc = adler32_combine($crc1, $crc2, $len2)l
1134 $crc = crc32_combine($adler1, $adler2, $len2)
1135
1136These functions allow checksums to be merged.
1137
1138=head1 ACCESSING ZIP FILES
1139
1140Although it is possible (with some effort on your part) to use this
1141module to access .zip files, there is a module on CPAN that will do all
1142the hard work for you. Check out the C<Archive::Zip> module on CPAN at
1143
1144 http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz
1145
1146
1147=head1 CONSTANTS
1148
1149All the I<zlib> constants are automatically imported when you make use
1150of I<Compress::Raw::Zlib>.
1151
1152
1153=head1 SEE ALSO
1154
1155L<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>
1156
1157L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1158
1159L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1160L<Archive::Tar|Archive::Tar>,
1161L<IO::Zlib|IO::Zlib>
1162
1163
1164For RFC 1950, 1951 and 1952 see
1165F<http://www.faqs.org/rfcs/rfc1950.html>,
1166F<http://www.faqs.org/rfcs/rfc1951.html> and
1167F<http://www.faqs.org/rfcs/rfc1952.html>
1168
1169The I<zlib> compression library was written by Jean-loup Gailly
1170F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1171
1172The primary site for the I<zlib> compression library is
1173F<http://www.zlib.org>.
1174
1175The primary site for gzip is F<http://www.gzip.org>.
1176
1177
1178
1179
1180=head1 AUTHOR
1181
1182This module was written by Paul Marquess, F<pmqs@cpan.org>.
1183
1184
1185
1186=head1 MODIFICATION HISTORY
1187
1188See the Changes file.
1189
1190=head1 COPYRIGHT AND LICENSE
1191
1192Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
1193
1194This program is free software; you can redistribute it and/or
1195modify it under the same terms as Perl itself.
1196
1197
1198