Documention for: crc32.r
Created by: vincentecuye
 on: 30-Jan-2013
Format: text/editable
Downloaded on: 19-Apr-2024

CRC-32
    File: %crc32.r
    Author: "Vincent Ecuyer"
    Date: 30-Jan-2013
    License: 'bsd

===Purpose

CRC32 checksum function. 

===Usage

Calculates a 32 bits cyclic redundancy code as used in gzip / pkzip / etc. 

Returns a binary:
    >> crc-32 "a string" 
    == #{99A255DA}

    >> crc-32 #{112233445566}
    == #{345913D6} 

or an integer: /integer
    >> crc-32/integer "a string" 
    == -1717414438

To compute the checksum part by part: /continue
    >> crc-32 "a str" 
    == #{61AD7C35}

    >> crc-32/continue "ing" #{61AD7C35} 
    == #{99A255DA} 

    >> crc-32/continue data none 
is a synonym of: 
    >> crc-32 data

Usage of /continue in a loop: 
    ; initial crc 
    crc: none
    until [
        ... 
        ; a new crc is computed from the previous one and the new data crc:  
        crc-32/continue data-part crc
        ... 
    ] 
    ; at the end of this loop, 'crc holds the crc-32 of the whole data

The /direct mode, with a specified buffer size, works directly on files (useful for big files): 

    ; calculates the checksum of a remote file with a 64 kb buffer 
    >> crc-32/direct ftp://192.168.1.33/rebol.exe 64 * 1024 
    == #{67AD9CF6} 

Note: In the case of a file access error, connection timeout, or an execution halted by the user, the opened file can still be locked. Any new invocation of 'crc-32 will release (close) the file and clear the internal buffer. Example: 
    >> crc-32 "" 

===Note

The script contains a precomputed table for speedup. REBOL VM isn't really suited for fast bitwise operations, so this code is quite slow on big files. If the rebcode VM is available, it's used to achieve a more usable speed (between checksum/method 'md5 and checksum/method 'sha1).

To prevent the code to return a wrong result following a future REBOL VM revision, a consistency check is done at loading, with an error raised if something goes wrong.

===REBOL 3

When used with REBOL 3, this script is loaded as a module: only the 'crc-32 function is exported, and the 'ctx-crc-32 object (holding the context) is kept private. 

"crc-32/integer" on a binary is identical to "checksum/method 'crc32" on the same binary. In this case, this module is redundant in R3, and mostly useful to ensure code compatibility with R2. When possible, checksum/method 'crc32 is used, so the performance impact is limited - it isn't always the case, as the /continue refinement falls back to the slower method.

The /direct refinement is ignored right now, as the port! model has changed in R3.