# orca.tz

> A module of Orca's API.

Time zones, from the system's TZif files (RFC 8536).

```mojo
var ny = Zone.load("America/New_York")
var offset = ny.offset_at(utc(2024, 7, 1))   # -14400, EDT
```

A TZif file of version 2 or later lists the zone's transitions as 64-bit
times, each with the UTC offset in force from then on, and ends with a POSIX
`TZ` string (`EST5EDT,M3.2.0,M11.1.0`) that gives the rule after the last
transition. "Slim" files, which some systems install, list transitions only
up to when the current rule began and rely on that string for every year
since; "fat" ones list them to 2037. `Zone` reads both, and a version 1 file,
which has only 32-bit times and no rule. Leap-second records are skipped:
orca's times are POSIX times, as the `right/` zones' aren't.

Files are read from `ORCA_ZONEINFO`, default `/usr/share/zoneinfo`. `UTC`
needs no file.

## Structs

### `PosixTZ`

```mojo
struct PosixTZ
```

A POSIX `TZ` rule: a standard offset, and maybe a daylight one with the rules for when it starts and ends.

Implements: `Copyable`, `Movable`

Fields:

- `std: Int`: Seconds east of UTC.
- `dst: Int`
- `has_dst: Bool`
- `start: _Rule`
- `end: _Rule`

#### `__init__`

```mojo
def __init__(out self, std: Int)
```

#### `parse`

```mojo
def parse(s: String) -> Self
```

Reads `std offset [dst [offset] [,start[/time],end[/time]]]`. A daylight zone without rules gets the US ones, as glibc does.

#### `offset_at`

```mojo
def offset_at(self, t: Int64) -> Int
```

#### `last_change`

```mojo
def last_change(self, t: Int64) -> Int64
```

The latest change at or before `t`; `Int64.MIN` if none.

### `Zone`

```mojo
struct Zone
```

A time zone: its transitions, and the rule after the last one.

Implements: `Copyable`, `Movable`

Fields:

- `name: String`
- `times: List[Int64]`: Transition times, ascending.
- `offsets: List[Int]`: The offset (seconds east of UTC) from each transition on.
- `first: Int`: The offset before the first transition.
- `footer: Optional[PosixTZ]`

#### `__init__`

```mojo
def __init__(out self, name: String, offset: Int = Int(0))
```

A fixed offset, such as UTC.

#### `load`

```mojo
def load(name: String) -> Self
```

The zone `name`, such as `America/New_York`, from the TZif file under `ORCA_ZONEINFO` (default `/usr/share/zoneinfo`).

#### `parse`

```mojo
def parse(name: String, data: List[UInt8]) -> Self
```

Reads a TZif file.

#### `offset_at`

```mojo
def offset_at(self, t: Int64) -> Int
```

The offset in seconds east of UTC at `t`.

#### `last_change`

```mojo
def last_change(self, t: Int64) -> Int64
```

The latest transition at or before `t`; `Int64.MIN` if none.

#### `to_local`

```mojo
def to_local(self, t: Int64) -> Int64
```

`t` read on this zone's wall clock.