Table of Contents

CronExpression Class

Definition

Namespace
Bodu.Globalization.Recurrence
Assembly
Bodu.Globalization.Recurrence.dll
Package
Bodu.Globalization.Recurrence 1.3.0
Source
CronExpression.DayOfMonthToken.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
CronExpression
Implements
Inherited Members
Extension Methods

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.

The day fields also accept the Quartz tokens, each standing for the whole field. In the day-of-month field L is the last day of the month and L-n the day n days before it, up to thirty; LW and L-nW are the weekday nearest either; and nW is the weekday nearest the n-th, without leaving the month. In the day-of-week field dL is the month's last weekday d and d#k its k-th, from one to five, with d a number or a name as elsewhere in the field. Either day field accepts ? for *. A token that names no day of a month, such as 30W in February or a fifth Tuesday a month lacks, selects nothing that month.

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; a token counts as a restriction and ?, like *, does not. Quartz itself would require the instant to satisfy both. Weekdays keep the Vixie numbering, in which both zero and seven are Sunday, rather than the Quartz numbering from one.

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 scan 400 years in each direction: one whole cycle of the Gregorian calendar, which repeats exactly every 400 years, so an expression without a match in the cycle never matches, and a search answers null only when no occurrence follows (or precedes) the instant at all. Occurrences of a satisfiable expression can be decades apart: the 29th of February on a chosen weekday recurs at gaps of up to forty years. A search also answers null rather than pass either end of the calendar, 0001-01-01 or 9999-12-31, and the DateTimeOffset overloads do so for an occurrence whose UTC instant falls outside that range.

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 and any Quartz day token, 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 field sets 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 set contributes its values, matching the fields Equals(CronExpression?) compares, as does the day-field combination mode. Mixing only each field's count 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 no later instant in the calendar matches.

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 when no later instant that a DateTimeOffset can hold matches.

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 no earlier instant in the calendar matches.

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 when no earlier instant that a DateTimeOffset can hold matches.

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; the message names the defect.

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 is not a valid cron expression in the layout; the message names the defect.

ToString()

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

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. A Quartz day token is written in upper case with a numeric weekday and no zero offset (SUNL as 0L, l-0w as LW), and ? as *.

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; the message names the defect.

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

ProductVersions
.NET8, 10