README
1NAME
2 "Time::HiRes::Value" - a class representing a time value or interval in
3 exact microseconds
4
5DESCRIPTION
6 The "Time::HiRes" module allows perl to access the system's clock to
7 microsecond accuracy. However, floating point numbers are not suitable
8 for manipulating such time values, as rounding errors creep in to
9 calculations performed on floating-point representations of UNIX time.
10 This class provides a solution to this problem, by storing the seconds
11 and miliseconds in separate integer values, in an array. In this way,
12 the value can remain exact, and no rounding errors result.
13
14FUNCTIONS
15 $time = Time::HiRes::Value->new( $sec, $usec )
16 This function returns a new instance of a "Time::HiRes::Value" object.
17 This object is immutable, and represents the time passed in to the
18 "*$sec*" and "*$usec*" parameters.
19
20 If the "*$usec*" value is provided then the new "Time::HiRes::Value"
21 object will store the values passed directly, which must both be
22 integers. Negative values are represented in "additive" form; that is, a
23 value of -1.5 seconds would be represented by
24
25 Time::HiRes::Value->new( -2, 500000 );
26
27 If the "*$usec*" value is not provided, then the "*$sec*" value will be
28 parsed as a decimal string, attempting to match out a decimal point to
29 split seconds and microseconds. This method avoids rounding errors
30 introduced by floating-point maths.
31
32 $time = Time::HiRes::Value->now()
33 This function returns a new instance of "Time::HiRes::Value" containing
34 the current system time, as returned by the system's "gettimeofday()"
35 call.
36
37OPERATORS
38 Each of the methods here overloads an operator
39
40 $self->STRING()
41 "$self"
42 This method returns a string representation of the time, in the form of
43 a decimal string with 6 decimal places. For example
44
45 15.000000
46 -3.000000
47 4.235996
48
49 A leading "-" sign will be printed if the stored time is negative, and
50 the "*$usec*" part will always contain 6 digits.
51
52 $self->add( $other )
53 $self->sum( $other )
54 $self + $other
55 This method returns a new "Time::HiRes::Value" value, containing the sum
56 of the passed values. If a string is passed, it will be parsed according
57 to the same rules as for the "new()" constructor.
58
59 Note that "sum" is provided as an alias to "add".
60
61 $self->sub( $other )
62 $self->diff( $other )
63 $self - $other
64 This method returns a new "Time::HiRes::Value" value, containing the
65 difference of the passed values. If a string is passed, it will be
66 parsed according to the same rules as for the "new()" constructor.
67
68 Note that "diff" is provided as an alias to "sub".
69
70 $self->mult( $other )
71 $self * $other
72 This method returns a new "Time::HiRes::Value" value, containing the
73 product of the passed values. $other must not itself be a
74 "Time::HiRes::Value" object; it is an error to attempt to multiply two
75 times together.
76
77 $self->div( $other )
78 $self / $other
79 This method returns a new "Time::HiRes::Value" value, containing the
80 quotient of the passed values. $other must not itself be a
81 "Time::HiRes::Value" object; it is an error for a time to be used as a
82 divisor.
83
84 $self->cmp( $other )
85 $self <=> $other
86 This method compares the two passed values, and returns a number that is
87 positive, negative or zero, as per the usual rules for the "<=>"
88 operator. If a string is passed, it will be parsed according to the same
89 rules as for the "new()" constructor.
90
91SEE ALSO
92 * Time::HiRes - Obtain system timers in resolution greater than 1
93 second
94
95AUTHOR
96 Paul Evans <leonerd@leonerd.org.uk>
97
98