README.md

STYME is a lightweight, zero-dependency C# library for parsing simple natural-language date/time expressions and applying them to a base date/time.

Usage Examples

Basic

using STYME;

// By default NaturalDateTime uses the current system time as the base
var parser = new NaturalDateTime();
var result = parser.Parse("add 2 days");
Console.WriteLine(result);

Output (example):

2025-10-04T14:23:00

You can parse expressions relative to a specific DateTime using NaturalDateTime.From.

using STYME;

var baseTime = new DateTime(2020, 1, 1, 0, 0, 0);
var parser = NaturalDateTime.From(baseTime);
var result = parser.Parse("add 1 month");
Console.WriteLine(result);

Output:

2020-02-01T00:00:00

Add

You can add time using the add keyword.

using STYME;

var baseTime = new DateTime(2020, 3, 1, 12, 0, 0);
var parser = NaturalDateTime.From(baseTime);
var result = parser.Parse("add 1 year");
Console.WriteLine(result);

Output:

2021-03-01T00:00:00

Deduct / Subtract

You can subtract time using the deduct (or subtract) keyword.

using STYME;

var baseTime = new DateTime(2020, 3, 1, 12, 0, 0);
var parser = NaturalDateTime.From(baseTime);
var result = parser.Parse("deduct 1 month");
Console.WriteLine(result);

Output:

2020-02-01T12:00:00

Chaining operations

You can chain multiple operations using and.

using STYME;

var baseTime = new DateTime(2020, 1, 1, 0, 0, 0);
var parser = NaturalDateTime.From(baseTime);
var result = parser.Parse("add 3 days and deduct 5 hours");
Console.WriteLine(result);

Output:

2020-01-03T19:00:00

Next

Use next to jump to the upcoming occurrence of a day of the week or a month. The time of day is preserved.

using STYME;

var baseTime = new DateTime(2025, 1, 1, 8, 0, 0);
var parser = NaturalDateTime.From(baseTime);
var result = parser.Parse("next monday");
Console.WriteLine(result);

Output:

2025-01-06T08:00:00

This operator can also be chained with the and operator.

using STYME;

var baseTime = new DateTime(2025, 1, 1, 8, 0, 0);
var parser = NaturalDateTime.From(baseTime);
var result = parser.Parse("next friday and add 2 hours");
Console.WriteLine(result);

Output:

2025-01-03T10:00:00

End of week/month/year

Use end to move to the end of the current week, month, or year. Fillers such as of and the are optional.

using STYME;

var baseTime = new DateTime(2025, 6, 15, 20, 45, 0);
var parser = NaturalDateTime.From(baseTime);
var result = parser.Parse("end of the month");
Console.WriteLine(result);

Output:

2025-06-30T20:45:00

Recurring schedules

You can generate a lazy sequence of future dates using every. The sequence is infinite, so add your own break condition.

using STYME;

var baseTime = new DateTime(2025, 1, 1, 0, 0, 0);
var parser = NaturalDateTime.From(baseTime);
var schedule = parser.Enumerate("every 2 weeks");

foreach (var occurrence in schedule)
{
    Console.WriteLine(occurrence);
    // Break when you reach the point you care about.
    if (occurrence >= new DateTime(2025, 2, 12))
    {
        break;
    }
}

Output:

2025-01-01T00:00:00
2025-01-15T00:00:00
2025-01-29T00:00:00
2025-02-12T00:00:00

Supported units with add and deduct

The add and deduct expressions support the following units (singular and plural forms):

• second, seconds
• minute, minutes
• hour, hours
• day, days
• week, weeks
• month, months
• year, years
• decade, decades
• century, centuries
• millennium, millennia

Example:

using STYME;

var parser = NaturalDateTime.From(new DateTime(2000, 1, 1));
Console.WriteLine(parser.Parse("add 2 decades")); // 2020-01-01
Console.WriteLine(parser.Parse("deduct 1 century")); // 1900-01-01

Todo

• Add month support (set DateTime to specific month)
• Add day support (i.e. "next friday")
• Add complex time support (i.e. "quarter past five")
• Add multiple complex operations (i.e. "add one year then next friday")

Support

• .NET 8.0 and later

License

STYME is licensed under the MIT License.