Class Time
 java.lang.Object

 ptolemy.actor.util.Time

 All Implemented Interfaces:
java.lang.Comparable
public class Time extends java.lang.Object implements java.lang.Comparable
An object of the Time class represents time in a model. An instance of Time has a value that is immutable. It has no limit on the magnitude, and it does not lose resolution as the magnitude increases. There are two time constants: NEGATIVE_INFINITY and POSITIVE_INFINITY.The time value is quantized to the time resolution specified by the timeResolution parameter of the associated director. The reason for this is that without quantization, it is extremely difficult to compare two time values with digittodigit accuracy because of the unpredictable numerical errors introduced during computation. In practice, two time values can only be distinguished if their difference can be detected by some measuring instrument, which always has a smallest unit for measurement. This smallest unit measurement gives the physical meaning of the time resolution used for quantization. There are three exceptions that do not really need a notion of time resolution, ZERO, POSITIVE_INFINITY, and NEGATIVE_INFINITY. These are provided as static fields, and normally these should be the only instances of Time constructed without a director.
This implementation of Time does not lose resolution as the magnitude of the time increases (unlike floating point numbers). This is because Time is represented internally as a multiple of the resolution, and the multiple is not constrained to any limited magnitude.
The time value can be retrieved in three ways, the
toString()
method and thegetDoubleValue()
method and thegetLongValue()
method. The first method returns a string representation while the second method returns a double value. There are some limitations on both methods. For the toString() method, we cannot directly do numerical operations on strings. For the getDoubleValue() method, we can not guarantee that the returned double value preserves the time resolution because of the limited digits for double representation. We recommend to operate on time objects directly instead of the time values of time objects. getLongValue() returns an integer multiple of the director resolution.Two operations, add and subtract, can be performed on a time object, where the argument can be a double or a time object. If the argument is not a time object, the argument is quantized before the operations are performed. These operations return a new time object with a quantized result.
The time value of a time object can be infinite. The add and subtract operations on infinite time values follow rules similar to the IEEE Standard 754 for Floating Point Numbers. In particular, adding two positive or negative infinities yield a positive or negative infinity; adding a positive infinity to a negative infinity, however, triggers an ArithmeticException; the negation of a positive or negative infinity is a negative or positive infinity, respectively.
This class implements the Comparable interface, where two time objects can be compared in the following way. If any of the two time objects contains an infinite time value, the rules are: a negative infinity is equal to a negative infinity and less than anything else; a positive infinity is equal to a positive infinity and bigger than anything else. If none of the time objects has an infinite time value, the time values of two time objects are compared. If the time values are the same, the two time objects are treated equal, or they represent the same model time. Otherwise, the time object containing a bigger time value is regarded to happen after the time object with a smaller time value.
All time objects share the same time resolution, which is provided by the toplevel director. In some domains, such as CT and DE, users can change the time resolution by configuring the timeResolution parameter. The default value for this parameter "1E10", which has value 10 ^{10 }. To preserve the consistency of time values, timeResolution cannot be changed when a model is running (attempting to do so will trigger an exception).
 Since:
 Ptolemy II 4.1
 Version:
 $Id$
 Author:
 Haiyang Zheng, Edward A. Lee, Elaine Cheong
 Pt.AcceptedRating:
 Red (hyzheng)
 Pt.ProposedRating:
 Yellow (hyzheng)


Field Summary
Fields Modifier and Type Field Description static Time
NEGATIVE_INFINITY
A static and final time constant holding a negative infinity.static Time
POSITIVE_INFINITY
A static and final time constant holding a positive infinity.static Time
ZERO
A static and final time constant holding a zero.

