<a id="nupp.simd"></a>
# `nupp.simd`

## Types

<a id="nupp.simd.BlockU8x64"></a>
### `BlockU8x64` _interface_

```nupp
sealed interface simd.BlockU8x64
    andByte: function(borrows self: BlockU8x64, value: uint32): simd.BlockU8x64

    andBits: function(borrows self: BlockU8x64, other: BlockU8x64): simd.BlockU8x64
    shiftRight: function(borrows self: BlockU8x64, count: uint32): simd.BlockU8x64
    lookup16: function(borrows self: BlockU8x64, table: simd.TableU8x16): simd.BlockU8x64
    anyBitsSet: function(borrows self: BlockU8x64, value: uint32): simd.MaskBits64
    lastVector: function(borrows self: BlockU8x64): simd.VectorU8
    utf8Errors: function(
        borrows self: BlockU8x64,
        previous: simd.VectorU8,
        byte1High: simd.TableU8x16,
        byte1Low: simd.TableU8x16,
        byte2High: simd.TableU8x16
    ): simd.MaskBits64

    equal: function(borrows self: BlockU8x64, value: uint32): simd.MaskBits64
    equalAny6: function(
        borrows self: BlockU8x64,
        v0: uint32,
        v1: uint32,
        v2: uint32,
        v3: uint32,
        v4: uint32,
        v5: uint32
    ): simd.MaskBits64
    inRange: function(borrows self: BlockU8x64, low: uint32, high: uint32): simd.MaskBits64
    outsideRange: function(borrows self: BlockU8x64, low: uint32, high: uint32): simd.MaskBits64
end
```

Four adjacent preferred-width registers covering exactly 64 bytes.

Block comparisons return one target-independent bitmap, so scanners can
classify a cache-line-sized unit without publishing intermediate register
masks through scalar Nupp values.

#### Methods

<a id="nupp.simd.BlockU8x64.andByte"></a>
##### `andByte`

```nupp
andByte: function(borrows self: BlockU8x64, value: uint32): simd.BlockU8x64
```

Applies one byte mask to every lane in all four registers.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `BlockU8x64` |  |
| `value` | `uint32` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.BlockU8x64` |  |

<a id="nupp.simd.BlockU8x64.andBits"></a>
##### `andBits`

```nupp
andBits: function(borrows self: BlockU8x64, other: BlockU8x64): simd.BlockU8x64
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `BlockU8x64` |  |
| `other` | `BlockU8x64` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.BlockU8x64` |  |

<a id="nupp.simd.BlockU8x64.shiftRight"></a>
##### `shiftRight`

```nupp
shiftRight: function(borrows self: BlockU8x64, count: uint32): simd.BlockU8x64
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `BlockU8x64` |  |
| `count` | `uint32` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.BlockU8x64` |  |

<a id="nupp.simd.BlockU8x64.lookup16"></a>
##### `lookup16`

```nupp
lookup16: function(borrows self: BlockU8x64, table: simd.TableU8x16): simd.BlockU8x64
```

Looks up every lane in the same immutable 16-byte table.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `BlockU8x64` |  |
| `table` | `simd.TableU8x16` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.BlockU8x64` |  |

<a id="nupp.simd.BlockU8x64.anyBitsSet"></a>
##### `anyBitsSet`

```nupp
anyBitsSet: function(borrows self: BlockU8x64, value: uint32): simd.MaskBits64
```

Returns one bit for each lane having any bit in `value` set.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `BlockU8x64` |  |
| `value` | `uint32` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskBits64` |  |

<a id="nupp.simd.BlockU8x64.lastVector"></a>
##### `lastVector`

```nupp
lastVector: function(borrows self: BlockU8x64): simd.VectorU8
```

Returns the final preferred-width register for cross-block carry.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `BlockU8x64` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.VectorU8` |  |

<a id="nupp.simd.BlockU8x64.utf8Errors"></a>
##### `utf8Errors`

```nupp
utf8Errors: function(
    borrows self: BlockU8x64,
    previous: simd.VectorU8,
    byte1High: simd.TableU8x16,
    byte1Low: simd.TableU8x16,
    byte2High: simd.TableU8x16
): simd.MaskBits64
```

