Table of Contents

Cron expressions

CronExpression is a parsed Vixie-style cron expression. It is a predicate over instants - an instant matches when its minute, hour, day-of-month, month, and day-of-week (and second, in the six-field layout) are each members of the corresponding field set - so, unlike a recurrence rule, it has no series start: GetNextOccurrence(after) and GetPreviousOccurrence(before) take only the boundary instant. It parses from text, renders back to canonical text, compares by value, and never reads the wall clock.

For the "which form" decision and the shared due-ness recipe, start at the recurrence overview.

Pattern 1 - parse and query

Parse(string) infers the layout from the field count: five fields is CronFormat.Standard (minute, hour, day-of-month, month, day-of-week) and six is CronFormat.WithSeconds (a leading seconds field). The Format property reports which one was chosen.

using Bodu.Globalization.Recurrence;

CronExpression nightly = CronExpression.Parse("0 2 * * *");           // Standard: 02:00 every day
CronExpression quarterHourly = CronExpression.Parse("0 */15 * * * *"); // WithSeconds (six fields)

CronFormat layout = quarterHourly.Format;                             // WithSeconds

var now = new DateTime(2026, 3, 10, 14, 32, 0);
DateTime? next = nightly.GetNextOccurrence(now);                      // 2026-03-11 02:00
DateTime? previous = nightly.GetPreviousOccurrence(now);              // 2026-03-10 02:00

Answers preserve the Kind of the argument and carry zero seconds in the five-field layout (an after of 01:59:30 still answers 02:00:00). Both boundary flags work as on every other form: inclusive: true lets an occurrence exactly equal to the boundary be returned.

using Bodu.Globalization.Recurrence;

CronExpression nightly = CronExpression.Parse("0 2 * * *");
var exactly = new DateTime(2026, 3, 10, 2, 0, 0);

DateTime? excl = nightly.GetNextOccurrence(exactly);                    // 2026-03-11 02:00
DateTime? incl = nightly.GetNextOccurrence(exactly, inclusive: true);   // 2026-03-10 02:00

Pass the layout explicitly with Parse(string, CronFormat) when the field count must not be inferred - a six-field string parsed as Standard, or a five-field string parsed as WithSeconds, fails with "A cron expression must contain the number of fields required by the specified format."

Pattern 2 - validate user input with TryParse

Five TryParse overloads cover the same choices without exceptions. The two that add out string? failureMessage name the defect, which is the right shape for configuration validation:

using Bodu.Globalization.Recurrence;

string[] candidates = ["0 2 * *", "60 * * * *", "0 0 L-31 * *", "0 2 * * FOO"];

foreach (string text in candidates)
{
    if (!CronExpression.TryParse(text, out CronExpression? expression, out string? failureMessage))
        Console.WriteLine($"'{text}': {failureMessage}");
}
// '0 2 * *':      A cron expression must contain the number of fields required by the specified format.
// '60 * * * *':   The cron field '60' is not valid.
// '0 0 L-31 * *': The cron field 'L-31' is not valid.
// '0 2 * * FOO':  The cron field 'FOO' is not valid.

// Layout-pinned variant, and the boolean-only overloads:
bool six = CronExpression.TryParse("0 */5 * * * *", CronFormat.WithSeconds, out CronExpression? withSeconds, out string? why);
bool ok  = CronExpression.TryParse("@daily", out CronExpression? daily);
bool ok2 = CronExpression.TryParse("@daily", CronFormat.Standard, out CronExpression? daily2);

Parse raises the same messages as FormatException. A seven-field Quartz string with a trailing year is rejected on field count.

Field syntax

