NAME

Time::HiRes::Value - a class representing a time value or interval in exact microseconds

DESCRIPTION

The Time::HiRes module allows perl to access the system's clock to microsecond accuracy. However, floating point numbers are not suitable for manipulating such time values, as rounding errors creep in to calculations performed on floating-point representations of UNIX time. This class provides a solution to this problem, by storing the seconds and miliseconds in separate integer values, in an array. In this way, the value can remain exact, and no rounding errors result.

FUNCTIONS

$time = Time::HiRes::Value->new( $sec, $usec )

This function returns a new instance of a Time::HiRes::Value object. This object is immutable, and represents the time passed in to the $sec and $usec parameters.

If the $usec value is provided then the new Time::HiRes::Value object will store the values passed directly, which must both be integers. Negative values are represented in "additive" form; that is, a value of -1.5 seconds would be represented by

 Time::HiRes::Value->new( -2, 500000 );

If the $usec value is not provided, then the $sec value will be parsed as a decimal string, attempting to match out a decimal point to split seconds and microseconds. This method avoids rounding errors introduced by floating-point maths.

$time = Time::HiRes::Value->now()

This function returns a new instance of Time::HiRes::Value containing the current system time, as returned by the system's gettimeofday() call.

OPERATORS

Each of the methods here overloads an operator

$self->STRING()

"$self"

This method returns a string representation of the time, in the form of a decimal string with 6 decimal places. For example

 15.000000
 -3.000000
  4.235996

A leading - sign will be printed if the stored time is negative, and the $usec part will always contain 6 digits.

$self->add( $other )

$self->sum( $other )

$self + $other

This method returns a new Time::HiRes::Value value, containing the sum of the passed values. If a string is passed, it will be parsed according to the same rules as for the new() constructor.

Note that sum is provided as an alias to add.

$self->sub( $other )

$self->diff( $other )

$self - $other

This method returns a new Time::HiRes::Value value, containing the difference of the passed values. If a string is passed, it will be parsed according to the same rules as for the new() constructor.

Note that diff is provided as an alias to sub.

$self->mult( $other )

$self * $other

This method returns a new Time::HiRes::Value value, containing the product of the passed values. $other must not itself be a Time::HiRes::Value object; it is an error to attempt to multiply two times together.

$self->div( $other )

$self / $other

This method returns a new Time::HiRes::Value value, containing the quotient of the passed values. $other must not itself be a Time::HiRes::Value object; it is an error for a time to be used as a divisor.

$self->cmp( $other )

$self <=> $other

This method compares the two passed values, and returns a number that is positive, negative or zero, as per the usual rules for the <=> operator. If a string is passed, it will be parsed according to the same rules as for the new() constructor.

SEE ALSO

• Time::HiRes - Obtain system timers in resolution greater than 1 second

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>