Applies the lookup4 UTF-8 validator across the whole block.

`previous` is the final preferred-width register before this block. The
three tables are the high and low nibble classes for byte one and the
high nibble classes for byte two. Set result bits identify invalid byte
positions in this block.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `BlockU8x64` |  |
| `previous` | `simd.VectorU8` |  |
| `byte1High` | `simd.TableU8x16` |  |
| `byte1Low` | `simd.TableU8x16` |  |
| `byte2High` | `simd.TableU8x16` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskBits64` |  |

<a id="nupp.simd.BlockU8x64.equal"></a>
##### `equal`

```nupp
equal: function(borrows self: BlockU8x64, value: uint32): simd.MaskBits64
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `BlockU8x64` |  |
| `value` | `uint32` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskBits64` |  |

<a id="nupp.simd.BlockU8x64.equalAny6"></a>
##### `equalAny6`

```nupp
equalAny6: function(
    borrows self: BlockU8x64,
    v0: uint32,
    v1: uint32,
    v2: uint32,
    v3: uint32,
    v4: uint32,
    v5: uint32
): simd.MaskBits64
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `BlockU8x64` |  |
| `v0` | `uint32` |  |
| `v1` | `uint32` |  |
| `v2` | `uint32` |  |
| `v3` | `uint32` |  |
| `v4` | `uint32` |  |
| `v5` | `uint32` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskBits64` |  |

<a id="nupp.simd.BlockU8x64.inRange"></a>
##### `inRange`

```nupp
inRange: function(borrows self: BlockU8x64, low: uint32, high: uint32): simd.MaskBits64
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `BlockU8x64` |  |
| `low` | `uint32` |  |
| `high` | `uint32` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskBits64` |  |

<a id="nupp.simd.BlockU8x64.outsideRange"></a>
##### `outsideRange`

```nupp
outsideRange: function(borrows self: BlockU8x64, low: uint32, high: uint32): simd.MaskBits64
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `BlockU8x64` |  |
| `low` | `uint32` |  |
| `high` | `uint32` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskBits64` |  |

<a id="nupp.simd.MaskBits64"></a>
### `MaskBits64` _interface_

```nupp
sealed interface simd.MaskBits64
    add: function(borrows self: MaskBits64, other: MaskBits64): simd.MaskBits64

    andBits: function(borrows self: MaskBits64, other: MaskBits64): simd.MaskBits64
    orBits: function(borrows self: MaskBits64, other: MaskBits64): simd.MaskBits64
    xorBits: function(borrows self: MaskBits64, other: MaskBits64): simd.MaskBits64
    notBits: function(borrows self: MaskBits64): simd.MaskBits64
    shiftLeft: function(borrows self: MaskBits64, count: uint32): simd.MaskBits64
    shiftRight: function(borrows self: MaskBits64, count: uint32): simd.MaskBits64
    prefixXor: function(borrows self: MaskBits64, carry: boolean): simd.MaskBits64
    lowBits: function(borrows self: MaskBits64): uint32
    highBits: function(borrows self: MaskBits64): uint32
    any: function(borrows self: MaskBits64): boolean
    count: function(borrows self: MaskBits64): uint32
    firstSet: function(borrows self: MaskBits64): uint32
    clearFirst: function(borrows self: MaskBits64): simd.MaskBits64
end
```

A target-independent 64-bit predicate bitmap.

This is deliberately not a general `uint64`: ordinary Nupp numbers retain
their LuaJIT representation and exactness rules. The two uint32 halves let
scanners combine register masks, carry prefix state across them, and drain
events without boxing cdata.

#### Methods

<a id="nupp.simd.MaskBits64.add"></a>
##### `add`

```nupp
add: function(borrows self: MaskBits64, other: MaskBits64): simd.MaskBits64
```

Adds with carry across the word boundary.

Present because run-parity over a block is stated as an addition: adding
a run's start bit to the run propagates a carry to the first bit past
its end, which is how a scanner tells an odd run of escapes from an even
one without walking the runs. Nothing else here carries between words.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskBits64` |  |
| `other` | `MaskBits64` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskBits64` |  |

<a id="nupp.simd.MaskBits64.andBits"></a>
##### `andBits`

```nupp
andBits: function(borrows self: MaskBits64, other: MaskBits64): simd.MaskBits64
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskBits64` |  |
| `other` | `MaskBits64` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskBits64` |  |

