--- name: "Time::Clock" section: "3pm" platform: "linux" package: "libtime-clock-perl" version: "1.03-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Time::Clock" --- # Time::Clock(3pm) Twenty-four hour clock object with nanosecond precision. ## NAME Time::Clock - Twenty-four hour clock object with nanosecond precision. ## SYNOPSIS ``` $t = Time::Clock->new(hour => 12, minute => 34, second => 56); print $t->as_string; # 12:34:56 $t->parse('8pm'); print "$t"; # 20:00:00 print $t->format('%I:%M %p'); # 08:00 PM $t->add(minutes => 15, nanoseconds => 123000000); print $t->as_string; # 20:15:00.123 $t->subtract(hours => 30); print $t->as_string; # 14:15:00.123 ... ``` ## DESCRIPTION A Time::Clock object is a twenty-four hour clock with nanosecond precision and wrap-around. It is a clock only; it has absolutely no concept of dates. Vagaries of date/time such as leap seconds and daylight savings time are unsupported. When a Time::Clock object hits 23:59:59.999999999 and at least one more nanosecond is added, it will wrap around to 00:00:00.000000000. This works in reverse when time is subtracted. Time::Clock objects automatically stringify to a user-definable format. ## CLASS METHODS - **default\_format FORMAT** Set the default format used by the as\_string method for all objects of this class. Defaults to "%H:%M:%S%n". See the documentation for the format method for a complete list of format specifiers. Note that this method may also be called as an object method, in which case it sets the default format for the individual object only. ## CONSTRUCTOR - **new PARAMS** Constructs a new Time::Clock object based on PARAMS, where PARAMS are name/value pairs. Any object method is a valid parameter name. Example: ``` $t = Time::Clock->new(hour => 12, minute => 34, second => 56); ``` If a single argument is passed to new, it is equivalent to calling the parse method. That is, this: ``` $t = Time::Clock->new('12:34:56'); ``` is equivalent to this: ``` $t = Time::Clock->new; $t->parse('12:34:56'); ``` Returns the newly constructed Time::Clock object. ## OBJECT METHODS - **add PARAMS** Add the time specified by PARAMS to the clock. Valid PARAMS are: - "hours INT" An integer number of hours. - "minutes INT" An integer number of minutes. - "seconds INT" An integer number of seconds. - "nanoseconds INT" An integer number of nanoseconds. If the amount of time added is large enough, the clock will wrap around from 23:59:59.999999999 to 00:00:00.000000000 as needed. - **ampm AM/PM** Get or set the AM/PM attribute of the clock. Valid values of AM/PM must contain the letters "AM" or "PM" (case-insensitive), optionally followed by periods. A clock whose hour is greater than 12 cannot be set to AM. Any attempt to do so will cause a fatal error. Setting a clock whose hour is less than 12 to PM will cause its hour to be increased by 12. Example: ``` $t = Time::Clock->new('8:00'); print $t->as_string; # 08:00:00 $t->ampm('PM'); print $t->as_string; # 20:00:00 ``` Return the string "AM" if the hour is less than 12, "PM" otherwise. - **as\_integer\_seconds** Returns the integer number of seconds since 00:00:00. - **as\_string** Returns a string representation of the clock, formatted according to the clock object's default\_format. - **default\_format FORMAT** Set the default format used by the as\_string method for this object. Defaults to "%H:%M:%S%n". See the documentation for the format method for a complete list of format specifiers. Note that this method may also be called as a class method, in which case it sets the default format all objects of this class. - **format FORMAT** Returns the clock value formatted according to the FORMAT string containing "%"-prefixed format specifiers. Valid format specifiers are: - %H The hour as a two-digit, zero-padded integer using a 24-hour clock (range 00 to 23). - %I The hour as a two-digit, zero-padded integer using a 12-hour clock (range 01 to 12). - %i The hour as an integer using a 12-hour clock (range 1 to 12). - %k The hour as an integer using a 24-hour clock (range 0 to 23). - %M The minute as a two-digit, zero-padded integer (range 00 to 59). - %n If the clock has a non-zero nanosecond value, then this format produces a decimal point followed by the fractional seconds up to and including the last non-zero digit. If no nanosecond value is defined, or if it is zero, then this format produces an empty string. Examples: ``` $t = Time::Clock->new('12:34:56'); print $t->format('%H:%M:%S%n'); # 12:34:56 $t->nanosecond(0); print $t->format('%H:%M:%S%n'); # 12:34:56 $t->nanosecond(123000000); print $t->format('%H:%M:%S%n'); # 12:34:56.123 ``` - "%\[1-9\]n" If the clock has a defined nanosecond value, then this format produces a decimal point followed by the specified number of digits of fractional seconds (1-9). Examples: ``` $t = Time::Clock->new('12:34:56'); print $t->format('%H:%M:%S%4n'); # 12:34:56 $t->nanosecond(0); print $t->format('%H:%M:%S%4n'); # 12:34:56.0000 $t->nanosecond(123000000); print $t->format('%H:%M:%S%4n'); # 12:34:56.1230 ``` - %N Nanoseconds as a nine-digit, zero-padded integer (range 000000000 to 999999999) - "%\[1-9\]N" Fractional seconds as a one- to nine-digit, zero-padded integer. Examples: ``` $t = Time::Clock->new('12:34:56'); print $t->format('%H:%M:%S.%4N'); # 12:34:56.0000 $t->nanosecond(123000000); print $t->format('%H:%M:%S.%6N'); # 12:34:56.123000 $t->nanosecond(123000000); print $t->format('%H:%M:%S.%2N'); # 12:34:56.12 ``` - %p Either "AM" or "PM" according to the value return by the ampm method. - %P Like `%p` but lowercase: "am" or "pm" - %S The second as a two-digit, zero-padded integer (range 00 to 61). - %s The integer number of seconds since 00:00:00. - %T The time in 24-hour notation (%H:%M:%S). - "%%" A literal "%" character. - **hour INT** Get or set the hour of the clock. INT must be an integer from 0 to 23. - **minute INT** Get or set the minute of the clock. INT must be an integer from 0 to 59. - **nanosecond INT** Get or set the nanosecond of the clock. INT must be an integer from 0 to 999999999. - **parse STRING** Set the clock time by parsing STRING. The invoking object is returned. Valid string values contain an hour with optional minutes, seconds, fractional seconds, and AM/PM string. There should be a colon (":") between hours, minutes, and seconds, and a decimal point (".") between the seconds and fractional seconds. Fractional seconds may contain up to 9 digits. The AM/PM string is case-insensitive and may have periods after each letter. The string "now" will initialize the clock object with the current (local) time. If the Time::HiRes module is installed, this time will have fractional seconds. A time value with an hour of 24 and zero minutes, seconds, and nanoseconds is also accepted by this method. Here are some examples of valid time strings: ``` 12:34:56.123456789 12:34:56.123 PM 24:00 8:30pm 6 A.m. now ``` - **second INT** Get or set the second of the clock. INT must be an integer from 0 to 59. - **subtract PARAMS** Subtract the time specified by PARAMS from the clock. Valid PARAMS are: - "hours INT" An integer number of hours. - "minutes INT" An integer number of minutes. - "seconds INT" An integer number of seconds. - "nanoseconds INT" An integer number of nanoseconds. If the amount of time subtracted is large enough, the clock will wrap around from 00:00:00.000000000 to 23:59:59.999999999 as needed. ## AUTHOR John C. Siracusa (siracusa@gmail.com) ## LICENSE Copyright (c) 2010 by John C. Siracusa. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.