# roaring.portable

> A module of roaring's API.

Shared constants and little-endian byte helpers for the Roaring "portable" serialization format (RoaringFormatSpec) — used by both the 32-bit container layer and the `Bitmap32`/`Bitmap64` assemblers.

Format recap (see https://github.com/RoaringBitmap/RoaringFormatSpec):
  - No run containers: 4-byte LE cookie `SERIAL_COOKIE_NO_RUNCONTAINER`
    (12346), 4-byte LE container count N, N x (2-byte LE key, 2-byte LE
    cardinality-1), N x 4-byte LE offset (always present), then container
    bodies back to back.
  - Has run containers: 4-byte LE value combining cookie `SERIAL_COOKIE`
    (12347) in the low 16 bits and (N-1) in the high 16 bits, a
    ceil(N/8)-byte bitset marking which containers are run containers, N x
    (2-byte LE key, 2-byte LE cardinality-1), then N x 4-byte LE offset
    UNLESS N < `NO_OFFSET_THRESHOLD` (in which case offsets are omitted),
    then container bodies.

Container promotion: an array container holds up to `ARRAY_MAX_CARDINALITY`
(4096) sorted UInt16 values (2 bytes each); above that it becomes a bitset
container (fixed `BITSET_BYTES` = 8192 bytes = 65536 bits). A run container
stores a 2-byte run count followed by that many (2-byte LE start, 2-byte LE
length-1) pairs, and is used only when `run_optimize()` finds it smaller.

## Functions

### `write_u16_le`

```mojo
def write_u16_le(mut buf: List[UInt8], v: UInt16)
```

### `write_u32_le`

```mojo
def write_u32_le(mut buf: List[UInt8], v: UInt32)
```

### `write_u64_le`

```mojo
def write_u64_le(mut buf: List[UInt8], v: UInt64)
```

### `read_u16_le`

```mojo
def read_u16_le[origin: Origin[mut=origin.mut], //](data: Span[UInt8, origin], pos: Int) -> UInt16
```

### `read_u32_le`

```mojo
def read_u32_le[origin: Origin[mut=origin.mut], //](data: Span[UInt8, origin], pos: Int) -> UInt32
```

### `read_u64_le`

```mojo
def read_u64_le[origin: Origin[mut=origin.mut], //](data: Span[UInt8, origin], pos: Int) -> UInt64
```

## Aliases

### `SERIAL_COOKIE_NO_RUNCONTAINER`

```mojo
comptime SERIAL_COOKIE_NO_RUNCONTAINER = UInt32(12346)
```

### `SERIAL_COOKIE`

```mojo
comptime SERIAL_COOKIE = UInt32(12347)
```

### `NO_OFFSET_THRESHOLD`

```mojo
comptime NO_OFFSET_THRESHOLD = Int(4)
```

### `ARRAY_MAX_CARDINALITY`

```mojo
comptime ARRAY_MAX_CARDINALITY = Int(4096)
```

### `BITSET_WORDS`

```mojo
comptime BITSET_WORDS = Int(1024)
```

### `BITSET_BYTES`

```mojo
comptime BITSET_BYTES = Int(8192)
```