<a id="nupp.simd.MaskBits64.orBits"></a>
##### `orBits`

```nupp
orBits: function(borrows self: MaskBits64, other: MaskBits64): simd.MaskBits64
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskBits64` |  |
| `other` | `MaskBits64` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskBits64` |  |

<a id="nupp.simd.MaskBits64.xorBits"></a>
##### `xorBits`

```nupp
xorBits: function(borrows self: MaskBits64, other: MaskBits64): simd.MaskBits64
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskBits64` |  |
| `other` | `MaskBits64` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskBits64` |  |

<a id="nupp.simd.MaskBits64.notBits"></a>
##### `notBits`

```nupp
notBits: function(borrows self: MaskBits64): simd.MaskBits64
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskBits64` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskBits64` |  |

<a id="nupp.simd.MaskBits64.shiftLeft"></a>
##### `shiftLeft`

```nupp
shiftLeft: function(borrows self: MaskBits64, count: uint32): simd.MaskBits64
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskBits64` |  |
| `count` | `uint32` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskBits64` |  |

<a id="nupp.simd.MaskBits64.shiftRight"></a>
##### `shiftRight`

```nupp
shiftRight: function(borrows self: MaskBits64, count: uint32): simd.MaskBits64
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskBits64` |  |
| `count` | `uint32` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskBits64` |  |

<a id="nupp.simd.MaskBits64.prefixXor"></a>
##### `prefixXor`

```nupp
prefixXor: function(borrows self: MaskBits64, carry: boolean): simd.MaskBits64
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskBits64` |  |
| `carry` | `boolean` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskBits64` |  |

<a id="nupp.simd.MaskBits64.lowBits"></a>
##### `lowBits`

```nupp
lowBits: function(borrows self: MaskBits64): uint32
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskBits64` |  |

###### Returns

| Type | Description |
| --- | --- |
| `uint32` |  |

<a id="nupp.simd.MaskBits64.highBits"></a>
##### `highBits`

```nupp
highBits: function(borrows self: MaskBits64): uint32
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskBits64` |  |

###### Returns

| Type | Description |
| --- | --- |
| `uint32` |  |

<a id="nupp.simd.MaskBits64.any"></a>
##### `any`

```nupp
any: function(borrows self: MaskBits64): boolean
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskBits64` |  |

###### Returns

| Type | Description |
| --- | --- |
| `boolean` |  |

<a id="nupp.simd.MaskBits64.count"></a>
##### `count`

```nupp
count: function(borrows self: MaskBits64): uint32
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskBits64` |  |

###### Returns

| Type | Description |
| --- | --- |
| `uint32` |  |

<a id="nupp.simd.MaskBits64.firstSet"></a>
##### `firstSet`

```nupp
firstSet: function(borrows self: MaskBits64): uint32
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskBits64` |  |

###### Returns

| Type | Description |
| --- | --- |
| `uint32` |  |

<a id="nupp.simd.MaskBits64.clearFirst"></a>
##### `clearFirst`

```nupp
clearFirst: function(borrows self: MaskBits64): simd.MaskBits64
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskBits64` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskBits64` |  |

<a id="nupp.simd.MaskU8"></a>
### `MaskU8` _interface_

```nupp
sealed interface simd.MaskU8
    andBits: function(borrows self: MaskU8, other: MaskU8): simd.MaskU8
    orBits: function(borrows self: MaskU8, other: MaskU8): simd.MaskU8
    xorBits: function(borrows self: MaskU8, other: MaskU8): simd.MaskU8
    notBits: function(borrows self: MaskU8): simd.MaskU8
    select: function(borrows self: MaskU8, whenTrue: simd.VectorU8, whenFalse: simd.VectorU8): simd.VectorU8
    any: function(borrows self: MaskU8): boolean
    all: function(borrows self: MaskU8): boolean
    count: function(borrows self: MaskU8): uint32
    bits: function(borrows self: MaskU8): uint32
