Duration

Related Docs: object Duration | package duration

Utility for working with java.util.concurrent.TimeUnit durations.

This class is not meant as a general purpose representation of time, it is optimized for the needs of `scala.concurrent`.

Basic Usage

Examples:

```import scala.concurrent.duration._

val duration = Duration(100, MILLISECONDS)
val duration = Duration(100, "millis")

duration.toNanos
duration < 1.second
duration <= Duration.Inf```

Invoking inexpressible conversions (like calling `toSeconds` on an infinite duration) will throw an IllegalArgumentException.

Implicits are also provided for Int, Long and Double. Example usage:

```import scala.concurrent.duration._

val duration = 100 millis```

The DSL provided by the implicit conversions always allows construction of finite durations, even for infinite Double inputs; use Duration.Inf instead.

Extractors, parsing and arithmetic are also included:

```val d = Duration("1.2 ￂﾵs")
val Duration(length, unit) = 5 millis
val d2 = d * 2.5
val d3 = d2 + 1.millisecond```

Handling of Time Units

Calculations performed on finite durations always retain the more precise unit of either operand, no matter whether a coarser unit would be able to exactly express the same duration. This means that Duration can be used as a lossless container for a (length, unit) pair if it is constructed using the corresponding methods and no arithmetic is performed on it; adding/subtracting durations should in that case be done with care.

Correspondence to Double Semantics

The semantics of arithmetic operations on Duration are two-fold:

• exact addition/subtraction with nanosecond resolution for finite durations, independent of the summands' magnitude
• isomorphic to `java.lang.Double` when it comes to infinite or undefined values

The conversion between Duration and Double is done using Duration.toUnit (with unit NANOSECONDS) and Duration.fromNanos(Double).

Ordering

The default ordering is consistent with the ordering of Double numbers, which means that Undefined is considered greater than all other durations, including Duration.Inf.

Source
Duration.scala
Linear Supertypes
math.Ordered[Duration], Comparable[Duration], Serializable, java.io.Serializable, AnyRef, Any
Known Subclasses
Ordering
1. Alphabetic
2. By inheritance
Inherited
1. Duration
2. Ordered
3. Comparable
4. Serializable
5. Serializable
6. AnyRef
7. Any
Implicitly
1. by orderingToOrdered
2. by durationToPair
4. by StringFormat
5. by Ensuring
6. by ArrowAssoc
1. Hide All
2. Show all
Visibility
1. Public
2. All

Abstract Value Members

1. abstract def *(factor: Double): Duration

Return this duration multiplied by the scalar factor.

Return this duration multiplied by the scalar factor. When involving non-finite factors the semantics match those of Double.

Exceptions thrown

`IllegalArgumentException` in case of a finite overflow: the range of a finite duration is +-(2^63-1)ns, and no conversion to infinite durations takes place.

2. abstract def +(other: Duration): Duration

Return the sum of that duration and this.

Return the sum of that duration and this. When involving non-finite summands the semantics match those of Double.

Exceptions thrown

`IllegalArgumentException` in case of a finite overflow: the range of a finite duration is +-(2^63-1)ns, and no conversion to infinite durations takes place.

3. abstract def -(other: Duration): Duration

Return the difference of that duration and this.

Return the difference of that duration and this. When involving non-finite summands the semantics match those of Double.

Exceptions thrown

`IllegalArgumentException` in case of a finite overflow: the range of a finite duration is +-(2^63-1)ns, and no conversion to infinite durations takes place.

4. abstract def /(divisor: Duration): Double

Return the quotient of this and that duration as floating-point number.

Return the quotient of this and that duration as floating-point number. The semantics are determined by Double as if calculating the quotient of the nanosecond lengths of both factors.

5. abstract def /(divisor: Double): Duration

Return this duration divided by the scalar factor.

Return this duration divided by the scalar factor. When involving non-finite factors the semantics match those of Double.

Exceptions thrown

