W3cubDocs

/Scala 2.13 Library

Class scala.concurrent.duration.Duration

Companion object Duration

sealed abstract class Duration extends Serializable with Ordered[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], java.io.Serializable, AnyRef, Any
Known Subclasses
Infinite, FiniteDuration

Abstract Value Members

abstract def *(factor: Double): Duration

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.

abstract def +(other: Duration): Duration

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.

abstract def -(other: Duration): Duration

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.

abstract def /(divisor: Duration): Double

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.

abstract def /(divisor: Double): Duration

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.

abstract def compare(that: Duration): Int

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

abstract def isFinite: Boolean

abstract def length: Long

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

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

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)

abstract def toDays: Long

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

Exceptions thrown

IllegalArgumentException when invoked on a non-finite duration

abstract def toHours: Long

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

Exceptions thrown

IllegalArgumentException when invoked on a non-finite duration

abstract def toMicros: Long

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

Exceptions thrown

IllegalArgumentException when invoked on a non-finite duration

abstract def toMillis: Long

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

Exceptions thrown

IllegalArgumentException when invoked on a non-finite duration

abstract def toMinutes: Long

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

Exceptions thrown

IllegalArgumentException when invoked on a non-finite duration

abstract def toNanos: Long

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

Exceptions thrown

IllegalArgumentException when invoked on a non-finite duration

abstract def toSeconds: Long

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

Exceptions thrown

IllegalArgumentException when invoked on a non-finite duration

abstract def toUnit(unit: TimeUnit): Double

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

abstract def unary_-: Duration

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

abstract def unit: TimeUnit

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

final def !=(arg0: Any): Boolean

Test two objects for inequality.

returns

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

Definition Classes
AnyRef → Any

final def ##(): Int

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

def ->[B](y: B): (Duration, B)

Implicit
This member is added by an implicit conversion from Duration toArrowAssoc[Duration] performed by method ArrowAssoc in scala.Predef.
Definition Classes
ArrowAssoc
Annotations
@inline()

def <(that: Duration): Boolean

Returns true if this is less than that

Definition Classes
Ordered

def <=(that: Duration): Boolean

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

Definition Classes
Ordered

final def ==(arg0: Any): Boolean

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

returns

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

Definition Classes
AnyRef → Any

def >(that: Duration): Boolean

Returns true if this is greater than that.

Definition Classes
Ordered

def >=(that: Duration): Boolean

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

Definition Classes
Ordered

final def asInstanceOf[T0]: 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

the receiver object.

Definition Classes
Any
Exceptions thrown

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

def clone(): AnyRef

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
@throws(classOf[java.lang.CloneNotSupportedException]) @native()
Note

not specified by SLS as a member of AnyRef

def compareTo(that: Duration): Int

Result of comparing this with operand that.

Definition Classes
Ordered → Comparable

def div(other: Duration): Double

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.

def div(divisor: Double): Duration

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.

def ensuring(cond: (Duration) => Boolean, msg: => Any): Duration

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

def ensuring(cond: (Duration) => Boolean): Duration

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

def ensuring(cond: Boolean, msg: => Any): Duration

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

def ensuring(cond: Boolean): Duration

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

final def eq(arg0: AnyRef): Boolean

Tests whether the argument (that) 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

def equals(arg0: AnyRef): Boolean

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

def finalize(): Unit

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
@throws(classOf[java.lang.Throwable])
Note

not specified by SLS as a member of AnyRef

def formatted(fmtstr: String): String

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

Implicit
This member is added by an implicit conversion from Duration toStringFormat[Duration] performed by method StringFormat in scala.Predef.
Definition Classes
StringFormat
Annotations
@inline()

final def getClass(): Class[_ <: AnyRef]

Returns the runtime class representation of the object.

returns

a class object corresponding to the runtime type of the receiver.

Definition Classes
AnyRef → Any
Annotations
@native()

def gt(other: Duration): Boolean

def gteq(other: Duration): Boolean

def hashCode(): Int

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

returns

the hash code value for this object.

Definition Classes
AnyRef → Any
Annotations
@native()