Constructor Summary
Constructors Constructor Description Time(Director director)
Construct a Time object with zero as the time value.Time(Director director, double timeValue)
Construct a Time object with the specified double value as its time value.Time(Director director, long timeValue)
Construct a Time object with the specified long value as its time value.

Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description protected double
_timeResolution()
Return the time resolution for this Time object, which in this class is the time resolution of the director given in the constructor.Time
add(double timeValue)
Return a new time object whose time value is increased by the given double value.Time
add(Time time)
Return a new time object whose time value is the sum of that of this time object and of the specified time object.Time
addUnchecked(double timeValue)
Add the specified double to this time without checking whether the specified double is too large to ensure the time resolution of the director.int
compareTo(java.lang.Object time)
Return 1, 0, or 1 if this time object is less than, equal to, or greater than the given argument.boolean
equals(java.lang.Object time)
Return true if this time object has the same time value as that of the given time object.double
getDoubleValue()
Return the double representation of the time value of this time object.long
getLongValue()
Return the long representation of the time value of this time object.int
hashCode()
Return the hash code for the time object.boolean
isInfinite()
Return true if the current time value is infinite.boolean
isNegative()
Return true if the current time value is a negative value (including negative infinity).boolean
isNegativeInfinite()
Return true if the current time value is a negative infinity.boolean
isPositive()
Return true if the current time value is a positive value (including positive infinity).boolean
isPositiveInfinite()
Return true if the current time value is a positive infinity.boolean
isZero()
Return true if the current time value is zero.double
maximumAccurateValueAsDouble()
Return the maximum value of time whose representation as a double is always accurate to the specified time resolution.static Time
milliseconds(Director director, long milliseconds)
Return a new Time object whose value equals the argument, which is interpreted in milliseconds.Time
subtract(double timeValue)
Return a new Time object whose time value is decreased by the given double value.Time
subtract(Time time)
Return a new time object whose time value is decreased by the time value of the specified time object.double
subtractToDouble(Time time)
Subtract the specified time from this time and return the result as a double.java.lang.String
toString()
Return the string representation of this time object.



Field Detail

NEGATIVE_INFINITY
public static final Time NEGATIVE_INFINITY
A static and final time constant holding a negative infinity.

POSITIVE_INFINITY
public static final Time POSITIVE_INFINITY
A static and final time constant holding a positive infinity.

ZERO
public static final Time ZERO
A static and final time constant holding a zero.


Constructor Detail

Time
public Time(Director director)
Construct a Time object with zero as the time value. This object is associated with the given director, which provides the necessary information for quantization. Parameters:
director
 The director with which this time object is associated. This must not be null, or subsequent uses of the class will fail.

Time
public Time(Director director, double timeValue) throws IllegalActionException
Construct a Time object with the specified double value as its time value. The specified director provides the resolution that is used to quantize the double value so that the value of the resulting Time object is a multiple of the precision. Parameters:
director
 The director with which this time object is associated.timeValue
 A double value as the specified time value. Throws:
java.lang.ArithmeticException
 If the argument is NaN.IllegalActionException
 If the given double time value does not match the time resolution.

Time
public Time(Director director, long timeValue)
Construct a Time object with the specified long value as its time value. Parameters:
director
 The director with which this time object is associated.timeValue
 A long value as the specified time value, as a multiple of the resolution.


Method Detail

add
public Time add(double timeValue)
Return a new time object whose time value is increased by the given double value. The specified double value is quantized to a multiple of the precision before it is added. Parameters:
timeValue
 The amount of the time increment. Returns:
 A new time object with the incremented time value.
 Throws:
java.lang.ArithmeticException
 If the result is not a valid number (the argument is NaN or the sum would be), or the given time value does not match the time resolution.

add
public Time add(Time time)
Return a new time object whose time value is the sum of that of this time object and of the specified time object. The two time objects are expected to have directors with the same time resolution. If they do not, then the returned result is a new Time object representing the sum of the double values of the two Time objects. This would not be as accurate. Parameters:
time
 The time object contains the amount of time increment. Returns:
 A new time object with the quantized and incremented time value.
 Throws:
java.lang.ArithmeticException
 If the result is not a valid number (it is the sum of positive and negative infinity).

addUnchecked
public Time addUnchecked(double timeValue)
Add the specified double to this time without checking whether the specified double is too large to ensure the time resolution of the director.That is, two calls to this method could yield the same result even if the two arguments differ by more than the time resolution. The
add(double)
method, in contrast, will throw an exception if two such calls could yield the same result.This method should only be used if the time resolution is not really needed for this addition. For example, when finding the stop time of long simulation, where `timeValue` is a large number, it would be reasonable to use this method if the stop time does not need to be so precise.
 Parameters:
timeValue
 The value to add. Returns:
 The sum of this Time object and the value to add.

compareTo
public int compareTo(java.lang.Object time)
Return 1, 0, or 1 if this time object is less than, equal to, or greater than the given argument. Note that a ClassCastException will be thrown if the argument is not an instance of Time. This object expects the directors associated with this and the specified Time objects to have the same time resolution. If this is not the case, then it compares the double representations of those time values, which is not as accurate. Specified by:
compareTo
in interfacejava.lang.Comparable
 Parameters:
