<a id="nupp.mem.sharedbytes"></a>
# `nupp.mem.sharedbytes`

Engine-owned immutable byte regions.

A region names an extent of one reference-counted engine block. It crosses
worker boundaries by reference, slices without copying, and is read in place
through a borrowed `nupp.mem.span` byte view; converting it to a Lua string
is one explicit call. See NEP 20.

```nupp
const sharedbytes = nupp.mem.sharedbytes

const region = sharedbytes.copy("hello, region")
const hello = region:slice(1, 5)
assert(hello:size() == 5 and hello:text() == "hello")
```

A producer that has bytes only behind a pointer writes into builder storage
directly through a reserve-and-commit pair, with no intermediate chunk string:

```nupp
const sharedbytes = nupp.mem.sharedbytes

local builder = sharedbytes.builder()
with writer = builder:reserve(5) do
    for index = 1, 5 do
        writer[index] = 64 + index
    end
end
builder:commit(5)
builder:append("!")
assert(builder:freeze():text() == "ABCDE!")
```

## Types

<a id="nupp.mem.sharedbytes.Builder"></a>
### `Builder` _record_

```nupp
record sharedbytes.Builder is sharedbytes.BuilderToken
    append: nosuspend function(sharedbytes.Builder, string): nil
    reserve: function(exclusive self: sharedbytes.Builder, integer): span.Writable<uint8> borrows (self)
    commit: nosuspend function(sharedbytes.Builder, integer): nil
    freeze: nosuspend function(takes self: sharedbytes.Builder): sharedbytes.Region
    drop: nosuspend function(takes self: sharedbytes.Builder): nil
end
```

A growable engine allocation that becomes a region when frozen.

#### Methods

<a id="nupp.mem.sharedbytes.Builder.append"></a>
##### `append`

```nupp
append: nosuspend function(sharedbytes.Builder, string): nil
```

Appends the chunk's bytes to the builder's storage.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `?` | `sharedbytes.Builder` |  |
| `?` | `string` |  |

###### Returns

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

###### Raises

- when a reservation is open or the engine cannot grow the storage

<a id="nupp.mem.sharedbytes.Builder.reserve"></a>
##### `reserve`

```nupp
reserve: function(exclusive self: sharedbytes.Builder, integer): span.Writable<uint8> borrows (self)
```

Grows the storage and lends a checked writer over exactly `count`
uninitialized bytes past what is already committed. All growth happens
here, before the writer exists, and the borrow keeps every other
builder operation a compile error while the writer lives, so the lent
pointer cannot be invalidated. One `commit` closes the reservation
after the writer drops.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `exclusive self` | `sharedbytes.Builder` |  |
| `?` | `integer` |  |

###### Returns

| Type | Description |
| --- | --- |
| `span.Writable\<uint8\> borrows (self)` |  |

###### Raises

- when the count is negative, a reservation is already open, or the engine cannot grow the storage

<a id="nupp.mem.sharedbytes.Builder.commit"></a>
##### `commit`

```nupp
commit: nosuspend function(sharedbytes.Builder, integer): nil
```

Closes the open reservation, keeping its first `written` bytes as
content; a short read commits what arrived, and the surplus returns to
capacity for the next reservation.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `?` | `sharedbytes.Builder` |  |
| `?` | `integer` |  |

###### Returns

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

###### Raises

- when no reservation is open or `written` exceeds it

<a id="nupp.mem.sharedbytes.Builder.freeze"></a>
##### `freeze`

```nupp
freeze: nosuspend function(takes self: sharedbytes.Builder): sharedbytes.Region
```

Consumes the builder and transfers its allocation into a region.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `takes self` | `sharedbytes.Builder` |  |

###### Returns

| Type | Description |
| --- | --- |
| `sharedbytes.Region` |  |

###### Raises

- when the builder was already frozen or a reservation is open, because sealing would silently drop bytes a producer may have written

<a id="nupp.mem.sharedbytes.Builder.drop"></a>
##### `drop`

```nupp
drop: nosuspend function(takes self: sharedbytes.Builder): nil
```

Releases an unfrozen builder's storage at scope exit.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `takes self` | `sharedbytes.Builder` |  |

###### Returns

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

<a id="nupp.mem.sharedbytes.BuilderToken"></a>
### `BuilderToken` _interface_

```nupp
affine interface sharedbytes.BuilderToken
    terminal drop: nosuspend function(takes self: sharedbytes.BuilderToken): nil
end
```

An affine accumulator of engine storage. Appending grows one private
allocation, and freezing transfers it into a region without copying.

#### Methods

