inYear method

MssqlCondition inYear(int year, { MssqlOperator operator = MssqlOperator.eq, Duration? zoneOffset, })

Every row whose value falls in year, as a half-open range.

The sargable form: [CreatedAt] >= @start AND [CreatedAt] < @end leaves the column bare, so an index on it can still be seeked. whereYear asks the same question as YEAR([CreatedAt]) = 2026, which hides the column from its own index — and which is still the only way to ask for a year in the offset a datetimeoffset column stored, rather than in a calendar the caller names. That is why both exist.

operator chooses which boundary is meant: lt is before the year, lte is up to the end of it, gt is after it, gte is from its start.

zoneOffset is required for a datetimeoffset column and refused for every other: a calendar year is not one range on that type until the offset is stated.

Implementation

MssqlCondition inYear(
  int year, {
  MssqlOperator operator = MssqlOperator.eq,
  Duration? zoneOffset,
}) {
  if (year < 1 || year > 9999) {
    throw ArgumentError.value(
      year,
      'year',
      'SQL Server dates run from year 1 to year 9999.',
    );
  }
  return MssqlCalendarRange(
    this,
    start: DateTime(year),
    // DateTime(year + 1) rather than adding 365 days: the calendar
    // constructor normalises, and adding a duration to a local DateTime
    // lands an hour out either side of a daylight-saving boundary.
    endExclusive: DateTime(year + 1),
    operator: operator,
    zoneOffset: zoneOffset,
  );
}