# collections

> Data structures — stack, queue, set, ordered map, heap, trie, ring buffer, list, tuple, and array helpers.

# collections

A set of data structures: stack, queue, set, ordered map, min-heap, trie, ring buffer, and singly-linked list, plus helpers for native arrays and tuples. Import it with `import collections`.

Most structures are handle-based: `new()` returns an integer id that you pass to every other call, and `free(id)` releases it. The exceptions are `collections.array` and `collections.tuple`, which operate directly on Langoost native arrays (no handle, no `free`).

## collections.stack

| Function | Signature | Description |
| --- | --- | --- |
| `new` | `collections.stack.new() → int` | Create a stack, return its id |
| `push` | `collections.stack.push(id: int, value: any) → bool` | Push a value (false if id unknown) |
| `pop` | `collections.stack.pop(id: int) → any` | Pop the top value (void if empty) |
| `peek` | `collections.stack.peek(id: int) → any` | View the top value (void if empty) |
| `size` | `collections.stack.size(id: int) → int` | Number of elements |
| `isEmpty` | `collections.stack.isEmpty(id: int) → bool` | Whether the stack is empty |
| `free` | `collections.stack.free(id: int) → void` | Release the stack |

## collections.queue

| Function | Signature | Description |
| --- | --- | --- |
| `new` | `collections.queue.new() → int` | Create a queue, return its id |
| `enqueue` | `collections.queue.enqueue(id: int, value: any) → bool` | Add to the back (false if id unknown) |
| `dequeue` | `collections.queue.dequeue(id: int) → any` | Remove from the front (void if empty) |
| `peek` | `collections.queue.peek(id: int) → any` | View the front value (void if empty) |
| `size` | `collections.queue.size(id: int) → int` | Number of elements |
| `isEmpty` | `collections.queue.isEmpty(id: int) → bool` | Whether the queue is empty |
| `free` | `collections.queue.free(id: int) → void` | Release the queue |

## collections.set

A set of unique strings.

| Function | Signature | Description |
| --- | --- | --- |
| `new` | `collections.set.new() → int` | Create a set, return its id |
| `add` | `collections.set.add(id: int, value: string) → bool` | Add a value (false if id unknown) |
| `has` | `collections.set.has(id: int, value: string) → bool` | Whether the value is present |
| `remove` | `collections.set.remove(id: int, value: string) → void` | Remove a value |
| `size` | `collections.set.size(id: int) → int` | Number of elements |
| `toArray` | `collections.set.toArray(id: int) → string[]` | Members as an array (unordered) |
| `free` | `collections.set.free(id: int) → void` | Release the set |

## collections.map

An ordered map with string keys; `keys` preserves insertion order.

| Function | Signature | Description |
| --- | --- | --- |
| `new` | `collections.map.new() → int` | Create a map, return its id |
| `set` | `collections.map.set(id: int, key: string, value: any) → bool` | Set a key (false if id unknown) |
| `get` | `collections.map.get(id: int, key: string) → any` | Get a value (void if missing) |
| `has` | `collections.map.has(id: int, key: string) → bool` | Whether the key exists |
| `delete` | `collections.map.delete(id: int, key: string) → bool` | Remove a key |
| `keys` | `collections.map.keys(id: int) → string[]` | Keys in insertion order |
| `size` | `collections.map.size(id: int) → int` | Number of entries |
| `free` | `collections.map.free(id: int) → void` | Release the map |

## collections.heap

A min-heap of integers.

| Function | Signature | Description |
| --- | --- | --- |
| `new` | `collections.heap.new() → int` | Create a heap, return its id |
| `push` | `collections.heap.push(id: int, value: int) → bool` | Insert a value (false if id unknown) |
| `pop` | `collections.heap.pop(id: int) → int` | Remove and return the minimum (0 if empty) |
| `peek` | `collections.heap.peek(id: int) → int` | View the minimum (void if empty) |
| `size` | `collections.heap.size(id: int) → int` | Number of elements |
| `free` | `collections.heap.free(id: int) → void` | Release the heap |

## collections.trie

A prefix tree over strings.

