# stdlib

The standard library is a vendored package. Every module lives in `vendor/stdlib/src/<name>.cplus` and imports as `"stdlib/<name>"`. You import the modules you use, not the whole library.

## I/O

```cplus
import "stdlib/io" as io;
io::print("no newline");
io::println("with newline");
io::eprintln("to stderr");
```

Backed by `printf`, buffered through stdio.

## Result and Option

Both are generic. There is no `?` propagation; match on the variant or use `guard let`.

```cplus
import "stdlib/result" as result;
import "stdlib/option" as option;

let r: result::Result[i32, result::IoError] = result::io_ok::[i32](42);
let some_n: option::Option[i32] = option::some::[i32](7);
```

## Collections

`stdlib/vec` is a growable vector that implements `Drop`, so its buffer frees on scope exit:

```cplus
import "stdlib/vec" as vec;

let mut v: vec::Vec[i32] = vec::with_capacity::[i32](16 as usize);
v.push(1);
v.push(2);
let n: usize = v.len();
let first: option::Option[i32] = v.get(0);
```

Other methods: `as_slice()`, `reserve(extra)`, `clear()`, `pop()`, and the `unsafe` bulk fast path `extend_from_raw(ptr, count)`.

`stdlib/hash_map` is a generic `HashMap[K, V]` (open addressing, linear probing, 0.75 load-factor grow). `K` must be `Hash + Eq`; primitives and `str` work today:

```cplus
import "stdlib/hash_map" as hash_map;

let mut m: hash_map::HashMap[str, i32] = hash_map::new::[str, i32]();
m.insert("hello", 42);
let present: bool = m.contains_key("hello");
```

## Files and networking

- `stdlib/fs` — `open_read`, `create`, `read_to_end`. `File` implements `Drop` and closes on scope exit.
- `stdlib/net` — TCP client and server (`connect_tcp`, `listen_tcp`, `accept`). IPv4, numeric IPs.
- `stdlib/env` — environment variables (`var_into`) and argv access.

## Ownership wrappers

- `stdlib/box` — a single heap-allocated owned value; `unwrap()` consumes it.
- `stdlib/arc` — atomic refcounted shared ownership; `clone()` increments atomically, the last reference frees.
- `stdlib/rc` — the single-threaded, non-atomic version. `Rc[T]` is `!Send` and `!Sync`, so the compiler rejects passing one across threads (**E0502**). Use `Arc[T]` to share across threads.

## Concurrency

- `stdlib/thread`, `stdlib/atomic` — threads and atomics.
- `stdlib/mutex` — pthread-backed mutual exclusion, internally refcounted (it collapses `Arc` into itself, since C+ has no `&T` to make `Arc[Mutex[T]]` work).
- `stdlib/channel` — typed message passing; handles clone for multi-producer / multi-consumer use.
- `stdlib/future`, `stdlib/executor`, `stdlib/reactor`, `stdlib/time` — the async runtime.

## Other modules

`stdlib/cow` (clone-on-write string), `stdlib/range` (the `0..n` `for in` type), `stdlib/iterator`, and `stdlib/marker` (the compiler's `Copy` / `Send` / `Sync` markers, which you rarely touch directly).