idlastro / Miscellaneous (Non-Astronomy) Procedures: CHECKSUM32

[Source code]

NAME
CHECKSUM32
PURPOSE
To compute the 32bit checksum of an array (ones-complement arithmetic)
EXPLANATION
The 32bit checksum is adopted in the FITS Checksum convention
http://fits.gsfc.nasa.gov/registry/checksum.html
CALLING SEQUENCE
CHECKSUM32, array, checksum, [/FROM_IEEE, /NoSAVE, /Incremental]
INPUTS
array - any numeric idl array.  If the number of bytes in the array is 
        not a multiple of four then it is padded with zeros internally
        (the array is returned unchanged).   Convert a string array 
        (e.g. a FITS header) to bytes prior to calling CHECKSUM32.
INPUT-OUTPUT
checksum - unsigned long scalar, giving sum of array elements using 
         ones-complement arithmetic.    This is normally an output
         parameter, but can also be an input parameter if /Incremental 
         is set.  
OPTIONAL INPUT KEYWORD
/FROM_IEEE - If this keyword is set, then the input is assumed to be in
     big endian format (e.g. an untranslated FITS array).   This keyword
     only has an effect on little endian machines (e.g. Linux boxes).
/Incremental - If this keyword is set, use the checksum
     parameter as input of a partial checksum from a previous
     call, allowing checksums for large arrays to be calculated 
     incrementally. 
/NoSAVE - if set, then the input array is not saved upon exiting.   Use 
     the /NoSave keyword to save time if the input array is not needed 
     in further computations. 
METHOD
Uses TOTAL() to sum the array into an unsigned integer variable.  The
overflow bits beyond 2^32 are then shifted back to the least significant
bits.    The summing is done in chunks of 2^31 numbers to avoid loss
f precision.    Adapted from FORTRAN code in
easarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/general/checksum/node30.html
RESTRICTIONS
(1) Not valid for object or pointer data types
EXAMPLE
(1) Find the 32 bit checksum of the array x = findgen(35)
DL> checksum32, x, s    ===> s =  2920022024
(2) Find the checksum of an array too large to fit in memory at one time
    by breaking it up into 15 pieces.
DL> a = randomn(seed,100,100, 15)
        IDL> for i=0,14 do checksum32,a[*, *,i], checksum_incr, /incremental
FUNCTION CALLED
HOST_TO_IEEE, IS_IEEE_BIG(), N_BYTES()
MODIFICATION HISTORY
Written    W. Landsman          June 2001
Work correctly on little endian machines, added /FROM_IEEE and /NoSave
           W. Landsman          November 2002
Pad with zeros when array size not a multiple of 4 W.Landsman Aug 2003
Always copy to new array, somewhat slower but more robust algorithm
    especially for Linux boxes   W. Landsman Sep. 2004 
Sep. 2004 update not implemented correctly (sigh) W. Landsman Dec 2004         
No need to byteswap 4 byte datatypes on little endian W. L. May 2009
Use /INTEGER keyword to TOTAL() function W.L. June 2009
Allow incremental calculation of checksums. Mats Löfdahl July 2019.