end
```

One predicate bit per logical vector lane.

#### Methods

<a id="nupp.simd.MaskU8.andBits"></a>
##### `andBits`

```nupp
andBits: function(borrows self: MaskU8, other: MaskU8): simd.MaskU8
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskU8` |  |
| `other` | `MaskU8` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskU8` |  |

<a id="nupp.simd.MaskU8.orBits"></a>
##### `orBits`

```nupp
orBits: function(borrows self: MaskU8, other: MaskU8): simd.MaskU8
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskU8` |  |
| `other` | `MaskU8` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskU8` |  |

<a id="nupp.simd.MaskU8.xorBits"></a>
##### `xorBits`

```nupp
xorBits: function(borrows self: MaskU8, other: MaskU8): simd.MaskU8
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskU8` |  |
| `other` | `MaskU8` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskU8` |  |

<a id="nupp.simd.MaskU8.notBits"></a>
##### `notBits`

```nupp
notBits: function(borrows self: MaskU8): simd.MaskU8
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskU8` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskU8` |  |

<a id="nupp.simd.MaskU8.select"></a>
##### `select`

```nupp
select: function(borrows self: MaskU8, whenTrue: simd.VectorU8, whenFalse: simd.VectorU8): simd.VectorU8
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskU8` |  |
| `whenTrue` | `simd.VectorU8` |  |
| `whenFalse` | `simd.VectorU8` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.VectorU8` |  |

<a id="nupp.simd.MaskU8.any"></a>
##### `any`

```nupp
any: function(borrows self: MaskU8): boolean
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskU8` |  |

###### Returns

| Type | Description |
| --- | --- |
| `boolean` |  |

<a id="nupp.simd.MaskU8.all"></a>
##### `all`

```nupp
all: function(borrows self: MaskU8): boolean
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskU8` |  |

###### Returns

| Type | Description |
| --- | --- |
| `boolean` |  |

<a id="nupp.simd.MaskU8.count"></a>
##### `count`

```nupp
count: function(borrows self: MaskU8): uint32
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskU8` |  |

###### Returns

| Type | Description |
| --- | --- |
| `uint32` |  |

<a id="nupp.simd.MaskU8.bits"></a>
##### `bits`

```nupp
bits: function(borrows self: MaskU8): uint32
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `MaskU8` |  |

###### Returns

| Type | Description |
| --- | --- |
| `uint32` |  |

<a id="nupp.simd.PaddedStringU8"></a>
### `PaddedStringU8` _interface_

```nupp
sealed interface simd.PaddedStringU8
    readonly length: uint32
    readonly fullLength: uint32
    readonly tailLength: uint32
    loadFull: function(borrows self: PaddedStringU8, offset: uint32): simd.VectorU8
    loadTail: function(borrows self: PaddedStringU8): simd.VectorU8
    loadBlock64: function(borrows self: PaddedStringU8, offset: uint32): simd.BlockU8x64
end
```

A rooted string split into complete blocks and one zero-padded
final block. The view exists only for the duration of its AOT entry.

#### Methods

<a id="nupp.simd.PaddedStringU8.loadFull"></a>
##### `loadFull`

```nupp
loadFull: function(borrows self: PaddedStringU8, offset: uint32): simd.VectorU8
```

Loads a complete block. The offset must be below `fullLength` and
aligned to the preferred species width.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `PaddedStringU8` |  |
| `offset` | `uint32` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.VectorU8` |  |

<a id="nupp.simd.PaddedStringU8.loadTail"></a>
##### `loadTail`

```nupp
loadTail: function(borrows self: PaddedStringU8): simd.VectorU8
```

Loads the sole incomplete block, already copied and zero padded.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `PaddedStringU8` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.VectorU8` |  |

<a id="nupp.simd.PaddedStringU8.loadBlock64"></a>
##### `loadBlock64`

```nupp
loadBlock64: function(borrows self: PaddedStringU8, offset: uint32): simd.BlockU8x64
```

Loads 64 complete bytes at an aligned offset. An unavailable block is
zero, on the same defensive terms as `loadFull`; scanners normally call
this only after proving `offset + 64 <= length`.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `PaddedStringU8` |  |
| `offset` | `uint32` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.BlockU8x64` |  |