`IllegalArgumentException` in case of a finite overflow: the range of a finite duration is +-(2^63-1)ns, and no conversion to infinite durations takes place.

6. abstract def compare(that: Duration): Int

Result of comparing `this` with operand `that`.

Result of comparing `this` with operand `that`.

Implement this method to determine how instances of A will be sorted.

Returns `x` where:

• `x < 0` when `this < that`
• `x == 0` when `this == that`
• `x > 0` when `this > that`
Definition Classes
Ordered
7. abstract def isFinite(): Boolean

This method returns whether this duration is finite, which is not the same as `!isInfinite` for Double because this method also returns `false` for Duration.Undefined.

8. abstract def length: Long

Obtain the length of this Duration measured in the unit obtained by the `unit` method.

Obtain the length of this Duration measured in the unit obtained by the `unit` method.

Exceptions thrown

`IllegalArgumentException` when invoked on a non-finite duration

9. abstract def toCoarsest: Duration

Return duration which is equal to this duration but with a coarsest Unit, or self in case it is already the coarsest Unit

Return duration which is equal to this duration but with a coarsest Unit, or self in case it is already the coarsest Unit

Examples:

```Duration(60, MINUTES).toCoarsest // Duration(1, HOURS)
Duration(1000, MILLISECONDS).toCoarsest // Duration(1, SECONDS)
Duration(48, HOURS).toCoarsest // Duration(2, DAYS)
Duration(5, SECONDS).toCoarsest // Duration(5, SECONDS)```
10. abstract def toDays: Long

Return the length of this duration measured in whole days, rounding towards zero.

Return the length of this duration measured in whole days, rounding towards zero.

Exceptions thrown

`IllegalArgumentException` when invoked on a non-finite duration

11. abstract def toHours: Long

Return the length of this duration measured in whole hours, rounding towards zero.

Return the length of this duration measured in whole hours, rounding towards zero.

Exceptions thrown

`IllegalArgumentException` when invoked on a non-finite duration

12. abstract def toMicros: Long

Return the length of this duration measured in whole microseconds, rounding towards zero.

Return the length of this duration measured in whole microseconds, rounding towards zero.

Exceptions thrown

`IllegalArgumentException` when invoked on a non-finite duration

13. abstract def toMillis: Long

Return the length of this duration measured in whole milliseconds, rounding towards zero.

Return the length of this duration measured in whole milliseconds, rounding towards zero.

Exceptions thrown

`IllegalArgumentException` when invoked on a non-finite duration

14. abstract def toMinutes: Long

Return the length of this duration measured in whole minutes, rounding towards zero.

Return the length of this duration measured in whole minutes, rounding towards zero.

Exceptions thrown

`IllegalArgumentException` when invoked on a non-finite duration

15. abstract def toNanos: Long

Return the length of this duration measured in whole nanoseconds, rounding towards zero.

Return the length of this duration measured in whole nanoseconds, rounding towards zero.

Exceptions thrown

`IllegalArgumentException` when invoked on a non-finite duration

16. abstract def toSeconds: Long

Return the length of this duration measured in whole seconds, rounding towards zero.

Return the length of this duration measured in whole seconds, rounding towards zero.

Exceptions thrown

`IllegalArgumentException` when invoked on a non-finite duration

17. abstract def toUnit(unit: TimeUnit): Double

Return the number of nanoseconds as floating point number, scaled down to the given unit.

Return the number of nanoseconds as floating point number, scaled down to the given unit. The result may not precisely represent this duration due to the Double datatype's inherent limitations (mantissa size effectively 53 bits). Non-finite durations are represented as

18. abstract def unary_-: Duration

Negate this duration.

Negate this duration. The only two values which are mapped to themselves are Duration.Zero and Duration.Undefined.

19. abstract def unit: TimeUnit

Obtain the time unit in which the length of this duration is measured.

Obtain the time unit in which the length of this duration is measured.

Exceptions thrown

`IllegalArgumentException` when invoked on a non-finite duration

Concrete Value Members

1. final def !=(arg0: Any): Boolean

