# `nupp.mem.representation.spi` Implementation interfaces consumed during ordinary module initialization. Discover with nupp.spi.load; the consumer chooses the unique highest priority. Omitted priority is zero. Importing these declarations loads no implementation. ## Types ### `CastElements` _type_ ```nupp type CastElements = function(element: ctype, pointer: any): any ``` Casts storage to elements of any supplied ctype. The implementation must remain generic in T and use the target's representation; accepting one particular element type is not sufficient. ### `CstorageProvider` _interface_ ```nupp interface CstorageProvider ... ``` A coherent family of physical storage operations. `representation` is `native`, the only family Nupp compiles for, and the facade checks it before publishing this table: a provider built for some other layout cannot be selected into a program whose layout is already compiled. Allocation, descriptors, scalar codecs, and copies must agree on byte order, alignment, width, and pointer units. Decode inputs contain at least the scalar width in bytes. Borrowed views preserve source lifetimes; `borrows`, generic casts, and const views are part of the implementation contract. Opaque values in these signatures carry provider storage, not permission to change a compiled representation at runtime. #### Members | Name | Kind | Description | | --- | --- | --- | | [`priority`](#nupp.mem.representation.spi.CstorageProvider.priority) | field | | | [`boundedCount`](#nupp.mem.representation.spi.CstorageProvider.boundedCount) | method | Returns the requested count after any representation-specific extent check. | | [`representation`](#nupp.mem.representation.spi.CstorageProvider.representation) | field | The storage family this table implements, which must be native. | | [`structs`](#nupp.mem.representation.spi.CstorageProvider.structs) | field | Struct descriptors and row operations sharing this storage family. | | [`layout`](#nupp.mem.representation.spi.CstorageProvider.layout) | field | Returns target layout facts for a type or descriptor, where the family reports them. | | [`scalar`](#nupp.mem.representation.spi.CstorageProvider.scalar) | method | Returns the canonical descriptor for a scalar kind within this provider. | | [`descriptor`](#nupp.mem.representation.spi.CstorageProvider.descriptor) | method | Reports layout and bounds for a provider value. | | [`reference`](#nupp.mem.representation.spi.CstorageProvider.reference) | field | Creates a deferred descriptor reference for recursive layouts. | | [`allocateArray`](#nupp.mem.representation.spi.CstorageProvider.allocateArray) | method | Allocates count elements of the supplied descriptor. | | [`allocateBytes`](#nupp.mem.representation.spi.CstorageProvider.allocateBytes) | method | Allocates a writable byte region containing count bytes. | | [`borrowString`](#nupp.mem.representation.spi.CstorageProvider.borrowString) | method | Returns a read-only byte view whose lifetime borrows the source string. | | [`castBytes`](#nupp.mem.representation.spi.CstorageProvider.castBytes) | method | Returns a read-only byte view borrowing the pointer owner. | | [`castElements`](#nupp.mem.representation.spi.CstorageProvider.castElements) | field | Interprets a pointer using any supplied element ctype. | | [`copy`](#nupp.mem.representation.spi.CstorageProvider.copy) | method | Copies count bytes into destination without replacing its owner. | | [`fill`](#nupp.mem.representation.spi.CstorageProvider.fill) | method | Fills count bytes in destination with the given byte value. | | [`sizeOf`](#nupp.mem.representation.spi.CstorageProvider.sizeOf) | method | Returns the descriptor size in bytes. | | [`string`](#nupp.mem.representation.spi.CstorageProvider.string) | method | Copies count source bytes into an independent Lua string. | | [`decodeUint8`](#nupp.mem.representation.spi.CstorageProvider.decodeUint8) | method | Decodes a unsigned 8-bit integer using the target storage byte order. | | [`encodeUint8`](#nupp.mem.representation.spi.CstorageProvider.encodeUint8) | method | Encodes a unsigned 8-bit integer using the target storage byte order. | | [`decodeInt8`](#nupp.mem.representation.spi.CstorageProvider.decodeInt8) | method | Decodes a signed 8-bit integer using the target storage byte order. | | [`encodeInt8`](#nupp.mem.representation.spi.CstorageProvider.encodeInt8) | method | Encodes a signed 8-bit integer using the target storage byte order. | | [`decodeUint16`](#nupp.mem.representation.spi.CstorageProvider.decodeUint16) | method | Decodes a unsigned 16-bit integer using the target storage byte order. | | [`encodeUint16`](#nupp.mem.representation.spi.CstorageProvider.encodeUint16) | method | Encodes a unsigned 16-bit integer using the target storage byte order. | | [`decodeInt16`](#nupp.mem.representation.spi.CstorageProvider.decodeInt16) | method | Decodes a signed 16-bit integer using the target storage byte order. | | [`encodeInt16`](#nupp.mem.representation.spi.CstorageProvider.encodeInt16) | method | Encodes a signed 16-bit integer using the target storage byte order. | | [`decodeUint32`](#nupp.mem.representation.spi.CstorageProvider.decodeUint32) | method | Decodes a unsigned 32-bit integer using the target storage byte order. | | [`encodeUint32`](#nupp.mem.representation.spi.CstorageProvider.encodeUint32) | method | Encodes a unsigned 32-bit integer using the target storage byte order. | | [`decodeInt32`](#nupp.mem.representation.spi.CstorageProvider.decodeInt32) | method | Decodes a signed 32-bit integer using the target storage byte order. | | [`encodeInt32`](#nupp.mem.representation.spi.CstorageProvider.encodeInt32) | method | Encodes a signed 32-bit integer using the target storage byte order. | | [`decodeUint64`](#nupp.mem.representation.spi.CstorageProvider.decodeUint64) | method | Decodes a unsigned 64-bit integer using the target storage byte order. | | [`encodeUint64`](#nupp.mem.representation.spi.CstorageProvider.encodeUint64) | method | Encodes a unsigned 64-bit integer using the target storage byte order. | | [`decodeInt64`](#nupp.mem.representation.spi.CstorageProvider.decodeInt64) | method | Decodes a signed 64-bit integer using the target storage byte order. | | [`encodeInt64`](#nupp.mem.representation.spi.CstorageProvider.encodeInt64) | method | Encodes a signed 64-bit integer using the target storage byte order. | | [`decodeFloat32`](#nupp.mem.representation.spi.CstorageProvider.decodeFloat32) | method | Decodes an IEEE-754 binary32 value using the target storage byte order. | | [`encodeFloat32`](#nupp.mem.representation.spi.CstorageProvider.encodeFloat32) | method | Encodes an IEEE-754 binary32 value using the target storage byte order. | | [`decodeFloat64`](#nupp.mem.representation.spi.CstorageProvider.decodeFloat64) | method | Decodes an IEEE-754 binary64 value using the target storage byte order. | | [`encodeFloat64`](#nupp.mem.representation.spi.CstorageProvider.encodeFloat64) | method | Encodes an IEEE-754 binary64 value using the target storage byte order. | #### `priority` _field_ ```nupp priority: integer? ``` `@readonly` #### `boundedCount` _method_ ```nupp boundedCount: function(borrows source: any, count: integer): integer ``` `@readonly` Returns the requested count after any representation-specific extent check. Callers remain responsible for valid native pointer extents. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows source` | `any` | | | `count` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `integer` | | #### `representation` _field_ ```nupp representation: string ``` `@readonly` The storage family this table implements, which must be `native`. #### `structs` _field_ ```nupp structs: StructvalueProvider? ``` `@readonly` Struct descriptors and row operations sharing this storage family. #### `layout` _field_ ```nupp layout: (function(subject: any): any)? ``` `@readonly` Returns target layout facts for a type or descriptor, where the family reports them. #### `scalar` _method_ ```nupp scalar: function(kind: string): any ``` `@readonly` Returns the canonical descriptor for a scalar kind within this provider. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `kind` | `string` | | ##### Returns | Type | Description | | --- | --- | | `any` | | #### `descriptor` _method_ ```nupp descriptor: function(value: any): any ``` `@readonly` Reports layout and bounds for a provider value. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | ##### Returns | Type | Description | | --- | --- | | `any` | | #### `reference` _field_ ```nupp reference: (function(resolve: function(): any): any)? ``` `@readonly` Creates a deferred descriptor reference for recursive layouts. #### `allocateArray` _method_ ```nupp allocateArray: function(element: any, count: integer): any ``` `@readonly` Allocates count elements of the supplied descriptor. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `element` | `any` | | | `count` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `any` | | #### `allocateBytes` _method_ ```nupp allocateBytes: function(count: integer): uint8[?] ``` `@readonly` Allocates a writable byte region containing count bytes. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `count` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `uint8\[?\]` | | #### `borrowString` _method_ ```nupp borrowString: function(borrows bytes: string): const uint8[?] borrows (bytes) ``` `@readonly` Returns a read-only byte view whose lifetime borrows the source string. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows bytes` | `string` | | ##### Returns | Type | Description | | --- | --- | | `const uint8\[?\] borrows (bytes)` | | #### `castBytes` _method_ ```nupp castBytes: function(borrows pointer: any): const uint8[?] borrows (pointer) ``` `@readonly` Returns a read-only byte view borrowing the pointer owner. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows pointer` | `any` | | ##### Returns | Type | Description | | --- | --- | | `const uint8\[?\] borrows (pointer)` | | #### `castElements` _field_ ```nupp castElements: CastElements ``` `@readonly` Interprets a pointer using any supplied element ctype. #### `copy` _method_ ```nupp copy: function(borrows destination: any, borrows source: any, count: integer): nil ``` `@readonly` Copies count bytes into destination without replacing its owner. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows destination` | `any` | | | `borrows source` | `any` | | | `count` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `fill` _method_ ```nupp fill: function(destination: any, count: integer, value: integer): nil ``` `@readonly` Fills count bytes in destination with the given byte value. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `destination` | `any` | | | `count` | `integer` | | | `value` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `sizeOf` _method_ ```nupp sizeOf: function(element: any): integer ``` `@readonly` Returns the descriptor size in bytes. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `element` | `any` | | ##### Returns | Type | Description | | --- | --- | | `integer` | | #### `string` _method_ ```nupp string: function(borrows source: any, count: integer): string ``` `@readonly` Copies count source bytes into an independent Lua string. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows source` | `any` | | | `count` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `string` | | #### `decodeUint8` _method_ ```nupp decodeUint8: function(bytes: string): uint32 ``` `@readonly` Decodes a unsigned 8-bit integer using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ##### Returns | Type | Description | | --- | --- | | `uint32` | | #### `encodeUint8` _method_ ```nupp encodeUint8: function(value: uint32): string ``` `@readonly` Encodes a unsigned 8-bit integer using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `uint32` | | ##### Returns | Type | Description | | --- | --- | | `string` | | #### `decodeInt8` _method_ ```nupp decodeInt8: function(bytes: string): int32 ``` `@readonly` Decodes a signed 8-bit integer using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ##### Returns | Type | Description | | --- | --- | | `int32` | | #### `encodeInt8` _method_ ```nupp encodeInt8: function(value: int32): string ``` `@readonly` Encodes a signed 8-bit integer using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `int32` | | ##### Returns | Type | Description | | --- | --- | | `string` | | #### `decodeUint16` _method_ ```nupp decodeUint16: function(bytes: string): uint32 ``` `@readonly` Decodes a unsigned 16-bit integer using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ##### Returns | Type | Description | | --- | --- | | `uint32` | | #### `encodeUint16` _method_ ```nupp encodeUint16: function(value: uint32): string ``` `@readonly` Encodes a unsigned 16-bit integer using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `uint32` | | ##### Returns | Type | Description | | --- | --- | | `string` | | #### `decodeInt16` _method_ ```nupp decodeInt16: function(bytes: string): int32 ``` `@readonly` Decodes a signed 16-bit integer using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ##### Returns | Type | Description | | --- | --- | | `int32` | | #### `encodeInt16` _method_ ```nupp encodeInt16: function(value: int32): string ``` `@readonly` Encodes a signed 16-bit integer using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `int32` | | ##### Returns | Type | Description | | --- | --- | | `string` | | #### `decodeUint32` _method_ ```nupp decodeUint32: function(bytes: string): uint32 ``` `@readonly` Decodes a unsigned 32-bit integer using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ##### Returns | Type | Description | | --- | --- | | `uint32` | | #### `encodeUint32` _method_ ```nupp encodeUint32: function(value: uint32): string ``` `@readonly` Encodes a unsigned 32-bit integer using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `uint32` | | ##### Returns | Type | Description | | --- | --- | | `string` | | #### `decodeInt32` _method_ ```nupp decodeInt32: function(bytes: string): int32 ``` `@readonly` Decodes a signed 32-bit integer using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ##### Returns | Type | Description | | --- | --- | | `int32` | | #### `encodeInt32` _method_ ```nupp encodeInt32: function(value: int32): string ``` `@readonly` Encodes a signed 32-bit integer using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `int32` | | ##### Returns | Type | Description | | --- | --- | | `string` | | #### `decodeUint64` _method_ ```nupp decodeUint64: function(bytes: string): uint64 ``` `@readonly` Decodes a unsigned 64-bit integer using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ##### Returns | Type | Description | | --- | --- | | `uint64` | | #### `encodeUint64` _method_ ```nupp encodeUint64: function(value: uint64): string ``` `@readonly` Encodes a unsigned 64-bit integer using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `uint64` | | ##### Returns | Type | Description | | --- | --- | | `string` | | #### `decodeInt64` _method_ ```nupp decodeInt64: function(bytes: string): int64 ``` `@readonly` Decodes a signed 64-bit integer using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ##### Returns | Type | Description | | --- | --- | | `int64` | | #### `encodeInt64` _method_ ```nupp encodeInt64: function(value: int64): string ``` `@readonly` Encodes a signed 64-bit integer using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `int64` | | ##### Returns | Type | Description | | --- | --- | | `string` | | #### `decodeFloat32` _method_ ```nupp decodeFloat32: function(bytes: string): float ``` `@readonly` Decodes an IEEE-754 binary32 value using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ##### Returns | Type | Description | | --- | --- | | `float` | | #### `encodeFloat32` _method_ ```nupp encodeFloat32: function(value: number): string ``` `@readonly` Encodes an IEEE-754 binary32 value using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `number` | | ##### Returns | Type | Description | | --- | --- | | `string` | | #### `decodeFloat64` _method_ ```nupp decodeFloat64: function(bytes: string): number ``` `@readonly` Decodes an IEEE-754 binary64 value using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ##### Returns | Type | Description | | --- | --- | | `number` | | #### `encodeFloat64` _method_ ```nupp encodeFloat64: function(value: number): string ``` `@readonly` Encodes an IEEE-754 binary64 value using the target storage byte order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `number` | | ##### Returns | Type | Description | | --- | --- | | `string` | | ### `StructvalueProvider` _interface_ ```nupp interface StructvalueProvider ... ``` Struct-value operations supplied as part of the storage family. Descriptors, arrays, and constructed values must agree with compiler layouts and canonical struct declarations. referenceValued reports whether a row reference addresses the underlying storage. The storage implementation supplies compatible struct operations as part of the same family. #### Members | Name | Kind | Description | | --- | --- | --- | | [`scalar`](#nupp.mem.representation.spi.StructvalueProvider.scalar) | method | Returns a scalar descriptor accepted by define and array. | | [`array`](#nupp.mem.representation.spi.StructvalueProvider.array) | method | Allocates count elements using this family's element descriptor. | | [`define`](#nupp.mem.representation.spi.StructvalueProvider.define) | method | Constructs a type descriptor from a compiler layout and method table. | | [`referenceValued`](#nupp.mem.representation.spi.StructvalueProvider.referenceValued) | field | Whether row references address their underlying storage. | #### `scalar` _method_ ```nupp scalar: function(kind: string): any ``` `@readonly` Returns a scalar descriptor accepted by define and array. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `kind` | `string` | | ##### Returns | Type | Description | | --- | --- | | `any` | | #### `array` _method_ ```nupp array: function(element: any, count: integer): any ``` `@readonly` Allocates count elements using this family's element descriptor. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `element` | `any` | | | `count` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `any` | | #### `define` _method_ ```nupp define: function(layout: any, methods: table): any ``` `@readonly` Constructs a type descriptor from a compiler layout and method table. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `layout` | `any` | | | `methods` | `table` | | ##### Returns | Type | Description | | --- | --- | | `any` | | #### `referenceValued` _field_ ```nupp referenceValued: boolean ``` `@readonly` Whether row references address their underlying storage.