#### Fields

<a id="nupp.simd.PaddedStringU8.length"></a>
##### `length`

```nupp
length: uint32
```

<a id="nupp.simd.PaddedStringU8.fullLength"></a>
##### `fullLength`

```nupp
fullLength: uint32
```

<a id="nupp.simd.PaddedStringU8.tailLength"></a>
##### `tailLength`

```nupp
tailLength: uint32
```

<a id="nupp.simd.SpeciesU8"></a>
### `SpeciesU8` _interface_

```nupp
sealed interface simd.SpeciesU8
    readonly lanes: integer
    splat: function(borrows self: SpeciesU8, value: uint32): simd.VectorU8
    load: function(borrows self: SpeciesU8, borrows source: Span<uint8>, offset: integer): simd.VectorU8
    loadString: function(borrows self: SpeciesU8, source: string, offset: integer): simd.VectorU8
    loadStrided3: function(borrows self: SpeciesU8, source: string, offset: uint32, lane: uint32): simd.VectorU8
    tail: function(borrows self: SpeciesU8, active: integer): simd.MaskU8
end
```

The preferred register-sized operation set for one element type.

#### Methods

<a id="nupp.simd.SpeciesU8.splat"></a>
##### `splat`

```nupp
splat: function(borrows self: SpeciesU8, value: uint32): simd.VectorU8
```

Broadcasts the low byte of `value` to every lane.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `SpeciesU8` |  |
| `value` | `uint32` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.VectorU8` |  |

<a id="nupp.simd.SpeciesU8.load"></a>
##### `load`

```nupp
load: function(borrows self: SpeciesU8, borrows source: Span<uint8>, offset: integer): simd.VectorU8
```

Loads at a zero-based offset. Inactive final lanes are zero and are
excluded by `tail`; the implementation never reads beyond the span.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `SpeciesU8` |  |
| `borrows source` | `Span\<uint8\>` |  |
| `offset` | `integer` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.VectorU8` |  |

<a id="nupp.simd.SpeciesU8.loadString"></a>
##### `loadString`

```nupp
loadString: function(borrows self: SpeciesU8, source: string, offset: integer): simd.VectorU8
```

Loads directly from a string rooted by a Lua-builder AOT entry. This is
the VM-aware counterpart of `load`: storage remains owned and pinned by
Lua for the duration of the native call.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `SpeciesU8` |  |
| `source` | `string` |  |
| `offset` | `integer` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.VectorU8` |  |

<a id="nupp.simd.SpeciesU8.loadStrided3"></a>
##### `loadStrided3`

```nupp
loadStrided3: function(borrows self: SpeciesU8, source: string, offset: uint32, lane: uint32): simd.VectorU8
```

Loads one lane of a three-byte interleaved group from a rooted string.

`lane` selects which byte of each group is collected: 0 gathers bytes
0, 3, 6 and so on, 1 gathers 1, 4, 7, and 2 gathers 2, 5, 8. Three
calls at the same offset therefore de-interleave `3 * lanes` bytes into
three registers, which is the shape a codec over three-byte groups
wants and the shape aarch64's `ld3` already produces.

A group that would read past the string contributes zero, on the same
defensive terms as the other loads here.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `SpeciesU8` |  |
| `source` | `string` |  |
| `offset` | `uint32` |  |
| `lane` | `uint32` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.VectorU8` |  |

<a id="nupp.simd.SpeciesU8.tail"></a>
##### `tail`

```nupp
tail: function(borrows self: SpeciesU8, active: integer): simd.MaskU8
```

