IcalPeriod Struct
Definition
Namespace: DataStandardizer.File.iCal
A PERIOD value (RFC 5545 §3.3.9): a start and either an end or a positive duration, such as 19970101T180000Z/19970102T070000Z or 19970101T180000Z/PT5H30M. IcalFreeBusy.Periods holds values of this type.
Syntax
public readonly struct IcalPeriod : IEquatable<IcalPeriod>, ISpanFormattable
Remarks
Start, end and duration. A period has a start (IcalDateTime) and either an end or a duration (IcalDuration). End is null when the period has a duration, and Duration is null when it has an end.
Validity. RFC 5545 §3.3.9 says the start must be before the end, and the duration must be positive. The constructors and the parsers check this:
- An end is checked against the start only when both have the same kind and time zone, comparing their wall-clock fields. Values of different kinds or zones can’t be compared without resolving the zone, so they are accepted.
- A duration must not be negative or zero (
PT0S,P0DandP0Ware all rejected).
The default value starts and ends at 0001-01-01 at midnight, floating, which is not a valid period. It can be formatted, but not parsed back.
Time zones. A TZID parameter on the property applies to both the start and the end. Pass it as timeZoneId when parsing; neither date-time may then be in UTC. The time zone identifier is not written when formatting; it belongs in a TZID parameter.
Forms. A period is parsed from and formatted in one of the forms of IcalValueFormat. Every form joins the two parts with a solidus (/). The date-times use the form’s date-time syntax, and the duration is the same in every form.
| Form | Example | Standard |
|---|---|---|
Text | 19970101T180000Z/PT5H30M | RFC 5545 §3.3.9 |
Json | 1997-01-01T18:00:00Z/PT5H30M | RFC 7265 §3.6.9 |
Xml | 1997-01-01T18:00:00Z/PT5H30M | RFC 6321 §3.6.9 |
In a jCal document a period is a JSON array of two strings, and in an xCal document a period element holding start and end or duration elements. The Json and Xml forms are the two parts joined with a solidus; JcalReader, JcalWriter, XcalReader and XcalWriter map them to and from the array and the elements.
Parsing from a string. Parse and TryParse take a ReadOnlySpan<char>; there are no string overloads. A string converts to ReadOnlySpan<char> implicitly on .NET Core 2.1 and later and on .NET Standard 2.1. On .NET Framework, call AsSpan() on the string. The type does not implement IParsable<T> or ISpanParsable<T>, because parsing needs an IcalValueFormat.
Formatting. On the net10.0 build the type implements ISpanFormattable. An empty format string gives the Text form; T, J and X choose a form, in either case.
Allocation. TryParse from a span and TryFormat into a span do not allocate (covered by IcalValueAllocationTests). ToString allocates a small buffer and the result string.
Constructors
| Constructor | Notes |
|---|---|
IcalPeriod(IcalDateTime start, IcalDateTime end) | Creates a period with a start and an end. Throws ArgumentException if end has the same kind and time zone as start and is not later. |
IcalPeriod(IcalDateTime start, IcalDuration duration) | Creates a period with a start and a duration. Throws ArgumentException if duration is zero or negative. |
Properties
| Property | Signature | Notes |
|---|---|---|
Duration | IcalDuration? Duration { get; } | The duration; or null if the period has an end instead. |
End | IcalDateTime? End { get; } | The end; or null if the period has a duration instead. |
Start | IcalDateTime Start { get; } | The start. |
Methods
Parsing
| Method | Returns | Notes |
|---|---|---|
Parse(ReadOnlySpan<char> value, IcalValueFormat format) | IcalPeriod | Static. Parses a period whose date-times are floating or in UTC. Throws FormatException if value is not a valid period in format, or ArgumentOutOfRangeException if format is not an IcalValueFormat member. |
Parse(ReadOnlySpan<char> value, string? timeZoneId, IcalValueFormat format) | IcalPeriod | Static. Parses a period in the named time zone when timeZoneId is not null. Throws FormatException if value is not a valid period (including a date-time in UTC when timeZoneId is given); ArgumentException if timeZoneId is empty; or ArgumentOutOfRangeException if format is not an IcalValueFormat member. |
TryParse(ReadOnlySpan<char> value, IcalValueFormat format, out IcalPeriod result) | bool | Static. false if value is not a valid period in format. Throws ArgumentOutOfRangeException if format is not an IcalValueFormat member. Does not allocate. |
TryParse(ReadOnlySpan<char> value, string? timeZoneId, IcalValueFormat format, out IcalPeriod result) | bool | Static. As above, in the named time zone when timeZoneId is not null. Throws ArgumentException if timeZoneId is empty, or ArgumentOutOfRangeException if format is not an IcalValueFormat member. |
Formatting
| Method | Returns | Notes |
|---|---|---|
ToString() | string | The Text form. The time zone identifier is not written. |
ToString(IcalValueFormat format) | string | The period in format, without the time zone identifier. Throws ArgumentOutOfRangeException if format is not an IcalValueFormat member. |
TryFormat(Span<char> destination, out int charsWritten, IcalValueFormat format) | bool | Writes the period in format, without the time zone identifier. Returns false, with charsWritten 0, if destination is too short. Throws ArgumentOutOfRangeException if format is not an IcalValueFormat member. Does not allocate. |
Equality
| Method | Returns | Notes |
|---|---|---|
Equals(IcalPeriod other) | bool | true for equal starts and equal ends or durations. A period with an end never equals one with a duration. |
Equals(object? obj) | bool | true when obj is an equal IcalPeriod. |
GetHashCode() | int | Consistent with Equals. |
Explicit interface implementations (.NET)
| Member | Returns | Notes |
|---|---|---|
ISpanFormattable.TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format, IFormatProvider? provider) | bool | Calls TryFormat with the form named by format: empty or T for Text, J for Json, X for Xml, in either case. provider is ignored. Throws FormatException for any other format string. |
IFormattable.ToString(string? format, IFormatProvider? formatProvider) | string | Calls ToString(IcalValueFormat) with the form named by format, as above. Throws FormatException for any other format string. |
Operators
| Operator | Returns | Notes |
|---|---|---|
==(IcalPeriod left, IcalPeriod right) | bool | Same as left.Equals(right). |
!=(IcalPeriod left, IcalPeriod right) | bool | Same as !left.Equals(right). |
Applies to
Targets netstandard1.1, netstandard2.0, netstandard2.1, and net10.0. ISpanFormattable and its explicit members are implemented on the net10.0 build only. The nullable reference annotations, such as string? on the timeZoneId parameters, apply to the netstandard2.1 and net10.0 builds. JcalReader and JcalWriter are not available on netstandard1.1, but the Json form of this type is.