CronExpression Class

Definition

Namespace

Bodu.Globalization.Recurrence

Assembly

Bodu.Globalization.Recurrence.dll

Package

Bodu.Globalization.Recurrence 1.0.0

Source

CronExpression.Formatting.cs

Represents a parsed Vixie-style cron expression and computes the occurrences that satisfy it.

public sealed class CronExpression : IEquatable<CronExpression>, IFormattable, IParsable<CronExpression>

Inheritance

object

CronExpression

Implements

IEquatable<CronExpression>

IFormattable

IParsable<CronExpression>

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

A cron expression matches instants whose second (in the six-field WithSeconds layout), minute, hour, day-of-month, month, and day-of-week fields are each members of the corresponding field set. Each field supports *, single values, ranges (a-b), steps (*/n, a-b/n), and comma-separated lists, with three-letter month (JAN-DEC) and weekday (SUN-SAT) names. The macros @yearly / @annually, @monthly, @weekly, @daily / @midnight, and @hourly are also recognized.

When both the day-of-month and day-of-week fields are restricted, an instant matches if it satisfies either field, following the traditional Vixie cron rule. The Quartz extensions L, W, #, and ? are not yet supported.

Every occurrence answer is a pure function of the arguments: no API reads the wall clock or consults the machine time zone. The DateTimeOffset overloads interpret the wall-clock time in the argument's own offset and return occurrences carrying that offset; daylight-saving transitions are the caller's concern - a host that wants a local-time schedule across a transition re-derives the offset on each evaluation.

Occurrence searches are bounded by a twelve-year horizon in each direction, which covers the largest possible gap between occurrences of any satisfiable expression (a February 29th schedule crossing a non-leap century year); an expression that can never match, such as February 30th, answers null at the horizon rather than scanning unboundedly.

Properties

Format

Gets the field layout the expression was parsed as.

public CronFormat Format { get; }

Property Value

CronFormat

The cron field layout.

Methods

Equals(CronExpression?)

Determines whether this expression matches the same instants as another expression.

public bool Equals(CronExpression? other)

Parameters

other CronExpression

The expression to compare with this instance.

Returns

bool

true when other is non-null and every field set, together with the day-field combination mode, is equal; otherwise false.

Remarks

The day fields' restricted-ness participates through Bodu.Globalization.Recurrence.CronExpression.DaysCombineByUnion, because that is what selects the union or intersection branch in Bodu.Globalization.Recurrence.CronExpression.DayMatches(System.DateTime): 0 0 */2 * MON and 0 0 1-31/2 * MON carry identical masks yet select instants two weeks apart, so they are not equal values.

Only the combination mode is compared, not each flag, because a single restricted day field is not observable: * * 1-31 * * restricts the day-of-month while * * * * * does not, yet both fall to the intersection branch and select every day, so the two remain equal.

Equals(object?)

Determines whether this expression 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 a CronExpression equal to this instance; otherwise false.

GetHashCode()

Returns a hash code for the expression.

public override int GetHashCode()

Returns

int

A hash code consistent with Equals(CronExpression?).

Remarks

Every field mask contributes its contents, matching the fields Equals(CronExpression?) compares, as does the day-field combination mode. Mixing only each mask's cardinality would satisfy the equality contract but collapse the common case - a schedule selecting one value per field, such as 0 2 * * * - onto a single bucket.

GetNextOccurrence(DateTime, bool)

Returns the first instant matching the expression that falls after the specified instant.

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

Parameters

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 matching instant preserving the Kind of after, or null when none occurs within the search horizon.

GetNextOccurrence(DateTimeOffset, bool)

Returns the first instant matching the expression that falls after the specified instant, preserving its offset.

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

Parameters

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 matching instant carrying the offset of after, or null.

GetPreviousOccurrence(DateTime, bool)

Returns the last instant matching the expression that falls before the specified instant.

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

Parameters

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 matching instant preserving the Kind of before, or null when none occurs within the search horizon.

