# orca.civil

> A module of Orca's API.

Calendar arithmetic: dates to days since 1970-01-01 and back.

The algorithms are Howard Hinnant's (`days_from_civil`, and
`civil_from_days` in `Civil.of`), exact over the proleptic Gregorian calendar. Times are seconds since the
epoch; a *local* time is the same count read on a wall clock, as if the zone
were UTC, which is what cron matches against.

## Structs

### `Civil`

```mojo
struct Civil
```

A date and a time of day, on a wall clock.

Implements: `Copyable`, `Movable`, `Writable`

Fields:

- `year: Int`
- `month: Int`
- `day: Int`
- `hour: Int`
- `minute: Int`
- `second: Int`

#### `of`

```mojo
def of(t: Int64) -> Self
```

The date and time `t` seconds after 1970-01-01T00:00.

#### `seconds`

```mojo
def seconds(self) -> Int64
```

The inverse of `of`.

#### `weekday`

```mojo
def weekday(self) -> Int
```

0 for Sunday to 6 for Saturday.

#### `write_to`

```mojo
def write_to(self, mut writer: T)
```

`YYYY-MM-DDTHH:MM:SS`.

## Functions

### `days_from_civil`

```mojo
def days_from_civil(year: Int, month: Int, day: Int) -> Int64
```

Days from 1970-01-01 to the date.

### `utc`

```mojo
def utc(year: Int, month: Int, day: Int, hour: Int = Int(0), minute: Int = Int(0)) -> Int64
```

Seconds since the epoch at a UTC date and time.

### `parse_time`

```mojo
def parse_time(s: StringSpan) -> Int64
```

Reads `YYYY-MM-DDTHH:MM[:SS]Z`, a UTC time, or a number of seconds since the epoch.

### `now`

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

Seconds since the epoch: `ORCA_NOW` if it's set (a time `parse_time` reads), else the system clock. The scheduler's tests fix time with it.