Tweaks to get Test::Builder::Tester's tests to work in the core.

[p5sagit/p5-mst-13.2.git] / lib / Digest.pm

diff --git a/lib/Digest.pm b/lib/Digest.pm
index c0e9cc1..e3448ae 100644 (file)
--- a/lib/Digest.pm
+++ b/lib/Digest.pm
@@ -3,15 +3,19 @@ package Digest;
 use strict;
 use vars qw($VERSION %MMAP $AUTOLOAD);
 
-$VERSION = "1.03";
+$VERSION = "1.12";
 
 %MMAP = (
   "SHA-1"      => ["Digest::SHA1", ["Digest::SHA", 1], ["Digest::SHA2", 1]],
+  "SHA-224"    => [["Digest::SHA", 224]],
   "SHA-256"    => [["Digest::SHA", 256], ["Digest::SHA2", 256]],
   "SHA-384"    => [["Digest::SHA", 384], ["Digest::SHA2", 384]],
   "SHA-512"    => [["Digest::SHA", 512], ["Digest::SHA2", 512]],
   "HMAC-MD5"   => "Digest::HMAC_MD5",
   "HMAC-SHA-1" => "Digest::HMAC_SHA1",
+  "CRC-16"     => [["Digest::CRC", type => "crc16"]],
+  "CRC-32"     => [["Digest::CRC", type => "crc32"]],
+  "CRC-CCITT"  => [["Digest::CRC", type => "crcccitt"]],
 );
 
 sub new
@@ -54,15 +58,15 @@ __END__
 
 =head1 NAME
 
-Digest:: - Modules that calculate message digests
+Digest - Modules that calculate message digests
 
 =head1 SYNOPSIS
 
-  $md2 = Digest->MD2;
-  $md5 = Digest->MD5;
-
-  $sha1 = Digest->SHA1;
+  $md5  = Digest->new("MD5");
   $sha1 = Digest->new("SHA-1");
+  $sha256 = Digest->new("SHA-256");
+  $sha384 = Digest->new("SHA-384");
+  $sha512 = Digest->new("SHA-512");
 
   $hmac = Digest->HMAC_MD5($key);
 
@@ -97,7 +101,7 @@ or embedding in places that can't handle arbitrary data.
 
 =item I<hex>
 
-A twice as long string of (lowercase) hexadecimal digits.
+A twice as long string of lowercase hexadecimal digits.
 
 =item I<base64>
 
@@ -139,7 +143,8 @@ name of the digest algorithm you want to use.
 The two first forms are simply syntactic sugar which automatically
 load the right module on first use.  The second form allow you to use
 algorithm names which contains letters which are not legal perl
-identifiers, e.g. "SHA-1".
+identifiers, e.g. "SHA-1".  If no implementation for the given algorithm
+can be found, then an exception is raised.
 
 If new() is called as an instance method (i.e. $ctx->new) it will just
 reset the state the object to the state of a newly created object.  No
@@ -155,20 +160,20 @@ a reference to the copy.
 
 This is just an alias for $ctx->new.
 
-=item $ctx->add($data,...)
+=item $ctx->add( $data, ... )
 
 The $data provided as argument are appended to the message we
 calculate the digest for.  The return value is the $ctx object itself.
 
-=item $ctx->addfile($io_handle)
+=item $ctx->addfile( $io_handle )
 
 The $io_handle is read until EOF and the content is appended to the
 message we calculate the digest for.  The return value is the $ctx
 object itself.
 
-=item $ctx->add_bits($data, $nbits)
+=item $ctx->add_bits( $data, $nbits )
 
-=item $ctx->add_bits($bitstring)
+=item $ctx->add_bits( $bitstring )
 
 The bits provided are appended to the message we calculate the digest
 for.  The return value is the $ctx object itself.
@@ -200,7 +205,7 @@ Note that the C<digest> operation is effectively a destructive,
 read-once operation. Once it has been performed, the $ctx object is
 automatically C<reset> and can be used to calculate another digest
 value.  Call $ctx->clone->digest if you want to calculate the digest
-without reseting the digest state.
+without resetting the digest state.
 
 =item $ctx->hexdigest
 
@@ -213,9 +218,46 @@ string.
 
 =back
 
+=head1 Digest speed
+
+This table should give some indication on the relative speed of
+different algorithms.  It is sorted by throughput based on a benchmark
+done with of some implementations of this API:
+
+ Algorithm      Size    Implementation                  MB/s
+
+ MD4            128     Digest::MD4 v1.3               165.0
+ MD5            128     Digest::MD5 v2.33               98.8
+ SHA-256        256     Digest::SHA2 v1.1.0             66.7
+ SHA-1          160     Digest::SHA v4.3.1              58.9
+ SHA-1          160     Digest::SHA1 v2.10              48.8
+ SHA-256        256     Digest::SHA v4.3.1              41.3
+ Haval-256      256     Digest::Haval256 v1.0.4         39.8
+ SHA-384        384     Digest::SHA2 v1.1.0             19.6
+ SHA-512        512     Digest::SHA2 v1.1.0             19.3
+ SHA-384        384     Digest::SHA v4.3.1              19.2
+ SHA-512        512     Digest::SHA v4.3.1              19.2
+ Whirlpool      512     Digest::Whirlpool v1.0.2        13.0
+ MD2            128     Digest::MD2 v2.03                9.5
+
+ Adler-32        32     Digest::Adler32 v0.03            1.3
+ CRC-16          16     Digest::CRC v0.05                1.1
+ CRC-32          32     Digest::CRC v0.05                1.1
+ MD5            128     Digest::Perl::MD5 v1.5           1.0
+ CRC-CCITT       16     Digest::CRC v0.05                0.8
+
+These numbers was achieved Apr 2004 with ActivePerl-5.8.3 running
+under Linux on a P4 2.8 GHz CPU.  The last 5 entries differ by being
+pure perl implementations of the algorithms, which explains why they
+are so slow.
+
 =head1 SEE ALSO
 
-L<Digest::MD5>, L<Digest::SHA1>, L<Digest::HMAC>, L<Digest::MD2>
+L<Digest::Adler32>, L<Digest::CRC>, L<Digest::Haval256>,
+L<Digest::HMAC>, L<Digest::MD2>, L<Digest::MD4>, L<Digest::MD5>,
+L<Digest::SHA>, L<Digest::SHA1>, L<Digest::SHA2>, L<Digest::Whirlpool>
+
+New digest implementations should consider subclassing from L<Digest::base>.
 
 L<MIME::Base64>
 
@@ -226,4 +268,10 @@ Gisle Aas <gisle@aas.no>
 The C<Digest::> interface is based on the interface originally
 developed by Neil Winton for his C<MD5> module.
 
+This library is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+    Copyright 1998-2001,2003-2004 Gisle Aas.
+    Copyright 1995-1996 Neil Winton.
+
 =cut