CronExpression Class
Definition
- Namespace
- Bodu.Globalization.Recurrence
- Assembly
- Bodu.Globalization.Recurrence.dll
- Package
- Bodu.Globalization.Recurrence 1.3.0
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
otherCronExpressionThe expression to compare with this instance.
Returns
- bool
true when
otheris 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
objobjectThe object to compare with this instance.
Returns
- bool
true when
objis 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
afterDateTimeThe instant the returned occurrence must follow.
inclusivebooltrue to allow an occurrence exactly equal to
after; otherwise the occurrence must be strictly later.
Returns
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
afterDateTimeOffsetThe instant the returned occurrence must follow.
inclusivebooltrue 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
beforeDateTimeThe instant the returned occurrence must precede.
inclusivebooltrue to allow an occurrence exactly equal to
before; otherwise the occurrence must be strictly earlier.
Returns
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
beforeDateTimeOffsetThe instant the returned occurrence must precede.
inclusivebooltrue 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
sstringThe cron expression text.
Returns
- CronExpression
The parsed expression.
Exceptions
- ArgumentNullException
Thrown when
sis null.- FormatException
Thrown when
sis 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
sstringThe cron expression text.
formatCronFormatThe expected field layout.
Returns
- CronExpression
The parsed expression.
Exceptions
- ArgumentNullException
Thrown when
sis null.- FormatException
Thrown when
sis 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
formatstringThe format specifier. Only the general specifier (
"G"or null) is supported.formatProviderIFormatProviderUnused; cron text is culture-invariant.
Returns
- string
The canonical cron text.
Exceptions
- FormatException
Thrown when
formatis 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
sstringThe cron expression text.
resultCronExpressionThe parsed expression, or null on failure.
Returns
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
sstringThe cron expression text.
resultCronExpressionThe parsed expression, or null on failure.
failureMessagestringnull on success; otherwise a message naming the specific defect, suitable for surfacing to the user verbatim.
Returns
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
sstringThe cron expression text.
formatCronFormatThe expected field layout.
resultCronExpressionThe parsed expression, or null on failure.
Returns
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
sstringThe cron expression text.
formatCronFormatThe expected field layout.
resultCronExpressionThe parsed expression, or null on failure.
failureMessagestringnull on success; otherwise a message naming the specific defect, suitable for surfacing to the user verbatim.
Returns
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
sstringThe cron expression text.
providerIFormatProviderUnused; cron text is culture-invariant.
Returns
- CronExpression
The parsed expression.
Exceptions
- ArgumentNullException
Thrown when
sis null.- FormatException
Thrown when
sis 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
sstringThe cron expression text.
providerIFormatProviderUnused; cron text is culture-invariant.
resultCronExpressionThe parsed expression, or null on failure.
Returns
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |