API Reference

January 23, 2026 · View on GitHub

This document provides a comprehensive reference for the NaturalCron library's public API.

// Parse a NaturalCron expression
var compiledExpr = NaturalCronExpr.Parse("daily at 14:30");

Quick Navigation

Parse Methods

Parse()

public static NaturalCronExpr Parse(string expression)

Parses a NaturalCron expression string into a NaturalCronExpr object.

Parameters:

  • expression: The NaturalCron expression string to parse

Returns: A NaturalCronExpr object representing the parsed expression

Throws: ArgumentException if the expression is invalid

TryParse()

public static (NaturalCronExpr?, IList<string> errors) TryParse(string expression)

Attempts to parse a NaturalCron expression string. Returns the parsed expression and any errors encountered.

Parameters:

  • expression: The NaturalCron expression string to parse

Returns: A tuple containing:

  • NaturalCronExpr?: The parsed expression object, or null if parsing failed
  • IList<string> errors: A list of error messages (empty if parsing succeeded)

Properties

Expression

public string Expression { get; }

The original expression string used to create this object.

Rules

public IReadOnlyCollection<NaturalCronRule> Rules { get; }

The parsed rules that define the recurrence.

Local Time Occurrence Methods

These methods work with the current thread's timezone and return results in the local timezone.

TryGetNextOccurrence()

public DateTime? TryGetNextOccurrence(DateTime baseTime, DateTime? maxLookahead = null)

Tries to get the next occurrence using the current thread's timezone. Returns null if no occurrence is found within the specified lookahead period.

Parameters:

  • baseTime: The base time in the current thread's timezone from which to find the next occurrence
  • maxLookahead: Maximum lookahead time in the current thread's timezone. If null, defaults to DateTime.MaxValue

Returns: The next occurrence in the current thread's timezone, or null if no occurrence is found

GetNextOccurrence()

public DateTime GetNextOccurrence(DateTime baseTime, DateTime? maxLookahead = null)

Gets the next occurrence using the current thread's timezone. Throws an exception if no occurrence is found within the specified lookahead period.

Parameters:

  • baseTime: The base time in the current thread's timezone from which to find the next occurrence
  • maxLookahead: Maximum lookahead time in the current thread's timezone. If null, defaults to DateTime.MaxValue

Returns: The next occurrence in the current thread's timezone

Throws: InvalidOperationException when no next occurrence is found

TryGetNextOccurrences()

public IList<DateTime> TryGetNextOccurrences(DateTime baseTime, int count, DateTime? maxLookahead = null)

Tries to get the next occurrences using the current thread's timezone. Returns as many occurrences as found, up to the specified count. Stops when no more occurrences are found or the count is reached.

Parameters:

  • baseTime: The base time in the current thread's timezone from which to find the next occurrences
  • count: The number of occurrences to retrieve
  • maxLookahead: Maximum lookahead time in the current thread's timezone. If null, defaults to DateTime.MaxValue

Returns: A list of occurrences in the current thread's timezone (may contain fewer than the requested count)

GetNextOccurrences()

public IList<DateTime> GetNextOccurrences(DateTime baseTime, int count, DateTime? maxLookahead = null)

Gets the next occurrences using the current thread's timezone. Throws an exception if fewer occurrences than requested are found. Use TryGetNextOccurrences if you are not sure there are enough occurrences available.

Parameters:

  • baseTime: The base time in the current thread's timezone from which to find the next occurrences
  • count: The number of occurrences to retrieve
  • maxLookahead: Maximum lookahead time in the current thread's timezone. If null, defaults to DateTime.MaxValue

Returns: A list of occurrences in the current thread's timezone

Throws: InvalidOperationException when fewer than the requested number of occurrences are found

UTC Occurrence Methods

These methods work with UTC times and return UTC results.

TryGetNextOccurrenceInUtc()

public DateTime? TryGetNextOccurrenceInUtc(DateTime utcBaseTime, DateTime? utcMaxLookahead = null)

Tries to get the next occurrence in UTC. Returns null if no occurrence is found within the specified lookahead period.

Parameters:

  • utcBaseTime: The base time in UTC from which to find the next occurrence
  • utcMaxLookahead: Maximum lookahead time in UTC. If null, defaults to DateTime.MaxValue

Returns: The next occurrence in UTC, or null if no occurrence is found

GetNextOccurrenceInUtc()

public DateTime GetNextOccurrenceInUtc(DateTime utcBaseTime, DateTime? utcMaxLookahead = null)

Gets the next occurrence in UTC. Throws an exception if no occurrence is found within the specified lookahead period.

Parameters:

  • utcBaseTime: The base time in UTC from which to find the next occurrence
  • utcMaxLookahead: Maximum lookahead time in UTC. If null, defaults to DateTime.MaxValue

Returns: The next occurrence in UTC

Throws: InvalidOperationException when no next occurrence is found

TryGetNextOccurrencesInUtc()

public IList<DateTime> TryGetNextOccurrencesInUtc(DateTime utcBaseTime, int count, DateTime? utcMaxLookahead = null)

Tries to get the next occurrences in UTC. Returns as many occurrences as found, up to the specified count. Stops when no more occurrences are found or the count is reached.

Parameters:

  • utcBaseTime: The base time in UTC from which to find the next occurrences
  • count: The number of occurrences to retrieve
  • utcMaxLookahead: Maximum lookahead time in UTC. If null, defaults to DateTime.MaxValue

Returns: A list of occurrences in UTC (may contain fewer than the requested count)

GetNextOccurrencesInUtc()

public IList<DateTime> GetNextOccurrencesInUtc(DateTime utcBaseTime, int count, DateTime? utcMaxLookahead = null)

Gets the next occurrences in UTC. Throws an exception if fewer occurrences than requested are found. Use TryGetNextOccurrencesInUtc if you are not sure there are enough occurrences available.

Parameters:

  • utcBaseTime: The base time in UTC from which to find the next occurrences
  • count: The number of occurrences to retrieve
  • utcMaxLookahead: Maximum lookahead time in UTC. If null, defaults to DateTime.MaxValue

Returns: A list of occurrences in UTC

Throws: InvalidOperationException when fewer than the requested number of occurrences are found

IANA Timezone Occurrence Methods

These methods work with a specified IANA timezone ID and return results in that timezone. The timezone ID is case-insensitive (e.g., "America/New_York" or "america/new_york").

TryGetNextOccurrenceInTz()

public DateTime? TryGetNextOccurrenceInTz(DateTime baseTimeInTz, string ianaTzId, DateTime? maxLookaheadInTz = null)

Tries to get the next occurrence in a specified IANA timezone. Returns null if no occurrence is found within the specified lookahead period.

Parameters:

  • baseTimeInTz: The base time interpreted in the specified IANA timezone from which to find the next occurrence
  • ianaTzId: IANA timezone ID (case-insensitive, e.g., "America/New_York" or "europe/lisbon")
  • maxLookaheadInTz: Maximum lookahead time in the specified timezone. If null, defaults to DateTime.MaxValue

Returns: The next occurrence in the specified timezone, or null if no occurrence is found

Throws: ArgumentException when the IANA timezone ID is invalid or not recognized

GetNextOccurrenceInTz()

public DateTime GetNextOccurrenceInTz(DateTime baseTimeInTz, string ianaTzId, DateTime? maxLookaheadInTz = null)

Gets the next occurrence in a specified IANA timezone. Throws an exception if no occurrence is found within the specified lookahead period.

Parameters:

  • baseTimeInTz: The base time interpreted in the specified IANA timezone from which to find the next occurrence
  • ianaTzId: IANA timezone ID (case-insensitive, e.g., "America/New_York" or "europe/lisbon")
  • maxLookaheadInTz: Maximum lookahead time in the specified timezone. If null, defaults to DateTime.MaxValue

Returns: The next occurrence in the specified timezone

Throws:

  • ArgumentException when the IANA timezone ID is invalid or not recognized
  • InvalidOperationException when no next occurrence is found

TryGetNextOccurrencesInTz()

public IList<DateTime> TryGetNextOccurrencesInTz(DateTime baseTimeInTz, int count, string ianaTzId, DateTime? maxLookaheadInTz = null)

Tries to get the next occurrences in a specified IANA timezone. Returns as many occurrences as found, up to the specified count. Stops when no more occurrences are found or the count is reached.

Parameters:

  • baseTimeInTz: The base time interpreted in the specified IANA timezone from which to find the next occurrences
  • count: The number of occurrences to retrieve
  • ianaTzId: IANA timezone ID (case-insensitive, e.g., "America/New_York" or "europe/lisbon")
  • maxLookaheadInTz: Maximum lookahead time in the specified timezone. If null, defaults to DateTime.MaxValue

Returns: A list of occurrences in the specified timezone (may contain fewer than the requested count)

Throws: ArgumentException when the IANA timezone ID is invalid or not recognized

GetNextOccurrencesInTz()

public IList<DateTime> GetNextOccurrencesInTz(DateTime baseTimeInTz, int count, string ianaTzId, DateTime? maxLookaheadInTz = null)

Gets the next occurrences in a specified IANA timezone. Throws an exception if fewer occurrences than requested are found. Use TryGetNextOccurrencesInTz if you are not sure there are enough occurrences available.

Parameters:

  • baseTimeInTz: The base time interpreted in the specified IANA timezone from which to find the next occurrences
  • count: The number of occurrences to retrieve
  • ianaTzId: IANA timezone ID (case-insensitive, e.g., "America/New_York" or "europe/lisbon")
  • maxLookaheadInTz: Maximum lookahead time in the specified timezone. If null, defaults to DateTime.MaxValue

Returns: A list of occurrences in the specified timezone

Throws:

  • ArgumentException when the IANA timezone ID is invalid or not recognized
  • InvalidOperationException when fewer than the requested number of occurrences are found

Timezone Behavior

Understanding how timezones work in NaturalCron is crucial for correct usage:

