`nupp.checksum`

Numeric checksums, for noticing that bytes got corrupted.

One call for a whole string, or a context you feed in pieces.

const checksum = nupp.checksum

print(checksum.value("crc32c", "hello"))

with running = checksum.newChecksum("crc32") do
    running:write("hel")
    running:write("lo")
    print(running:value())
end

value is a snapshot rather than a finish, so a context keeps going after one is taken. A context is an io.Writer, so reader:transferTo(running) checksums a whole stream without holding it. These say nothing about whether bytes were changed on purpose: for that reach for nupp.mac.

Built-in algorithms#

Name	Width	Parameters
`adler32`	32	Adler-32
`crc32`	32	Reflected IEEE CRC-32
`crc32c`	32	Reflected Castagnoli CRC-32C
`crc64-ecma`	64	ECMA-182, non-reflected, zero initialization and xor
`crc64nvme`	64	Reflected CRC-64/NVME

crc32, crc32c, and crc64nvme use the lowercase names from Smithy's httpChecksum trait. crc64-ecma is ECMA-182, a different algorithm from crc64nvme. The CRC implementations use crc-fast, which selects hardware acceleration when the CPU supports it.

A snapshot is a number, so whatever writes one to the wire picks its byte order.

A host may supply its own catalog through nupp.checksum.spi, selected during setup before this module loads. Its entries override the built-ins of the same name and may add others, and the ones it does not name stay available. The catalog is read once, at load, so no lookup or update resolves a service.

Submodules

Module	Description
`nupp.checksum.spi`	Implementation interfaces for nupp.checksum algorithm catalogs.

Module contents

Types

Type	Kind	Description
`Algorithm`	record	Checksum metadata and a factory for independent state.
`Checksum`	interface	Owned incremental checksum state with non-consuming numeric reads.

Functions

Function	Kind	Description
`algorithm`	function	Requires a checksum algorithm descriptor.
`algorithms`	function	Lists available canonical checksum names in ascending order.
`lookup`	function	Finds a checksum algorithm without creating incremental state.
`newChecksum`	function	Creates independent owned checksum state.
`value`	function	Computes a checksum; its bit width belongs to the algorithm descriptor.

Types#

`Algorithm`record#

record Algorithm ...

Checksum metadata and a factory for independent state.

Members

Name	Kind	Description
`name`	field	Canonical algorithm name.
`width`	field	Number of meaningful checksum bits, from one through 64.
`implementation`	field
`newChecksum`	method	Creates independent owned state for incremental writes and snapshots.

`name`field#

name: string

@readonly

Canonical algorithm name.

`width`field#

width: integer

@readonly

Number of meaningful checksum bits, from one through 64.

`implementation`field#

implementation: provider.Algorithm

@private

`newChecksum`method#

newChecksum: function newChecksum(self): Checksum

Creates independent owned state for incremental writes and snapshots.

Arguments

Name	Type	Description
`self`	`any`

Returns

Type	Description
`Checksum`

`Checksum`interface#

interface Checksum is Writer ...

Owned incremental checksum state with non-consuming numeric reads.

Members

Name	Kind	Description
`close`	method	Consumes this context and releases its provider state without suspension.
`algorithm`	method	Returns the canonical algorithm name.
`width`	method	Returns the number of meaningful bits in each snapshot.
`write`	method	Absorbs raw bytes while retaining no input views.
`writeSpan`	method	Absorbs a borrowed byte view without retaining it.
`flush`	method	Nothing is buffered behind a checksum, so this only returns true.
`value`	method	Returns an unsigned snapshot without consuming this context.

`close`method#

close: @nosuspend function(takes self: Checksum): nil

Consumes this context and releases its provider state without suspension.

Arguments

Name	Type	Description
`takes self`	`Checksum`

Returns

Type	Description
`nil`

`algorithm`method#

algorithm: function(self: Checksum): string

Returns the canonical algorithm name.

Arguments

Name	Type	Description
`self`	`Checksum`

