# Inputs and Outputs

> USearch for Swift

### Arenas

Every output whose length only the call knows, such as matches, rows, products, monoliths and cursor or stream batches, lands in an `Arena` you pass, and the verb answers a view over it without copying.
There is one verb per operation: no allocating twin, no caller buffers, and no default arena.
`Arena(on: executor)` places it where that executor computes, decided once, and `Arena()` makes host pages for the calling thread.
Each call rewinds its arena, so the previous call's views die and a steady loop allocates once it reaches its high-water mark.
To keep a result past the next call, or to read one while making the next, pass that call another arena.
An arena serves one call at a time, so each deferred call needs its own.
Views stay on the arena's thread, which the compiler checks, and reading a stale one traps as an out-of-bounds index does.
A view cannot be `~Escapable` while its lifetime annotation is still behind an experimental feature flag as of Swift 6.4, so it checks its arena at runtime instead.
An arena from a VRAM executor holds device memory, which host accessors refuse with a trap, and serves only that executor's calls, keeping the executor alive until the arena goes.

```swift
let arena = try Arena(on: executor)                                              // Arena() is host pages for the calling thread
for batch in batches {
    let matches = try index.on(executor).search(batch, wanted: 10, arena: arena) // rewinds: last batch's matches are gone
    total += matches.joined().reduce(0) { $0 + $1.distance }
}
let found = try Arena(), fetched = try Arena()                                   // two live results, two arenas
for match in try index.search(query, wanted: 10, arena: found)[0] {
    rerank(match.key, try index.get(key: match.key, as: Float.self, arena: fetched))
}
let calls = try shards.indices.map { at in
    try shards[at].deferred(executors[at]).search(queries, wanted: 10, arena: arenas[at]) // one executor and one arena per submitted call
}
var results: [Matches] = []
for call in calls { results.append(try await call.value) }                       // or: try call.wait()
```

A result keeps the arena it reads alive, so it outlives the index and the caller's reference alike.

### Rows & Scalars

A `RowsView` borrows a NumKong `MatrixView`, or keeps a NumKong `Tensor` alive.
A matrix view borrows and never owns, so it stays valid only for as long as the storage it points into, which is why a call over one sits inside a `withUnsafeBufferPointer`.

```swift
let padded: [Float] = load()                                               // 768 dimensions pitched at 1024
try padded.withUnsafeBufferPointer { buffer in
    let rows = MatrixView(baseAddress: buffer.baseAddress!, rows: 1_000, columns: 768, rowStrideBytes: 1024 * 4)
    try index.on(executor).insert(keys: keys, vectors: RowsView(rows))
}
```

The library checks every row view's width against the index geometry itself, so a mismatch surfaces as its own `shapeMismatch`.
Sub-byte kinds count logical dimensions rather than stored values, so a `U1x8` view one value wide carries eight dimensions.

The scalar type of what you hand the index is independent of the scalar type it stores: the library converts on ingest and on export.
`Double`, `Float`, `Int8`, and `UInt8` are native, and the low-precision encodings come from NumKong: `BFloat16`, `E5M2`, `E4M3`, `E3M2`, `E2M3` and `U1x8`, each of which converts from a `Float` rather than only naming a bit pattern.

```swift
let row = [BFloat16(float: 0.3), BFloat16(float: 0.5), BFloat16(float: 1.2)]
```

`Scalar`, `DenseMetric` and `Mood` spell themselves through the library's own name tables, and `Scalar(name: "bf16")` reads one back.

### Search

A search writes up to `wanted` matches per query into its arena, ranked nearest first, and answers `Matches` reading them in place: `matches[query]` is one query's `QueryMatches`, so neither level copies a match out.
A query's own `count` stops at the matches the call wrote, however many were wanted.
Both levels are `RandomAccessCollection`, so a query walks, maps and slices like any other sequence.

```swift
let stats = DenseTraversalStats()
let matches = try index.on(executor).search(queries, wanted: 10, arena: arena, config: DenseSearchConfig(
    expansionFactor: 64, stats: stats))
for query in 0 ..< matches.count {
    for match in matches[query] { print(match.key, match.distance) }
}
print(stats.visitedMembers, stats.computedDistances, stats.restarts)
```

