ApproximateTimeTransformation class

A transformation to convert a Duration representing an offset of time into an approximate, human-friendly description.

This transformation produces a humanized description of an input Duration, which is used to calculate a value for each supported TimeUnit. The highest unit to have a non-zero value is considered the "primary" unit, and the next smaller unit is the "secondary" regardless of whether it has a non-zero value. In the case of the primary unit being the smallest supported unit (seconds), there is no secondary unit.

If isRelativeToNow is true, the input Duration is assumed to be relative to now, which allows for additional context to be included in the output. A negative input is considered to be in the past, whilst a positive input is in the future. For example, an output of 'tomorrow' only makes sense when the input is relative to now. If isRelativeToNow is false, a simpler output will be produced making no assumptions about the relativity of the input. In addition, the sign of the input is ignored.

The granularity argument determines whether only the primary unit affects the output, or whether the secondary unit is used to provide a lengthier, but more refined description. For example, a Duration of 1 hour and 5 minutes will be described at 'an hour from now' for a primary-only granularity, or 'just over an hour from now' for a primary and secondary granularity (assuming isRelativeToNow is true in both examples).

Prior to transformation, the calculated tally of units can optionally be rounded by setting round is true. Rounding involves examining the highest unit value not included in the output (i.e. the secondary unit value if granularity is Granularity.primaryUnit, or the tertiary unit value if granularity is Granularity.primaryAndSecondaryUnits) to see whether it equals or exceeds the midpoint of that unit. If so, the next highest unit value is incremented (and all lower unit values are truncated to zero).

The table below gives some examples of how given inputs are transformed when using the specified configuration:

| Duration | Granularity | Round | Is Relative to Now | Output | |-|-|-|-| | 0 seconds | N/A | N/A | true | now | | 0 seconds | N/A | N/A | false | zero | | 1 second | N/A | N/A | true | a second from now | | 1 second | N/A | N/A | false | 1 second | | -1 second | N/A | N/A | true | a second ago | | -1 second | N/A | N/A | false | 1 second | | 3 seconds | N/A | N/A | true | 3 seconds from now | | 3 seconds | N/A | N/A | false | 3 seconds | | 1 minute, 30 seconds | primaryUnit | false | true | a minute from now | | 1 minute, 30 seconds | primaryUnit | true | true | 2 minutes from now | | 1 minute, 5 seconds | primaryAndSecondaryUnits | N/A | true | just over a minute from now | | 1 minute, 55 seconds | primaryAndSecondaryUnits | N/A | true | just under 2 minutes from now | | 1 hour, 29 minutes, 30 seconds | primaryUnit | true | true | an hour from now | | 1 hour, 30 minutes, 30 seconds | primaryUnit | true | true | 2 hours from now | | 1 hour, 29 minutes, 29 seconds | primaryAndSecondaryUnits | true | true | over an hour from now | | 1 hour, 29 minutes, 30 seconds | primaryAndSecondaryUnits | true | true / under 2 hours from now |

final transformation = ApproximateTimeTransformation(
  granularity: Granularity.primaryAndSecondaryUnits,
  round: true,
  isRelativeToNow: true,
);

// 'over an hour from now'
transformation.transform(Duration(hours: 1, minutes: 29, seconds: 29), 'en_US');

// 'under 2 hours from now'
transformation.transform(Duration(hours: 1, minutes: 29, seconds: 30), 'en_US');

// 'an hour ago'
transformation.transform(Duration(hours: -1), 'en_US');
Inheritance
Available Extensions
Annotations
  • @immutable

Constructors

ApproximateTimeTransformation({required Granularity granularity, required bool round, required bool isRelativeToNow})
const

Properties

granularity → Granularity
The Granularity to which the input DateTime will be humanized.
final
hashCode → int
The hash code for this object.
no setterinherited
isRelativeToNow → bool
If true, the input Duration will be interpreted as relative to now. Doing so allows the output to be tailored under that assumption, such as producing 'now' or 'tomorrow'.
final
round → bool
Whether to round the input Duration prior to humanizing it.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited
transform(Duration input, String locale) → String
Transforms input into an instance of U using the provided locale.
override

Operators

operator ==(Object other) → bool
The equality operator.
inherited