IcalDateTime Struct
Definition
Namespace: DataStandardizer.File.iCal
A DATE-TIME value (RFC 5545 §3.3.5): a date and a time of day, which is floating, in UTC, or in a named time zone. It is made of an IcalDate and an IcalTime, plus the time zone identifier of a zoned value.
Syntax
public readonly struct IcalDateTime : IEquatable<IcalDateTime>, ISpanFormattable
Remarks
Kinds. Kind says which form the value has:
Floating: no time zone, such as19980118T230000.Utc: the time is in UTC, such as19980119T070000Z.Zoned: a local time in the zone named by the property’sTZIDparameter.
A zoned value carries the time zone identifier from its TZID parameter. The identifier is not part of the value’s lexical form. You supply it to the Parse and TryParse overloads that take timeZoneId, and TryFormat and ToString don’t write it. RFC 5545 §3.2.19 says TZID must not be applied to a time in UTC, so a zoned value always has a floating Time.
The default value is 0001-01-01 at midnight, floating.
Forms. A date-time is parsed from and formatted in one of the forms of IcalValueFormat:
| Form | Example | Standard |
|---|---|---|
Text | 19980118T230000, 19980119T070000Z | RFC 5545 §3.3.5 |
Json | 1998-01-18T23:00:00, 1998-01-19T07:00:00Z | RFC 7265 §3.6.5 |
Xml | 1998-01-18T23:00:00, 1998-01-19T07:00:00Z | RFC 6321 §3.6.5 |
The Json and Xml forms are the same. Parsing needs exactly the whole value, with a real date and no fractional seconds. The T separator and Z suffix may be upper or lower case; they are always written in upper case.
Equality. Two values are equal when they have the same date, time and kind, and, for zoned values, the same time zone identifier. Identifiers are compared ordinally, so identifiers that differ only in case are different zones. A floating value never equals a value in UTC. The type has no ordering: it does not implement IComparable<T> and has no < or > operators, because comparing values of different kinds or zones needs a time zone resolver. See Time zone resolution.
Leap seconds. A time with a second of 60 can be parsed and held, but ToDateTime throws InvalidOperationException for it, because DateTime cannot represent it.
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 does not allocate, including the overload that takes a time zone identifier, which keeps a reference to the string it is given. TryFormat into a span does not allocate. Both are covered by IcalValueAllocationTests. ToString allocates a small buffer and the result string.
Constructors
| Constructor | Notes |
|---|---|
IcalDateTime(IcalDate date, IcalTime time) | Creates a floating date-time, or one in UTC if time.IsUtc is true. |
IcalDateTime(IcalDate date, IcalTime time, string timeZoneId) | Creates a zoned date-time. Throws ArgumentNullException if timeZoneId is null, or ArgumentException if timeZoneId is empty or time is in UTC. |
Properties
| Property | Signature | Notes |
|---|---|---|
Date | IcalDate Date { get; } | The date. |
Kind | IcalDateTimeKind Kind { get; } | Zoned if there is a time zone identifier, Utc if the time is in UTC, otherwise Floating. |
Time | IcalTime Time { get; } | The time of day. Its IsUtc is true only when Kind is Utc. |
TimeZoneId | string? TimeZoneId { get; } | The time zone identifier of a zoned value; or null if the value is floating or in UTC. |
Methods
Parsing
| Method | Returns | Notes |
|---|---|---|
Parse(ReadOnlySpan<char> value, IcalValueFormat format) | IcalDateTime | Static. Parses a floating date-time or one in UTC. Throws FormatException if value is not a valid date-time in format, or ArgumentOutOfRangeException if format is not an IcalValueFormat member. |
Parse(ReadOnlySpan<char> value, string? timeZoneId, IcalValueFormat format) | IcalDateTime | Static. Parses a zoned date-time when timeZoneId is not null; otherwise as above. Throws FormatException if value is not valid, or is in UTC and timeZoneId is given; ArgumentException if timeZoneId is empty; or ArgumentOutOfRangeException if format is not an IcalValueFormat member. |
TryParse(ReadOnlySpan<char> value, IcalValueFormat format, out IcalDateTime result) | bool | Static. false if value is not a valid date-time in format. Throws ArgumentOutOfRangeException if format is not an IcalValueFormat member. Does not allocate. |
TryParse(ReadOnlySpan<char> value, string? timeZoneId, IcalValueFormat format, out IcalDateTime result) | bool | Static. As above, giving a zoned value when timeZoneId is not null. false if value is in UTC and timeZoneId is given. Throws ArgumentException if timeZoneId is empty, or ArgumentOutOfRangeException if format is not an IcalValueFormat member. Does not allocate. |
Formatting
| Method | Returns | Notes |
|---|---|---|
ToString() | string | The Text form, such as 19980119T070000Z. The time zone identifier is not written. |
ToString(IcalValueFormat format) | string | The date-time 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 date-time in format, without the time zone identifier, which belongs in a TZID parameter. Returns false, with charsWritten 0, if destination is too short (up to 16 characters for Text, 20 for Json and Xml). Throws ArgumentOutOfRangeException if format is not an IcalValueFormat member. Does not allocate. |
Conversion
| Method | Returns | Notes |
|---|---|---|
FromDateTime(DateTime value) | IcalDateTime | Static. A date-time in UTC if value.Kind is DateTimeKind.Utc, otherwise a floating one. Fractions of a second are dropped. |
FromDateTime(DateTime value, string timeZoneId) | IcalDateTime | Static. A zoned date-time from the wall-clock time of value. Fractions of a second and value.Kind are ignored. Throws ArgumentNullException if timeZoneId is null, or ArgumentException if it is empty. |
ToDateTime() | DateTime | Of kind DateTimeKind.Utc for a value in UTC; otherwise of kind DateTimeKind.Unspecified holding the wall-clock time. A zoned value is not converted to UTC. Throws InvalidOperationException if the second is 60. |
Equality
| Method | Returns | Notes |
|---|---|---|
Equals(IcalDateTime other) | bool | true for the same date, time and kind, and for zoned values the same time zone identifier, compared ordinally. |
Equals(object? obj) | bool | true when obj is an equal IcalDateTime. |
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 |
|---|---|---|
==(IcalDateTime left, IcalDateTime right) | bool | Same as left.Equals(right). |
!=(IcalDateTime left, IcalDateTime 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 TimeZoneId and on the timeZoneId parameters, apply to the netstandard2.1 and net10.0 builds.