`expansionFactor` is the breadth of the candidates the walk explores, and zero derives it from the geometry.
The `insert`, `refine`, `search`, `maxsim`, `multiply` and `attend` configs take a `DenseTraversalStats`, and every call overwrites the stats it is handed rather than accumulating, so a sweep sums them itself.
Insertions and searches overlap freely on one handle: searches read only entries published behind the visibility watermark, while insertions publish in order.

`import USearch`

## Scalar

A stored or exchanged scalar type, named by width and encoding.

```swift
struct Scalar
```

Sub-byte kinds pack several
dimensions per byte, as their `xN` suffixes spell.

Conforms to: `Hashable`, `Sendable`, `CustomStringConvertible`, `Equatable`

## unknown

No scalar named - an unset field.

```swift
static let unknown: Scalar
```

## f64

64-bit double precision.

```swift
static let f64: Scalar
```

## f32

32-bit single precision.

```swift
static let f32: Scalar
```

## bf16

The brain floating-point format.

```swift
static let bf16: Scalar
```

## f16

IEEE half precision.

```swift
static let f16: Scalar
```

## e5m2

8-bit floating point with five exponent bits.

```swift
static let e5m2: Scalar
```

## e4m3

8-bit floating point with four exponent bits.

```swift
static let e4m3: Scalar
```

## e3m2

6-bit floating point with three exponent bits.

```swift
static let e3m2: Scalar
```

## e2m3

6-bit floating point with two exponent bits.

```swift
static let e2m3: Scalar
```

## i8

An 8-bit signed integer.

```swift
static let i8: Scalar
```

## i4x2

Two 4-bit signed integers per byte.

```swift
static let i4x2: Scalar
```

## i32

A 32-bit signed integer, the coordinates of geospatial points.

```swift
static let i32: Scalar
```

## u8

An 8-bit unsigned integer.

```swift
static let u8: Scalar
```

## u4x2

Two 4-bit unsigned integers per byte.

```swift
static let u4x2: Scalar
```

## u1x8

Eight single-bit dimensions per byte.

```swift
static let u1x8: Scalar
```

## description

The kind rendered as the library spells it.

```swift
var description: String { get }
```

## init

Reads a spelling back, and nil for one no kind carries.

```swift
init?(name: String)
```

## ScalarValue

An element type a matrix may hold.

```swift
protocol ScalarValue
```

