# Module: `nupp.span` Bounds-carrying borrowed pointer views. `ByteSpan` keeps a runtime element count beside a rooted pointer. Indexing and slicing check that count before the only unsafe pointer operations in this module. Public code never has to dereference or offset a raw pointer. ## Types ### `ByteSpan` _record_ A checked, shared view over contiguous elements. ```nupp local record ByteSpan readonly anchor: any readonly pointer: uint8[?] borrows anchor readonly offset: integer readonly count: integer end ``` #### Methods ##### `get` Returns one byte after checking the one-based index. ```nupp get: function ByteSpan:get(index: integer): uint8 ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `index` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `uint8` | | ###### Raises - when index is outside 1 through count ##### `slice` Returns a checked subspan, inclusive at both ends. ```nupp slice: function ByteSpan:slice(first: integer, last: integer?): ByteSpan borrows self ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `first` | `integer` | | | `last` | `integer?` | | ###### Returns | Type | Description | | --- | --- | | `ByteSpan borrows self` | | ###### Raises - when the requested range is outside this span #### Fields | Name | Type | Description | | --- | --- | --- | | `anchor` | `any` | | | `pointer` | `uint8\[?\] borrows anchor` | | | `offset` | `integer` | | | `count` | `integer` | | ### `ByteWriteSpan` _record_ An affine checked write range. Its live token keeps the source under an incompatible-borrow barrier until `commit` or scope exit consumes it. ```nupp local record ByteWriteSpan readonly anchor: any readonly pointer: uint8[?] borrows anchor readonly offset: integer readonly count: integer @drop function commit(takes self: ByteWriteSpan): nil end function set(self: ByteWriteSpan, index: integer, value: uint8): nil end end ``` #### Methods ##### `commit` ```nupp commit: function commit(takes self: ByteWriteSpan): nil ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `ByteWriteSpan` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `set` ```nupp set: function set(self: ByteWriteSpan, index: integer, value: uint8): nil ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `ByteWriteSpan` | | | `index` | `integer` | | | `value` | `uint8` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | #### Fields | Name | Type | Description | | --- | --- | --- | | `anchor` | `any` | | | `pointer` | `uint8\[?\] borrows anchor` | | | `offset` | `integer` | | | `count` | `integer` | | ## Functions ### `span.from_carray` _function_ Creates a checked shared span over a C array and an explicit logical count. ```nupp function span.from_carray(borrows source: uint8[?], count: integer): ByteSpan borrows source ``` #### Arguments | Name | Type | Description | | --- | --- | --- | | `source` | `uint8\[?\]` | | | `count` | `integer` | | #### Returns | Type | Description | | --- | --- | | `ByteSpan borrows source` | | #### Raises - when count is negative ### `span.from_string` _function_ Creates a byte span over a Lua string and keeps that string rooted. ```nupp function span.from_string(borrows source: string): ByteSpan borrows source ``` #### Arguments | Name | Type | Description | | --- | --- | --- | | `source` | `string` | | #### Returns | Type | Description | | --- | --- | | `ByteSpan borrows source` | | ### `span.write_carray` _function_ Creates an affine write span. The source is exclusive during construction and the returned dependent owner prevents invalidating operations until it is committed. ```nupp function span.write_carray(exclusive source: uint8[?], count: integer): ByteWriteSpan borrows source ``` #### Arguments | Name | Type | Description | | --- | --- | --- | | `source` | `uint8\[?\]` | | | `count` | `integer` | | #### Returns | Type | Description | | --- | --- | | `ByteWriteSpan borrows source` | | #### Raises - when count is negative