getRelativeDayResult method

RelativeDayResult? getRelativeDayResult({ DateTime? now, String weekdayFormatter(DateTime)?, })

Returns the full RelativeDayResult (bucket plus optional weekday name) for this date relative to now.

now defaults to DateTime.now when omitted. weekdayFormatter is the caller-supplied label source for the weekday buckets — the library stays intl-free and never touches app locale state by delegating the weekday string to the caller. When the bucket is not a weekday bucket the formatter is never called, so a null formatter is safe for all other buckets. Returns null for dates outside the classifiable window (see getSimpleRelativeDay).

A throwing weekdayFormatter propagates: the library does not swallow it, so a caller's locale failure surfaces rather than silently yielding a weekday bucket with a null name.

Example:

final DateTime now = DateTime(2024, 12, 29); // Sunday
final RelativeDayResult? r = DateTime(2025, 1, 1).getRelativeDayResult(
  now: now,
  weekdayFormatter: (d) => 'Wednesday',
);
r?.type;        // nextWeekday
r?.weekdayName; // 'Wednesday'

Audited: 2026-06-12 11:26 EDT

Implementation

RelativeDayResult? getRelativeDayResult({
  DateTime? now,
  String Function(DateTime)? weekdayFormatter,
}) {
  final DateTime today = _toDateOnly(now ?? DateTime.now());
  final DateTime dateOnly = _toDateOnly(this);

  // Whole calendar days: both operands are UTC midnight, so they are an exact
  // multiple of 24 hours apart and a DST "short day" cannot truncate the
  // count (see _toDateOnly for why local midnights would misreport here).
  final int daysDiff = dateOnly.difference(today).inDays;

  // Ordered cheapest-first: the exact single-day buckets and the named
  // weekday window never touch month math; the month boundary is the last
  // resort. The first non-null wins, so the buckets stay mutually exclusive.
  return _exactBucket(daysDiff) ??
      _weekdayWindowBucket(daysDiff, dateOnly, weekdayFormatter) ??
      _monthBucket(dateOnly, today);
}