Class Speed

java.lang.Object

net.okapia.osid.primordium.mapping.spi.AbstractSpeed

net.okapia.osid.primordium.mapping.Speed

All Implemented Interfaces:

Serializable, Comparable<Speed>, OsidPrimitive, Speed, Speed, OsidPrimitive

public final class Speed
extends AbstractSpeed
implements Speed

An implementation of Primitive for OSID Speeds. A speed is a distance per a single time unit. Build one directly -- valueOf(long) for meters per second, or valueOf(org.osid.mapping.Distance, org.osid.calendaring.DateTimeResolution) for a distance per a chosen unit -- or let valueOf(org.osid.mapping.Distance, org.osid.calendaring.Duration, org.osid.calendaring.DateTimeResolution) reduce an arbitrary distance over an arbitrary duration ("98 km in 1h 43m") to that per-one-unit form.

See Also:

• Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class AbstractSpeed

AbstractSpeed.ParsedSpeed

Modifier and Type	Class	Description
protected static final class	AbstractSpeed.ParsedSpeed	The distance and time unit parsed from a speed string.

Constructor Summary

Constructors

Constructor	Description
Speed(Distance distance, DateTimeResolution time)	Constructs a new Speed of a distance per one time unit.

Method Summary

Modifier and Type	Method	Description
static Speed	light()	Gets the speed of light in a vacuum: 299,792,458 meters per second.
protected Speed	makeSpeed(Distance distance, DateTimeResolution time)	Builds a speed of this type for a bound.
static Speed	unknown()	Gets an unknown speed: an unknown distance over a second.
static Speed	valueOf(long metersPerSecond)	Creates a new Speed of meters per second.
static Speed	valueOf(String text)	Creates a new Speed from the string form produced by toString(), e.g.
static Speed	valueOf(BigDecimal metersPerSecond)	Creates a new Speed of meters per second.
static Speed	valueOf(Distance distance, DateTimeResolution per)	Creates a new Speed of a distance per one of the given time unit.
static Speed	valueOf(Distance distance, Duration duration)	Creates a new Speed from an arbitrary distance over an arbitrary duration, reduced to meters per second.
static Speed	valueOf(Distance distance, Duration duration, DateTimeResolution per)	Creates a new Speed from an arbitrary distance over an arbitrary duration, reduced to the distance covered in one of the given time unit.

Methods inherited from class AbstractSpeed

compareTo, equals, getDistance, getLowerBound, getTimeUnit, getUpperBound, hashCode, isContained, isExclusive, isExclusive, isGreater, isInclusive, isLess, parseSpeed, secondsOf, toString

Modifier and Type	Method	Description
int	compareTo(Speed speed)	Compares this speed with the specified Speed to determine the natural order.
final boolean	equals(Object obj)	Determines if the given Speed is equal to this one.
final Distance	getDistance()	Gets the distance.
Speed	getLowerBound()	Gets the lower bound of the speed: the distance's lower bound over the same time unit.
final DateTimeResolution	getTimeUnit()	Gets the time unit.
Speed	getUpperBound()	Gets the upper bound of the speed: the distance's upper bound over the same time unit.
final int	hashCode()	Returns a hash code value for this Speed based on its distance and time unit.
boolean	isContained(Speed speed1, Speed speed2)	Tests if the range of this Speed, as specified by its uncertainty, is included within the given two Speeds.
boolean	isExclusive(Speed speed)	Tests if the range of this Speed, as specified by its uncertainty, does not overlap the given Speed.
boolean	isExclusive(Speed speed1, Speed speed2)	Tests if the range of this Speed, as specified by its uncertainty, does not overlap with the range of the given two speeds.
boolean	isGreater(Speed speed)	Tests if this Speed is greater than the given Speed.
boolean	isInclusive(Speed speed)	Tests if the range of this Speed, as specified by its uncertainty, includes the given Speed ranged by its uncertainty.
boolean	isLess(Speed speed)	Tests if this Speed is less than the given Speed.
protected static AbstractSpeed.ParsedSpeed	parseSpeed(String text)	Parses the toString() form of a speed into its distance and time unit.
protected static BigDecimal	secondsOf(DateTimeResolution unit)	The number of seconds in one of the given time unit, taken from the calendaring Duration so the conventions (a Julian year, and so on) match the rest of the toolkit.
String	toString()	Returns a string representation of this Speed: the distance followed by the time unit, e.g.

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Details

Speed

public Speed(Distance distance,
 DateTimeResolution time)

Constructs a new Speed of a distance per one time unit.

Parameters:

distance - the distance traveled in one unit of time

time - the time unit

Throws:

NullArgumentException - distance or time is null

Method Details

makeSpeed

protected Speed makeSpeed(Distance distance,
 DateTimeResolution time)

Builds a speed of this type for a bound.

Specified by:

makeSpeed in class AbstractSpeed

Parameters:

distance - the distance

time - the time unit

Returns:

a new speed

valueOf

public static Speed valueOf(long metersPerSecond)

Creates a new Speed of meters per second.

Parameters:

metersPerSecond - the value in meters per second

Returns:

a new speed

valueOf

public static Speed valueOf(BigDecimal metersPerSecond)

Creates a new Speed of meters per second.

Parameters:

metersPerSecond - the value in meters per second

Returns:

a new speed

Throws:

NullArgumentException - metersPerSecond is null

valueOf

public static Speed valueOf(Distance distance,
 DateTimeResolution per)

Creates a new Speed of a distance per one of the given time unit.

Parameters:

distance - the distance traveled in one time unit

per - the time unit

Returns:

a new speed

Throws:

NullArgumentException - distance or per is null

valueOf

public static Speed valueOf(Distance distance,
 Duration duration,
 DateTimeResolution per)

Creates a new Speed from an arbitrary distance over an arbitrary duration, reduced to the distance covered in one of the given time unit. For example, 98 km over a duration of 1 hour 43 minutes, per hour, becomes a speed of about 57 km per hour -- the denominator is always one unit.

Parameters:

distance - the distance traveled

duration - the time taken

per - the time unit to express the speed in

Returns:

a new speed

Throws:

InvalidArgumentException - duration is zero, or per is INFINITY

NullArgumentException - an argument is null

valueOf

public static Speed valueOf(Distance distance,
 Duration duration)

Creates a new Speed from an arbitrary distance over an arbitrary duration, reduced to meters per second.

Parameters:

distance - the distance traveled

duration - the time taken

Returns:

a new speed

Throws:

InvalidArgumentException - duration is zero

NullArgumentException - distance or duration is null

valueOf

public static Speed valueOf(String text)

Creates a new Speed from the string form produced by toString(), e.g. "90 km/h". The time symbol follows the final /.

Parameters:

text - the speed string

Returns:

a new speed

Throws:

InvalidArgumentException - text cannot be parsed

NullArgumentException - text is null

unknown

public static Speed unknown()

Gets an unknown speed: an unknown distance over a second. The time unit must be finite -- a speed is a distance per one unit and INFINITY has no seconds -- so the unknown-ness is carried entirely by the distance, which has infinite resolution and infinite uncertainty.

Returns:

an unknown speed

light

public static Speed light()

Gets the speed of light in a vacuum: 299,792,458 meters per second. The value is exact -- since 1983 the meter has been defined from it rather than measured against it.

Returns:

the speed of light