AnchoredInterval Class

Definition

Namespace

Bodu.Globalization.Recurrence

Assembly

Bodu.Globalization.Recurrence.dll

Package

Bodu.Globalization.Recurrence 1.0.0

Source

AnchoredInterval.Formatting.cs

Represents a recurrence whose occurrences repeat at a fixed Interval from a caller-supplied anchor instant, rather than being aligned to the calendar.

public sealed class AnchoredInterval : IEquatable<AnchoredInterval>, IFormattable, ISpanParsable<AnchoredInterval>, IParsable<AnchoredInterval>

Inheritance

object

AnchoredInterval

Implements

IEquatable<AnchoredInterval>

IFormattable

ISpanParsable<AnchoredInterval>

IParsable<AnchoredInterval>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Remarks

The occurrence series of an anchored interval is anchor + k·interval for k ≥ 1: the anchor itself is not an occurrence. The anchor models an instant such as "the last completed run", "first enrolment", or "contract start" - its meaning is entirely the caller's; this type never interprets it. Like RecurrenceRule, the interval carries no anchor of its own: the anchor is supplied to every occurrence query, so the same interval can be applied to different anchors.

Every answer is a pure function of the arguments. No API of this type reads the wall clock or consults the machine time zone; due-ness therefore stays the caller's one-line comparison, typically lastCompleted < GetPreviousOccurrence(now, inclusive: true) over instants the caller supplies. Missed occurrences coalesce structurally: an evaluation long after several missed occurrences answers identically to an evaluation just after the first one, because the answer is an instant, not a backlog.

The canonical textual form is the RFC 5545 §3.3.6 duration grammar, for example PT4H, P1D, P1DT2H30M, or P2W. Because that grammar carries no sub-second precision, the interval must be a positive whole number of seconds, which keeps ToString() an exact round-trip through Parse(string).

Constructors

AnchoredInterval(TimeSpan)

Initializes a new instance of the AnchoredInterval class.

public AnchoredInterval(TimeSpan interval)

Parameters

interval TimeSpan

The spacing between successive occurrences.

Exceptions

ArgumentOutOfRangeException

Thrown when interval is zero or negative.

ArgumentException

Thrown when interval carries sub-second ticks, which the canonical iCalendar duration text cannot represent.

Properties

Interval

Gets the spacing between successive occurrences.

public TimeSpan Interval { get; }

Property Value

TimeSpan

The positive, whole-second interval between occurrences.

Methods

Equals(AnchoredInterval?)

Determines whether this interval is equal to another interval.

public bool Equals(AnchoredInterval? other)

Parameters

other AnchoredInterval

The interval to compare with this instance.

Returns

bool

true when other is non-null and represents the same Interval; otherwise false.

Equals(object?)

Determines whether this interval is equal to another object.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with this instance.

Returns

bool

true when obj is an AnchoredInterval equal to this instance; otherwise false.

GetHashCode()

Returns a hash code for the interval.

public override int GetHashCode()

Returns

int

A hash code consistent with Equals(AnchoredInterval?).

GetNextOccurrence(DateTime, DateTime, bool)

Returns the first occurrence of the interval that falls after the specified instant.

public DateTime? GetNextOccurrence(DateTime anchor, DateTime after, bool inclusive = false)

Parameters

anchor DateTime

The instant the occurrence series is anchored to.

after DateTime

The instant the returned occurrence must follow.

inclusive bool

true to allow an occurrence exactly equal to after; otherwise the occurrence must be strictly later.

Returns

DateTime?

The next occurrence preserving the Kind of anchor, or null when no further occurrence is representable.

Remarks

The occurrence series is anchor + k·interval for k ≥ 1; when after precedes the first occurrence, the first occurrence is returned. The instants are compared by their tick values; Kind is never interpreted, so the caller is responsible for supplying commensurable arguments.

GetNextOccurrence(DateTimeOffset, DateTimeOffset, bool)

Returns the first occurrence of the interval that falls after the specified instant, normalising between the arguments' offsets.

public DateTimeOffset? GetNextOccurrence(DateTimeOffset anchor, DateTimeOffset after, bool inclusive = false)

Parameters

anchor DateTimeOffset

The instant the occurrence series is anchored to.

after DateTimeOffset

The instant the returned occurrence must follow.

inclusive bool

true to allow an occurrence exactly equal to after; otherwise the occurrence must be strictly later.

Returns

