IcalDuration Struct

Definition

Namespace: DataStandardizer.File.iCal

A DURATION value (RFC 5545 §3.3.6): a number of weeks, or a number of days and an exact time, such as P15DT5H0M20S, -PT15M or P7W.

Syntax

public readonly struct IcalDuration : IEquatable<IcalDuration>, ISpanFormattable

Remarks

Nominal and exact parts. Weeks and days are nominal: added to a date-time, they move it by calendar days, which across a daylight saving change can be 23 or 25 hours. Hours, minutes and seconds are exact. So P1D and PT24H are different durations, and this type keeps them apart: they are not equal. For the same reason a duration in weeks (P1W) is not equal to the same number of days (P7D), although the two have the same effect.

Sign. The whole duration has one sign, so the parts are all negative or all positive. A zero duration is never negative, so -PT0S parses to the same value as PT0S. A leading + is accepted when parsing and never written.

Normal form. The exact time is held as a number of seconds and written in hours, minutes and seconds, so PT90M is written back as PT1H30M. A zero minute between an hour and a second is written, as RFC 5545 requires (PT1H0M5S). The default value is zero, written PT0S.

Forms. A duration has the same lexical form in every IcalValueFormat: Text (RFC 5545 §3.3.6), Json (RFC 7265 §3.6.6) and Xml (RFC 6321 §3.6.6). The format argument is checked but does not change the result. Parsing follows the RFC 5545 grammar: the designator letters may be upper or lower case, and the time parts must come in the order H, M, S with none skipped after the first, so PT1H20S is rejected. They are always written in upper case. White space is not trimmed, in any form.

Range. Weeks and days are each limited to int.MaxValue. The exact time is limited to what a TimeSpan can hold.

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 (covered by IcalValueAllocationTests). TryFormat writes straight into the destination span. ToString allocates a small buffer and the result string.

Constructors

Constructor Notes
IcalDuration(int days, TimeSpan time) Creates a duration of nominal days and an exact time. Throws ArgumentException if days and time have opposite signs, or time is not a whole number of seconds; or ArgumentOutOfRangeException if days is int.MinValue.

Properties

Property Signature Notes
Days int Days { get; } The number of nominal days, negative if the duration is negative. Does not include Weeks.
IsNegative bool IsNegative { get; } true if the duration is negative. Always false for a zero duration.
IsWeeks bool IsWeeks { get; } true if the duration is given in weeks. If so, Days and Time are zero.
Time TimeSpan Time { get; } The exact time, negative if the duration is negative.
Weeks int Weeks { get; } The number of nominal weeks, negative if the duration is negative.

Methods

Parsing

Method Returns Notes
Parse(ReadOnlySpan<char> value, IcalValueFormat format) IcalDuration Static. Throws FormatException if value is not a valid duration, or ArgumentOutOfRangeException if format is not an IcalValueFormat member.
TryParse(ReadOnlySpan<char> value, IcalValueFormat format, out IcalDuration result) bool Static. false if value is not a valid duration. Throws ArgumentOutOfRangeException if format is not an IcalValueFormat member. Does not allocate.

Formatting

Method Returns Notes
ToString() string The Text form, such as P15DT5H0M20S.
ToString(IcalValueFormat format) string The duration, which is the same in every form. Throws ArgumentOutOfRangeException if format is not an IcalValueFormat member.
TryFormat(Span<char> destination, out int charsWritten, IcalValueFormat format) bool Writes the duration. Returns false, with charsWritten 0, if destination is too short. Throws ArgumentOutOfRangeException if format is not an IcalValueFormat member.

Construction and arithmetic

Method Returns Notes
FromWeeks(int weeks) IcalDuration Static. A duration of nominal weeks. Throws ArgumentOutOfRangeException if weeks is int.MinValue.
Negate() IcalDuration The same duration with the opposite sign. A zero duration stays non-negative.

Equality

Method Returns Notes
Equals(IcalDuration other) bool true for the same sign, the same weeks, days and seconds, and the same IsWeeks. Nominal and exact parts are compared separately, so P1D does not equal PT24H, and P1W does not equal P7D.
Equals(object? obj) bool true when obj is an equal IcalDuration.
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
==(IcalDuration left, IcalDuration right) bool Same as left.Equals(right).
!=(IcalDuration left, IcalDuration 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 apply to the netstandard2.1 and net10.0 builds.

See also


This site uses Just the Docs, a documentation theme for Jekyll.