A mask with the first `active` lanes set, clamped to this species.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `SpeciesU8` |  |
| `active` | `integer` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskU8` |  |

#### Fields

<a id="nupp.simd.SpeciesU8.lanes"></a>
##### `lanes`

```nupp
lanes: integer
```

<a id="nupp.simd.TableU8x16"></a>
### `TableU8x16` _interface_

```nupp
sealed interface simd.TableU8x16
end
```

One immutable 16-byte lookup table embedded in generated native code.

<a id="nupp.simd.VectorU8"></a>
### `VectorU8` _interface_

```nupp
sealed interface simd.VectorU8
    equal: function(borrows self: VectorU8, value: uint32): simd.MaskU8
    inRange: function(borrows self: VectorU8, low: uint32, high: uint32): simd.MaskU8
    andBits: function(borrows self: VectorU8, other: VectorU8): simd.VectorU8
    orBits: function(borrows self: VectorU8, other: VectorU8): simd.VectorU8
    xorBits: function(borrows self: VectorU8, other: VectorU8): simd.VectorU8
    notBits: function(borrows self: VectorU8): simd.VectorU8
    shiftRight: function(borrows self: VectorU8, count: uint32): simd.VectorU8
    shiftLeft: function(borrows self: VectorU8, count: uint32): simd.VectorU8
    lookup16: function(borrows self: VectorU8, table: simd.TableU8x16): simd.VectorU8
    lookup64: function(
        borrows self: VectorU8,
        low: simd.TableU8x16,
        lowMid: simd.TableU8x16,
        highMid: simd.TableU8x16,
        high: simd.TableU8x16
    ): simd.VectorU8
end
```

One immutable packed value for the preferred target species.

#### Methods

<a id="nupp.simd.VectorU8.equal"></a>
##### `equal`

```nupp
equal: function(borrows self: VectorU8, value: uint32): simd.MaskU8
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `VectorU8` |  |
| `value` | `uint32` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskU8` |  |

<a id="nupp.simd.VectorU8.inRange"></a>
##### `inRange`

```nupp
inRange: function(borrows self: VectorU8, low: uint32, high: uint32): simd.MaskU8
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `VectorU8` |  |
| `low` | `uint32` |  |
| `high` | `uint32` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.MaskU8` |  |

<a id="nupp.simd.VectorU8.andBits"></a>
##### `andBits`

```nupp
andBits: function(borrows self: VectorU8, other: VectorU8): simd.VectorU8
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `VectorU8` |  |
| `other` | `VectorU8` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.VectorU8` |  |

<a id="nupp.simd.VectorU8.orBits"></a>
##### `orBits`

```nupp
orBits: function(borrows self: VectorU8, other: VectorU8): simd.VectorU8
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `VectorU8` |  |
| `other` | `VectorU8` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.VectorU8` |  |

<a id="nupp.simd.VectorU8.xorBits"></a>
##### `xorBits`

```nupp
xorBits: function(borrows self: VectorU8, other: VectorU8): simd.VectorU8
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `VectorU8` |  |
| `other` | `VectorU8` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.VectorU8` |  |

<a id="nupp.simd.VectorU8.notBits"></a>
##### `notBits`

```nupp
notBits: function(borrows self: VectorU8): simd.VectorU8
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `VectorU8` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.VectorU8` |  |

<a id="nupp.simd.VectorU8.shiftRight"></a>
##### `shiftRight`

```nupp
shiftRight: function(borrows self: VectorU8, count: uint32): simd.VectorU8
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `VectorU8` |  |
| `count` | `uint32` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.VectorU8` |  |

<a id="nupp.simd.VectorU8.shiftLeft"></a>
##### `shiftLeft`

```nupp
shiftLeft: function(borrows self: VectorU8, count: uint32): simd.VectorU8
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `VectorU8` |  |
| `count` | `uint32` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.VectorU8` |  |

<a id="nupp.simd.VectorU8.lookup16"></a>
##### `lookup16`

```nupp
lookup16: function(borrows self: VectorU8, table: simd.TableU8x16): simd.VectorU8
```

Looks up every lane in one immutable 16-byte table. Indexes outside
0..15 produce zero, matching the native table instructions.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `VectorU8` |  |
| `table` | `simd.TableU8x16` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.VectorU8` |  |

<a id="nupp.simd.VectorU8.lookup64"></a>
##### `lookup64`

```nupp
lookup64: function(
    borrows self: VectorU8,
    low: simd.TableU8x16,
    lowMid: simd.TableU8x16,
    highMid: simd.TableU8x16,
    high: simd.TableU8x16
): simd.VectorU8
```