DateTimeOffset?

The next occurrence carrying the offset of after, or null when no further occurrence is representable.

Remarks

The arguments are compared as absolute instants, so an anchor supplied in UTC composes correctly with an after in any other offset. No offset conversion is performed beyond that normalisation; the machine time zone is never consulted.

GetOccurrences(DateTime)

Enumerates the occurrences of the interval anchored at the specified instant.

public IEnumerable<DateTime> GetOccurrences(DateTime anchor)

Parameters

anchor DateTime

The instant the occurrence series is anchored to.

Returns

IEnumerable<DateTime>

The occurrences anchor + k·interval for k ≥ 1 in ascending order, each preserving the Kind of anchor. The sequence ends at the last representable occurrence.

GetOccurrences(DateTime, DateTime, DateTime)

Enumerates the occurrences of the interval that fall within an inclusive window.

public IEnumerable<DateTime> GetOccurrences(DateTime anchor, DateTime from, DateTime to)

Parameters

anchor DateTime

The instant the occurrence series is anchored to.

from DateTime

The inclusive lower bound of the window.

to DateTime

The inclusive upper bound of the window.

Returns

IEnumerable<DateTime>

The occurrences within [from, to] in ascending chronological order.

GetOccurrences(DateTimeOffset)

Enumerates the occurrences of the interval anchored at the specified instant, preserving its offset.

public IEnumerable<DateTimeOffset> GetOccurrences(DateTimeOffset anchor)

Parameters

anchor DateTimeOffset

The instant the occurrence series is anchored to.

Returns

IEnumerable<DateTimeOffset>

The occurrences in ascending order, each carrying the offset of anchor. The sequence ends at the last representable occurrence.

GetOccurrences(DateTimeOffset, DateTimeOffset, DateTimeOffset)

Enumerates the occurrences of the interval that fall within an inclusive window, preserving the anchor's offset.

public IEnumerable<DateTimeOffset> GetOccurrences(DateTimeOffset anchor, DateTimeOffset from, DateTimeOffset to)

Parameters

anchor DateTimeOffset

The instant the occurrence series is anchored to.

from DateTimeOffset

The inclusive lower bound of the window.

to DateTimeOffset

The inclusive upper bound of the window.

Returns

IEnumerable<DateTimeOffset>

The occurrences within [from, to] in ascending chronological order.

Remarks

The window bounds are compared as absolute instants, so they may be supplied in offsets that differ from the anchor's; each returned occurrence carries the anchor's offset.

GetPreviousOccurrence(DateTime, DateTime, bool)

Returns the last occurrence of the interval that falls before the specified instant.

public DateTime? GetPreviousOccurrence(DateTime anchor, DateTime before, bool inclusive = false)

Parameters

anchor DateTime

The instant the occurrence series is anchored to.

before DateTime

The instant the returned occurrence must precede.

inclusive bool

true to allow an occurrence exactly equal to before; otherwise the occurrence must be strictly earlier.

Returns

DateTime?

The previous occurrence preserving the Kind of anchor, or null when no occurrence precedes before.

Remarks

Because the series starts at anchor + interval, the query answers null until the first occurrence has passed - the anchor itself is never returned. Due-ness therefore stays the caller's comparison lastCompleted < GetPreviousOccurrence(now, inclusive: true), with missed occurrences coalescing structurally.

GetPreviousOccurrence(DateTimeOffset, DateTimeOffset, bool)

Returns the last occurrence of the interval that falls before the specified instant, normalising between the arguments' offsets.

public DateTimeOffset? GetPreviousOccurrence(DateTimeOffset anchor, DateTimeOffset before, bool inclusive = false)

Parameters

anchor DateTimeOffset

The instant the occurrence series is anchored to.

before DateTimeOffset

The instant the returned occurrence must precede.

inclusive bool

true to allow an occurrence exactly equal to before; otherwise the occurrence must be strictly earlier.

Returns

DateTimeOffset?

The previous occurrence carrying the offset of before, or null when no occurrence precedes before.

Remarks

The arguments are compared as absolute instants, so an anchor supplied in UTC composes correctly with a before in any other offset. The anchor itself is never returned; see GetPreviousOccurrence(DateTime, DateTime, bool) for the due-ness rationale.

Parse(string)

Parses the RFC 5545 §3.3.6 duration text of an interval, such as PT4H or P1DT2H30M.

public static AnchoredInterval Parse(string s)