time
 A time object to compare to. Returns:
 The integer 1, 0, or 1 if this is less than, equal to, or greater than the argument.

equals
public boolean equals(java.lang.Object time)
Return true if this time object has the same time value as that of the given time object. Overrides:
equals
in classjava.lang.Object
 Parameters:
time
 The time object that this time object is compared to. Returns:
 True if the two time objects have the same time value.

getDoubleValue
public double getDoubleValue()
Return the double representation of the time value of this time object. Note that the returned result is not necessarily as accurate as the internal representation. In particular, if the internal representation is too large, then then the returned result may be infinite. In addition, if the magnitude of the returned number is large relative to the time resolution of the associated director, then the result may be inaccurate by more than the time resolution. Returns:
 The double representation of the time value.

getLongValue
public long getLongValue()
Return the long representation of the time value of this time object. The long representation is a multiple of the resolution of the associated director. Note that a Time value of positive infinity will return Long.MAX_VALUE and a Time value of negative infinity will return Long.MIN_VALUE. Returns:
 The long representation of the time value.

hashCode
public int hashCode()
Return the hash code for the time object. If two time objects contains the same quantized time value, they have the same hash code. Note that the quantization is performed on the time value before calculating the hash code. Overrides:
hashCode
in classjava.lang.Object
 Returns:
 The hash code for the time object.

isInfinite
public final boolean isInfinite()
Return true if the current time value is infinite. Returns:
 true if the current time value is infinite.

isNegative
public final boolean isNegative()
Return true if the current time value is a negative value (including negative infinity). Returns:
 true if the current time value is a negative value (including negative infinity).

isNegativeInfinite
public final boolean isNegativeInfinite()
Return true if the current time value is a negative infinity. Returns:
 true if the current time value is a negative infinity.

isPositive
public final boolean isPositive()
Return true if the current time value is a positive value (including positive infinity). Returns:
 true if the current time value is a positive value (including positive infinity).

isPositiveInfinite
public final boolean isPositiveInfinite()
Return true if the current time value is a positive infinity. Returns:
 true if the current time value is a positive infinity.

isZero
public final boolean isZero()
Return true if the current time value is zero. Returns:
 true if the current time value is a zero.

maximumAccurateValueAsDouble
public double maximumAccurateValueAsDouble()
Return the maximum value of time whose representation as a double is always accurate to the specified time resolution. In other words, if you ask this instance of Time for its value as a double, if the returned double is larger than the number returned by this method, then the double representation is not necessarily accurate to the specified resolution. Returns:
 The maximum value of time above which the double representation may not be accurate to the specified resolution.

milliseconds
public static Time milliseconds(Director director, long milliseconds)
Return a new Time object whose value equals the argument, which is interpreted in milliseconds. Parameters:
director
 The director with which this time object is associated.milliseconds
 The time in ms. Returns:

subtract
public Time subtract(double timeValue)
Return a new Time object whose time value is decreased by the given double value. Quantization is performed on both the timeValue argument and the result. Parameters:
timeValue
 The amount of time decrement. Returns:
 A new time object with time value decremented.

subtract
public Time subtract(Time time)
Return a new time object whose time value is decreased by the time value of the specified time object. This method assumes that the two time values have directors with the same time resolution. If this is not the case, then the result is a new Time object whose value is constructed from the difference between the double values for this and the specified Time objects, using the time resolution of the director of this one. Parameters:
time
 The time object contains the amount of time decrement. Returns:
 A new time object with time value decremented.

subtractToDouble
public double subtractToDouble(Time time)
Subtract the specified time from this time and return the result as a double.This is equivalent to calling
subtract(Time)
and then invoking getDoubleValue(), but it is more efficient, in that it avoids unnecessary construction of Time objects. Parameters:
time
 The time to subtract. Returns:
 This Time minus the specified time, as a double.

toString
public java.lang.String toString()
Return the string representation of this time object. This is actually an approximation generated by first converting to a double. Note that the string representation of infinities can not be used to construct the time objects containing infinite time values. Overrides:
toString
in classjava.lang.Object
 Returns:
 A String representation of this time object.

_timeResolution
protected double _timeResolution()
Return the time resolution for this Time object, which in this class is the time resolution of the director given in the constructor. If no director was given, then return a default time resolution of 10E10. This is a protected method to allow subclasses to use their own time resolution. Returns:
 The time resolution of the director.

