Assimilate CGI 3.03

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

diff --git a/lib/Digest.pm b/lib/Digest.pm
index c0e9cc1..9353db1 100644 (file)
--- a/lib/Digest.pm
+++ b/lib/Digest.pm
@@ -3,7 +3,7 @@ package Digest;
 use strict;
 use vars qw($VERSION %MMAP $AUTOLOAD);
 
-$VERSION = "1.03";
+$VERSION = "1.05";
 
 %MMAP = (
   "SHA-1"      => ["Digest::SHA1", ["Digest::SHA", 1], ["Digest::SHA2", 1]],
@@ -54,15 +54,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 +97,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>
 
@@ -155,20 +155,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.
@@ -213,9 +213,41 @@ 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.1                24.9
+ MD5           128     Digest::MD5 v2.30               18.7
+ Haval-256     256     Digest::Haval256 v1.0.4         17.0
+ SHA-1         160     Digest::SHA1 v2.06              15.3
+ SHA-1         160     Digest::SHA v4.0.0              10.1
+ SHA-256       256     Digest::SHA2 v1.0.0              7.6
+ SHA-256       256     Digest::SHA v4.0.0               6.5
+ SHA-384       384     Digest::SHA2 v1.0.0              2.7
+ SHA-384       384     Digest::SHA v4.0.0               2.7
+ SHA-512       512     Digest::SHA2 v1.0.0              2.7
+ SHA-512       512     Digest::SHA v4.0.0               2.7
+ Whirlpool     512     Digest::Whirlpool v1.0.2         1.4
+ MD2           128     Digest::MD2 v2.03                1.1
+
+ Adler-32       32     Digest::Adler32 v0.03            0.2
+ MD5           128     Digest::Perl::MD5 v1.5           0.1
+
+These numbers was achieved Nov 2003 with ActivePerl-5.8.1 running
+under Linux on a P-II 350 MHz CPU.  The last 2 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::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 +258,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 Gisle Aas.
+    Copyright 1995-1996 Neil Winton.
+
 =cut