Parameters

s string

The duration text to parse.

Returns

AnchoredInterval

The parsed interval.

Exceptions

ArgumentNullException

Thrown when s is null.

FormatException

Thrown when s is not a valid positive iCalendar duration; the message names the defect.

ToString()

Returns the canonical RFC 5545 §3.3.6 duration text of the interval, such as PT4H or P1DT2H30M.

public override string ToString()

Returns

string

The canonical duration text, which round-trips through Parse(string).

Remarks

An interval that is an exact multiple of seven days renders in the weeks form (P2W); otherwise the normalized day and time components render with zero components omitted.

ToString(string?)

Returns the canonical RFC 5545 §3.3.6 duration text of the interval.

public string ToString(string? format)

Parameters

format string

The format specifier. Only the general specifier ("G" or null) is supported.

Returns

string

The canonical duration text.

Exceptions

FormatException

Thrown when format is not a supported specifier.

ToString(string?, IFormatProvider?)

Returns the canonical RFC 5545 §3.3.6 duration text of the interval.

public string ToString(string? format, IFormatProvider? formatProvider)

Parameters

format string

The format specifier. Only the general specifier ("G" or null) is supported.

formatProvider IFormatProvider

Unused; duration text is culture-invariant.

Returns

string

The canonical duration text.

Exceptions

FormatException

Thrown when format is not a supported specifier.

TryParse(string?, out AnchoredInterval)

Attempts to parse the RFC 5545 §3.3.6 duration text of an interval.

public static bool TryParse(string? s, out AnchoredInterval result)

Parameters

s string

The duration text to parse.

result AnchoredInterval

The parsed interval, or null on failure.

Returns

bool

true if parsing succeeded; otherwise false.

TryParse(string?, out AnchoredInterval, out string?)

Attempts to parse the RFC 5545 §3.3.6 duration text of an interval, reporting the parse defect on failure.

public static bool TryParse(string? s, out AnchoredInterval result, out string? failureMessage)

Parameters

s string

The duration text to parse.

result AnchoredInterval

The parsed interval, or null on failure.

failureMessage string

null on success; otherwise a message naming the specific defect, suitable for surfacing to the user verbatim.

Returns

bool

true if parsing succeeded; otherwise false.

Explicit Interface Implementations

Parse(ReadOnlySpan<char>, IFormatProvider?)

Parses the RFC 5545 §3.3.6 duration text of an interval from a character span.

static AnchoredInterval Parse(ReadOnlySpan<char> s, IFormatProvider? provider)

Parameters

s ReadOnlySpan<char>

The duration text to parse.

provider IFormatProvider

Unused; duration text is culture-invariant.

Returns

AnchoredInterval

The parsed interval.

Exceptions

FormatException

Thrown when s is not a valid positive iCalendar duration; the message names the defect.

Parse(string, IFormatProvider?)

Parses the RFC 5545 §3.3.6 duration text of an interval.

static AnchoredInterval Parse(string s, IFormatProvider? provider)

Parameters

s string

The duration text to parse.

provider IFormatProvider

Unused; duration text is culture-invariant.

Returns

AnchoredInterval

The parsed interval.

Exceptions

ArgumentNullException

Thrown when s is null.

FormatException

Thrown when s is not a valid positive iCalendar duration; the message names the defect.

TryParse(ReadOnlySpan<char>, IFormatProvider?, out AnchoredInterval)

Attempts to parse the RFC 5545 §3.3.6 duration text of an interval from a character span.

static bool TryParse(ReadOnlySpan<char> s, IFormatProvider? provider, out AnchoredInterval result)

Parameters

s ReadOnlySpan<char>

The duration text to parse.

provider IFormatProvider

Unused; duration text is culture-invariant.

result AnchoredInterval

The parsed interval, or null on failure.

Returns

bool

true if parsing succeeded; otherwise false.

TryParse(string?, IFormatProvider?, out AnchoredInterval)

Attempts to parse the RFC 5545 §3.3.6 duration text of an interval.

static bool TryParse(string? s, IFormatProvider? provider, out AnchoredInterval result)

Parameters

s string

The duration text to parse.

provider IFormatProvider

Unused; duration text is culture-invariant.

result AnchoredInterval

The parsed interval, or null on failure.

Returns

bool

true if parsing succeeded; otherwise false.

Applies to

Product	Versions
.NET	8, 10

See Also

RecurrenceRule

CronExpression