# iceberg.util

> A module of iceberg's API.

The three things a writer needs from outside itself: the wall clock, a random 64-bit number, and a UUID.

Mojo's `std.time` only exposes monotonic counters, so `last-updated-ms` and a
snapshot's `timestamp-ms` come from `clock_gettime(CLOCK_REALTIME)` directly.
Snapshot ids are "a random long" in the spec's words, and every file this
library writes is named with a version 4 UUID. Both are read from the
operating system (`/dev/urandom`), not drawn from `std.random`: that
generator starts from the same state in every process unless something seeds
it, so two processes committing to one table at once would draw the same
snapshot ids and file names and overwrite each other's manifest lists.

## Functions

### `now_ms`

```mojo
def now_ms() -> Int64
```

Milliseconds since the Unix epoch.

### `random_long`

```mojo
def random_long() -> Int64
```

A random signed 64-bit value, for a snapshot id.

The spec says only "a unique long"; every implementation uses a random
one, and the top bit is cleared so the id prints without a sign — which is
what Java's `SnapshotIdGeneratorUtil` does too.

### `uuid4`

```mojo
def uuid4() -> String
```

A version 4 UUID in the canonical 8-4-4-4-12 form.

### `seed_random`

```mojo
def seed_random()
```

Seeds `std.random` from the clock. Ids and UUIDs no longer come from it, so this is only for callers' own use of `std.random`.

### `zero_pad`

```mojo
def zero_pad(v: Int, width: Int) -> String
```

`5, 5` -> `00005`, the way Java names metadata files.