A period refers to a continuous time span with a well-defined start and end. It represents a range rather than a single event and serves as a frame of reference by providing structure.
Examples:
Q1 2025: January 1 – March 31, 2025FY2025: April 1, 2024 – March 31, 2025Week 5 of 2025: January 29 – February 4, 2025
In Chrononuensis, a period is represented by the interface IPeriod. Its canonical
date-domain representation is a non-empty half-open range:
[StartDate, EndDateExclusive)
The start belongs to the period and the exclusive end does not. Empty periods are
not valid, so EndDateExclusive must be after StartDate. This representation does
not require a time zone or a conversion to DateTime.
Types implementing IPeriod
The following types implement the IPeriod interface:
- Century
- Decade
- Olympiad
- Year
- YearSemester
- YearQuarter
- YearMonth
- YearWeek
- YearDay
- CustomPeriod
Each of these types provides a structured way to represent specific time intervals.
MonthDay and its parser are supported, but MonthDay does not implement IPeriod because a month and day without a year do not identify a continuous time span. See Structures for the complete structure and parser inventory.
Properties
All types implementing IPeriod expose the following properties:
Days
Returns the total number of days within the period.
var yearQuarter = YearQuarter.Parse("2025-Q1");
Assert.That(yearQuarter.Days, Is.EqualTo(31 + 28 + 31));
In this example, the first quarter of 2025 spans 31 days in January, 28 days in February, and 31 days in March (equal to 90 days).
StartDate
Returns the inclusive start date of the period.
var yearQuarter = YearQuarter.Parse("2025-Q1");
Assert.That(yearQuarter.StartDate, Is.EqualTo(new DateOnly(2025, 1, 1)));
The first date of Q1 2025 is January 1, 2025.
EndDateExclusive
Returns the first date after the period.
var yearQuarter = YearQuarter.Parse("2025-Q1");
Assert.That(yearQuarter.EndDateExclusive, Is.EqualTo(new DateOnly(2025, 4, 1)));
Q1 2025 includes dates up to March 31 and excludes April 1.
Custom periods
CustomPeriod uses the same canonical constructor contract:
var january = new CustomPeriod(
new DateOnly(2025, 1, 1),
new DateOnly(2025, 2, 1));
The constructor rejects equal or reversed bounds. To migrate code that supplies an
inclusive final date, use CustomPeriod.FromInclusiveDates(firstDate, lastDate).
An inclusive DateOnly.MaxValue cannot be converted because DateOnly has no value
for the following exclusive date. A canonical period may use DateOnly.MaxValue as
its exclusive end, making DateOnly.MaxValue.AddDays(-1) its latest included date.
Compatibility properties
FirstDate and LastDate remain available as inclusive display values derived from
the canonical bounds. LowerBound and UpperBound also remain available as derived
midnight DateTime values. New date-only code should use StartDate and
EndDateExclusive directly.
LowerBound
Represents the lower bound of the period, defined as a close/open interval, typically at the start of FirstDate
var yearQuarter = YearQuarter.Parse("2025-Q1");
Assert.That(yearQuarter.LowerBound, Is.EqualTo(new DateTime(2025, 1, 1, 0, 0, 0)));
The lower bound of Q1 2025 starts on January 1, 2025, at midnight.
UpperBound
Represents the upper bound of the period, defined as a close/open interval, typically at the start of the day following LastDate.
var yearQuarter = YearQuarter.Parse("2025-Q1");
Assert.That(yearQuarter.UpperBound, Is.EqualTo(new DateTime(2025, 4, 1, 0, 0, 0)));
The upper bound of Q1 2025 is April 1, 2025, at midnight, meaning the period runs from January 1, 2025 (inclusive) to April 1, 2025 (exclusive).
Equality
All supported IPeriod implementations compare by their resolved canonical bounds.
For example, a YearMonth and a CustomPeriod representing the same half-open range
are equal and have the same hash code, regardless of their concrete types.