Module: `nupp.data`

Data and text#

nupp.data groups serialization, Unicode, identifiers and byte digests. Reach it directly from the global nupp namespace; the C and Rust providers remain hidden.

JSON#

encodeJSON and decodeJSON use the mature cjson implementation without exposing its module name:

null, emptyArray, arrayMt, and emptyArrayMt preserve distinctions Lua tables cannot express by themselves. The configuration methods match cjson's established semantics, but live on nupp.data. newJSON() returns an independent nupp.JSON encoder/decoder with its own settings:

JSON selects the cjson native feature. No require("cjson") is needed or recommended.

Member	Result	Purpose
`encodeJSON(value)`	`string`	Encode one Lua value.
`decodeJSON(text)`	`any`	Decode one JSON document.
`newJSON()`	`nupp.JSON`	Create an independently configured codec.
`null`, `emptyArray`	sentinel values	Represent JSON values that plain Lua tables cannot distinguish.
`arrayMt`, `emptyArrayMt`	metatables	Mark array-shaped tables explicitly.

Both nupp.data and an object returned by newJSON provide the configuration methods encodeEmptyTableAsObject, decodeArrayWithArrayMt, decodeAllowComment, encodeSparseArray, encodeMaxDepth, decodeMaxDepth, encodeNumberPrecision, encodeKeepBuffer, encodeInvalidNumbers, decodeInvalidNumbers, encodeEscapeForwardSlash, encodeSkipUnsupportedValueTypes, and encodeIndent. Omitting a method's setting reads the current value where the provider supports that form; passing a setting changes only that codec.

UTF-8#

nupp.data.utf8 treats strings and nupp.ByteView values as byte sequences. Byte offsets are 1-based here so they compose with Lua string positions. Invalid input decodes as U+FFFD while validation remains explicit.

validPrefixLength(value, maxBytes) returns the largest valid prefix no longer than the byte budget. truncate applies that operation to a string. The underlying lua-utf8 provider loads only when this namespace is selected and reached.

Member	Result	Position rule
`length(value)`	`integer`	Counts decoded scalar values, replacing malformed bytes individually.
`decodeAt(value, byteOffset)`	`integer?, integer`	Decodes forward from a 1-based byte offset and returns the next offset.
`decodeBefore(value, byteOffset)`	`integer?, integer`	Decodes the scalar ending before a 1-based byte offset.
`encode(codepoint)`	`string`	Encodes one Unicode scalar value.
`isValid(value)`	`boolean`	Validates the complete byte sequence.
`validPrefixLength(value, maxBytes)`	`integer`	Finds a valid prefix within a byte budget.
`truncate(text, maxBytes)`	`string`	Copies that valid prefix.

UUIDs#

uuid4() returns a random RFC 9562 version 4 identifier. uuid7() returns a time-ordered version 7 identifier, useful when identifier order should roughly follow creation order:

Both are lowercase canonical strings. They share one uuid feature and never expose a native UUID object.

Hashes and checksums#

Each function accepts a string or immutable nupp.ByteView.

fnv1a64 is a fast non-cryptographic identity rendered as 16 lowercase hexadecimal digits. sha256 is a cryptographic digest rendered as 64 lowercase hexadecimal digits. adler32 and crc32 return unsigned 32-bit numbers and accept a previous result for incremental checksumming. Checksums detect accidental damage; they do not authenticate data. A supplied previous checksum must itself be an unsigned 32-bit integer.

FNV-1a, Adler-32 and CRC-32 are pure generated Lua. SHA-256 is independently gated in the shared Rust provider. See automatic native selection.

Member	Result	Native provider
`uuid4()`	canonical UUID string	shared provider, `uuid` feature
`uuid7()`	canonical UUID string	shared provider, `uuid` feature
`fnv1a64(value)`	16 lowercase hex digits	none
`sha256(value)`	64 lowercase hex digits	shared provider, `sha256` feature
`adler32(value, previous?)`	unsigned 32-bit number	none
`crc32(value, previous?)`	unsigned 32-bit number	none

JSON, UTF-8, UUIDs, hashes and checksums.

Submodules

Module	Description
`nupp.data.utf8`	UTF-8 codepoint operations over strings and byte views.

