From 0f7aed8a59178a9756f2b66da35c774fa08681bd Mon Sep 17 00:00:00 2001 From: Kevin Toshihiro Uehara Date: Tue, 24 Dec 2024 17:53:53 -0300 Subject: [PATCH] doc: fix the `crc32` documentation PR-URL: https://github.com/nodejs/node/pull/55898 Fixes: https://github.com/nodejs/node/issues/55800 Reviewed-By: Luigi Pinca Reviewed-By: Antoine du Hamel --- doc/api/zlib.md | 122 ++++++++++++++++++++++++------------------------ 1 file changed, 61 insertions(+), 61 deletions(-) diff --git a/doc/api/zlib.md b/doc/api/zlib.md index 2d3ea8050f230b..db4b81e9cede89 100644 --- a/doc/api/zlib.md +++ b/doc/api/zlib.md @@ -926,67 +926,6 @@ The `zlib.bytesWritten` property specifies the number of bytes written to the engine, before the bytes are processed (compressed or decompressed, as appropriate for the derived class). -### `zlib.crc32(data[, value])` - - - -* `data` {string|Buffer|TypedArray|DataView} When `data` is a string, - it will be encoded as UTF-8 before being used for computation. -* `value` {integer} An optional starting value. It must be a 32-bit unsigned - integer. **Default:** `0` -* Returns: {integer} A 32-bit unsigned integer containing the checksum. - -Computes a 32-bit [Cyclic Redundancy Check][] checksum of `data`. If -`value` is specified, it is used as the starting value of the checksum, -otherwise, 0 is used as the starting value. - -The CRC algorithm is designed to compute checksums and to detect error -in data transmission. It's not suitable for cryptographic authentication. - -To be consistent with other APIs, if the `data` is a string, it will -be encoded with UTF-8 before being used for computation. If users only -use Node.js to compute and match the checksums, this works well with -other APIs that uses the UTF-8 encoding by default. - -Some third-party JavaScript libraries compute the checksum on a -string based on `str.charCodeAt()` so that it can be run in browsers. -If users want to match the checksum computed with this kind of library -in the browser, it's better to use the same library in Node.js -if it also runs in Node.js. If users have to use `zlib.crc32()` to -match the checksum produced by such a third-party library: - -1. If the library accepts `Uint8Array` as input, use `TextEncoder` - in the browser to encode the string into a `Uint8Array` with UTF-8 - encoding, and compute the checksum based on the UTF-8 encoded string - in the browser. -2. If the library only takes a string and compute the data based on - `str.charCodeAt()`, on the Node.js side, convert the string into - a buffer using `Buffer.from(str, 'utf16le')`. - -```mjs -import zlib from 'node:zlib'; -import { Buffer } from 'node:buffer'; - -let crc = zlib.crc32('hello'); // 907060870 -crc = zlib.crc32('world', crc); // 4192936109 - -crc = zlib.crc32(Buffer.from('hello', 'utf16le')); // 1427272415 -crc = zlib.crc32(Buffer.from('world', 'utf16le'), crc); // 4150509955 -``` - -```cjs -const zlib = require('node:zlib'); -const { Buffer } = require('node:buffer'); - -let crc = zlib.crc32('hello'); // 907060870 -crc = zlib.crc32('world', crc); // 4192936109 - -crc = zlib.crc32(Buffer.from('hello', 'utf16le')); // 1427272415 -crc = zlib.crc32(Buffer.from('world', 'utf16le'), crc); // 4150509955 -``` - ### `zlib.close([callback])` + +* `data` {string|Buffer|TypedArray|DataView} When `data` is a string, + it will be encoded as UTF-8 before being used for computation. +* `value` {integer} An optional starting value. It must be a 32-bit unsigned + integer. **Default:** `0` +* Returns: {integer} A 32-bit unsigned integer containing the checksum. + +Computes a 32-bit [Cyclic Redundancy Check][] checksum of `data`. If +`value` is specified, it is used as the starting value of the checksum, +otherwise, 0 is used as the starting value. + +The CRC algorithm is designed to compute checksums and to detect error +in data transmission. It's not suitable for cryptographic authentication. + +To be consistent with other APIs, if the `data` is a string, it will +be encoded with UTF-8 before being used for computation. If users only +use Node.js to compute and match the checksums, this works well with +other APIs that uses the UTF-8 encoding by default. + +Some third-party JavaScript libraries compute the checksum on a +string based on `str.charCodeAt()` so that it can be run in browsers. +If users want to match the checksum computed with this kind of library +in the browser, it's better to use the same library in Node.js +if it also runs in Node.js. If users have to use `zlib.crc32()` to +match the checksum produced by such a third-party library: + +1. If the library accepts `Uint8Array` as input, use `TextEncoder` + in the browser to encode the string into a `Uint8Array` with UTF-8 + encoding, and compute the checksum based on the UTF-8 encoded string + in the browser. +2. If the library only takes a string and compute the data based on + `str.charCodeAt()`, on the Node.js side, convert the string into + a buffer using `Buffer.from(str, 'utf16le')`. + +```mjs +import zlib from 'node:zlib'; +import { Buffer } from 'node:buffer'; + +let crc = zlib.crc32('hello'); // 907060870 +crc = zlib.crc32('world', crc); // 4192936109 + +crc = zlib.crc32(Buffer.from('hello', 'utf16le')); // 1427272415 +crc = zlib.crc32(Buffer.from('world', 'utf16le'), crc); // 4150509955 +``` + +```cjs +const zlib = require('node:zlib'); +const { Buffer } = require('node:buffer'); + +let crc = zlib.crc32('hello'); // 907060870 +crc = zlib.crc32('world', crc); // 4192936109 + +crc = zlib.crc32(Buffer.from('hello', 'utf16le')); // 1427272415 +crc = zlib.crc32(Buffer.from('world', 'utf16le'), crc); // 4150509955 +``` + ## `zlib.createBrotliCompress([options])`