Repository files navigation

Standard CRC-32 algorithm implementation in JS (for the browser and nodejs).Emphasis on correctness, performance, and IE6+ support.

With a node package manager likenpm:

$ npm i --save https://cdn.sheetjs.com/crc-32-latest/crc-32-latest.tgz

When installed globally, npm installs a scriptcrc32 that computes thechecksum for a specified file or standard input.

Hosted versions are available athttps://cdn.sheetjs.com/:

• crc32.js (CommonJS):https://cdn.sheetjs.com/crc-32-latest/package/crc32.js
• crc32.mjs (ESM):https://cdn.sheetjs.com/crc-32-latest/package/crc32.mjs
• crc32c.js (CommonJS):https://cdn.sheetjs.com/crc-32-latest/package/crc32c.js
• crc32c.mjs (ESM):https://cdn.sheetjs.com/crc-32-latest/package/crc32c.mjs

Using NodeJS or a bundler withrequire:

varCRC32=require("crc-32");

Using NodeJS or a bundler withimport:

import{bstr,buf,str}from"crc-32";

In the browser, thecrc32.js script can be loaded directly:

<scriptsrc="crc32.js"></script>

The browser script exposes a variableCRC32.

The script will manipulatemodule.exports if available . This is not alwaysdesirable. To prevent the behavior, defineDO_NOT_EXPORT_CRC.

The module and CDNs also include a parallel script for CRC32C calculations.

Using NodeJS or a bundler:

varCRC32C=require("crc-32/crc32c");

Using NodeJS or a bundler withimport:

import{bstr,buf,str}from"crc-32/crc32c";

In the browser, thecrc32c.js script can be loaded directly:

<scriptsrc="crc32c.js"></script>

The browser exposes a variableCRC32C.

The script will manipulatemodule.exports if available . This is not alwaysdesirable. To prevent the behavior, defineDO_NOT_EXPORT_CRC.

In all cases, the relevant function takes an argument representing data and anoptional second argument representing the starting "seed" (for rolling CRC).

The return value is a signed 32-bit integer!

• CRC32.buf(byte array or buffer[, seed]) assumes the argument is a sequenceof 8-bit unsigned integers (nodejsBuffer,Uint8Array or array of bytes).

• CRC32.bstr(binary string[, seed]) assumes the argument is a binary stringwhere bytei is the low byte of the UCS-2 char:str.charCodeAt(i) & 0xFF

• CRC32.str(string[, seed]) assumes the argument is a standard JS string andcalculates the hash of the UTF-8 encoding.

For example:

// var CRC32 = require('crc-32');               // uncomment this line if in nodeCRC32.str("SheetJS")// -1647298270CRC32.bstr("SheetJS")// -1647298270CRC32.buf([83,104,101,101,116,74,83])// -1647298270crc32=CRC32.buf([83,104])// -1826163454  "Sh"crc32=CRC32.str("eet",crc32)//  1191034598  "Sheet"CRC32.bstr("JS",crc32)// -1647298270  "SheetJS"[CRC32.str("\u2603"),CRC32.str("\u0003")]// [ -1743909036,  1259060791 ][CRC32.bstr("\u2603"),CRC32.bstr("\u0003")]// [  1259060791,  1259060791 ][CRC32.buf([0x2603]),CRC32.buf([0x0003])]// [  1259060791,  1259060791 ]// var CRC32C = require('crc-32/crc32c');       // uncomment this line if in nodeCRC32C.str("SheetJS")// -284764294CRC32C.bstr("SheetJS")// -284764294CRC32C.buf([83,104,101,101,116,74,83])// -284764294crc32c=CRC32C.buf([83,104])// -297065629   "Sh"crc32c=CRC32C.str("eet",crc32c)//  1241364256  "Sheet"CRC32C.bstr("JS",crc32c)// -284764294   "SheetJS"[CRC32C.str("\u2603"),CRC32C.str("\u0003")]// [  1253703093,  1093509285 ][CRC32C.bstr("\u2603"),CRC32C.bstr("\u0003")]// [  1093509285,  1093509285 ][CRC32C.buf([0x2603]),CRC32C.buf([0x0003])]// [  1093509285,  1093509285 ]

Even though the initial seed is optional, for performance reasons it is highlyrecommended to explicitly pass the default seed 0.

In NodeJS with the native Buffer implementation, it is oftentimes faster toconvert binary strings withBuffer.from(bstr, "binary") first:

/* Frequently slower in NodeJS */crc32=CRC32.bstr(bstr,0);/* Frequently faster in NodeJS */crc32=CRC32.buf(Buffer.from(bstr,"binary"),0);

This does not apply to browserBuffer shims, and thus is not implemented inthe library directly.

Unconventional for a CRC32 checksum, this library uses signed 32-bit integers.This is for performance reasons. Standard JS operators can convert betweensigned and unsigned 32-bit integers:

CRC32.str("SheetJS")// -1647298270 (signed)CRC32.str("SheetJS")>>>0//  2647669026 (unsigned)(CRC32.str("SheetJS")>>>0).toString(16)//  "9dd03922" (hex)(2647669026|0)// -1647298270

• x >>> 0 converts a number value to unsigned 32-bit integer.

• x | 0 converts a number value to signed 32-bit integer.

make test will run the nodejs-based test.

To run the in-browser tests, run a local server and go to thectest directory.make ctestserv will start a pythonSimpleHTTPServer server on port 8000.

To update the browser artifacts, runmake ctest.

To generate the bits file, use thecrc32 function from pythonzlib:

>>>fromzlibimportcrc32>>>x="foo bar baz٪☃🍣">>>crc32(x)1531648243>>>crc32(x+x)-218791105>>>crc32(x+x+x)1834240887

The includedcrc32.njs script can process files or standard input:

$echo"this is a test"> t.txt$ bin/crc32.njs t.txt1912935186

For comparison, the includedcrc32.py script uses pythonzlib:

$ bin/crc32.py t.txt1912935186

On OSX the commandcksum generates unsigned CRC-32 with Algorithm 3:

$ cksum -o 3< IE8.Win7.For.Windows.VMware.zip1891069052 4161613172$ crc32 --unsigned~/Downloads/IE8.Win7.For.Windows.VMware.zip1891069052

make perf will run algorithmic performance tests (which should justify certaindecisions in the code).

Theadler-32 project has more performance notes

Please consult the attached LICENSE file for details. All rights not explicitlygranted by the Apache 2.0 license are reserved by the Original Author.