# `CalendarEvent`

A calendar event (RFC 5545's `VEVENT`): an all-day event's first and last days, both included, or a timed event's local start and end and its zone, never both, with what it is called and, where it has them, where it is, what it is about and how it repeats. Written as a `VEVENT`, an all-day event's `DTEND` the day after its last.

[Time and calendar](types.md#time-and-calendar); not ordered; since Jadpo 0.1.0.

## Make one

Build one from its fields, `CalendarEvent { summary: ... }`.

`text.parse(raw, as: CalendarEvent)` reads one from its text; text that isn't one at all fails `malformed`, such as `""`.

Its parts keep these rules; a value that breaks one fails with the rule's name:

- `days_or_times`: `first_day and last_day with no start, end or zone, or start, end and zone with no days`
- `last_day_not_before_first`: `last_day >= first_day`
- `end_after_start`: `end > start`
- `recurrence_from_start`: `recurrence starts on first_day, or at start in zone`

## Fields

| Field | Type |
|---|---|
| `summary` | `Text` |
| `first_day` | [`CalendarDate`](type-calendar-date.md)`?` |
| `last_day` | [`CalendarDate`](type-calendar-date.md)`?` |
| `start` | [`LocalDateTime`](type-local-date-time.md)`?` |
| `end` | [`LocalDateTime`](type-local-date-time.md)`?` |
| `zone` | [`Zone`](type-zone.md)`?` |
| `location` | `Text?` |
| `description` | `Text?` |
| `recurrence` | [`RecurrenceRule`](type-recurrence-rule.md)`?` |

## Text, JSON and storage

`text.from` writes its canonical text, the one form `text.parse` reads back. JSON sends an object of its parts.

| Text | JSON |
|---|---|
| `BEGIN:VEVENT\nDTSTART;VALUE=DATE:20261225\nDTEND;VALUE=DATE:20261226\nSUMMARY:Christmas Day\nEND:VEVENT` | `{"summary":"Christmas Day","first_day":"2026-12-25","last_day":"2026-12-25","start":null,"end":null,"zone":null,"location":null,"description":null,"recurrence":null}` |
| `BEGIN:VEVENT\nDTSTART;VALUE=DATE:20261024\nDTEND;VALUE=DATE:20261027\nSUMMARY:Half-term walk\nLOCATION:Keswick\, Cumbria\nDESCRIPTION:Boots\; maps\nFlask\nEND:VEVENT` | `{"summary":"Half-term walk","first_day":"2026-10-24","last_day":"2026-10-26","start":null,"end":null,"zone":null,"location":"Keswick, Cumbria","description":"Boots; maps\nFlask","recurrence":null}` |
| `BEGIN:VEVENT\nDTSTART;VALUE=DATE:20240229\nDTEND;VALUE=DATE:20240301\nSUMMARY:Wedding anniversary\nRRULE:FREQ=YEARLY\nEND:VEVENT` | `{"summary":"Wedding anniversary","first_day":"2024-02-29","last_day":"2024-02-29","start":null,"end":null,"zone":null,"location":null,"description":null,"recurrence":"DTSTART;VALUE=DATE:20240229\nRRULE:FREQ=YEARLY"}` |
| `BEGIN:VEVENT\nDTSTART;TZID=Europe/London:20261024T220000\nDTEND;TZID=Europe/London:20261025T020000\nSUMMARY:Night shift\nRRULE:FREQ=WEEKLY;COUNT=4\nEND:VEVENT` | `{"summary":"Night shift","first_day":null,"last_day":null,"start":"2026-10-24T22:00:00","end":"2026-10-25T02:00:00","zone":"Europe/London","location":null,"description":null,"recurrence":"DTSTART;TZID=Europe/London:20261024T220000\nRRULE:FREQ=WEEKLY;COUNT=4"}` |

It is stored in 9 columns, each named for the field, `_` and its suffix. This is `BEGIN:VEVENT\nDTSTART;VALUE=DATE:20240229\nDTEND;VALUE=DATE:20240301\nSUMMARY:Wedding anniversary\nRRULE:FREQ=YEARLY\nEND:VEVENT`:

| Column | Type | Holds |
|---|---|---|
| `<field>_summary` | `text` | `'Wedding anniversary'` |
| `<field>_first_day` | `date` | `'2024-02-29'::date` |
| `<field>_last_day` | `date` | `'2024-02-29'::date` |
| `<field>_start` | `timestamp` | `NULL::timestamp` |
| `<field>_end` | `timestamp` | `NULL::timestamp` |
| `<field>_zone` | `text` | `NULL::text` |
| `<field>_location` | `text` | `NULL::text` |
| `<field>_description` | `text` | `NULL::text` |
| `<field>_recurrence` | `text` | `E'DTSTART;VALUE=DATE:20240229\nRRULE:FREQ=YEARLY'` |

## Shown to people

`text.format(value, locale:)` shows it to people in their locale.

With `locale: Locale.en_gb`:

| Value | Shown |
|---|---|
| `"BEGIN:VEVENT\nDTSTART;VALUE=DATE:20261225\nDTEND;VALUE=DATE:20261226\nSUMMARY:Christmas Day\nEND:VEVENT"` | `"BEGIN:VEVENT\nDTSTART;VALUE=DATE:20261225\nDTEND;VALUE=DATE:20261226\nSUMMARY:Christmas Day\nEND:VEVENT"` |
| `"BEGIN:VEVENT\nDTSTART;VALUE=DATE:20261024\nDTEND;VALUE=DATE:20261027\nSUMMARY:Half-term walk\nLOCATION:Keswick\\, Cumbria\nDESCRIPTION:Boots\\; maps\\nFlask\nEND:VEVENT"` | `"BEGIN:VEVENT\nDTSTART;VALUE=DATE:20261024\nDTEND;VALUE=DATE:20261027\nSUMMARY:Half-term walk\nLOCATION:Keswick\\, Cumbria\nDESCRIPTION:Boots\\; maps\\nFlask\nEND:VEVENT"` |
| `"BEGIN:VEVENT\nDTSTART;VALUE=DATE:20240229\nDTEND;VALUE=DATE:20240301\nSUMMARY:Wedding anniversary\nRRULE:FREQ=YEARLY\nEND:VEVENT"` | `"BEGIN:VEVENT\nDTSTART;VALUE=DATE:20240229\nDTEND;VALUE=DATE:20240301\nSUMMARY:Wedding anniversary\nRRULE:FREQ=YEARLY\nEND:VEVENT"` |
| `"BEGIN:VEVENT\nDTSTART;TZID=Europe/London:20261024T220000\nDTEND;TZID=Europe/London:20261025T020000\nSUMMARY:Night shift\nRRULE:FREQ=WEEKLY;COUNT=4\nEND:VEVENT"` | `"BEGIN:VEVENT\nDTSTART;TZID=Europe/London:20261024T220000\nDTEND;TZID=Europe/London:20261025T020000\nSUMMARY:Night shift\nRRULE:FREQ=WEEKLY;COUNT=4\nEND:VEVENT"` |

## Operations

It has the contract's own operations: `text.parse`, `text.from`, `text.format`, `json.read`, `json.write` and `==`. It isn't ordered, so `<` and sorting don't take it. [Every standard type meets one contract](../topics/every-standard-type-meets-one-contract.md) says how they work.