Every field accepts *, a single value, a range a-b, a step */n, a-b/n or a/n (from a to the field's maximum), and comma-separated lists of those. Months take JAN-DEC and weekdays SUN-SAT, case-insensitively; weekday 7 is an alias for Sunday (0). The two day fields also accept ? and the Quartz day tokens described below.

Field Range Notes
second (six-field only) 0-59
minute 0-59
hour 0-23
day-of-month 1-31 also ?, L, L-n, LW, L-nW, and nW
month 1-12 or JAN-DEC
day-of-week 0-7 or SUN-SAT 0 and 7 are both Sunday; also ?, dL, and d#k

Several behaviours are worth stating because libraries disagree on them:

  • A step wider than its range selects the range start rather than being rejected: */60 and */90 in the minute field both mean minute 0 (cronie warns about this; some libraries throw). A step of 0 is rejected ("The cron field '1-5/0' is not valid.").
  • a/n runs to the field's maximum, and the day-of-week maximum is 7, which is Sunday again: 59/15 in the minute field is minute 59 alone, and 1/2 in the day-of-week field selects Monday, Wednesday, Friday and Sunday.
  • A range must ascend. A reversed range such as 55-5 or FRI-TUE is rejected rather than wrapped around the field, and so is MON-SUN, because SUN is 0: write MON-7 or 1-7 for Monday to Sunday.
  • Day-of-month and day-of-week combine by union only when both are restricted. Following Vixie cron, an instant matches when it satisfies either field if both are restricted, and both fields otherwise - and "restricted" is decided by the field's leading character, so */2 (leading *) is unrestricted while 1-31/2 is restricted even though the two select the same days:
using Bodu.Globalization.Recurrence;

var now = new DateTime(2026, 3, 10, 14, 32, 0);

// Both restricted → union: the 13th of any month OR any Friday.
DateTime? unionNext = CronExpression.Parse("0 0 13 * FRI").GetNextOccurrence(now);   // 2026-03-13 (a Friday)

// Day-of-month starts with '*' → not restricted → intersection: odd days that are Mondays.
DateTime? starStep = CronExpression.Parse("0 0 */2 * MON").GetNextOccurrence(now);    // 2026-03-23 Mon
// Same days written as a restricted range → union: odd days OR Mondays.
DateTime? rangeStep = CronExpression.Parse("0 0 1-31/2 * MON").GetNextOccurrence(now); // 2026-03-11 Wed
Note

Because the combination is chosen by the leading character rather than by the days a field selects, it is part of the expression's meaning. ToString() preserves it - 0 0 */2 * MON renders as 0 0 */2 * 1, keeping the star - so the canonical text always re-parses to the same schedule, and Equals treats the intersection and union readings as different values. Where the plain rendering cannot change the combination, it is used unchanged: * * */10 * * still renders as * * 1,11,21,31 * *, because the day-of-week * keeps that expression on the intersection branch either way.

The Quartz day tokens

The day fields also accept the tokens Quartz added to cron for days that a list of values cannot name. Each token stands for the whole field:

Token Field Selects
L day-of-month The last day of the month.
L-n day-of-month The day n days before the last, for n from 0 to 30: L-1 is the second-to-last day.
nW day-of-month The weekday (Monday to Friday) nearest day n, for n from 1 to 31, without leaving the month.
LW, L-nW day-of-month The weekday nearest the last day, or nearest the day n days before it.
dL day-of-week The month's last weekday d: FRIL and 5L are the last Friday.
d#k day-of-week The month's k-th weekday d, for k from 1 to 5: MON#1 is the first Monday.
? either No restriction, exactly as *.

The weekday nearest a Saturday is the Friday before it, and the weekday nearest a Sunday is the Monday after it, unless that would leave the month: a Saturday that begins the month moves on to Monday the 3rd, and a Sunday that ends it moves back to the Friday. A token that names no day of a month selects nothing in it, so 30W passes over February and MON#5 over every month with four Mondays.

using Bodu.Globalization.Recurrence;

var now = new DateTime(2026, 3, 10, 14, 32, 0);

DateTime? monthEnd    = CronExpression.Parse("0 23 L * *").GetNextOccurrence(now);    // 2026-03-31 23:00
DateTime? lastFriday  = CronExpression.Parse("0 17 * * FRIL").GetNextOccurrence(now); // 2026-03-27 17:00
DateTime? firstMonday = CronExpression.Parse("0 9 * * MON#1").GetNextOccurrence(now); // 2026-04-06 09:00
DateTime? nearFifteen = CronExpression.Parse("0 9 15W * *").GetNextOccurrence(now);   // 2026-03-16 09:00, as the 15th is a Sunday

// The 1st of August 2026 is a Saturday; the nearest weekday that stays in August is Monday the 3rd.
DateTime? firstWeekday = CronExpression.Parse("0 9 1W * *").GetNextOccurrence(new DateTime(2026, 7, 15));   // 2026-08-03 09:00

Three rules differ from Quartz itself, and matter when an expression is carried over from it:

  • Weekday numbers keep the Vixie numbering, 0 or 7 for Sunday through 6 for Saturday. Quartz numbers Sunday 1 through Saturday 7, so a Quartz 6#3, the third Friday, reads here as the third Saturday. A weekday written by name (FRI#3) means the same in both.
  • A token counts as a restriction for the union rule. 0 0 L * MON fires on the last day of every month and on every Monday. Quartz requires ? in one of the two day fields, so it never has to combine them; Cronos, which accepts both, takes the intersection.
  • A token stands for the whole field. It cannot be listed, ranged, or stepped (1,15W, L-3/2, and MON#1,FRI#1 are rejected), it is not accepted outside the two day fields, and L alone in the day-of-week field, which Quartz reads as Saturday, is rejected rather than guessed at.

The @ macros

Exactly seven macros are recognised, each expanding to a five-field expression. @reboot and Go-style @every are not supported and fail parsing with "The cron macro '@reboot' is not recognized, or a macro was supplied where the six-field layout was required."

Macro Equivalent Canonical ToString()
@yearly, @annually 00:00 on 1 January 0 0 1 1 *
@monthly 00:00 on the 1st 0 0 1 * *
@weekly 00:00 every Sunday 0 0 * * 0
@daily, @midnight 00:00 every day 0 0 * * *
@hourly minute 0 of every hour 0 * * * *

A macro always yields CronFormat.Standard; parsing one with CronFormat.WithSeconds fails.

Pattern 3 - business-hours polling

*/15 9-17 * * MON-FRI fires every quarter hour from 09:00 through 17:45 on weekdays. Because the hour field is a set, the last slot of the day is 17:45 and the next after that is 09:00 on the next weekday:

using Bodu.Globalization.Recurrence;

CronExpression polling = CronExpression.Parse("*/15 9-17 * * MON-FRI");

DateTime? next = polling.GetNextOccurrence(new DateTime(2026, 3, 13, 17, 50, 0));       // Fri 17:50 → 2026-03-16 Mon 09:00
DateTime? last = polling.GetPreviousOccurrence(new DateTime(2026, 3, 14, 10, 0, 0));    // Sat 10:00 → 2026-03-13 Fri 17:45

string canonical = polling.ToString();
// "0,15,30,45 9,10,11,12,13,14,15,16,17 * * 1,2,3,4,5"

To stop at 17:00 rather than 17:45, list the fields explicitly: */15 9-16 * * MON-FRI plus 0 17 * * MON-FRI as a second expression, or a RecurrenceRule with BYHOUR/BYMINUTE.

Pattern 4 - month-end jobs

L selects the last day of each month, whatever its length, and LW the last weekday of it, which is the last day itself unless that falls on a weekend:

using Bodu.Globalization.Recurrence;

CronExpression close   = CronExpression.Parse("0 23 L * *");
CronExpression payroll = CronExpression.Parse("0 18 LW * *");
var now = new DateTime(2026, 5, 10, 9, 0, 0);

DateTime? closing = close.GetNextOccurrence(now);    // 2026-05-31 23:00, a Sunday
DateTime? paying  = payroll.GetNextOccurrence(now);  // 2026-05-29 18:00, the Friday before it

LW knows weekends but not public holidays. To skip those too, filter the occurrences with IsNonWorkingDay from Bodu.Globalization.Calendar - see Hosting schedules. The same last-weekday schedule written as a recurrence rule, FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1, is pattern 6 of the rule guide.

Every search scans 400 years in the requested direction: one whole cycle of the Gregorian calendar, which repeats exactly every 400 years (146,097 days, a whole number of weeks, with its leap days in the same places). An expression without a match in the cycle never matches, so a search answers null only when no occurrence follows (or precedes) the query at all. Occurrences can be decades apart: 29 February on a chosen weekday recurs at gaps of up to forty years, across the non-leap 2100 included.

using Bodu.Globalization.Recurrence;

DateTime? leapDay   = CronExpression.Parse("0 0 29 2 *").GetNextOccurrence(new DateTime(2096, 3, 1));      // 2104-02-29
DateTime? fifthMon  = CronExpression.Parse("0 0 * 2 MON#5").GetNextOccurrence(new DateTime(2016, 3, 1));   // 2044-02-29
DateTime? never     = CronExpression.Parse("0 0 30 2 *").GetNextOccurrence(new DateTime(2026, 3, 10));     // null
DateTime? neverBack = CronExpression.Parse("0 0 30 2 *").GetPreviousOccurrence(new DateTime(2026, 3, 10)); // null

A search near either end of the calendar answers null rather than step past 0001-01-01 or 9999-12-31, and the DateTimeOffset overloads answer null for an occurrence whose UTC instant falls outside that range.

null therefore means "never": no occurrence lies in that direction anywhere in the calendar.

DateTimeOffset handling

The DateTimeOffset overloads interpret the argument's wall-clock time in its own offset and return an occurrence carrying that offset - no conversion, no time-zone lookup. 0 9 * * * queried at 2026-03-10 14:32 +10:00 answers 2026-03-11 09:00 +10:00; queried at 14:32 +00:00 it answers 09:00 +00:00. A host that wants "09:00 local" across a daylight-saving change re-derives the offset on every evaluation; see Hosting schedules.

using Bodu.Globalization.Recurrence;

CronExpression nine = CronExpression.Parse("0 9 * * *");
var sydney = new DateTimeOffset(2026, 3, 10, 14, 32, 0, TimeSpan.FromHours(10));

DateTimeOffset? next = nine.GetNextOccurrence(sydney);   // 2026-03-11 09:00 +10:00

Canonical text and equality

ToString() renders a field as * when every value is selected and otherwise as an ascending comma-separated numeric list - names, ranges, and steps are expanded, and 7 becomes 0. The two day fields are the exception: where the plain rendering would flip the union / intersection combination, the field keeps a spelling that preserves it (*/2 stays */2, a restricted but complete field stays 1-31), so the canonical 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 (FRIL as 5L, L-0W as LW, MON#1 as 1#1), and ? as *. Equals compares the six field sets, the layout, and that combination, so 0 9-17 * * MON-FRI equals 0 9,10,11,12,13,14,15,16,17 * * 1-5 while 0 0 */2 * MON does not equal 0 0 1-31/2 * MON - the two select instants two weeks apart. A single restricted day field is not observable on its own, so * * * * * and * * 1-31 * * remain equal. A token compares by its canonical form, so 0L equals 7L and L-0 equals L, while 0 0 L 1 * does not equal 0 0 31 1 * although both fire only on 31 January, as Cronos also holds. Only the "G" / null format specifier is defined on ToString(string?, IFormatProvider?); anything else throws FormatException.

API summary

Member Purpose
Parse(string) / Parse(string, IFormatProvider?) Parse, inferring the layout from the field count.
Parse(string, CronFormat) Parse with a required layout.
TryParse(string?, out result) / TryParse(string?, IFormatProvider?, out result) / TryParse(string?, CronFormat, out result) Boolean parse.
TryParse(string?, out result, out failureMessage) / TryParse(string?, CronFormat, out result, out failureMessage) Boolean parse that names the defect.
Format The layout the expression was parsed as.
GetNextOccurrence(after, inclusive = false) Next matching instant, or null when none follows; DateTime and DateTimeOffset.
GetPreviousOccurrence(before, inclusive = false) Previous matching instant, or null when none precedes.
ToString() / ToString(string?, IFormatProvider?) Canonical text: numeric lists and the Quartz day tokens.
Equals / GetHashCode Field-set equality.

Where to go next