Module contents

Constructors

Constructor	Description
`newJSON`	Creates an independent JSON codec with its own settings.

Functions

Function	Kind	Description
`adler32`	function	Computes or continues an Adler-32 checksum.
`crc32`	function	Computes or continues a CRC-32 checksum.
`decodeAllowComment`	function	Sets whether the decoder accepts comments, or reads the current setting when omitted.
`decodeArrayWithArrayMt`	function	Sets whether decoded arrays carry arrayMt, or reads the current setting when omitted.
`decodeInvalidNumbers`	function	Sets whether the decoder accepts NaN and infinities, or reads the current setting when omitted.
`decodeJSON`	function	Decodes one JSON document into Lua values.
`decodeMaxDepth`	function	Sets the maximum nested-container depth accepted by the decoder, or reads the current limit when omitted.
`encodeEmptyTableAsObject`	function	Sets whether an empty table encodes as an object, or reads the current setting when omitted.
`encodeEscapeForwardSlash`	function	Sets whether / is escaped in JSON strings, or reads the current setting when omitted.
`encodeIndent`	function	Sets the indentation used for encoded containers, or reads the current indentation when omitted.
`encodeInvalidNumbers`	function	Configures encoding of NaN and infinities, or reads the current setting when omitted.
`encodeJSON`	function	Encodes a Lua value as JSON text.
`encodeKeepBuffer`	function	Sets whether the encoder reuses its internal buffer, or reads the current setting when omitted.
`encodeMaxDepth`	function	Sets the maximum nested-container depth accepted by the encoder, or reads the current limit when omitted.
`encodeNumberPrecision`	function	Sets the significant-digit precision used to encode numbers, or reads the current precision when omitted.
`encodeSkipUnsupportedValueTypes`	function	Sets whether unsupported values are skipped instead of raising, or reads the current setting when omitted.
`encodeSparseArray`	function	Configures how excessively sparse arrays are encoded, or reads the current settings when every argument is omitted.
`fnv1a64`	function	Computes the 64-bit FNV-1a digest of bytes.
`sha256`	function	Computes the SHA-256 digest of bytes.
`uuid4`	function	Generates a random version 4 UUID.
`uuid7`	function	Generates a time-ordered version 7 UUID.

Values

Value	Kind	Description
`arrayMt`	variable	Metatable marking a table to encode as a JSON array.
`emptyArray`	variable	Sentinel that always encodes as an empty JSON array.
`emptyArrayMt`	variable	Metatable marking a table to encode as an empty JSON array.
`null`	variable	Sentinel that decodes from and encodes as JSON null.

Constructors#

`newJSON`constructor#

Creates an independent JSON codec with its own settings.

local newJSON: function(): nupp.JSON

Returns

Type	Description
`nupp.JSON`	the new codec

Functions#

`adler32`function#

Computes or continues an Adler-32 checksum.

local adler32: function(value: string | nupp.ByteView, previous: integer?): integer

Arguments

Name	Type	Description
`value`	`string \| nupp.ByteView`	the bytes to checksum
`previous`	`integer?`	a previous Adler-32 value, or 1 to start

Returns

Type	Description
`integer`	the unsigned 32-bit checksum

`crc32`function#

Computes or continues a CRC-32 checksum.

local crc32: function(value: string | nupp.ByteView, previous: integer?): integer

Arguments

Name	Type	Description
`value`	`string \| nupp.ByteView`	the bytes to checksum
`previous`	`integer?`	a previous CRC-32 value, or 0 to start

Returns

Type	Description
`integer`	the unsigned 32-bit checksum

`decodeAllowComment`function#

Sets whether the decoder accepts comments, or reads the current setting when omitted.

local decodeAllowComment: function(setting: boolean | string?): boolean

Arguments

Name	Type	Description
`setting`	`boolean \| string?`	the new setting

Returns

Type	Description
`boolean`	whether comments are accepted

`decodeArrayWithArrayMt`function#

Sets whether decoded arrays carry arrayMt, or reads the current setting when omitted.

local decodeArrayWithArrayMt: function(setting: boolean | string?): boolean

Arguments

Name	Type	Description
`setting`	`boolean \| string?`	the new setting

