# orca.cron

> A module of Orca's API.

Cron expressions, and when they next fire in a time zone.

```mojo
var c = CronExpr.parse("0 3 2 * *")          # 03:00 on the 2nd
var t = c.next_fire(now(), Zone.load("America/New_York"))
```

Five fields: minute (0-59), hour (0-23), day of month (1-31), month (1-12
or `jan`-`dec`) and day of week (0-7 or `sun`-`sat`, 0 and 7 both Sunday).
A field is a list of `*`, `a`, `a-b`, each with an optional `/step`
(`a/step` runs from `a` to the field's end). `@yearly`, `@annually`,
`@monthly`, `@weekly`, `@daily`, `@midnight` and `@hourly` stand for the
usual expressions.

As in Vixie cron, when both the day of month and the day of week are
restricted (neither starts with `*`), a day matches if either does.

Times are matched on the zone's wall clock. A time that a spring-forward
skips fires at the first moment after the gap, and a time that a fall-back
repeats fires once, at its first occurrence, as Vixie cron and systemd
timers do. An expression that can never match, such as `0 0 30 2 *`, is
refused when it's parsed.

## Structs

### `CronExpr`

```mojo
struct CronExpr
```

A parsed cron expression.

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

Fields:

- `text: String`
- `minutes: UInt64`
- `hours: UInt64`
- `days: UInt64`
- `months: UInt64`
- `weekdays: UInt64`
- `any_day: Bool`: The day-of-month field starts with `*`.
- `any_weekday: Bool`: The day-of-week field starts with `*`.

#### `__init__`

```mojo
def __init__(out self, text: String)
```

#### `parse`

```mojo
def parse(text: StringSpan) -> Self
```

#### `matches_day`

```mojo
def matches_day(self, c: Civil) -> Bool
```

#### `next_fire`

```mojo
def next_fire(self, after: Int64, zone: Zone) -> Int64
```

The first time after `after` (seconds since the epoch) that the expression fires on `zone`'s wall clock.

#### `write_to`

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