IcalEvent Class
Definition
Namespace: DataStandardizer.File.iCal
An event (RFC 5545 §3.6.1): the VEVENT component. It gives typed access to the properties of an event, and expands its recurrence set into occurrences.
Syntax
public sealed class IcalEvent : IcalComponent
Remarks
The typed properties follow the rules described under Typed accessors on IcalComponent: a getter reads the first property of its name, a setter replaces every property of its name in the place of the first, setting null removes them, and a getter throws IcalFileException if the stored value is not valid.
Recurrence expansion. GetOccurrences gives the instances of the event’s recurrence set (RFC 5545 §3.8.5) that start in a window, as IcalOccurrence<IcalEvent> values:
- The recurrence set is
DTSTART, which is always the first instance even when no rule gives it, the occurrences of eachRRULE, and the dates, date-times and periods of eachRDATE.DTSTARTcounts towards theCOUNTof a rule that does not give it, as RFC 5545 §3.3.10 requires, so such a rule gives one occurrence fewer. EachEXDATEremoves an instance,DTSTARTamong them. AnEXDATEthat is a DATE removes every instance on that local date. An instance given more than once appears once. - Each instance ends as RFC 5545 §3.8.5.3 sets out.
DTENDgives every instance the exact duration it givesDTSTART, so the local time of the end can change across a daylight saving change.DURATIONis added to each start: its weeks and days are nominal and keep the local time of day, and its hours, minutes and seconds are exact, soP1DandPT24Hdiffer across a change. AnRDATEperiod gives its instance its own end. With neitherDTENDnorDURATION, an instance ends when it starts, or a day later for a DATE (RFC 5545 §3.6.1). - Each event of
calendarwith the sameUIDand aRECURRENCE-IDreplaces the instance it names, with the start and end of its ownDTSTART,DTENDandDURATION. Of two for the same instance, the one with the higherSEQUENCEwins, then the later one. WithRANGE=THISANDFUTURE, it also replaces every later instance: each is moved by the change it makes to the start, in the local time ofDTSTART, and takes its duration. An override is matched to an instance by its instant, and is ignored if anEXDATEremoves that instance. - An event that has a
RECURRENCE-IDitself gives only its own instance. When expanding every event of a calendar, skip those whose recurring event is in it too. - The instances are generated in local time and each is resolved to UTC through the resolver, as RFC 5545 §3.3.5 requires. A time in a daylight saving gap is read with the offset in use before the gap, and a time in an overlap takes its first occurrence. So a daily event at 09:00 stays at 09:00 local time while its time in UTC moves by an hour.
- Floating times and DATE values have no instant. Each is compared with the window by its wall-clock time, as though it were in UTC, as is a floating
fromorto. - An instance is given when its start, after any override, falls in the window:
fromis inclusive andtoexclusive. Either may benullfor no limit, but anulltoneeds everyRRULEto haveCOUNTorUNTIL. - The properties are read, and the time zones of
DTSTARTand the window resolved, whenGetOccurrencesis called, so most exceptions are thrown then. The instances are generated lazily as they are enumerated. An event with noDTSTARThas no instances.
The overloads without a resolver use IcalTimeZoneResolver.Default, which is IcalTimeZoneResolver.Calendar: it resolves a TZID only from the VTIMEZONE components of calendar, and with no calendar nothing resolves. A zoned DTSTART that does not resolve throws IcalFileException. For a calendar that uses a TZID with no VTIMEZONE, fall back to the TZ Database with a chain such as IcalTimeZoneResolver.Chain(IcalTimeZoneResolver.Calendar, IcalTimeZoneResolver.TzData). The overloads without options use a default IcalOptions, whose MaxRecurrenceIterations is 100,000.
Constructors
| Constructor | Notes |
|---|---|
IcalEvent() | Creates an empty VEVENT component, with no properties. |
Properties
| Property | Signature | Notes |
|---|---|---|
Alarms | IEnumerable<IcalAlarm> Alarms { get; } | The VALARM components (RFC 5545 §3.6.6) nested in the event, filtered from Components. |
Attendees | IReadOnlyList<IcalContentLine> Attendees { get; } | ATTENDEE (RFC 5545 §3.8.4.1), as the content lines themselves. Each is a CAL-ADDRESS with parameters such as CN and PARTSTAT. Change them through Properties. |
Categories | IReadOnlyList<string> Categories { get; set; } | CATEGORIES (RFC 5545 §3.8.1.2), the items of every CATEGORIES property. Setting writes one property holding the whole list; an empty list or null removes them. Throws ArgumentException on set if an item is null. |
Classification | string? Classification { get; set; } | CLASS (RFC 5545 §3.8.1.3), such as PUBLIC. TEXT. null removes it. |
Color | string? Color { get; set; } | COLOR (RFC 7986 §5.9), a CSS3 color name such as turquoise. TEXT. null removes it. |
Conferences | IReadOnlyList<IcalContentLine> Conferences { get; } | CONFERENCE (RFC 7986 §5.11), as the content lines themselves. Each is a URI with parameters such as FEATURE and LABEL. Change them through Properties. |
Created | IcalDateTime? Created { get; set; } | CREATED (RFC 5545 §3.8.7.1). A DATE-TIME, which RFC 5545 requires to be in UTC; setting a floating or zoned value throws ArgumentException. null removes it. |
Description | string? Description { get; set; } | DESCRIPTION (RFC 5545 §3.8.1.5). TEXT. null removes it. |
DtEnd | IcalDateOrDateTime? DtEnd { get; set; } | DTEND (RFC 5545 §3.8.2.2), a DATE or a DATE-TIME. The VALUE and TZID parameters are read and written with the value. null removes it. |
DtStamp | IcalDateTime? DtStamp { get; set; } | DTSTAMP (RFC 5545 §3.8.7.2). A DATE-TIME, which RFC 5545 requires to be in UTC; setting a floating or zoned value throws ArgumentException. null removes it. |
DtStart | IcalDateOrDateTime? DtStart { get; set; } | DTSTART (RFC 5545 §3.8.2.4), a DATE or a DATE-TIME. The VALUE and TZID parameters are read and written with the value. null removes it. |
Duration | IcalDuration? Duration { get; set; } | DURATION (RFC 5545 §3.8.2.5). null removes it. |
Images | IReadOnlyList<IcalContentLine> Images { get; } | IMAGE (RFC 7986 §5.10), as the content lines themselves. Each is a URI or inline BINARY data, with parameters such as DISPLAY and FMTTYPE. Change them through Properties. |
LastModified | IcalDateTime? LastModified { get; set; } | LAST-MODIFIED (RFC 5545 §3.8.7.3). A DATE-TIME, which RFC 5545 requires to be in UTC; setting a floating or zoned value throws ArgumentException. null removes it. |
Location | string? Location { get; set; } | LOCATION (RFC 5545 §3.8.1.7). TEXT. null removes it. |
Organizer | Uri? Organizer { get; set; } | ORGANIZER (RFC 5545 §3.8.4.3), a CAL-ADDRESS such as mailto:a@example.com. Throws ArgumentException on set for a relative URI. null removes it. |
Priority | int? Priority { get; set; } | PRIORITY (RFC 5545 §3.8.1.9), from 0 (undefined) and 1 (highest) to 9 (lowest). The setter does not check the range; Validate does. null removes it. |
RecurrenceId | IcalDateOrDateTime? RecurrenceId { get; set; } | RECURRENCE-ID (RFC 5545 §3.8.4.4), the instance this event overrides, a DATE or a DATE-TIME. The VALUE and TZID parameters are read and written with the value. null removes it. |
RecurrenceRules | IReadOnlyList<IcalRecurrenceRule> RecurrenceRules { get; set; } | RRULE (RFC 5545 §3.8.5.3), one rule per property. Setting writes one property per rule, in the place of the first; an empty list or null removes them. |
Resources | IReadOnlyList<string> Resources { get; set; } | RESOURCES (RFC 5545 §3.8.1.10), the items of every RESOURCES property. Setting writes one property holding the whole list; an empty list or null removes them. Throws ArgumentException on set if an item is null. |
Sequence | int? Sequence { get; set; } | SEQUENCE (RFC 5545 §3.8.7.4), the revision sequence number. null removes it. |
Status | string? Status { get; set; } | STATUS (RFC 5545 §3.8.1.11), such as CONFIRMED. TEXT. null removes it. |
Summary | string? Summary { get; set; } | SUMMARY (RFC 5545 §3.8.1.12). TEXT. null removes it. |
Transparency | string? Transparency { get; set; } | TRANSP (RFC 5545 §3.8.2.7), OPAQUE or TRANSPARENT. TEXT. null removes it. |
Uid | string? Uid { get; set; } | UID (RFC 5545 §3.8.4.7), a persistent, globally unique identifier. TEXT. null removes it. |
Url | Uri? Url { get; set; } | URL (RFC 5545 §3.8.4.6). Throws ArgumentException on set for a relative URI. null removes it. |
Every getter throws IcalFileException if the stored value is not valid for its type: a TEXT value or list item with a backslash that does not start a valid escape or with a comma or semicolon that is not escaped (RFC 5545 §3.3.11), a DATE-TIME property with VALUE=DATE, a value that does not parse, or a URI that is not absolute. TEXT properties remove TEXT escaping on get and add it on set.
Methods
| Method | Returns | Notes |
|---|---|---|
GetOccurrences(IcalCalendar? calendar, IcalDateTime? from, IcalDateTime? to) | IEnumerable<IcalOccurrence<IcalEvent>> | Expands the recurrence set with IcalTimeZoneResolver.Default and default options. See Recurrence expansion and the exceptions below. |
GetOccurrences(IcalCalendar? calendar, IcalDateTime? from, IcalDateTime? to, IIcalTimeZoneResolver resolver) | IEnumerable<IcalOccurrence<IcalEvent>> | Expands with resolver and default options. Throws ArgumentNullException if resolver is null. |
GetOccurrences(IcalCalendar? calendar, IcalDateTime? from, IcalDateTime? to, IIcalTimeZoneResolver resolver, IcalOptions options) | IEnumerable<IcalOccurrence<IcalEvent>> | Expands with resolver; of options, only MaxRecurrenceIterations applies. Throws ArgumentNullException if resolver or options is null, or ArgumentException if options.MaxRecurrenceIterations is less than 1. |
calendar is the calendar the event is in. It holds the VTIMEZONE components that time zones are resolved from, and the events that override instances. Pass null if there is none.
All three overloads throw:
ArgumentExceptioniftoisnulland anRRULEhas neitherCOUNTnorUNTIL, or if anRRULEhas a frequency belowDAILY, orBYHOUR,BYMINUTEorBYSECOND, andDTSTARTis a DATE.InvalidOperationExceptionif anRRULEbreaks a constraint listed underIcalRecurrenceRule.IsValid. Also thrown while enumerating, when more consecutive periods thanMaxRecurrenceIterationsgive no occurrence.IcalFileExceptionif a property the instances are found from is not valid, or a time zone cannot be resolved.ArgumentOutOfRangeExceptionwhile enumerating, if an instance or its end falls after 9999-12-31.
Inherited members Components, LineNumber, Name, Properties, GetProperty, GetProperties, SetProperty, RemoveProperties, Validate and ToString are documented on IcalComponent.
Applies to
Targets netstandard1.1, netstandard2.0, netstandard2.1, and net10.0. The nullable reference annotations, such as IcalCalendar? calendar, apply to the netstandard2.1 and net10.0 builds.