relative method

String relative({ DateTime? to, Duration? formatAfter, String format = AmericanDateTimeFormats.abbrWithComma, bool round = true, bool abbr = false, Map<UnitOfTime, String>? abbreviations, int levelOfPrecision = 0, UnitOfTime minUnitOfTime = UnitOfTime.second, UnitOfTime maxUnitOfTime = UnitOfTime.year, bool excludeWeeks = false, String? ifNow, String? prependIfBefore, String? appendIfAfter, })

Formats this to a human-readable relative time format, relative to to.

to defaults to DateTime.now().

If formatBefore is not null, dateTime will be formatted to the format specified by format if dateTime occured before formatBefore.

If abbr is true, the labels for the units of time (seconds, minutes, hours, etc...) will be abbreviated to the first character of each label, respectively. If false, the entire word will be returned.

If round is true, units of time will be rounded up to the minimum allowed unit of time, as defined by levelOfPrecision and minUnitOfTime, see below. If false, values below the minimum allowed unit of time will be truncated.

levelOfPrecision defines the minimum allowable degree of separation from the maximum unit of time counted. I.e. minutes are 1 degree removed from hours, and seconds are 2 degrees removed from hours but only 1 degree removed from minutes. Note: Weeks will not be counted as a unit of time if excludeWeeks is true, see below.

minUnitOfTime is the minimum unit of time that will be included in the count. minUnitOfTime.index must be >= maxUnitOfTime.index.

maxUnitOfTime is the maximum unit of time that will be included in the count.

If excludeWeeks is true, weeks won't be counted. Instead, days will counted up to their respective month's number of days.

If ifNow is supplied, the value of ifNow will be returned in the event the difference is less than the smallest allowed interval of time, otherwise an empty string will be returned.

If prependIfBefore is not null and dateTime occurs before relativeTo, its value will be prepended to the returned string.

If appendIfAfter is not null and dateTime occurs after relativeTo, its value will be appended to the returned string.

Implementation

String relative({
  DateTime? to,
  Duration? formatAfter,
  String format = AmericanDateTimeFormats.abbrWithComma,
  bool round = true,
  bool abbr = false,
  Map<UnitOfTime, String>? abbreviations,
  int levelOfPrecision = 0,
  UnitOfTime minUnitOfTime = UnitOfTime.second,
  UnitOfTime maxUnitOfTime = UnitOfTime.year,
  bool excludeWeeks = false,
  String? ifNow,
  String? prependIfBefore,
  String? appendIfAfter,
}) {
  assert(minUnitOfTime.index >= maxUnitOfTime.index);

  return DateTimeFormat.relative(
    this,
    relativeTo: to,
    formatAfter: formatAfter,
    format: format,
    round: round,
    abbr: abbr,
    abbreviations: abbreviations,
    levelOfPrecision: levelOfPrecision,
    minUnitOfTime: minUnitOfTime,
    maxUnitOfTime: maxUnitOfTime,
    excludeWeeks: excludeWeeks,
    ifNow: ifNow,
    prependIfBefore: prependIfBefore,
    appendIfAfter: appendIfAfter,
  );
}