Returns

Type	Description
`boolean`	whether decoded arrays carry `arrayMt`

`decodeInvalidNumbers`function#

Sets whether the decoder accepts NaN and infinities, or reads the current setting when omitted.

local decodeInvalidNumbers: function(setting: boolean | string?): boolean

Arguments

Name	Type	Description
`setting`	`boolean \| string?`	the new setting

Returns

Type	Description
`boolean`	whether invalid numbers are accepted

`decodeJSON`function#

Decodes one JSON document into Lua values.

local decodeJSON: function(text: string): any

Arguments

Name	Type	Description
`text`	`string`	the JSON document to decode

Returns

Type	Description
`any`	the decoded value

`decodeMaxDepth`function#

Sets the maximum nested-container depth accepted by the decoder, or reads the current limit when omitted.

local decodeMaxDepth: function(depth: integer?): integer

Arguments

Name	Type	Description
`depth`	`integer?`	the new maximum depth

Returns

Type	Description
`integer`	the current maximum depth

`encodeEmptyTableAsObject`function#

Sets whether an empty table encodes as an object, or reads the current setting when omitted.

local encodeEmptyTableAsObject: function(setting: boolean | string?): boolean

Arguments

Name	Type	Description
`setting`	`boolean \| string?`	true or "on" for `{}`, false or "off" for `[]`

Returns

Type	Description
`boolean`	whether empty tables encode as objects

`encodeEscapeForwardSlash`function#

Sets whether / is escaped in JSON strings, or reads the current setting when omitted.

local encodeEscapeForwardSlash: function(setting: boolean | string?): boolean

Arguments

Name	Type	Description
`setting`	`boolean \| string?`	the new setting

Returns

Type	Description
`boolean`	whether forward slashes are escaped

`encodeIndent`function#

Sets the indentation used for encoded containers, or reads the current indentation when omitted.

local encodeIndent: function(indent: string?): string

Arguments

Name	Type	Description
`indent`	`string?`	the indentation string

Returns

Type	Description
`string`	the current indentation string

`encodeInvalidNumbers`function#

Configures encoding of NaN and infinities, or reads the current setting when omitted.

local encodeInvalidNumbers: function(setting: boolean | string?): boolean | string

Arguments

Name	Type	Description
`setting`	`boolean \| string?`	false to reject them, true to emit them, or "null" to emit null

Returns

Type	Description
`boolean \| string`	the active invalid-number setting

`encodeJSON`function#

Encodes a Lua value as JSON text.

local encodeJSON: function(value: any): string

Arguments

Name	Type	Description
`value`	`any`	the value to encode

Returns

Type	Description
`string`	the encoded JSON document

`encodeKeepBuffer`function#

Sets whether the encoder reuses its internal buffer, or reads the current setting when omitted.

local encodeKeepBuffer: function(keep: boolean | string?): boolean

Arguments

Name	Type	Description
`keep`	`boolean \| string?`	the new setting

Returns

Type	Description
`boolean`	whether the internal buffer is retained

`encodeMaxDepth`function#

Sets the maximum nested-container depth accepted by the encoder, or reads the current limit when omitted.

local encodeMaxDepth: function(depth: integer?): integer

Arguments

Name	Type	Description
`depth`	`integer?`	the new maximum depth

Returns

Type	Description
`integer`	the current maximum depth

`encodeNumberPrecision`function#

Sets the significant-digit precision used to encode numbers, or reads the current precision when omitted.

local encodeNumberPrecision: function(precision: integer?): integer

Arguments

Name	Type	Description
`precision`	`integer?`	the new number of significant digits

Returns

Type	Description
`integer`	the current precision

`encodeSkipUnsupportedValueTypes`function#

Sets whether unsupported values are skipped instead of raising, or reads the current setting when omitted.

local encodeSkipUnsupportedValueTypes: function(setting: boolean | string?): boolean

Arguments

Name	Type	Description
`setting`	`boolean \| string?`	the new setting

Returns

Type	Description
`boolean`	whether unsupported values are skipped

`encodeSparseArray`function#

Configures how excessively sparse arrays are encoded, or reads the current settings when every argument is omitted.

