Duration

The Duration class is designed to represent a time-based duration, typically measured in seconds and nanoseconds. It offers a range of static methods for creating durations based on days, hours, minutes, seconds, milliseconds, and nanoseconds. Additionally, it provides conversion methods to express the duration in various units, as well as the ability to calculate the duration between two temporal objects. This class is ideal for measuring time spans, tracking elapsed time, and performing time-based calculations in applications.

Static Methods

ofDays(days: Long)

• Obtains a Duration representing a number of standard 24-hour days.

• Example Usage:

  var daysDuration = Duration.ofDays(5);

ofHours(hours: Long)

• Obtains a Duration representing a number of standard hours.

• Example Usage:

  var hoursDuration = Duration.ofHours(12);

ofMinutes(minutes: Long)

• Obtains a Duration representing a number of standard minutes.

• Example Usage:

  var minutesDuration = Duration.ofMinutes(30);

ofSeconds(seconds: Long)

• Obtains a Duration representing a number of seconds.

• Example Usage:

  var secondsDuration = Duration.ofSeconds(120);

ofMillis(millis: Long)

• Obtains a Duration representing a number of milliseconds.

• Example Usage:

  var millisDuration = Duration.ofMillis(5000);

ofNanos(nanos: Long)

• Obtains a Duration representing a number of nanoseconds.

• Example Usage:

  var nanosDuration = Duration.ofNanos(123456789);

parse(text: String)

• Obtains a Duration from a text string such as PnDTnHnMn.nS.

• Parses a textual representation of a duration, including the string produced by toString().

• Example Usage:

  var parsedDuration = Duration.parse("PT20.345S");

Conversion Methods

toString()

• A string representation of this duration using ISO-8601 seconds based representation, such as PT8H6M12.345S.

• Example Usage:

  var stringRepresentation = parsedDuration.toString();

toDays()

• Gets the number of days in this duration.

• Example Usage:

  var days = daysDuration.toDays();

toHours()

• Gets the number of hours in this duration.

• Example Usage:

  var hours = hoursDuration.toHours();

toMinutes()

• Gets the number of minutes in this duration.

• Example Usage:

  var minutes = minutesDuration.toMinutes();

toSeconds()

• Gets the number of seconds in this duration.

• Example Usage:

  var seconds = secondsDuration.toSeconds();

toMillis()

• Converts this duration to the total length in milliseconds.

• Example Usage:

  var millis = millisDuration.toMillis();

toNanos()

• Converts this duration to the total length in nanoseconds expressed as a long.

• Example Usage:

  var nanos = nanosDuration.toNanos();

between(startInclusive: any, endExclusive: any)

• Obtains a Duration representing the duration between two temporal objects.

• Example Usage:

  var start = LocalDateTime.now(); // current date-time
  var end = start.plusHours(2); // current date-time plus 2 hours
  var duration = Duration.between(start, end); // duration is 2 hours

Examples

Example: Days Ago

Description: This script calculates the number of days between a specified ‘order_date’ and the current date.

Use Case: Useful for tracking the time elapsed since an order was placed.

var days = Duration.between(order_date.atStartOfDay(), 
                                LocalDate.now().atStartOfDay());

//Return the days as a number, we can also return toMinutes(), toYears(), ... as well
return days.toDays();

This example demonstrates how the Duration class can be used for tracking the age of data or calculating time-based metrics in various applications.