Before connecting an importer, check that the selected parser supports the forms your source produces. A calendar feed can contain a valid rule that a particular adapter doesn’t handle. A date description can parse successfully without identifying a single instant.
Each module documents a profile: the syntax and meaning it accepts. The API pages for your release list exact grammars, limits and errors.
Match the profile to your input§
| Area | Support and limits |
|---|---|
| Exact values | Compare explicit-offset timestamps and combine spans. Calculations use signed I64 microseconds and check overflow and precision. |
| Calendars | Convert Gregorian/Julian dates and calculate Gregorian deadlines. Their rules apply in all supported years; historical national reforms aren’t inferred. |
| Named zones | Interpret local labels with the optional IANA data package. Supply rules that cover the requested time range. |
| Timestamp/interval text | Parse supported explicit-offset timestamps and exact intervals. These profiles reject leap seconds and sub-microsecond input. |
| EDTF | Retain supported date precision and qualifications. The date adapter supports a subset of EDTF; check its grammar before importing a wider form. |
| IXDTF | Retain annotations and check supplied offset/zone assertions. An annotation can be retained without supporting its presentation; unknown critical extensions fail. |
| Recurrence | Import supported extracted RFC 5545 DATE/DATE-TIME values. There is no general ICS reader, and recurrence rules differ from repeated clamped arithmetic. |
| Explanation | Ask what a supported value means and which context it needs. Work/output limits apply; diagnostic prose isn’t a storage format. |
| Standard text storage | Save values through their standard parser/serializer pair. The text doesn’t embed every interpretation choice or an immutable zone table. |
Follow the API map to find the module for your task. A format’s name alone doesn’t establish support for every part of its standard.
Failure is part of the interface§
Different failures call for different responses:
Malformed: ask the user to fix the input’s spelling or structure.
Unsupported: the input needs a capability outside this parser’s profile; changing its spelling won’t add that capability.
Out of range: choose a supported date range or rules covering the requested time.
Incomplete evaluation: resume with the returned cursor or choose a suitable budget. Partial output isn’t a complete empty result.
Your application supplies clock readings, timezone data and any choice of a repeated local occurrence. The library won’t use your machine’s timezone or fetch replacement data. Standard adapters can have their own documented interpretation policies, so check the adapter as well as the underlying type.
Archive interval descriptions§
The current source also provides EdtfInterval and CalendarInterval for date intervals with independently described endpoints. For example, 2004-02-01/2005-02 retains a day on one side and a month on the other. 1985/ has an unknown end; 1985/.. has an explicitly open end. Those are different descriptions.
These modules and the archive intervals example are available from 0.3.0. Parsing and saving the interval doesn’t resolve it into timeline coverage. The module reports interpretation as unsupported rather than inventing exact endpoint dates. See the 0.3.0 API for its declared EDTF subset.
What is outside these guides?§
General ICS processing, wider calendar providers, leap-aware time and complete ISO/EDTF/RRULE coverage need separately declared support. The design describes the intended architecture, including work beyond the selected release.