# 📅 ical-rs [](https://docs.rs/ical-rs/latest/ical) [](https://codecov.io/gh/pimalaya/ical) [](https://matrix.to/#/#pimalaya:matrix.org) [](https://fosstodon.org/@pimalaya) [](https://pimalaya.org/sponsor/)
iCalendar parser, validator, editor, merger and builder library for Rust
## Table of contents
- [Features](#features)
- [RFC coverage](#rfc-coverage)
- [Usage](#usage)
- [Examples](#examples)
- [AI policy](https://github.com/pimalaya/.github/blob/master/AI_POLICY.md)
- [License](#license)
- [Social](#social)
- [Contributing](./CONTRIBUTING.md)
- [Sponsoring](#sponsoring)
## Features
- **Both iCalendar flavours**: read and write vCalendar 1.0 and iCalendar 2.0 through one version-agnostic model.
- **Nested structure, preserved**: events, to-dos, journals, free/busy blocks, time zones and alarms, parsed and round-tripped whole.
- **Byte-faithful editing**: change one field and every other byte comes back unchanged, line endings and fold points included.
- **Forgiving parser**: accept any real calendar, with a recovering mode for the ones a strict reading would throw away whole.
- **Strict building and validation**: construct calendars checked against the standard, with an escape hatch to step outside it.
- **Recurrence and time zones**: expand a rule or a whole recurrence set, and resolve an offset from the calendar's own rules.
- **Three-way merge**: reconcile two divergent edits against their common base, every action and conflict reported.
- **Small and portable**: no_std compatible, with an allocation-only core that pulls in no dependencies; the parser itself is optional.
- **Optional content decoding**: quoted-printable text, inline base64 binary and foreign character sets, each behind its own feature.
- **Optional jCal**: read and write a calendar as JSON.
- **Optional JSCalendar**: convert a calendar to and from the object model exchanged over JMAP.
> [!TIP]
> ical-rs uses [cargo features](https://doc.rust-lang.org/cargo/reference/features.html) to gate optional support. The default feature set is declared in [Cargo.toml](./Cargo.toml) or on [docs.rs](https://docs.rs/crate/ical-rs/latest/features).
## RFC coverage
| Spec | What is covered |
|--------|----------------------------------------------------------------------------------------------------------|
| [1.0] | vCalendar 1.0: the original versit format, including its quoted-printable and charset conventions |
| [5545] | iCalendar 2.0: the current standard, with its full component tree, property set, value types and parameters, its recurrence rules and its time zones |
| [5546] | iTIP: whose the properties of a scheduled component are, which the merge enforces |
| [6638] | CalDAV scheduling: the parameters a server reads and writes on an attendee |
| [7265] | jCal: the JSON representation of a calendar |
| [7529] | Non-Gregorian recurrence: `SKIP` is expanded for the Gregorian scale; another scale is carried, not expanded |
| [7953] | Availability: the availability window and the periods inside it |
| [7986] | Calendar extensions: the newer calendar-level properties |
| [8984] | JSCalendar: the JSON data model a JMAP calendar server exchanges, converted both ways |
| [9073] | Event publishing extensions: participants, locations, resources and structured data |
| [9074] | Alarm extensions: acknowledgement, proximity and the alarm relations |
| [9253] | Relationships: typed links, reference identifiers and concepts |
[1.0]: https://www.imc.org/pdi/vcal-10.txt
[5545]: https://www.rfc-editor.org/rfc/rfc5545
[5546]: https://www.rfc-editor.org/rfc/rfc5546
[6638]: https://www.rfc-editor.org/rfc/rfc6638
[7265]: https://www.rfc-editor.org/rfc/rfc7265
[7529]: https://www.rfc-editor.org/rfc/rfc7529
[7953]: https://www.rfc-editor.org/rfc/rfc7953
[7986]: https://www.rfc-editor.org/rfc/rfc7986
[8984]: https://www.rfc-editor.org/rfc/rfc8984
[9073]: https://www.rfc-editor.org/rfc/rfc9073
[9074]: https://www.rfc-editor.org/rfc/rfc9074
[9253]: https://www.rfc-editor.org/rfc/rfc9253
## Usage
See documentation at [docs.rs](https://docs.rs/ical-rs/latest/ical).
## Examples
See complete examples at [./examples](./examples).
## License
This project is licensed under either of:
- [MIT license](LICENSE-MIT)
- [Apache License, Version 2.0](LICENSE-APACHE)
## Social
- Chat on [Matrix](https://matrix.to/#/#pimalaya:matrix.org)
- News on [Mastodon](https://fosstodon.org/@pimalaya) or [RSS](https://fosstodon.org/@pimalaya.rss)
- Mail at [pimalaya.org@posteo.net](mailto:pimalaya.org@posteo.net)
## Sponsoring
[](https://nlnet.nl/)
Special thanks to the [NLnet foundation](https://nlnet.nl/) and the [European Commission](https://www.ngi.eu/) that have been financially supporting the project for years:
- 2022 → 2023: [NGI Assure](https://nlnet.nl/project/Himalaya/)
- 2023 → 2024: [NGI Zero Entrust](https://nlnet.nl/project/Pimalaya/)
- 2024 → 2026: [NGI Zero Core](https://nlnet.nl/project/Pimalaya-PIM/)
- 2026 → 2027: [NGI Zero Commons Fund](https://nlnet.nl/project/Pimalaya-pimdir/)
This program is part of Pimalaya, free software funded entirely by grants and donations. If you find it useful, consider [sponsoring](https://pimalaya.org/sponsor/) its development:
[](https://github.com/sponsors/soywod)
[](https://ko-fi.com/pimalaya)
[](https://www.buymeacoffee.com/pimalaya)
[](https://liberapay.com/pimalaya)
[](https://thanks.dev/u/gh/soywod)
[](https://www.paypal.com/paypalme/soywod)