1Time::Clock(3)        User Contributed Perl Documentation       Time::Clock(3)
2
3
4

NAME

6       Time::Clock - Twenty-four hour clock object with nanosecond precision.
7

SYNOPSIS

9         $t = Time::Clock->new(hour => 12, minute => 34, second => 56);
10         print $t->as_string; # 12:34:56
11
12         $t->parse('8pm');
13         print "$t"; # 20:00:00
14
15         print $t->format('%I:%M %p'); # 08:00 PM
16
17         $t->add(minutes => 15, nanoseconds => 123000000);
18         print $t->as_string; # 20:15:00.123
19
20         $t->subtract(hours => 30);
21         print $t->as_string; # 14:15:00.123
22
23         ...
24

DESCRIPTION

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
31       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
35       Time::Clock objects automatically stringify to a user-definable format.
36

CLASS METHODS

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
43           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

CONSTRUCTOR

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
53               $t = Time::Clock->new(hour => 12, minute => 34, second => 56);
54
55           If a single argument is passed to new, it is equivalent to calling
56           the parse method.  That is, this:
57
58               $t = Time::Clock->new('12:34:56');
59
60           is equivalent to this:
61
62               $t = Time::Clock->new;
63               $t->parse('12:34:56');
64
65           Returns the newly constructed Time::Clock object.
66

OBJECT METHODS

68       add PARAMS
69           Add the time specified by PARAMS to the clock.  Valid PARAMS are:
70
71           "hours INT"
72               An integer number of hours.
73
74           "minutes INT"
75               An integer number of minutes.
76
77           "seconds INT"
78               An integer number of seconds.
79
80           "nanoseconds INT"
81               An integer number of nanoseconds.
82
83           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
86       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
91           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
94           Setting a clock whose hour is less than 12 to PM will cause its
95           hour to be increased by 12.  Example:
96
97               $t = Time::Clock->new('8:00');
98               print $t->as_string; # 08:00:00
99
100               $t->ampm('PM');
101               print $t->as_string; # 20:00:00
102
103           Return the string "AM" if the hour is less than 12, "PM" otherwise.
104
105       as_integer_seconds
106           Returns the integer number of seconds since 00:00:00.
107
108       as_string
109           Returns a string representation of the clock, formatted according
110           to the clock object's default_format.
111
112       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
117           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
120       format FORMAT
121           Returns the clock value formatted according to the FORMAT string
122           containing "%"-prefixed format specifiers.  Valid format specifiers
123           are:
124
125           %H  The hour as a two-digit, zero-padded integer using a 24-hour
126               clock (range 00 to 23).
127
128           %I  The hour as a two-digit, zero-padded integer using a 12-hour
129               clock (range 01 to 12).
130
131           %i  The hour as an integer using a 12-hour clock (range 1 to 12).
132
133           %k  The hour as an integer using a 24-hour clock (range 0 to 23).
134
135           %M  The minute as a two-digit, zero-padded integer (range 00 to
136               59).
137
138           %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
144                   $t = Time::Clock->new('12:34:56');
145                   print $t->format('%H:%M:%S%n'); # 12:34:56
146
147                   $t->nanosecond(0);
148                   print $t->format('%H:%M:%S%n'); # 12:34:56
149
150                   $t->nanosecond(123000000);
151                   print $t->format('%H:%M:%S%n'); # 12:34:56.123
152
153           "%[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
158                   $t = Time::Clock->new('12:34:56');
159                   print $t->format('%H:%M:%S%4n'); # 12:34:56
160
161                   $t->nanosecond(0);
162                   print $t->format('%H:%M:%S%4n'); # 12:34:56.0000
163
164                   $t->nanosecond(123000000);
165                   print $t->format('%H:%M:%S%4n'); # 12:34:56.1230
166
167           %N  Nanoseconds as a nine-digit, zero-padded integer (range
168               000000000 to 999999999)
169
170           "%[1-9]N"
171               Fractional seconds as a one- to nine-digit, zero-padded
172               integer.  Examples:
173
174                   $t = Time::Clock->new('12:34:56');
175                   print $t->format('%H:%M:%S.%4N'); # 12:34:56.0000
176
177                   $t->nanosecond(123000000);
178                   print $t->format('%H:%M:%S.%6N'); # 12:34:56.123000
179
180                   $t->nanosecond(123000000);
181                   print $t->format('%H:%M:%S.%2N'); # 12:34:56.12
182
183           %p  Either "AM" or "PM" according to the value return by the ampm
184               method.
185
186           %P  Like %p but lowercase: "am" or "pm"
187
188           %S  The second as a two-digit, zero-padded integer (range 00 to
189               61).
190
191           %s  The integer number of seconds since 00:00:00.
192
193           %T  The time in 24-hour notation (%H:%M:%S).
194
195           "%%"
196               A literal "%" character.
197
198       hour INT
199           Get or set the hour of the clock.  INT must be an integer from 0 to
200           23.
201
202       minute INT
203           Get or set the minute of the clock.  INT must be an integer from 0
204           to 59.
205
206       nanosecond INT
207           Get or set the nanosecond of the clock.  INT must be an integer
208           from 0 to 999999999.
209
210       parse STRING
211           Set the clock time by parsing STRING.  The invoking object is
212           returned.
213
214           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
221           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
225           A time value with an hour of 24 and zero minutes, seconds, and
226           nanoseconds is also accepted by this method.
227
228           Here are some examples of valid time strings:
229
230               12:34:56.123456789
231               12:34:56.123 PM
232               24:00
233               8:30pm
234               6 A.m.
235               now
236
237       second INT
238           Get or set the second of the clock.  INT must be an integer from 0
239           to 59.
240
241       subtract PARAMS
242           Subtract the time specified by PARAMS from the clock.  Valid PARAMS
243           are:
244
245           "hours INT"
246               An integer number of hours.
247
248           "minutes INT"
249               An integer number of minutes.
250
251           "seconds INT"
252               An integer number of seconds.
253
254           "nanoseconds INT"
255               An integer number of nanoseconds.
256
257           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

AUTHOR

262       John C. Siracusa (siracusa@gmail.com)
263

LICENSE

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.
268
269
270
271perl v5.32.1                      2021-01-27                    Time::Clock(3)
Impressum