Test two objects for inequality.

Test two objects for inequality.

returns

`true` if !(this == that), false otherwise.

Definition Classes
AnyRef → Any
2. final def ##(): Int

Equivalent to `x.hashCode` except for boxed numeric types and `null`.

Equivalent to `x.hashCode` except for boxed numeric types and `null`. For numerics, it returns a hash value which is consistent with value equality: if two value type instances compare as true, then ## will produce the same hash value for each of them. For `null` returns a hashcode where `null.hashCode` throws a `NullPointerException`.

returns

a hash value consistent with ==

Definition Classes
AnyRef → Any
3. def ->[B](y: B): (Duration, B)

Implicit information
This member is added by an implicit conversion from Duration to ArrowAssoc[Duration] performed by method ArrowAssoc in scala.Predef.
Definition Classes
ArrowAssoc
Annotations
()
4. def <(that: Duration): Boolean

Returns true if `this` is less than `that`

Returns true if `this` is less than `that`

Definition Classes
Ordered
5. def <=(that: Duration): Boolean

Returns true if `this` is less than or equal to `that`.

Returns true if `this` is less than or equal to `that`.

Definition Classes
Ordered
6. final def ==(arg0: Any): Boolean

The expression `x == that` is equivalent to `if (x eq null) that eq null else x.equals(that)`.

The expression `x == that` is equivalent to `if (x eq null) that eq null else x.equals(that)`.

arg0

the object to compare against this object for equality.

returns

`true` if the receiver object is equivalent to the argument; `false` otherwise.

Definition Classes
AnyRef → Any
7. def >(that: Duration): Boolean

Returns true if `this` is greater than `that`.

Returns true if `this` is greater than `that`.

Definition Classes
Ordered
8. def >=(that: Duration): Boolean

Returns true if `this` is greater than or equal to `that`.

Returns true if `this` is greater than or equal to `that`.

Definition Classes
Ordered
9. final def asInstanceOf[T0]: T0

Cast the receiver object to be of type `T0`.

Cast the receiver object to be of type `T0`.

Note that the success of a cast at runtime is modulo Scala's erasure semantics. Therefore the expression `1.asInstanceOf[String]` will throw a `ClassCastException` at runtime, while the expression `List(1).asInstanceOf[List[String]]` will not. In the latter example, because the type argument is erased as part of compilation it is not possible to check whether the contents of the list are of the requested type.

returns

Definition Classes
Any
Exceptions thrown

`ClassCastException` if the receiver object is not an instance of the erasure of type `T0`.

10. def clone(): AnyRef

Create a copy of the receiver object.

Create a copy of the receiver object.

The default implementation of the `clone` method is platform dependent.

returns

a copy of the receiver object.

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
( ... )
Note

not specified by SLS as a member of AnyRef

11. def compareTo(that: Duration): Int

Result of comparing `this` with operand `that`.

Result of comparing `this` with operand `that`.

Definition Classes
Ordered → Comparable
12. def div(other: Duration): Double

Return the quotient of this and that duration as floating-point number.

Return the quotient of this and that duration as floating-point number. The semantics are determined by Double as if calculating the quotient of the nanosecond lengths of both factors.

13. def div(divisor: Double): Duration

Return this duration divided by the scalar factor.

Return this duration divided by the scalar factor. When involving non-finite factors the semantics match those of Double.

Exceptions thrown

`IllegalArgumentException` in case of a finite overflow: the range of a finite duration is +-(2^63-1)ns, and no conversion to infinite durations takes place.

14. def ensuring(cond: (Duration) ⇒ Boolean, msg: ⇒ Any): Duration

Implicit information
This member is added by an implicit conversion from Duration to Ensuring[Duration] performed by method Ensuring in scala.Predef.
Definition Classes
Ensuring
15. def ensuring(cond: (Duration) ⇒ Boolean): Duration