Every conformance below names a type Swift or NumKong
already owns, so a caller converts a [`Float`](#Float) into any stored kind rather than only naming it,
and this SDK defines no scalar of its own.

Conforming types: [`BFloat16`](#BFloat16), [`E5M2`](#E5M2), [`E4M3`](#E4M3), [`E3M2`](#E3M2), [`E2M3`](#E2M3), [`I4x2`](#I4x2), [`U4x2`](#U4x2), [`U1x8`](#U1x8), [`Double`](#Double), [`Float`](#Float), [`Float16`](#Float16), [`Int8`](#Int8), [`UInt8`](#UInt8)

## scalarKind

The scalar kind this element type crosses the boundary as.

```swift
static var scalarKind: Scalar { get }
```

## RowsView

A borrowed run of rows along a call's batch axis - the input of every verb whose rows share one width - with the row count that sets the call's batch size.

```swift
struct RowsView
```

Built over a NumKong `MatrixView`, it borrows and stays valid only as long as the storage the
view points into, so a memory-mapped dataset reaches the index with no reshape and no copy.
Built over a `Tensor`, it keeps the tensor alive, which is what a deferred call needs.

Conforms to: `Sendable`

## data

The first row.

```swift
let data: UnsafeRawPointer
```

## rows

The rows the run carries, which the call takes as its batch axis.

```swift
let rows: Int
```

## stride

Bytes between the starts of consecutive rows; zero repeats the first row.

```swift
let stride: Int
```

## columns

Logical values per row, wider than a view's [`columns`](https://www.unum.cloud/docs/usearch/swift/retrieval-and-streaming.md#columns) for the packed sub-byte kinds.

```swift
let columns: Int
```

## scalar

The scalar kind the rows hold.

```swift
let scalar: Scalar
```

## init

Borrows the rows of a NumKong view, which must outlive every call reading them.

```swift
init<Element>(_ matrix: MatrixView<Element>) where Element : ScalarValue
```

```swift
init<Element>(_ tensor: Tensor<Element>) where Element : ScalarValue
```

Views the rows of a NumKong tensor, keeping it alive as long as the view is.

## Match

One retrieved entry.

```swift
struct Match
```

Conforms to: `Equatable`, `Sendable`

## key

The matched entry's key.

```swift
let key: Key
```

## distance

Its distance to the query, in the index's metric.

```swift
let distance: Distance
```

## Matches

The ranked matches a search or a stream pull wrote into an arena, one list per query, read in place.

```swift
struct Matches
```

Conforms to: `RandomAccessCollection`, `BidirectionalCollection`, `Collection`, `Sequence`

## endIndex

One past the last query the call resolved.

```swift
let endIndex: Int
```

## startIndex

The first query's position, which a collection walk starts from.

```swift
var startIndex: Int { get }
```

## columns

The columns per query the call wrote, at most its [`wanted`](https://www.unum.cloud/docs/usearch/swift/linear-algebra.md#wanted) - the "k" in "kANN".

```swift
var columns: Int { get }
```

## subscript

One query's matches, as many as the call wrote.

```swift
subscript(query: Int) -> QueryMatches { get }
```

## QueryMatches

One query's matches, or one left row's pairs, read in place from the arena they live in.

```swift
struct QueryMatches
```

Conforms to: `RandomAccessCollection`, `BidirectionalCollection`, `Collection`, `Sequence`

## startIndex

The first match's position, which a collection walk starts from.

```swift
var startIndex: Int { get }
```

## endIndex

One past the last match the call wrote.

```swift
var endIndex: Int { get }
```

## subscript

The match at a position, key and score read from their paired arrays.

```swift
subscript(position: Int) -> Match { get }
```

## Traversal

How a search reaches the entries it scores.

```swift
struct Traversal
```

Conforms to: `Hashable`, `Sendable`, `CustomStringConvertible`, `Equatable`

## walk

Walks the graph, scoring the entries the expansion reaches - approximate, the default.

```swift
static let walk: Traversal
```

## scan

Scores every entry published when the query's scan starts - exact, on RAM and NVMe handles.

```swift
static let scan: Traversal
```

## description

The traversal rendered as the library spells it.

```swift
var description: String { get }
```

## init

Reads a spelling back, and nil for one no traversal carries.

```swift
init?(name: String)
```

## Arena

Memory the library writes every output whose length scales with a call into - matches, rows, products, monoliths, cursor and stream batches - reused across calls so a steady loop allocates once.

```swift
final class Arena
```

Every such verb requires one and answers a view reading it in place. Each call given the arena
rewinds it, so the views an earlier call answered stop reading: any read of them traps, as an
out-of-bounds index does. To keep a result past the next call, give that call another arena.
Every call borrows the arena, deferred ones included, and one naming it while another call
writes it is refused with [`contended`](https://www.unum.cloud/docs/usearch/swift/errors.md#contended). An arena serves one call at a time and is not `Sendable`.
One in GPU memory serves only calls on the executor that made it, and keeps that executor alive.

## residency

Where its memory lives, which the executor that made it decided.

```swift
let residency: Residency
```

## init

Makes an arena where [`executor`](https://www.unum.cloud/docs/usearch/swift/serialization.md#executor) computes, host pages or its GPU's memory, decided once; nil makes host pages for calls on the calling thread.

```swift
init(on executor: Executor? = nil) throws(USearchError)
```

## DenseTraversalStats

The traversal telemetry one call reports, passed in a config and written by the call.

```swift
final class DenseTraversalStats
```

Every
call overwrites it rather than accumulating, so a sweep over many batches sums them itself,
and it belongs to one call until that call is final.

Conforms to: `Sendable`

## init

```swift
init()
```

## visitedMembers

The graph members the call visited.

```swift
var visitedMembers: Int { get }
```

## computedDistances

The distances the call computed, diversity re-selections included.

```swift
var computedDistances: Int { get }
```

## restarts

The starvation re-seedings - a graph-connectivity health signal rather than a cost counter.

```swift
var restarts: Int { get }
```

## DenseInsertConfig

The knobs of [`insert`](https://www.unum.cloud/docs/usearch/swift/metrics.md#insert).

```swift
struct DenseInsertConfig
```

Every zeroed field derives, which is what almost every caller wants.

## expansionFactor

The breadth of the candidates the insertion walk searches for neighbors with; zero derives it from the geometry.

```swift
var expansionFactor: Int
```

## progress

Called with entries admitted; it reports and cannot cancel.

```swift
var progress: Progress?
```

## progressSteps

Reports the call makes at most, the last at completion; zero derives to ten.

```swift
var progressSteps: Int
```

## stats

The traversal telemetry to write.

```swift
var stats: DenseTraversalStats?
```

## init

```swift
init(expansionFactor: Int = 0, progress: Progress? = nil, progressSteps: Int = 0, stats: DenseTraversalStats? = nil)
```

## DenseSearchConfig

The knobs of [`search`](https://www.unum.cloud/docs/usearch/swift/metrics.md#search).

```swift
struct DenseSearchConfig
```

Every zeroed field derives.

## expansionFactor

The breadth of the candidates the walk explores; zero derives it from the geometry, and a scan ignores it.

```swift
var expansionFactor: Int
```

## traversal

Walks the graph by default; `.scan` scores every entry exactly, on RAM and NVMe handles, and a VRAM handle refuses it with [`unsupported`](https://www.unum.cloud/docs/usearch/swift/errors.md#unsupported).

```swift
var traversal: Traversal
```

## predicate

Narrows the matches to the keys it approves.

```swift
var predicate: (@Sendable (Key) throws -> Bool)?
```

Non-matching entries still route the
traversal, so recall does not collapse at low selectivity. It runs on the executor's
threads together, so it must be safe for concurrent use; an error it throws never unwinds
into the engine, but rejects that key, and the first one is what the call throws. A VRAM
handle refuses one with [`device`](https://www.unum.cloud/docs/usearch/swift/errors.md#device), since host code cannot narrow a device walk.

## progress

Called with queries resolved.

```swift
var progress: Progress?
```

## progressSteps

Reports the call makes at most, the last at completion; zero derives to ten.

```swift
var progressSteps: Int
```

## stats

The traversal telemetry to write.

```swift
var stats: DenseTraversalStats?
```

## init

```swift
init(expansionFactor: Int = 0, traversal: Traversal = .walk, predicate: (@Sendable (Key) throws -> Bool)? = nil, progress: Progress? = nil, progressSteps: Int = 0, stats: DenseTraversalStats? = nil)
```

## BFloat16

```swift
extension BFloat16 : ScalarValue
```

## scalarKind

```swift
static var scalarKind: Scalar { get }
```

## E5M2

```swift
extension E5M2 : ScalarValue
```

## scalarKind

```swift
static var scalarKind: Scalar { get }
```

## E4M3

```swift
extension E4M3 : ScalarValue
```

## scalarKind

```swift
static var scalarKind: Scalar { get }
```

## E3M2

```swift
extension E3M2 : ScalarValue
```

## scalarKind

```swift
static var scalarKind: Scalar { get }
```

## E2M3

```swift
extension E2M3 : ScalarValue
```

## scalarKind

```swift
static var scalarKind: Scalar { get }
```

## I4x2

```swift
extension I4x2 : ScalarValue
```

## scalarKind

```swift
static var scalarKind: Scalar { get }
```

## U4x2

```swift
extension U4x2 : ScalarValue
```

## scalarKind

```swift
static var scalarKind: Scalar { get }
```

## U1x8

```swift
extension U1x8 : ScalarValue
```

## scalarKind

```swift
static var scalarKind: Scalar { get }
```

## Double

```swift
extension Double : ScalarValue
```

## scalarKind

```swift
static var scalarKind: Scalar { get }
```

## Float

```swift
extension Float : ScalarValue
```

## scalarKind

```swift
static var scalarKind: Scalar { get }
```

## Float16

```swift
extension Float16 : ScalarValue
```

## scalarKind

```swift
static var scalarKind: Scalar { get }
```

## Int8

```swift
extension Int8 : ScalarValue
```

## scalarKind

```swift
static var scalarKind: Scalar { get }
```

## UInt8

```swift
extension UInt8 : ScalarValue
```

## scalarKind

```swift
static var scalarKind: Scalar { get }
```