<a id="nupp.mem.sharedbytes.BuilderToken.drop"></a>
##### `drop`

```nupp
drop: nosuspend function(takes self: sharedbytes.BuilderToken): nil
```

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `takes self` | `sharedbytes.BuilderToken` |  |

###### Returns

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

<a id="nupp.mem.sharedbytes.Region"></a>
### `Region` _record_

```nupp
record sharedbytes.Region
    size: nosuspend function(sharedbytes.Region): integer
    slice: function(sharedbytes.Region, integer, integer): sharedbytes.Region
    view: function(borrows self: sharedbytes.Region, integer?, integer?): span.ByteSpan borrows (self)
    viewAs: function<T>(borrows self: sharedbytes.Region, ctype<T>): span.Span<T> borrows (self)
    text: nosuspend function(sharedbytes.Region): string
end
```

An immutable extent of one engine-owned block. Crossing a worker boundary
moves a reference, never the bytes; reading happens in place through a
borrowed byte view, and `text` is the one explicit copy into a Lua state.

#### Methods

<a id="nupp.mem.sharedbytes.Region.size"></a>
##### `size`

```nupp
size: nosuspend function(sharedbytes.Region): integer
```

How many bytes the region holds.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `?` | `sharedbytes.Region` |  |

###### Returns

| Type | Description |
| --- | --- |
| `integer` |  |

<a id="nupp.mem.sharedbytes.Region.slice"></a>
##### `slice`

```nupp
slice: function(sharedbytes.Region, integer, integer): sharedbytes.Region
```

A zero-copy region over bytes `first` through `last` of this one.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `?` | `sharedbytes.Region` |  |
| `?` | `integer` |  |
| `?` | `integer` |  |

###### Returns

| Type | Description |
| --- | --- |
| `sharedbytes.Region` |  |

###### Raises

- when the bounds fall outside the region

<a id="nupp.mem.sharedbytes.Region.view"></a>
##### `view`

```nupp
view: function(borrows self: sharedbytes.Region, integer?, integer?): span.ByteSpan borrows (self)
```

A read-only borrowed view over the selected bytes, whole by default.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `sharedbytes.Region` |  |
| `?` | `integer?` |  |
| `?` | `integer?` |  |

###### Returns

| Type | Description |
| --- | --- |
| `span.ByteSpan borrows (self)` |  |

###### Raises

- when the bounds fall outside the region

<a id="nupp.mem.sharedbytes.Region.viewAs"></a>
##### `viewAs`

```nupp
viewAs: function<T>(borrows self: sharedbytes.Region, ctype<T>): span.Span<T> borrows (self)
```

A checked zero-copy view of the complete region as physical elements.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `borrows self` | `sharedbytes.Region` |  |
| `?` | `ctype\<T\>` |  |

###### Returns

| Type | Description |
| --- | --- |
| `span.Span\<T\> borrows (self)` |  |

###### Raises

- when the region is not aligned or is not a whole number of elements

<a id="nupp.mem.sharedbytes.Region.text"></a>
##### `text`

```nupp
text: nosuspend function(sharedbytes.Region): string
```

The region's bytes copied and interned as an ordinary string.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `?` | `sharedbytes.Region` |  |

###### Returns

| Type | Description |
| --- | --- |
| `string` |  |

###### Raises

- when the region's engine storage has been released

## Functions

<a id="nupp.mem.sharedbytes.builder"></a>
### `sharedbytes.builder` _function_

```nupp
function sharedbytes.builder(): affine(sharedbytes.Builder)
```

Opens an empty builder.

#### Returns

| Type | Description |
| --- | --- |
| `affine(sharedbytes.Builder)` |  |

#### Raises

- when the engine cannot allocate the builder

<a id="nupp.mem.sharedbytes.copy"></a>
### `sharedbytes.copy` _function_

```nupp
function sharedbytes.copy(text: string): sharedbytes.Region
```

Copies `text` once into an engine-owned region.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `text` | `string` |  |

#### Returns

| Type | Description |
| --- | --- |
| `sharedbytes.Region` |  |

#### Raises

- when the engine cannot allocate the region

<a id="nupp.mem.sharedbytes.readFile"></a>
### `sharedbytes.readFile` _function_

```nupp
function sharedbytes.readFile(path: string): sharedbytes.Region
```

Reads a whole file directly into an engine-owned region, with no
intermediate Lua string for the payload.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `path` | `string` |  |

#### Returns

| Type | Description |
| --- | --- |
| `sharedbytes.Region` |  |

#### Raises

- when the file cannot be opened, sized, or read