Implicit information
This member is added by an implicit conversion from Duration to Ensuring[Duration] performed by method Ensuring in scala.Predef.
Definition Classes
Ensuring
16. def ensuring(cond: Boolean, msg: ⇒ Any): Duration

Implicit information
This member is added by an implicit conversion from Duration to Ensuring[Duration] performed by method Ensuring in scala.Predef.
Definition Classes
Ensuring
17. def ensuring(cond: Boolean): Duration

Implicit information
This member is added by an implicit conversion from Duration to Ensuring[Duration] performed by method Ensuring in scala.Predef.
Definition Classes
Ensuring
18. final def eq(arg0: AnyRef): Boolean

Tests whether the argument (`arg0`) is a reference to the receiver object (`this`).

Tests whether the argument (`arg0`) is a reference to the receiver object (`this`).

The `eq` method implements an equivalence relation on non-null instances of `AnyRef`, and has three additional properties:

• It is consistent: for any non-null instances `x` and `y` of type `AnyRef`, multiple invocations of `x.eq(y)` consistently returns `true` or consistently returns `false`.
• For any non-null instance `x` of type `AnyRef`, `x.eq(null)` and `null.eq(x)` returns `false`.
• `null.eq(null)` returns `true`.

When overriding the `equals` or `hashCode` methods, it is important to ensure that their behavior is consistent with reference equality. Therefore, if two objects are references to each other (`o1 eq o2`), they should be equal to each other (`o1 == o2`) and they should hash to the same value (`o1.hashCode == o2.hashCode`).

returns

`true` if the argument is a reference to the receiver object; `false` otherwise.

Definition Classes
AnyRef
19. def equals(arg0: Any): Boolean

The equality method for reference types.

The equality method for reference types. Default implementation delegates to `eq`.

See also `equals` in scala.Any.

returns

`true` if the receiver object is equivalent to the argument; `false` otherwise.

Definition Classes
AnyRef → Any
20. def finalize(): Unit

Called by the garbage collector on the receiver object when there are no more references to the object.

Called by the garbage collector on the receiver object when there are no more references to the object.

The details of when and if the `finalize` method is invoked, as well as the interaction between `finalize` and non-local returns and exceptions, are all platform dependent.

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
( classOf[java.lang.Throwable] )
Note

not specified by SLS as a member of AnyRef

21. def formatted(fmtstr: String): String

Returns string formatted according to given `format` string.

Returns string formatted according to given `format` string. Format strings are as for `String.format` (@see java.lang.String.format).

Implicit information
This member is added by an implicit conversion from Duration to StringFormat[Duration] performed by method StringFormat in scala.Predef.
Definition Classes
StringFormat
Annotations
()
22. final def getClass(): Class[_]

A representation that corresponds to the dynamic class of the receiver object.

A representation that corresponds to the dynamic class of the receiver object.

The nature of the representation is platform dependent.

returns

a representation that corresponds to the dynamic class of the receiver object.

Definition Classes
AnyRef → Any
Note

not specified by SLS as a member of AnyRef

25. def hashCode(): Int

The hashCode method for reference types.

The hashCode method for reference types. See hashCode in scala.Any.

returns

the hash code value for this object.

Definition Classes
AnyRef → Any
26. final def isInstanceOf[T0]: Boolean

Test whether the dynamic type of the receiver object is `T0`.

Test whether the dynamic type of the receiver object is `T0`.

Note that the result of the test is modulo Scala's erasure semantics. Therefore the expression `1.isInstanceOf[String]` will return `false`, while the expression `List(1).isInstanceOf[List[String]]` will return `true`. In the latter example, because the type argument is erased as part of compilation it is not possible to check whether the contents of the list are of the specified type.

returns

`true` if the receiver object is an instance of erasure of type `T0`; `false` otherwise.

Definition Classes
Any

29. def max(other: Duration): Duration

Return the larger of this and that duration as determined by the natural ordering.

30. def min(other: Duration): Duration

Return the smaller of this and that duration as determined by the natural ordering.

31. def minus(other: Duration): Duration

Return the difference of that duration and this.

