IcalJournal Class
Definition
Namespace: DataStandardizer.File.iCal
A journal entry (RFC 5545 §3.6.3): the VJOURNAL component. It gives typed access to the properties of a journal entry, and expands its recurrence set into occurrences.
Syntax
public sealed class IcalJournal : 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.
RFC 5545 lets a VJOURNAL have more than one DESCRIPTION. So Descriptions gives the content lines themselves, and has no setter. Change them through Properties, or replace them all with one by calling SetProperty.
Recurrence expansion. GetOccurrences finds the instances as IcalEvent does, with the journal entries of calendar as the overrides. A journal entry has no end, so no instance has one, and IcalOccurrence.End is always null. The properties are read, and the time zones of DTSTART and the window resolved, when GetOccurrences is called. The instances are generated lazily as they are enumerated. A journal entry with no DTSTART has 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. The overloads without options use a default IcalOptions.
Constructors
| Constructor | Notes |
|---|---|
IcalJournal() | Creates an empty VJOURNAL component, with no properties. |
Properties
| Property | Signature | Notes |
|---|---|---|
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. |
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. |
Descriptions | IReadOnlyList<IcalContentLine> Descriptions { get; } | DESCRIPTION (RFC 5545 §3.8.1.5), as the content lines themselves. The values keep their TEXT escaping; call IcalContentLine.GetTextValue to remove 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. |
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. |
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. |
RecurrenceId | IcalDateOrDateTime? RecurrenceId { get; set; } | RECURRENCE-ID (RFC 5545 §3.8.4.4), the instance this journal entry 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. |
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 DRAFT or FINAL. TEXT. null removes it. |
Summary | string? Summary { get; set; } | SUMMARY (RFC 5545 §3.8.1.12). 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<IcalJournal>> | Expands the recurrence set with IcalTimeZoneResolver.Default and default options. |
GetOccurrences(IcalCalendar? calendar, IcalDateTime? from, IcalDateTime? to, IIcalTimeZoneResolver resolver) | IEnumerable<IcalOccurrence<IcalJournal>> | 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<IcalJournal>> | 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 journal entry is in, which holds the VTIMEZONE components and the overriding journal entries, or null. from is inclusive and to exclusive; either may be null for no limit, but a null to needs every RRULE to have COUNT or UNTIL. All three overloads throw the same exceptions as IcalEvent.GetOccurrences: ArgumentException, InvalidOperationException, IcalFileException and, while enumerating, ArgumentOutOfRangeException.
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 apply to the netstandard2.1 and net10.0 builds.