Durations

DurationStyle reads and writes durations as text, in the short form 10s and in ISO-8601 PT10S.

Why use it

Timeouts, intervals and cache lifetimes are durations. Configuration should say 30s, not 30000, and code should get a Dart Duration, not a number to interpret. The default conversion service calls DurationStyle.parse whenever a string becomes a Duration: for @Value, getPropertyAs<Duration> and @ConfigurationProperties fields. You call DurationStyle yourself only to parse or print durations in your own code.

Accepted forms:

Short form: a whole number with an optional unit ns, us, ms, s, m, h or d, in any case: 500ms, 10s, -2h, 2d.
ISO-8601: PT10S, PT1H30M, P1DT2H, PT0.5S, negative as -PT5S. Years and months are not accepted.
A plain number: milliseconds. @DurationUnit (from spring_boot_dart) changes that unit for a @ConfigurationProperties field.

Example

# lib/resources/application.properties
shop.timeout=30s
shop.retry-after=PT1M30S
shop.poll=250

import 'package:spring_core_dart/spring_core_dart.dart';

@Service()
class Poller {
  Poller(
    @Value(r'${shop.timeout}') this.timeout, // 30 seconds
    @Value(r'${shop.retry-after}') this.retryAfter, // 1 minute 30 seconds
    @Value(r'${shop.poll}') this.poll, // 250 milliseconds
  );

  final Duration timeout;
  final Duration retryAfter;
  final Duration poll;
}

In code:

DurationStyle.parse('500ms'); // Duration(milliseconds: 500)
DurationStyle.parse('P1DT2H'); // Duration(days: 1, hours: 2)
DurationStyle.parse('30', unit: ChronoUnit.seconds); // 30 seconds
DurationStyle.format(const Duration(minutes: 90)); // '90m'
DurationStyle.formatIso(const Duration(minutes: 90)); // 'PT1H30M'
ChronoUnit.seconds.of(30); // Duration(seconds: 30)

Members

DurationStyle (static methods):

Name	Returns	Meaning
`parse(value, {unit = ChronoUnit.millis})`	`Duration`	Reads the short form or ISO-8601. A number without a unit is in `unit`. Throws `FormatException` otherwise.
`format(value)`	`String`	The short form with the largest unit that divides the value exactly; zero is `0ms`.
`formatIso(value)`	`String`	ISO-8601 as `java.time.Duration.toString` writes it: hours, minutes and seconds only (`PT24H` for one day). Zero is `PT0S`.

ChronoUnit values: nanos, micros, millis, seconds, minutes, hours, days. unit.of(amount) gives a Duration.

In Spring (Java)

// Spring Boot
Duration d = DurationStyle.detectAndParse("500ms");
Duration iso = DurationStyle.detectAndParse("P1DT2H");
String text = DurationStyle.SIMPLE.print(Duration.ofMinutes(90));
String isoText = DurationStyle.ISO8601.print(Duration.ofMinutes(90));

Differences that matter:

parse detects the form, like Spring Boot's detectAndParse; format and formatIso are SIMPLE.print and ISO8601.print.
A Dart Duration has microsecond precision, so ns values are truncated to microseconds.
ChronoUnit has only the units a Duration can hold, from nanoseconds to days; there are no months or years.
In Spring, duration parsing belongs to Spring Boot. Here it is part of the core.

Durations

Why use it

Example

Members

In Spring (Java)

See also