Return the difference of that duration and this. When involving non-finite summands the semantics match those of Double.

Exceptions thrown

`IllegalArgumentException` in case of a finite overflow: the range of a finite duration is +-(2^63-1)ns, and no conversion to infinite durations takes place.

32. def mul(factor: Double): Duration

Return this duration multiplied by the scalar factor.

Return this duration multiplied by the scalar factor. When involving non-finite factors the semantics match those of Double.

Exceptions thrown

`IllegalArgumentException` in case of a finite overflow: the range of a finite duration is +-(2^63-1)ns, and no conversion to infinite durations takes place.

33. final def ne(arg0: AnyRef): Boolean

Equivalent to `!(this eq that)`.

Equivalent to `!(this eq that)`.

returns

`true` if the argument is not a reference to the receiver object; `false` otherwise.

Definition Classes
AnyRef
34. def neg(): Duration

Negate this duration.

Negate this duration. The only two values which are mapped to themselves are Duration.Zero and Duration.Undefined.

35. final def notify(): Unit

Wakes up a single thread that is waiting on the receiver object's monitor.

Wakes up a single thread that is waiting on the receiver object's monitor.

Definition Classes
AnyRef
Note

not specified by SLS as a member of AnyRef

36. final def notifyAll(): Unit

Wakes up all threads that are waiting on the receiver object's monitor.

Wakes up all threads that are waiting on the receiver object's monitor.

Definition Classes
AnyRef
Note

not specified by SLS as a member of AnyRef

37. def plus(other: Duration): Duration

Return the sum of that duration and this.

Return the sum of that duration and this. When involving non-finite summands the semantics match those of Double.

Exceptions thrown

`IllegalArgumentException` in case of a finite overflow: the range of a finite duration is +-(2^63-1)ns, and no conversion to infinite durations takes place.

38. def productArity: Int

The arity of this product.

The arity of this product.

returns

2

Implicit information
This member is added by an implicit conversion from Duration to (Long, TimeUnit) performed by method durationToPair in scala.concurrent.duration.
Definition Classes
Product2Product
39. def productElement(n: Int): Any

Returns the n-th projection of this product if 0 < n <= productArity, otherwise throws an `IndexOutOfBoundsException`.

Returns the n-th projection of this product if 0 < n <= productArity, otherwise throws an `IndexOutOfBoundsException`.

n

number of the projection to be returned

returns

same as `._(n+1)`, for example `productElement(0)` is the same as `._1`.

Implicit information
This member is added by an implicit conversion from Duration to (Long, TimeUnit) performed by method durationToPair in scala.concurrent.duration.
Definition Classes
Product2Product
Annotations
( clazz = classOf[IndexOutOfBoundsException] )
Exceptions thrown
40. def swap: (TimeUnit, Long)

Swaps the elements of this `Tuple`.

Swaps the elements of this `Tuple`.

returns

a new Tuple where the first element is the second element of this Tuple and the second element is the first element of this Tuple.

Implicit information
This member is added by an implicit conversion from Duration to (Long, TimeUnit) performed by method durationToPair in scala.concurrent.duration.
Definition Classes
Tuple2
41. final def synchronized[T0](arg0: ⇒ T0): T0

Definition Classes
AnyRef
42. def toString(): String

Creates a String representation of this object.

Creates a String representation of this object. The default representation is platform dependent. On the java platform it is the concatenation of the class name, "@", and the object's hashcode in hexadecimal.

returns

a String representation of the object.

Definition Classes
AnyRef → Any
43. final def wait(): Unit

Definition Classes
AnyRef
Annotations
( ... )
44. final def wait(arg0: Long, arg1: Int): Unit

Definition Classes
AnyRef
Annotations
( ... )
45. final def wait(arg0: Long): Unit

Definition Classes
AnyRef
Annotations
( ... )
46. def →[B](y: B): (Duration, B)

Implicit information
This member is added by an implicit conversion from Duration to ArrowAssoc[Duration] performed by method ArrowAssoc in scala.Predef.
Definition Classes
ArrowAssoc