final def isInstanceOf[T0]: Boolean

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

def lt(other: Duration): Boolean

def lteq(other: Duration): Boolean

def max(other: Duration): Duration

def min(other: Duration): Duration

def minus(other: Duration): Duration

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.

def mul(factor: Double): Duration

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.

final def ne(arg0: AnyRef): Boolean

Equivalent to !(this eq that).

returns

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

Definition Classes
AnyRef

def neg(): Duration

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

final def notify(): Unit

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

Definition Classes
AnyRef
Annotations
@native()
Note

not specified by SLS as a member of AnyRef

final def notifyAll(): Unit

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

Definition Classes
AnyRef
Annotations
@native()
Note

not specified by SLS as a member of AnyRef

def plus(other: Duration): Duration

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.

def productArity: Int

The arity of this product.

returns

2

Implicit
This member is added by an implicit conversion from Duration to(Long, TimeUnit) performed by method durationToPair in scala.concurrent.duration.
Definition Classes
Product2Product

def productElement(n: Int): Any

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
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
@throws(classOf[IndexOutOfBoundsException])
Exceptions thrown

IndexOutOfBoundsException if the n is out of range(n < 0 || n >= 2).

def productElementNames: Iterator[String]

An iterator over the names of all the elements of this product.

Implicit
This member is added by an implicit conversion from Duration to(Long, TimeUnit) performed by method durationToPair in scala.concurrent.duration.
Definition Classes
Product

def swap: (TimeUnit, Long)

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
This member is added by an implicit conversion from Duration to(Long, TimeUnit) performed by method durationToPair in scala.concurrent.duration.
Definition Classes
Tuple2

final def synchronized[T0](arg0: => T0): T0

Definition Classes
AnyRef

def toString(): String

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

final def wait(): Unit

Definition Classes
AnyRef
Annotations
@throws(classOf[java.lang.InterruptedException])

final def wait(arg0: Long, arg1: Int): Unit

Definition Classes
AnyRef
Annotations
@throws(classOf[java.lang.InterruptedException])

final def wait(arg0: Long): Unit

Definition Classes
AnyRef
Annotations
@throws(classOf[java.lang.InterruptedException]) @native()

Shadowed Implicit Value Members

def +(other: String): String

Implicit
This member is added by an implicit conversion from Duration toany2stringadd[Duration] performed by method any2stringadd in scala.Predef.
Shadowing
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
any2stringadd

def <(that: Duration): Boolean

Returns true if this is less than that

Implicit
This member is added by an implicit conversion from Duration tomath.Ordered[Duration] performed by method orderingToOrdered in scala.math.Ordered.
Shadowing
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

def <=(that: Duration): Boolean

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

Implicit
This member is added by an implicit conversion from Duration tomath.Ordered[Duration] performed by method orderingToOrdered in scala.math.Ordered.
Shadowing
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

def >(that: Duration): Boolean

Returns true if this is greater than that.

Implicit
This member is added by an implicit conversion from Duration tomath.Ordered[Duration] performed by method orderingToOrdered in scala.math.Ordered.
Shadowing
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

def >=(that: Duration): Boolean

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

Implicit
This member is added by an implicit conversion from Duration tomath.Ordered[Duration] performed by method orderingToOrdered in scala.math.Ordered.
Shadowing
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

def compare(that: Duration): Int

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
This member is added by an implicit conversion from Duration tomath.Ordered[Duration] performed by method orderingToOrdered in scala.math.Ordered.
Shadowing
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

def compareTo(that: Duration): Int

Result of comparing this with operand that.

Implicit
This member is added by an implicit conversion from Duration tomath.Ordered[Duration] performed by method orderingToOrdered in scala.math.Ordered.
Shadowing
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

def toString(): String

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
This member is added by an implicit conversion from Duration to(Long, TimeUnit) performed by method durationToPair in scala.concurrent.duration.
Shadowing
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

© 2002-2019 EPFL, with contributions from Lightbend.
Licensed under the Apache License, Version 2.0.
https://www.scala-lang.org/api/2.13.0/scala/concurrent/duration/Duration.html