Looks up every lane in four immutable 16-byte tables read as one
64-entry table. Indexes outside 0..63 produce zero.

Four tables rather than a 64-entry type because that is the shape the
instruction takes: aarch64 spends one `tbl` on it, and it is the lookup
a six-bit alphabet wants. On x86 it is built from the nibble lookup and
a blend, which is what AVX-512 VBMI's `vpermb` exists to replace.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `VectorU8` |  |
| `low` | `simd.TableU8x16` |  |
| `lowMid` | `simd.TableU8x16` |  |
| `highMid` | `simd.TableU8x16` |  |
| `high` | `simd.TableU8x16` |  |

###### Returns

| Type | Description |
| --- | --- |
| `simd.VectorU8` |  |

## Functions

<a id="nupp.simd.alignBytes"></a>
### `alignBytes` _function_

```nupp
function alignBytes(previous: any, current: any, offset: number): any
```

Aligns `previous .. current`, bringing the last `offset` bytes of the
previous vector into the beginning of the result. Offsets 1..3 are
admitted because they are the cross-block lookback needed by UTF-8 scans.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `previous` | `any` |  |
| `current` | `any` |  |
| `offset` | `number` |  |

#### Returns

| Type | Description |
| --- | --- |
| `any` |  |

<a id="nupp.simd.maskBits64"></a>
### `maskBits64` _function_

```nupp
function maskBits64(low: number, high: number): any
```

Combines low and high uint32 words into an 64-bit mask.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `low` | `number` |  |
| `high` | `number` |  |

#### Returns

| Type | Description |
| --- | --- |
| `any` |  |

<a id="nupp.simd.paddedStringU8"></a>
### `paddedStringU8` _function_

```nupp
function paddedStringU8(source: string): any
```

Roots a Lua string and prepares its one incomplete preferred-width block.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `source` | `string` |  |

#### Returns

| Type | Description |
| --- | --- |
| `any` |  |

<a id="nupp.simd.preferredU8"></a>
### `preferredU8` _function_

```nupp
function preferredU8(): any
```

Selects the artifact tier's preferred packed byte species.

#### Returns

| Type | Description |
| --- | --- |
| `any` |  |

<a id="nupp.simd.paddedBytesU8"></a>
### `simd.paddedBytesU8` _function_

```nupp
function simd.paddedBytesU8(borrows source: any): simd.PaddedStringU8
```

Roots either a Lua string or a borrowed string buffer for a padded read.
This union exists only at a Lua-builder AOT boundary.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows source` | `any` |  |

#### Returns

| Type | Description |
| --- | --- |
| `simd.PaddedStringU8` |  |

#### Raises

- outside an AOT-compiled function

<a id="nupp.simd.storeInterleaved4"></a>
### `simd.storeInterleaved4` _function_

```nupp
function simd.storeInterleaved4(scratch: any, offset: uint32, first: simd.VectorU8, second: simd.VectorU8, third: simd.VectorU8, fourth: simd.VectorU8): nil
```

Writes four registers interleaved into a byte scratch.

Lane `i` of each register lands at `offset + 4i` through `offset + 4i + 3`,
which is the inverse of the three-lane strided load and the shape a codec
emitting four-byte groups produces. aarch64 spends one `st4` on it.

Appends when `offset` is the scratch's current length and overwrites below
it, on the same terms as `nupp.codec.valuebuilder.setScratchBytes4`.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `scratch` | `any` |  |
| `offset` | `uint32` |  |
| `first` | `simd.VectorU8` |  |
| `second` | `simd.VectorU8` |  |
| `third` | `simd.VectorU8` |  |
| `fourth` | `simd.VectorU8` |  |

#### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

#### Raises

- outside an AOT-compiled function

<a id="nupp.simd.tableU8x16"></a>
### `tableU8x16` _function_

```nupp
function tableU8x16(...): any
```

Embeds one immutable 16-byte lookup table in an AOT entry.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `...` | `any` |  |

#### Returns

| Type | Description |
| --- | --- |
| `any` |  |