NAME

       String::CRC::Cksum - Perl extension for calculating checksums in a manner compatible with
       the POSIX cksum program.

SYNOPSIS

       OO style:
         use String::CRC::Cksum;

         $cksum = String::CRC::Cksum->new;
         $cksum1 = $cksum->new;     # clone (clone is reset)

         $cksum->add("string1");
         $cksum->add("string2");
         $cksum->add("string3", "string4", "string5", ...);
         ...
         ($ck, $sz) = $cksum->peek;
         $cksum->add("string6", ...);
         ...
         ($ck, $sz) = $cksum->result;

         $cksum1->addfile(\*file1);     # note: adding many files
         $cksum1->addfile(\*file2);     # is probably a silly thing
         $cksum1->addfile(\*file3);     # to do, but you *could*...
         ...

       Functional style:
         use String::CRC::Cksum qw(cksum);

         $ck = cksum("string1", "string2", ...);

         ($ck, $sz) = cksum("string1", "string2", ...);

         $ck = cksum(\*FILE);

         ($ck, $sz) = cksum(\*FILE);

DESCRIPTION

       The String::CRC::Cksum module calculates a 32 bit CRC, generating the same CRC value as
       the POSIX cksum program.  If called in a list context, returns the length of the data
       object as well, which is useful for fully emulating the cksum program. The returned
       checksum will always be a non-negative integral number in the range 0..2^32-1.

       Despite its name, this module is able to compute the checksum of files as well as of
       strings.  Just pass in a reference to a filehandle, or a reference to any object that can
       respond to a read() call and eventually return 0 at "end of file".

       Beware: consider proper use of binmode() if you are on a non-UNIX platform or processing
       files derived from other platforms.

       The object oriented interface can be used to progressively add data into the checksum
       before yielding the result.

       The functional interface is a convenient way to get a checksum of a single data item.

       None of the routines make local copies of passed-in strings so you can safely Cksum large
       strings safe in the knowledge that there won't be any memory issues.

       Passing in multiple files is acceptable, but perhaps of questionable value.  However I
       don't want to hamper your creativity...

FUNCTIONS

       The following functions are provided by the "String::CRC::Cksum" module.  None of these
       functions are exported by default.

       new()
           Creates a new String::CRC::Cksum object which is in a reset state, ready for action.
           If passed an existing String::CRC::Cksum object, it takes only the class - ie yields a
           fresh, reset object.

       reset()
           Resets the Cksum object to the intialized state.  An interesting phenomenom is, the
           CRC is not zero but 0xFFFFFFFF for a reset Cksum object.  The returned size of a reset
           item will be zero.

       add("string", ...)
           Progressively inject data into the Cksum object prior to requesting the final result.

       addfile(\*FILE, ...)
           Progressively inject all (remaining) data from the file into the Cksum object prior to
           requesting the final result.  The file handle passed in need only respond to the
           read() function to be usable, so feel free to pass in IO handles as needed.  [hmmm -
           methinks I should have a test for that]

       peek($)
           Yields the CRC checksum (and optionally the total size in list context) but does not
           reset the Cksum object.  Repeated calls to peek() may be made and more data may be
           added.

       result($)
           Yields the CRC checksum (and optionally the total size in list context) and then
           resets the Cksum object.

       cksum(@)
           A convenient functional interface that may be passed a list of strings and
           filehandles.  It will instantiate a Cksum object, apply the data and return the result
           in one swift, sweet operation.  See how much I'm looking after you?

           NOTE: the filehandles must be passed as \*FD because I'm detecting a file handle using
           the ref() function.  Therefore any blessed IO handle will also satisfy ref() and be
           interpreted as a file handle.

   EXPORT
       None by default.

SEE ALSO

       manpages: cksum(1) or cksum(C) depending on your flavour of UNIX.

       http://www.opengroup.org/onlinepubs/007904975/utilities/cksum.html

AUTHOR

       Andrew Clarke, <ahamm@cpan.org>.

COPYRIGHT AND LICENSE

       Copyright disclaimed 2003 by Andrew Clarke

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.