local encodeSparseArray: function(convert: boolean?, ratio: integer?, safe: integer?): (boolean, integer, integer)

Arguments

Name	Type	Description
`convert`	`boolean?`	whether sparse arrays become JSON objects instead of raising
`ratio`	`integer?`	the maximum ratio between the highest index and item count
`safe`	`integer?`	the array size below which sparsity is always accepted

Returns

Type	Description
`boolean`	whether sparse arrays are converted
`integer`	the current ratio limit
`integer`	the current safe size

`fnv1a64`function#

Computes the 64-bit FNV-1a digest of bytes.

local fnv1a64: function(value: string | nupp.ByteView): string

Arguments

Name	Type	Description
`value`	`string \| nupp.ByteView`	the bytes to hash

Returns

Type	Description
`string`	the lowercase hexadecimal digest

`sha256`function#

Computes the SHA-256 digest of bytes.

local sha256: function(value: string | nupp.ByteView): string

Arguments

Name	Type	Description
`value`	`string \| nupp.ByteView`	the bytes to hash

Returns

Type	Description
`string`	the lowercase hexadecimal digest

`uuid4`function#

Generates a random version 4 UUID.

local uuid4: function(): string

Returns

Type	Description
`string`	the canonical lowercase UUID text

`uuid7`function#

Generates a time-ordered version 7 UUID.

local uuid7: function(): string

Returns

Type	Description
`string`	the canonical lowercase UUID text

Values#

`arrayMt`variable#

Metatable marking a table to encode as a JSON array.

local arrayMt: metatable<{any}>

`emptyArray`variable#

Sentinel that always encodes as an empty JSON array.

local emptyArray: any

`emptyArrayMt`variable#

Metatable marking a table to encode as an empty JSON array.

local emptyArrayMt: metatable<{any}>

`null`variable#

Sentinel that decodes from and encodes as JSON null.

local null: any

Module: nupp.data

Data and text#

JSON#

UTF-8#

UUIDs#

Hashes and checksums#

Submodules

Module contents

Constructors

Functions

Values

Constructors#

newJSONconstructor#

Returns

Functions#

adler32function#

Arguments

Returns

crc32function#

Arguments

Returns

decodeAllowCommentfunction#

Arguments

Returns

decodeArrayWithArrayMtfunction#

Arguments

Returns

decodeInvalidNumbersfunction#

Arguments

Returns

decodeJSONfunction#

Arguments

Returns

decodeMaxDepthfunction#

Arguments

Returns

encodeEmptyTableAsObjectfunction#

Arguments

Returns

encodeEscapeForwardSlashfunction#

Arguments

Returns

encodeIndentfunction#

Arguments

Returns

encodeInvalidNumbersfunction#

Arguments

Returns

encodeJSONfunction#

Arguments

Returns

encodeKeepBufferfunction#

Arguments

Returns

encodeMaxDepthfunction#

Arguments

Returns

encodeNumberPrecisionfunction#

Arguments

Returns

encodeSkipUnsupportedValueTypesfunction#

Arguments

Returns

encodeSparseArrayfunction#

Arguments

Returns

fnv1a64function#

Arguments

Returns

sha256function#

Arguments

Returns

uuid4function#

Returns

uuid7function#

Returns

Values#

arrayMtvariable#

emptyArrayvariable#

emptyArrayMtvariable#

Module: `nupp.data`

`newJSON`constructor#

`adler32`function#

`crc32`function#

`decodeAllowComment`function#

`decodeArrayWithArrayMt`function#

`decodeInvalidNumbers`function#

`decodeJSON`function#

`decodeMaxDepth`function#

`encodeEmptyTableAsObject`function#

`encodeEscapeForwardSlash`function#

`encodeIndent`function#

`encodeInvalidNumbers`function#

`encodeJSON`function#

`encodeKeepBuffer`function#

`encodeMaxDepth`function#

`encodeNumberPrecision`function#

`encodeSkipUnsupportedValueTypes`function#

`encodeSparseArray`function#

`fnv1a64`function#

`sha256`function#

`uuid4`function#

`uuid7`function#

`arrayMt`variable#

`emptyArray`variable#

`emptyArrayMt`variable#

`null`variable#