| Function | Signature | Description |
| --- | --- | --- |
| `new` | `collections.trie.new() → int` | Create a trie, return its id |
| `insert` | `collections.trie.insert(id: int, word: string) → bool` | Insert a word (false if id unknown) |
| `search` | `collections.trie.search(id: int, word: string) → bool` | Whether the exact word is present |
| `startsWith` | `collections.trie.startsWith(id: int, prefix: string) → bool` | Whether any word has the prefix |
| `words` | `collections.trie.words(id: int) → string[]` | All stored words |
| `free` | `collections.trie.free(id: int) → void` | Release the trie |

## collections.ring

A fixed-capacity ring buffer.

| Function | Signature | Description |
| --- | --- | --- |
| `new` | `collections.ring.new(capacity: int) → int` | Create a ring buffer (capacity must be > 0) |
| `push` | `collections.ring.push(id: int, value: any) → bool` | Add a value (false if full or id unknown) |
| `pop` | `collections.ring.pop(id: int) → any` | Remove the oldest value (void if empty) |
| `size` | `collections.ring.size(id: int) → int` | Number of elements |
| `isFull` | `collections.ring.isFull(id: int) → bool` | Whether the buffer is at capacity |
| `free` | `collections.ring.free(id: int) → void` | Release the ring buffer |

## collections.list

A handle-based ordered list of strings.

| Function | Signature | Description |
| --- | --- | --- |
| `new` | `collections.list.new() → int` | Create a list, return its id |
| `append` | `collections.list.append(id: int, value: any) → void` | Append to the end (stored as a string) |
| `prepend` | `collections.list.prepend(id: int, value: any) → void` | Prepend to the front (stored as a string) |
| `get` | `collections.list.get(id: int, index: int) → string` | Value at index (empty string if out of range) |
| `size` | `collections.list.size(id: int) → int` | Number of elements |
| `toArray` | `collections.list.toArray(id: int) → string[]` | All elements as an array |
| `free` | `collections.list.free(id: int) → void` | Release the list |

## collections.array

Operates on Langoost native arrays (no handle). Mutating helpers return a new array.

| Function | Signature | Description |
| --- | --- | --- |
| `new` | `collections.array.new() → array` | Create an empty array |
| `length` | `collections.array.length(arr: array) → int` | Element count |
| `push` | `collections.array.push(arr: array, value: any) → array` | New array with `value` appended |
| `pop` | `collections.array.pop(arr: array) → any` | Last element (does not mutate) |
| `first` | `collections.array.first(arr: array) → any` | First element |
| `last` | `collections.array.last(arr: array) → any` | Last element |
| `contains` | `collections.array.contains(arr: array, value: any) → bool` | Whether `value` is present |
| `indexOf` | `collections.array.indexOf(arr: array, value: any) → int` | Index of `value`, or -1 |
| `reverse` | `collections.array.reverse(arr: array) → array` | New reversed array |
| `unique` | `collections.array.unique(arr: array) → array` | New array with duplicates removed |
| `slice` | `collections.array.slice(arr: array, start: int, end: int) → array` | Sub-array `[start, end)` |
| `join` | `collections.array.join(arr: array, sep: string) → string` | Join elements with a separator |

## collections.tuple

An immutable fixed-size view over a native array (no handle).

| Function | Signature | Description |
| --- | --- | --- |
| `new` | `collections.tuple.new(vals: array) → array` | Create a tuple from an array (copies it) |
| `get` | `collections.tuple.get(tuple: array, index: int) → any` | Element at index (empty string if out of range) |
| `size` | `collections.tuple.size(tuple: array) → int` | Element count |
| `contains` | `collections.tuple.contains(tuple: array, value: any) → bool` | Whether `value` is present |
| `toArray` | `collections.tuple.toArray(tuple: array) → array` | Return the underlying array |

## Example

```goost
import collections

// handle-based: ordered map
let m = collections.map.new()
collections.map.set(m, "name", "ada")
collections.map.set(m, "role", "engineer")
print(collections.map.get(m, "name"))   // ada
print(collections.map.keys(m))           // ["name", "role"]
collections.map.free(m)

// native arrays need no handle
let nums = [3, 1, 2, 1]
print(collections.array.unique(nums))    // [3, 1, 2]
print(collections.array.join(nums, "-")) // 3-1-2-1
```