IcalComponent Class
Definition
Namespace: DataStandardizer.File.iCal
A component of iCalendar data (RFC 5545 §3.6): a name, an ordered list of properties, and the components nested in it. It is the base type of the typed components, such as IcalCalendar and IcalEvent, and the type a reader creates for a component it does not recognise, such as an X- component.
Syntax
public class IcalComponent
Remarks
Properties are content lines. Each property is held as an IcalContentLine, so its parameters stay reachable. Properties that have no typed accessor, including unknown and X- properties, are kept and written back as they were read. Property and component names are compared case-insensitively.
Typed accessors. The derived types add typed properties, such as IcalEvent.Summary or IcalEvent.DtStart, that read from and write to Properties. They all follow the same rules:
- A getter reads the first property of its name, and returns
nullif there is none. - A setter replaces every property of its name with one property, in the place of the first one it replaces, or at the end if there was none. It keeps the parameters of the first property, except those the new value decides:
VALUEandTZIDfor a date or time,VALUEfor a duration, andVALUEandENCODINGfor a URI. TheRecurrenceRulessetter keeps no parameters, andIcalAlarm.TriggerDateTimealso dropsRELATED. - Setting
nullremoves every property of that name. - A list accessor, such as
CategoriesorRecurrenceRules, reads every property of its name. Setting an empty list removes them all, as doesnull. A TEXT list, such asCategories, is written as one property holding the whole list. An item that isnullthrowsArgumentException. - TEXT escaping (RFC 5545 §3.3.11) is removed by the getter and added by the setter.
- A DATE or DATE-TIME setter writes
VALUE=DATEfor a date, and aTZIDparameter for a date-time in a named time zone. - A URI setter takes an absolute URI only, and throws
ArgumentExceptionfor a relative one. - The getter does not check the value until it is read. A value that is not valid for the property, such as
PRIORITY:highorSUMMARY:\x, makes the getter throw IcalFileException. The exception carries the line number of the property, when it was read from a source. Expect this for a model built in code from content lines, or one read withIcalOptions.AllowInvalidValuesturned on. - Some properties have no setter and return the content lines themselves, such as
Attendees,ImagesandConferences. Their parameters, such asCNorFMTTYPE, carry most of their meaning. Change them throughProperties.
Validity. The typed setters do not check the rules of RFC 5545 that span more than one property, such as whether a component has its required properties. Use Validate to check a model built in code.
Thread safety. A component has no locking. Don’t change it while another thread reads it.
Deriving. The class is not sealed and has a public constructor, but the helpers behind the typed accessors are internal. The typed components of the package are all sealed.
Constructors
| Constructor | Notes |
|---|---|
IcalComponent(string name) | Creates an empty component with the given name, such as X-ABC-PROJECT. The name must be an iana-token or x-name (RFC 5545 §3.1): one or more letters, digits and hyphens. Throws ArgumentNullException if name is null, or ArgumentException if it is empty or holds any other character. |
Properties
| Property | Signature | Notes |
|---|---|---|
Components | IList<IcalComponent> Components { get; } | The components nested in this one, in order. Adding or setting null throws ArgumentNullException. |
LineNumber | long LineNumber { get; } | The 1-based number of the logical line holding the component’s BEGIN. For a component read by XcalReader, the line of the XML document on which its element starts. 0 if the component was not read from a source. |
Name | string Name { get; } | The component name, such as VEVENT. |
Properties | IList<IcalContentLine> Properties { get; } | The properties, in order. Adding or setting null throws ArgumentNullException. |
Methods
Properties by name
All names are compared case-insensitively.
| Method | Returns | Notes |
|---|---|---|
GetProperty(string name) | IcalContentLine? | The first property with the name, or null if there is none. Throws ArgumentNullException if name is null. |
GetProperties(string name) | IReadOnlyList<IcalContentLine> | Every property with the name, in order, as a new list. Empty if there are none. Throws ArgumentNullException if name is null. |
SetProperty(IcalContentLine property) | void | Replaces every property with the same name as property with property. It takes the place of the first one it replaces, or is added at the end if there was none. Throws ArgumentNullException if property is null. |
RemoveProperties(string name) | int | Removes every property with the name, and returns how many were removed. Throws ArgumentNullException if name is null. |
Other methods
| Method | Returns | Notes |
|---|---|---|
Validate() | IReadOnlyList<IcalDiagnostic> | Checks the component, and the components nested in it, against the rules of RFC 5545 and RFC 7986 that IcalReader and IcalWriter enforce: required properties and components, how often each property may appear, the syntax of property values, how often parameters occur and how many values they have, the syntax of the FMTTYPE parameter, where each component may be nested, and the VERSION of a calendar. Whether a TZID parameter names a VTIMEZONE, and whether a VEVENT needs a DTSTART, are checked only when this is an IcalCalendar. Returns one IcalDiagnostic per problem, in the order of the lines they were found on, or an empty list. Never throws for a problem, whatever the options. A component path in a diagnostic starts with this component’s name, such as VCALENDAR/VEVENT[2]. |
ToString() | string | The name and the number of properties and components, such as VEVENT (5 properties, 1 components). |
Applies to
Targets netstandard1.1, netstandard2.0, netstandard2.1, and net10.0. The nullable reference annotations, such as the IcalContentLine? return of GetProperty, apply to the netstandard2.1 and net10.0 builds.