use strict;
use vars qw($VERSION @ISA @EXPORT_OK);
-$VERSION = '2.16'; # $Date: 2001/09/07 05:45:14 $
+$VERSION = '2.25'; # $Date: 2003/07/05 05:25:37 $
require Exporter;
*import = \&Exporter::import;
=head1 SYNOPSIS
# Functional style
- use Digest::MD5 qw(md5 md5_hex md5_base64);
+ use Digest::MD5 qw(md5 md5_hex md5_base64);
$digest = md5($data);
$digest = md5_hex($data);
use, as well as an object oriented interface that can handle messages
of arbitrary length and which can read files directly.
-A binary digest will be 16 bytes long. A hex digest will be 32
-characters long. A base64 digest will be 22 characters long.
-
=head1 FUNCTIONS
-The following functions can be exported from the C<Digest::MD5>
-module. No functions are exported by default.
+The following functions are provided by the C<Digest::MD5> module.
+None of these functions are exported by default.
=over 4
=item md5($data,...)
This function will concatenate all arguments, calculate the MD5 digest
-of this "message", and return it in binary form.
+of this "message", and return it in binary form. The returned string
+will be 16 bytes long.
+
+The result of md5("a", "b", "c") will be exactly the same as the
+result of md5("abc").
=item md5_hex($data,...)
-Same as md5(), but will return the digest in hexadecimal form.
+Same as md5(), but will return the digest in hexadecimal form. The
+length of the returned string will be 32 and it will only contain
+characters from this set: '0'..'9' and 'a'..'f'.
=item md5_base64($data,...)
Same as md5(), but will return the digest as a base64 encoded string.
+The length of the returned string will be 22 and it will only contain
+characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+' and
+'/'.
-The base64 encoded string returned is not padded to be a multiple of 4
-bytes long. If you want interoperability with other base64 encoded
-md5 digests you might want to append the string "==" to the result.
+Note that the base64 encoded string returned is not padded to be a
+multiple of 4 bytes long. If you want interoperability with other
+base64 encoded md5 digests you might want to append the redundant
+string redundant "==" to the result.
=back
=head1 METHODS
-The following methods are available:
+The object oriented interface to C<Digest::MD5> is described in this
+section. After a C<Digest::MD5> object has been created, you will add
+data to it and finally ask for the digest in a suitable format. A
+single object can be used to calculate multiple digests.
+
+The following methods are provided:
=over 4
=item $md5 = Digest::MD5->new
The constructor returns a new C<Digest::MD5> object which encapsulate
-the state of the MD5 message-digest algorithm. You can add data to
-the object and finally ask for the digest.
+the state of the MD5 message-digest algorithm.
If called as an instance method (i.e. $md5->new) it will just reset the
state the object to the state of a newly created object. No new
This is just an alias for $md5->new.
+=item $md5->clone
+
+This a copy of the $md5 object. It is useful when you do not want to
+destroy the digests state, but need an intermediate value of the
+digest, e.g. when calculating digests iteratively on a continuous data
+stream. Example:
+
+ my $md5 = Digest::MD5->new;
+ while (<>) {
+ $md5->add($_);
+ print "Line $.: ", $md5->clone->hexdigest, "\n";
+ }
+
=item $md5->add($data,...)
The $data provided as argument are appended to the message we
calculate the digest for. The return value is the $md5 object itself.
+All these lines will have the same effect on the state of the $md5
+object:
+
+ $md5->add("a"); $md5->add("b"); $md5->add("c");
+ $md5->add("a")->add("b")->add("c");
+ $md5->add("a", "b", "c");
+ $md5->add("abc");
+
=item $md5->addfile($io_handle)
-The $io_handle is read until EOF and the content is appended to the
+The $io_handle will be read until EOF and its content appended to the
message we calculate the digest for. The return value is the $md5
object itself.
-In most cases you want to make sure that the $io_handle is set up to
-be in binmode().
+The addfile() method will croak() if it fails reading data for some
+reason. If it croaks it is unpredictable what the state of the $md5
+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 $md5 object if this occurs.
+
+In most cases you want to make sure that the $io_handle is in
+C<binmode> before you pass it as argument to the addfile() method.
=item $md5->digest
-Return the binary digest for the message.
+Return the binary digest for the message. The returned string will be
+16 bytes long.
Note that the C<digest> operation is effectively a destructive,
read-once operation. Once it has been performed, the C<Digest::MD5>
object is automatically C<reset> and can be used to calculate another
-digest value.
+digest value. Call $md5->clone->digest if you want to calculate the
+digest without reseting the digest state.
=item $md5->hexdigest
-Same as $md5->digest, but will return the digest in hexadecimal form.
+Same as $md5->digest, but will return the digest in hexadecimal
+form. The length of the returned string will be 32 and it will only
+contain characters from this set: '0'..'9' and 'a'..'f'.
=item $md5->b64digest
Same as $md5->digest, but will return the digest as a base64 encoded
-string.
+string. The length of the returned string will be 22 and it will only
+contain characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+'
+and '/'.
+
The base64 encoded string returned is not padded to be a multiple of 4
bytes long. If you want interoperability with other base64 encoded
use Digest::MD5 qw(md5_hex);
print "Digest is ", md5_hex("foobarbaz"), "\n";
-The above example would print out the message
+The above example would print out the message:
Digest is 6df23dc03f9b54cc38a0fc1483df6e21
-provided that the implementation is working correctly. The same
-checksum can also be calculated in OO style:
+The same checksum can also be calculated in OO style:
use Digest::MD5;
print Digest::MD5->new->addfile(*FILE)->hexdigest, " $file\n";
+Perl 5.8 support Unicode characters in strings. Since the MD5
+algorithm is only defined for strings of bytes, it can not be used on
+strings that contains chars with ordinal number above 255. The MD5
+functions and methods will croak if you try to feed them such input
+data:
+
+ use Digest::MD5 qw(md5_hex);
+
+ my $str = "abc\x{300}";
+ print md5_hex($str), "\n"; # croaks
+ # Wide character in subroutine entry
+
+What you can do is calculate the MD5 checksum of the UTF-8
+representation of such strings. This is achieved by filtering the
+string through encode_utf8() function:
+
+ use Digest::MD5 qw(md5_hex);
+ use Encode qw(encode_utf8);
+
+ my $str = "abc\x{300}";
+ print md5_hex(encode_utf8($str)), "\n";
+ # 8c2d46911f3f5a326455f0ed7a8ed3b3
+
=head1 SEE ALSO
L<Digest>,
This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
- Copyright 1998-2001 Gisle Aas.
+ Copyright 1998-2003 Gisle Aas.
Copyright 1995-1996 Neil Winton.
Copyright 1991-1992 RSA Data Security, Inc.
-The MD5 algorithm is defined in RFC 1321. The basic C code
-implementing the algorithm is derived from that in the RFC and is
-covered by the following copyright:
+The MD5 algorithm is defined in RFC 1321. This implementation is
+derived from the reference C code in RFC 1321 which is covered by
+the following copyright statement:
=over 4
=head1 AUTHORS
-The original MD5 interface was written by Neil Winton
+The original C<MD5> interface was written by Neil Winton
(C<N.Winton@axion.bt.co.uk>).
-This release was made by Gisle Aas <gisle@ActiveState.com>
+The C<Digest::MD5> module is written by Gisle Aas <gisle@ActiveState.com>.
=cut
projects / p5sagit/p5-mst-13.2.git / blobdiff