1Time::Clock(3) User Contributed Perl Documentation Time::Clock(3)
2
6 Time::Clock - Twenty-four hour clock object with nanosecond precision.
7
9 $t = Time::Clock->new(hour => 12, minute => 34, second => 56);
10 print $t->as_string; # 12:34:56
11 $t->parse('8pm');
13 print "$t"; # 20:00:00
14 print $t->format('%I:%M %p'); # 08:00 PM
16 $t->add(minutes => 15, nanoseconds => 123000000);
18 print $t->as_string; # 20:15:00.123
19 $t->subtract(hours => 30);
21 print $t->as_string; # 14:15:00.123
22 ...
24
26 A Time::Clock object is a twenty-four hour clock with nanosecond
27 precision and wrap-around. It is a clock only; it has absolutely no
28 concept of dates. Vagaries of date/time such as leap seconds and
29 daylight savings time are unsupported.
30 When a Time::Clock object hits 23:59:59.999999999 and at least one more
32 nanosecond is added, it will wrap around to 00:00:00.000000000. This
33 works in reverse when time is subtracted.
34 Time::Clock objects automatically stringify to a user-definable format.
36
38 default_format FORMAT
39 Set the default format used by the as_string method for all objects
40 of this class. Defaults to "%H:%M:%S%n". See the documentation
41 for the format method for a complete list of format specifiers.
42 Note that this method may also be called as an object method, in
44 which case it sets the default format for the individual object
45 only.
46
48 new PARAMS
49 Constructs a new Time::Clock object based on PARAMS, where PARAMS
50 are name/value pairs. Any object method is a valid parameter name.
51 Example:
52 $t = Time::Clock->new(hour => 12, minute => 34, second => 56);
54 If a single argument is passed to new, it is equivalent to calling
56 the parse method. That is, this:
57 $t = Time::Clock->new('12:34:56');
59 is equivalent to this:
61 $t = Time::Clock->new;
63 $t->parse('12:34:56');
64 Returns the newly constructed Time::Clock object.
66
68 add PARAMS
69 Add the time specified by PARAMS to the clock. Valid PARAMS are:
70 "hours INT"
72 An integer number of hours.
73 "minutes INT"
75 An integer number of minutes.
76 "seconds INT"
78 An integer number of seconds.
79 "nanoseconds INT"
81 An integer number of nanoseconds.
82 If the amount of time added is large enough, the clock will wrap
84 around from 23:59:59.999999999 to 00:00:00.000000000 as needed.
85 ampm AM/PM
87 Get or set the AM/PM attribute of the clock. Valid values of AM/PM
88 must contain the letters "AM" or "PM" (case-insensitive),
89 optionally followed by periods.
90 A clock whose hour is greater than 12 cannot be set to AM. Any
92 attempt to do so will cause a fatal error.
93 Setting a clock whose hour is less than 12 to PM will cause its
95 hour to be increased by 12. Example:
96 $t = Time::Clock->new('8:00');
98 print $t->as_string; # 08:00:00
99 $t->ampm('PM');
101 print $t->as_string; # 20:00:00
102 Return the string "AM" if the hour is less than 12, "PM" otherwise.
104 as_integer_seconds
106 Returns the integer number of seconds since 00:00:00.
107 as_string
109 Returns a string representation of the clock, formatted according
110 to the clock object's default_format.
111 default_format FORMAT
113 Set the default format used by the as_string method for this
114 object. Defaults to "%H:%M:%S%n". See the documentation for the
115 format method for a complete list of format specifiers.
116 Note that this method may also be called as a class method, in
118 which case it sets the default format all objects of this class.
119 format FORMAT
121 Returns the clock value formatted according to the FORMAT string
122 containing "%"-prefixed format specifiers. Valid format specifiers
123 are:
124 %H The hour as a two-digit, zero-padded integer using a 24-hour
126 clock (range 00 to 23).
127 %I The hour as a two-digit, zero-padded integer using a 12-hour
129 clock (range 01 to 12).
130 %i The hour as an integer using a 12-hour clock (range 1 to 12).
132 %k The hour as an integer using a 24-hour clock (range 0 to 23).
134 %M The minute as a two-digit, zero-padded integer (range 00 to
136 59).
137 %n If the clock has a non-zero nanosecond value, then this format
139 produces a decimal point followed by the fractional seconds up
140 to and including the last non-zero digit. If no nanosecond
141 value is defined, or if it is zero, then this format produces
142 an empty string. Examples:
143 $t = Time::Clock->new('12:34:56');
145 print $t->format('%H:%M:%S%n'); # 12:34:56
146 $t->nanosecond(0);
148 print $t->format('%H:%M:%S%n'); # 12:34:56
149 $t->nanosecond(123000000);
151 print $t->format('%H:%M:%S%n'); # 12:34:56.123
152 "%[1-9]n"
154 If the clock has a defined nanosecond value, then this format
155 produces a decimal point followed by the specified number of
156 digits of fractional seconds (1-9). Examples:
157 $t = Time::Clock->new('12:34:56');
159 print $t->format('%H:%M:%S%4n'); # 12:34:56
160 $t->nanosecond(0);
162 print $t->format('%H:%M:%S%4n'); # 12:34:56.0000
163 $t->nanosecond(123000000);
165 print $t->format('%H:%M:%S%4n'); # 12:34:56.1230
166 %N Nanoseconds as a nine-digit, zero-padded integer (range
168 000000000 to 999999999)
169 "%[1-9]N"
171 Fractional seconds as a one- to nine-digit, zero-padded
172 integer. Examples:
173 $t = Time::Clock->new('12:34:56');
175 print $t->format('%H:%M:%S.%4N'); # 12:34:56.0000
176 $t->nanosecond(123000000);
178 print $t->format('%H:%M:%S.%6N'); # 12:34:56.123000
179 $t->nanosecond(123000000);
181 print $t->format('%H:%M:%S.%2N'); # 12:34:56.12
182 %p Either "AM" or "PM" according to the value return by the ampm
184 method.
185 %P Like %p but lowercase: "am" or "pm"
187 %S The second as a two-digit, zero-padded integer (range 00 to
189 61).
190 %s The integer number of seconds since 00:00:00.
192 %T The time in 24-hour notation (%H:%M:%S).
194 "%%"
196 A literal "%" character.
197 hour INT
199 Get or set the hour of the clock. INT must be an integer from 0 to
200 23.
201 minute INT
203 Get or set the minute of the clock. INT must be an integer from 0
204 to 59.
205 nanosecond INT
207 Get or set the nanosecond of the clock. INT must be an integer
208 from 0 to 999999999.
209 parse STRING
211 Set the clock time by parsing STRING. The invoking object is
212 returned.
213 Valid string values contain an hour with optional minutes, seconds,
215 fractional seconds, and AM/PM string. There should be a colon
216 (":") between hours, minutes, and seconds, and a decimal point
217 (".") between the seconds and fractional seconds. Fractional
218 seconds may contain up to 9 digits. The AM/PM string is case-
219 insensitive and may have periods after each letter.
220 The string "now" will initialize the clock object with the current
222 (local) time. If the Time::HiRes module is installed, this time
223 will have fractional seconds.
224 A time value with an hour of 24 and zero minutes, seconds, and
226 nanoseconds is also accepted by this method.
227 Here are some examples of valid time strings:
229 12:34:56.123456789
231 12:34:56.123 PM
232 24:00
233 8:30pm
234 6 A.m.
235 now
236 second INT
238 Get or set the second of the clock. INT must be an integer from 0
239 to 59.
240 subtract PARAMS
242 Subtract the time specified by PARAMS from the clock. Valid PARAMS
243 are:
244 "hours INT"
246 An integer number of hours.
247 "minutes INT"
249 An integer number of minutes.
250 "seconds INT"
252 An integer number of seconds.
253 "nanoseconds INT"
255 An integer number of nanoseconds.
256 If the amount of time subtracted is large enough, the clock will
258 wrap around from 00:00:00.000000000 to 23:59:59.999999999 as
259 needed.
260
262 John C. Siracusa (siracusa@gmail.com)
263
265 Copyright (c) 2010 by John C. Siracusa. All rights reserved. This
266 program is free software; you can redistribute it and/or modify it
267 under the same terms as Perl itself.
268perl v5.38.0 2023-07-21 Time::Clock(3)