1. def +(other: String): String

Implicit information
This member is added by an implicit conversion from Duration to any2stringadd[Duration] performed by method any2stringadd in scala.Predef.
This implicitly inherited member is shadowed by one or more members in this class.
To access this member you can use a type ascription:
`(duration: any2stringadd[Duration]).+(other)`
Definition Classes
2. def <(that: Duration): Boolean

Returns true if `this` is less than `that`

Returns true if `this` is less than `that`

Implicit information
This member is added by an implicit conversion from Duration to math.Ordered[Duration] performed by method orderingToOrdered in scala.math.Ordered.
This implicitly inherited member is shadowed by one or more members in this class.
To access this member you can use a type ascription:
`(duration: math.Ordered[Duration]).<(that)`
Definition Classes
Ordered
3. def <=(that: Duration): Boolean

Returns true if `this` is less than or equal to `that`.

Returns true if `this` is less than or equal to `that`.

Implicit information
This member is added by an implicit conversion from Duration to math.Ordered[Duration] performed by method orderingToOrdered in scala.math.Ordered.
This implicitly inherited member is shadowed by one or more members in this class.
To access this member you can use a type ascription:
`(duration: math.Ordered[Duration]).<=(that)`
Definition Classes
Ordered
4. def >(that: Duration): Boolean

Returns true if `this` is greater than `that`.

Returns true if `this` is greater than `that`.

Implicit information
This member is added by an implicit conversion from Duration to math.Ordered[Duration] performed by method orderingToOrdered in scala.math.Ordered.
This implicitly inherited member is shadowed by one or more members in this class.
To access this member you can use a type ascription:
`(duration: math.Ordered[Duration]).>(that)`
Definition Classes
Ordered
5. def >=(that: Duration): Boolean

Returns true if `this` is greater than or equal to `that`.

Returns true if `this` is greater than or equal to `that`.

Implicit information
This member is added by an implicit conversion from Duration to math.Ordered[Duration] performed by method orderingToOrdered in scala.math.Ordered.
This implicitly inherited member is shadowed by one or more members in this class.
To access this member you can use a type ascription:
`(duration: math.Ordered[Duration]).>=(that)`
Definition Classes
Ordered
6. def compare(that: Duration): Int

Result of comparing `this` with operand `that`.

Result of comparing `this` with operand `that`.

Implement this method to determine how instances of A will be sorted.

Returns `x` where:

• `x < 0` when `this < that`
• `x == 0` when `this == that`
• `x > 0` when `this > that`
Implicit information
This member is added by an implicit conversion from Duration to math.Ordered[Duration] performed by method orderingToOrdered in scala.math.Ordered.
This implicitly inherited member is shadowed by one or more members in this class.
To access this member you can use a type ascription:
`(duration: math.Ordered[Duration]).compare(that)`
Definition Classes
Ordered
7. def compareTo(that: Duration): Int

Result of comparing `this` with operand `that`.

Result of comparing `this` with operand `that`.

Implicit information
This member is added by an implicit conversion from Duration to math.Ordered[Duration] performed by method orderingToOrdered in scala.math.Ordered.
This implicitly inherited member is shadowed by one or more members in this class.
To access this member you can use a type ascription:
`(duration: math.Ordered[Duration]).compareTo(that)`
Definition Classes
Ordered → Comparable
8. def toString(): String

Creates a String representation of this object.

Creates a String representation of this object. The default representation is platform dependent. On the java platform it is the concatenation of the class name, "@", and the object's hashcode in hexadecimal.

returns

a String representation of the object.

Implicit information
This member is added by an implicit conversion from Duration to (Long, TimeUnit) performed by method durationToPair in scala.concurrent.duration.
This implicitly inherited member is shadowed by one or more members in this class.
To access this member you can use a type ascription:
`(duration: (Long, TimeUnit)).toString()`
Definition Classes
Tuple2 → AnyRef → Any