Returns

Type	Description
`string`

`width`method#

width: function(self: Checksum): integer

Returns the number of meaningful bits in each snapshot.

Arguments

Name	Type	Description
`self`	`Checksum`

Returns

Type	Description
`integer`

`write`method#

write: function(exclusive self: Checksum, bytes: string): (boolean, string?)

Absorbs raw bytes while retaining no input views.

Arguments

Name	Type	Description
`exclusive self`	`Checksum`
`bytes`	`string`

Returns

Type	Description
`boolean`	true, since a checksum takes every byte it is given
`string?`

`writeSpan`method#

writeSpan: function(exclusive self: Checksum, borrows bytes: span.ByteSpan): (integer?, string?)

Absorbs a borrowed byte view without retaining it.

Arguments

Name	Type	Description
`exclusive self`	`Checksum`
`borrows bytes`	`span.ByteSpan`

Returns

Type	Description
`integer?`	how many bytes it absorbed, which is all of them
`string?`

`flush`method#

flush: function(self: Checksum): (boolean, string?)

Nothing is buffered behind a checksum, so this only returns true.

Arguments

Name	Type	Description
`self`	`Checksum`

Returns

Type	Description
`boolean`
`string?`

`value`method#

value: function(self: Checksum): uint64

Returns an unsigned snapshot without consuming this context.

Arguments

Name	Type	Description
`self`	`Checksum`

Returns

Type	Description
`uint64`

Functions#

`algorithm`function#

function algorithm(name: string): Algorithm

Requires a checksum algorithm descriptor.

Arguments

Name	Type	Description
`name`	`string`	the canonical checksum algorithm name

Returns

Type	Description
`Algorithm`	the selected descriptor

Raises

Type	Condition
`string`	when the algorithm is unavailable

`algorithms`function#

function algorithms(): {string}

Lists available canonical checksum names in ascending order.

Returns

Type	Description
`{string}`	the available names

`lookup`function#

function lookup(name: string): Algorithm?

Finds a checksum algorithm without creating incremental state.

Arguments

Name	Type	Description
`name`	`string`	the canonical checksum algorithm name

Returns

Type	Description
`Algorithm?`	the descriptor, or nil when unavailable

`newChecksum`function#

function newChecksum(name: string): Checksum

Creates independent owned checksum state.

Arguments

Name	Type	Description
`name`	`string`	the canonical checksum algorithm name

Returns

Type	Description
`Checksum`	an unfinished checksum context

`value`function#

function value(name: string, bytes: string): uint64

Computes a checksum; its bit width belongs to the algorithm descriptor.

Arguments

Name	Type	Description
`name`	`string`	the canonical checksum algorithm name
`bytes`	`string`	the message bytes

Returns

Type	Description
`uint64`	the unsigned checksum value

nupp.checksum

Built-in algorithms#

Submodules

Module contents

Types

Functions

Types#

Algorithmrecord#

Members

namefield#

widthfield#

implementationfield#

newChecksummethod#

Arguments

Returns

Checksuminterface#

Members

closemethod#

Arguments

Returns

algorithmmethod#

Arguments

Returns

widthmethod#

Arguments

Returns

writemethod#

Arguments

Returns

writeSpanmethod#

Arguments

Returns

flushmethod#

Arguments

Returns

valuemethod#

Arguments

Returns

Functions#

algorithmfunction#

Arguments

Returns

Raises

algorithmsfunction#

Returns

lookupfunction#

Arguments

Returns

newChecksumfunction#

Arguments

Returns

valuefunction#

Arguments

Returns

`nupp.checksum`

`Algorithm`record#

`name`field#

`width`field#

`implementation`field#

`newChecksum`method#

`Checksum`interface#

`close`method#

`algorithm`method#

`width`method#

`write`method#

`writeSpan`method#

`flush`method#

`value`method#

`algorithm`function#

`algorithms`function#

`lookup`function#

`newChecksum`function#

`value`function#