GetPreviousOccurrence(DateTimeOffset, bool)

Returns the last instant matching the expression that falls before the specified instant, preserving its offset.

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

Parameters

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 matching instant carrying the offset of before, or null.

Parse(string)

Parses a cron expression, inferring the field layout from the field count (five or six).

public static CronExpression Parse(string s)

Parameters

s string

The cron expression text.

Returns

CronExpression

The parsed expression.

Exceptions

ArgumentNullException

Thrown when s is null.

FormatException

Thrown when s is not a valid cron expression.

NotSupportedException

Thrown when the expression uses a Quartz extension token.

Parse(string, CronFormat)

Parses a cron expression using the specified field layout.

public static CronExpression Parse(string s, CronFormat format)

Parameters

s string

The cron expression text.

format CronFormat

The expected field layout.

Returns

CronExpression

The parsed expression.

Exceptions

ArgumentNullException

Thrown when s is null.

FormatException

Thrown when s does not match the layout.

NotSupportedException

Thrown when the expression uses a Quartz extension token.

ToString()

Returns the canonical cron text of the expression, with each field rendered as * or a comma-separated list of numeric values.

public override string ToString()

Returns

string

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

Remarks

Where the two day fields are concerned, Vixie reads restricted-ness from the field's leading character alone, and when both fields are restricted they combine by union rather than intersection. The canonical text therefore keeps a leading on an unrestricted field that does not select every value (/2), and keeps a restricted field explicit when it does (1-31), but only in the cases where the plain rendering would flip that combination - so the text always re-parses to an equal expression.

ToString(string?, IFormatProvider?)

Returns the canonical cron text of the expression.

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; cron text is culture-invariant.

Returns

string

The canonical cron text.

Exceptions

FormatException

Thrown when format is not a supported specifier.

TryParse(string?, out CronExpression)

Attempts to parse a cron expression, inferring the field layout from the field count.

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

Parameters

s string

The cron expression text.

result CronExpression

The parsed expression, or null on failure.

Returns

bool

true if parsing succeeded; otherwise false.

TryParse(string?, out CronExpression, out string?)

Attempts to parse a cron expression, reporting the parse defect on failure.

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

Parameters

s string

The cron expression text.

result CronExpression

The parsed expression, 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.

TryParse(string?, CronFormat, out CronExpression)

Attempts to parse a cron expression using the specified field layout.

public static bool TryParse(string? s, CronFormat format, out CronExpression result)

Parameters

s string

The cron expression text.

format CronFormat

The expected field layout.

result CronExpression

The parsed expression, or null on failure.

Returns

bool

true if parsing succeeded; otherwise false.

TryParse(string?, CronFormat, out CronExpression, out string?)

Attempts to parse a cron expression using the specified field layout, reporting the parse defect on failure.

public static bool TryParse(string? s, CronFormat format, out CronExpression result, out string? failureMessage)

Parameters

s string

The cron expression text.

format CronFormat

The expected field layout.

result CronExpression

The parsed expression, 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(string, IFormatProvider?)

Parses a cron expression, inferring the field layout from the field count (five or six).

static CronExpression Parse(string s, IFormatProvider? provider)

Parameters

s string

The cron expression text.

provider IFormatProvider

Unused; cron text is culture-invariant.

Returns

CronExpression

The parsed expression.

Exceptions

ArgumentNullException

Thrown when s is null.

FormatException

Thrown when s is not a valid cron expression.

NotSupportedException

Thrown when the expression uses a Quartz extension token.

TryParse(string?, IFormatProvider?, out CronExpression)

Attempts to parse a cron expression, inferring the field layout from the field count.

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

Parameters

s string

The cron expression text.

provider IFormatProvider

Unused; cron text is culture-invariant.

result CronExpression

The parsed expression, or null on failure.

Returns

bool

true if parsing succeeded; otherwise false.

Applies to

Product	Versions
.NET	8, 10