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

       Andrew Clarke, <ahamm@cpan.org>.

       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.

perl v5.32.0                                       2021-01-08                                         Cksum(3pm)

       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...

       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.

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

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

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

OOstyle:
         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*...
         ...

       Functionalstyle:
         use String::CRC::Cksum qw(cksum);

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

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

         $ck = cksum(\*FILE);

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