Trait providing a now
method that returns the current time in milliseconds
since January 1, 1970, 00:00:00 GMT.
A time span.
A time span.
A Span
is used to express time spans in ScalaTest, in constructs such as the
failAfter
method of trait Timeouts
,
the timeLimit
field of trait
TimeLimitedTests
, and
the timeouts of traits Eventually
,
and AsyncAssertions
. Here's an example:
import org.scalatest.time.Span import org.scalatest.time.Millis import org.scalatest.concurrent.Timeouts._ failAfter(Span(100, Millis)) { // ... }
If you prefer you can mix in or import the members of SpanSugar
and place a units value after the timeout value.
Here are some examples:
import org.scalatest.time.SpanSugar._ import org.scalatest.concurrent.Timeouts._ failAfter(100 millis) { // ... } failAfter(1 second) { // ... }
In addition to expression the numeric value with an Int
or a Long
, you
can also express it via a Float
or Double
. Here are some examples:
import org.scalatest.time.Span import org.scalatest.time.Seconds import org.scalatest.concurrent.Timeouts._ failAfter(Span(1.5, Seconds)) { // ... } import org.scalatest.time.SpanSugar._ failAfter(0.8 seconds) { // ... }
Internally, a Span
is expressed in terms of a Long
number of nanoseconds. Thus, the maximum
time span that can be represented is Long.MaxValue
nanoseconds, or approximately 292 years.
Hopefully these won't be "famous last words," but 292 years should be sufficient for software testing purposes.
Any attempt to create a Span
longer than Long.MaxValue
nanoseconds will be met with
an IllegalArgumentException
:
Span(Long.MaxValue, Nanoseconds) // Produces the longest possible time.Span Span(Long.MaxValue, Seconds) // Produces an IllegalArgumentException
All of class Span
's constructors are private. The only way you can create a new Span
is
via one of the two apply
factory methods in Span
's
companion object. Here is a table showing one example of each numeric type and unit value:
Int
|
Long
|
Float
|
Double
|
---|---|---|---|
Span(1, Nanosecond) | Span(1L, Nanosecond) | Span(1.0F, Nanosecond) | Span(1.0, Nanosecond) |
Span(100, Nanoseconds) | Span(100L, Nanoseconds) | Span(99.8F, Nanoseconds) | Span(99.8, Nanoseconds) |
Span(1, Microsecond) | Span(1L, Microsecond) | Span(1.0F, Microsecond) | Span(1.0, Microsecond) |
Span(100, Microseconds) | Span(100L, Microseconds) | Span(99.8F, Microseconds) | Span(99.8, Microseconds) |
Span(1, Millisecond) | Span(1L, Millisecond) | Span(1.0F, Millisecond) | Span(1.0, Millisecond) |
Span(100, Milliseconds) | Span(100L, Milliseconds) | Span(99.8F, Milliseconds) | Span(99.8, Milliseconds) |
Span(100, Millis) | Span(100L, Millis) | Span(99.8F, Millis) | Span(99.8, Millis) |
Span(1, Second) | Span(1L, Second) | Span(1.0F, Second) | Span(1.0, Second) |
Span(100, Seconds) | Span(100L, Seconds) | Span(99.8F, Seconds) | Span(99.8, Seconds) |
Span(1, Minute) | Span(1L, Minute) | Span(1.0F, Minute) | Span(1.0, Minute) |
Span(100, Minutes) | Span(100L, Minutes) | Span(99.8F, Minutes) | Span(99.8, Minutes) |
Span(1, Hour) | Span(1L, Hour) | Span(1.0F, Hour) | Span(1.0, Hour) |
Span(100, Hours) | Span(100L, Hours) | Span(99.8F, Hours) | Span(99.8, Hours) |
Span(1, Day) | Span(1L, Day) | Span(1.0F, Day) | Span(1.0, Day) |
Span(100, Days) | Span(100L, Days) | Span(99.8F, Days) | Span(99.8, Days) |
Note that because of implicit conversions in the Span
companion object, you can use a
scala.concurrent.duration.Duration
where a Span
is needed, and vice versa.
Trait providing four implicit conversions that allow you to specify spans of time
by invoking "units" methods such as millis
, seconds
, and minutes
on Int
, Long
, Float
, and Double
.
Trait providing four implicit conversions that allow you to specify spans of time
by invoking "units" methods such as millis
, seconds
, and minutes
on Int
, Long
, Float
, and Double
.
This trait enables you to specify a span of time in a clear, boilerplate-free way when you
need to provide an instance of Span
. This
can be used, for example, with the failAfter
method of trait
Timeouts
or the timeLimit
field of trait
TimeLimitedTests
. It can also be used to specify
timeouts when using traits Eventually
,
Futures
,
Waiter
. Here are examples of each unit enabled by this trait:
Int
|
Long
|
Float
|
Double
|
---|---|---|---|
1 nanosecond | 1L nanosecond | 1.0F nanosecond | 1.0 nanosecond |
100 nanoseconds | 100L nanoseconds | 99.8F nanoseconds | 99.8 nanoseconds |
1 microsecond | 1L microsecond | 1.0F microsecond | 1.0 microsecond |
100 microseconds | 100L microseconds | 99.8F microseconds | 99.8 microseconds |
1 millisecond | 1L millisecond | 1.0F millisecond | 1.0 millisecond |
100 milliseconds | 100L milliseconds | 99.8F milliseconds | 99.8 milliseconds |
100 millis | 100L millis | 99.8F millis | 99.8 millis |
1 second | 1L second | 1.0F second | 1.0 second |
100 seconds | 100L seconds | 99.8F seconds | 99.8 seconds |
1 minute | 1L minute | 1.0F minute | 1.0 minute |
100 minutes | 100L minutes | 99.8F minutes | 99.8 minutes |
1 hour | 1L hour | 1.0F hour | 1.0 hour |
100 hours | 100L hours | 99.8F hours | 99.8 hours |
1 day | 1L day | 1.0F day | 1.0 day |
100 days | 100L days | 99.8F days | 99.8 days |
This trait is not the default way to specify Span
s for two reasons. First, it adds
four implicits, which would give the compiler more work to do and may conflict with other implicits the
user has in scope. Instead, Span
provides a clear, concise default way to specify time
spans that requires no implicits. Here's an example:
Span(1, Second)
If you already have implicit conversions in scope that provide a similar syntax sugar for expression
time spans, you can use that by providing an implicit conversion from the result of those expressions
to Span
. Note that because of implicit conversions in the Span
companion object,
you can use a scala.concurrent.duration.Duration
(including in its "sugary" form) where
a Span
is needed, and vice versa.
Defines a family of singleton objects representing units of time.
Defines a family of singleton objects representing units of time.
The singleton objects that extend this abstract class may be passed
to the constructor of Span
to specify
units of time. For example:
Span(1, Second)
Indicates units for a single day.
Indicates units for a single day.
This singleton object may be passed to the constructor of Span
to
specify day units of time, so long as the value passed to Span
is 1. For example:
Span(1, Day)
Indicates day units.
Indicates day units.
This singleton object may be passed to the constructor of Span
to
specify day units of time. For example:
Span(10, Days)
Indicates units for a single hour.
Indicates units for a single hour.
This singleton object may be passed to the constructor of Span
to
specify hour units of time, so long as the value passed to Span
is 1. For example:
Span(1, Hour)
Indicates hour units.
Indicates hour units.
This singleton object may be passed to the constructor of Span
to
specify hour units of time. For example:
Span(10, Hours)
Indicates units for a single microsecond.
Indicates units for a single microsecond.
This singleton object may be passed to the constructor of Span
to
specify microsecond units of time, so long as the value passed to Span
is 1. For example:
Span(1, Microsecond)
Indicates microsecond units.
Indicates microsecond units.
This singleton object may be passed to the constructor of Span
to
specify microsecond units of time. For example:
Span(10, Microseconds)
Indicates millisecond units (shorthand form).
Indicates millisecond units (shorthand form).
This singleton object may be passed to the constructor of Span
to
specify millisecond units of time. For example:
Span(10, Millis)
Note: Millis
is merely a shorthand for Milliseconds
.
When passed to Span
, Millis
means exactly the same thing as
Milliseconds
.
Indicates units for a single millisecond.
Indicates units for a single millisecond.
This singleton object may be passed to the constructor of Span
to
specify millisecond units of time, so long as the value passed to Span
is 1. For example:
Span(1, Millisecond)
Indicates millisecond units.
Indicates millisecond units.
This singleton object may be passed to the constructor of Span
to
specify millisecond units of time. For example:
Span(10, Milliseconds)
Indicates units for a single minute.
Indicates units for a single minute.
This singleton object may be passed to the constructor of Span
to
specify minute units of time, so long as the value passed to Span
is 1. For example:
Span(1, Minute)
Indicates minute units.
Indicates minute units.
This singleton object may be passed to the constructor of Span
to
specify minute units of time. For example:
Span(10, Minutes)
Indicates units for a single nanosecond.
Indicates units for a single nanosecond.
This singleton object may be passed to the constructor of Span
to
specify nanosecond units of time, so long as the value passed to Span
is 1. For example:
Span(1, Nanosecond)
Indicates nanosecond units.
Indicates nanosecond units.
This singleton object may be passed to the constructor of Span
to
specify nanosecond units of time. For example:
Span(10, Nanoseconds)
Companion object to trait Now
that enables its members to be imported as
an alternative to mixing them in.
Companion object to trait Now
that enables its members to be imported as
an alternative to mixing them in.
Indicates units for a single second.
Indicates units for a single second.
This singleton object may be passed to the constructor of Span
to
specify second units of time, so long as the value passed to Span
is 1. For example:
Span(1, Second)
Indicates second units.
Indicates second units.
This singleton object may be passed to the constructor of Span
to
specify second units of time. For example:
Span(10, Seconds)
Companion object for Span
that provides two factory methods for creating Span
instances.
Companion object for Span
that provides two factory methods for creating Span
instances.
The first argument to each factory method is a numeric value; the second argument is a Units
value.
One factory method takes a Long
, so it can be invoked with either an Int
or
Long, as in:
import org.scalatest.time._ Span(1, Second) Span(1L, Millisecond)
The other factory method takes a Double
, so it can be invoked with either a Float
or
a Double
:
import org.scalatest.time._ Span(2.5F, Seconds) Span(99.9, Microseconds)
Companion object that facilitates the importing of SpanSugar
members as
an alternative to mixing it in.
Companion object that facilitates the importing of SpanSugar
members as
an alternative to mixing it in. One use case is to import SpanSugar
members so you can use
them in the Scala interpreter:
$scala -classpath scalatest.jar Welcome to Scala version 2.9.1.final (Java HotSpot(TM) 64-Bit Server VM, Java 1.6.0_29). Type in expressions to have them evaluated. Type :help for more information. scala> import org.scalatest._ import org.scalatest._ scala> import concurrent.Eventually._ import org.scalatest.concurrent.Eventually._ scala> import time.SpanSugar._ import org.scalatest.time.SpanSugar._ scala> eventually(timeout(100 millis)) { 1 + 1 should equal (3) }
Trait providing a
now
method that returns the current time in milliseconds since January 1, 1970, 00:00:00 GMT.