Expression Timezone vs Return Timezone

  1. Expression timezone (tz Asia/Tokyo): Specifies the timezone for calculation - when the recurrence rules are evaluated
  2. Return value timezone: Always matches the method used:
    • UTC methods (GetNextOccurrenceInUtc) → return UTC time
    • Local methods (GetNextOccurrence) → return system/local time
    • IANA timezone methods (GetNextOccurrenceInTz) → return in the specified IANA timezone

Example

For expression "daily at 09:00 tz Asia/Tokyo":

  • Calculates when 9:00 AM Tokyo time occurs
  • If using GetNextOccurrence(), calculates using Tokyo timezone and returns in the current thread timezone
  • If using GetNextOccurrenceInUtc(), calculates using Tokyo timezone and returns in UTC
  • If using GetNextOccurrenceInTz(baseTime, "America/New_York"), calculates using Tokyo timezone and returns in New York timezone
  • If no timezone in the expression, the calculation uses the input time's timezone context
  • The input parameter time is interpreted in:
    • Current thread timezone for local methods
    • UTC for UTC methods
    • The specified IANA timezone for IANA timezone methods

The tz keyword affects the calculation timezone, not the return timezone.

Usage Examples

Basic Usage

// Parse an expression
var expr = NaturalCronExpr.Parse("daily at 14:30");

// Get next occurrence in local time
var next = expr.GetNextOccurrence(DateTime.Now);

// Get next occurrence in UTC
var nextUtc = expr.GetNextOccurrenceInUtc(DateTime.UtcNow);

Safe Parsing

var (expr, errors) = NaturalCronExpr.TryParse("daily at 14:30");
if (expr != null)
{
    var next = expr.GetNextOccurrence(DateTime.Now);
}
else
{
    Console.WriteLine($"Parse errors: {string.Join(", ", errors)}");
}

Multiple Occurrences

var expr = NaturalCronExpr.Parse("every monday at 09:00");

// Get next 5 occurrences
var occurrences = expr.GetNextOccurrences(DateTime.Now, 5);

// Try to get next 10 occurrences (may return fewer)
var moreOccurrences = expr.TryGetNextOccurrences(DateTime.Now, 10);

Working with Timezones

var expr = NaturalCronExpr.Parse("daily at 09:00 tz America/New_York");

// This calculates 9 AM New York time and returns it in local system time
var nextLocal = expr.GetNextOccurrence(DateTime.Now);

// This calculates 9 AM New York time and returns it in UTC
var nextUtc = expr.GetNextOccurrenceInUtc(DateTime.UtcNow);

Working with Specific IANA Timezones

var expr = NaturalCronExpr.Parse("daily at 14:30");

// Get next occurrence in Tokyo time (input and output in Tokyo timezone)
var tokyoTime = new DateTime(2024, 1, 1, 10, 0, 0);
var nextInTokyo = expr.GetNextOccurrenceInTz(tokyoTime, "Asia/Tokyo");

// Get next 5 occurrences in London time
var londonTime = new DateTime(2024, 1, 1, 10, 0, 0);
var occurrencesInLondon = expr.GetNextOccurrencesInTz(londonTime, 5, "Europe/London");

// Case-insensitive timezone ID
var nextInNY = expr.GetNextOccurrenceInTz(DateTime.Now, "america/new_york");

// Safe usage with Try methods
var result = expr.TryGetNextOccurrenceInTz(DateTime.Now, "America/Los_Angeles");
if (result.HasValue)
{
    Console.WriteLine($"Next occurrence: {result.Value}");
}

Expression Timezone + Different Return Timezone

// Expression calculates in Tokyo time, but returns in New York time
var expr = NaturalCronExpr.Parse("daily at 09:00 tz Asia/Tokyo");
var nyTime = new DateTime(2024, 1, 1, 20, 0, 0); // 8 PM in New York
var nextInNY = expr.GetNextOccurrenceInTz(nyTime, "America/New_York");
// Returns when 9 AM Tokyo occurs, but expressed in New York timezone

Rule Filter Methods

These methods return subsets of rules filtered by time unit:

SecondRules()

public IReadOnlyCollection<NaturalCronRule> SecondRules()

Returns all rules that operate on seconds.

MinuteRules()

public IReadOnlyCollection<NaturalCronRule> MinuteRules()

Returns all rules that operate on minutes.

HourRules()

public IReadOnlyCollection<NaturalCronRule> HourRules()

Returns all rules that operate on hours.

DayRules()

public IReadOnlyCollection<NaturalCronRule> DayRules()

Returns all rules that operate on days.

WeekRules()

public IReadOnlyCollection<NaturalCronRule> WeekRules()

Returns all rules that operate on weeks.

MonthRules()

public IReadOnlyCollection<NaturalCronRule> MonthRules()

Returns all rules that operate on months.

YearRules()

public IReadOnlyCollection<NaturalCronRule> YearRules()

Returns all rules that operate on years.

TimeZoneRule()

public NaturalCronIanaTimeZoneRule? TimeZoneRule()

Returns the timezone rule if one is defined in the expression, otherwise null.

✅ Back to Main README