[PATCHES] various small Math::BigInt et. al. fixes

[perl5.git] / lib / Digest.pm

diff --git a/lib/Digest.pm b/lib/Digest.pm
index e3448ae..98102ae 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.12";
+$VERSION = "1.15";
 
 %MMAP = (
   "SHA-1"      => ["Digest::SHA1", ["Digest::SHA", 1], ["Digest::SHA2", 1]],
@@ -80,11 +80,18 @@ bytes or bits.
 
 An important property of the digest algorithms is that the digest is
 I<likely> to change if the message change in some way.  Another
-property is that digest functions are one-way functions, i.e. it
+property is that digest functions are one-way functions, that is it
 should be I<hard> to find a message that correspond to some given
 digest.  Algorithms differ in how "likely" and how "hard", as well as
 how efficient they are to compute.
 
+Note that the properties of the algorithms change over time, as the
+algorithms are analyzed and machines grow faster.  If your application
+for instance depends on it being "impossible" to generate the same
+digest for a different message it is wise to make it easy to plug in
+stronger algorithms as the one used grow weaker.  Using the interface
+documented here should make it easy to change algorithms later.
+
 All C<Digest::> modules provide the same programming interface.  A
 functional interface for simple use, as well as an object oriented
 interface that can handle messages of arbitrary length and which can
@@ -160,10 +167,26 @@ a reference to the copy.
 
 This is just an alias for $ctx->new.
 
-=item $ctx->add( $data, ... )
+=item $ctx->add( $data )
+
+=item $ctx->add( $chunk1, $chunk2, ... )
+
+The string value of the $data provided as argument is appended to the
+message we calculate the digest for.  The return value is the $ctx
+object itself.
+
+If more arguments are provided then they are all appended to the
+message, thus all these lines will have the same effect on the state
+of the $ctx object:
 
-The $data provided as argument are appended to the message we
-calculate the digest for.  The return value is the $ctx object itself.
+  $ctx->add("a"); $ctx->add("b"); $ctx->add("c");
+  $ctx->add("a")->add("b")->add("c");
+  $ctx->add("a", "b", "c");
+  $ctx->add("abc");
+
+Most algorithms are only defined for strings of bytes and this method
+might therefore croak if the provided arguments contain chars with
+ordinal number above 255.
 
 =item $ctx->addfile( $io_handle )
 
@@ -171,29 +194,42 @@ 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.
 
+The addfile() method will croak() if it fails reading data for some
+reason.  If it croaks it is unpredictable what the state of the $ctx
+object will be in. The addfile() method might have been able to read
+the file partially before it failed.  It is probably wise to discard
+or reset the $ctx object if this occurs.
+
+In most cases you want to make sure that the $io_handle is in
+"binmode" before you pass it as argument to the addfile() method.
+
 =item $ctx->add_bits( $data, $nbits )
 
 =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.
+The add_bits() method is an alternative to add() that allow partial
+bytes to be appended to the message.  Most users should just ignore
+this method as partial bytes is very unlikely to be of any practical
+use.
 
 The two argument form of add_bits() will add the first $nbits bits
-from data.  For the last potentially partial byte only the high order
+from $data.  For the last potentially partial byte only the high order
 C<< $nbits % 8 >> bits are used.  If $nbits is greater than C<<
 length($data) * 8 >>, then this method would do the same as C<<
-$ctx->add($data) >>, i.e. $nbits is silently ignored.
+$ctx->add($data) >>.
 
 The one argument form of add_bits() takes a $bitstring of "1" and "0"
 chars as argument.  It's a shorthand for C<< $ctx->add_bits(pack("B*",
 $bitstring), length($bitstring)) >>.
 
+The return value is the $ctx object itself.
+
 This example shows two calls that should have the same effect:
 
    $ctx->add_bits("111100001010");
    $ctx->add_bits("\xF0\xA0", 12);
 
-Most digest algorithms are byte based.  For those it is not possible
+Most digest algorithms are byte based and for these it is not possible
 to add bits that are not a multiple of 8, and the add_bits() method
 will croak if you try.
 
@@ -261,6 +297,8 @@ New digest implementations should consider subclassing from L<Digest::base>.
 
 L<MIME::Base64>
 
+http://en.wikipedia.org/wiki/Cryptographic_hash_function
+
 =head1 AUTHOR
 
 Gisle Aas <gisle@aas.no>
@@ -271,7 +309,7 @@ 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.
+    Copyright 1998-2006 Gisle Aas.
+    Copyright 1995,1996 Neil Winton.
 
 =cut