.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Time::Clock 3pm"
.TH Time::Clock 3pm "2018-01-14" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Time::Clock \- Twenty\-four hour clock object with nanosecond precision.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  $t = Time::Clock\->new(hour => 12, minute => 34, second => 56);
\&  print $t\->as_string; # 12:34:56
\&
\&  $t\->parse(\*(Aq8pm\*(Aq);
\&  print "$t"; # 20:00:00
\&
\&  print $t\->format(\*(Aq%I:%M %p\*(Aq); # 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
\&
\&  ...
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
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.
.PP
Time::Clock objects automatically stringify to a user-definable format.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.IP "\fBdefault_format \s-1FORMAT\s0\fR" 4
.IX Item "default_format FORMAT"
Set the default format used by the as_string method for all objects of this class.  Defaults to \*(L"%H:%M:%S%n\*(R".  See the documentation for the format method for a complete list of format specifiers.
.Sp
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.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "\fBnew \s-1PARAMS\s0\fR" 4
.IX Item "new PARAMS"
Constructs a new Time::Clock object based on \s-1PARAMS,\s0 where \s-1PARAMS\s0 are
name/value pairs.  Any object method is a valid parameter name.  Example:
.Sp
.Vb 1
\&    $t = Time::Clock\->new(hour => 12, minute => 34, second => 56);
.Ve
.Sp
If a single argument is passed to new, it is equivalent to calling the parse method.  That is, this:
.Sp
.Vb 1
\&    $t = Time::Clock\->new(\*(Aq12:34:56\*(Aq);
.Ve
.Sp
is equivalent to this:
.Sp
.Vb 2
\&    $t = Time::Clock\->new;
\&    $t\->parse(\*(Aq12:34:56\*(Aq);
.Ve
.Sp
Returns the newly constructed Time::Clock object.
.SH "OBJECT METHODS"
.IX Header "OBJECT METHODS"
.IP "\fBadd \s-1PARAMS\s0\fR" 4
.IX Item "add PARAMS"
Add the time specified by \s-1PARAMS\s0 to the clock.  Valid \s-1PARAMS\s0 are:
.RS 4
.ie n .IP """hours INT""" 4
.el .IP "\f(CWhours INT\fR" 4
.IX Item "hours INT"
An integer number of hours.
.ie n .IP """minutes INT""" 4
.el .IP "\f(CWminutes INT\fR" 4
.IX Item "minutes INT"
An integer number of minutes.
.ie n .IP """seconds INT""" 4
.el .IP "\f(CWseconds INT\fR" 4
.IX Item "seconds INT"
An integer number of seconds.
.ie n .IP """nanoseconds INT""" 4
.el .IP "\f(CWnanoseconds INT\fR" 4
.IX Item "nanoseconds INT"
An integer number of nanoseconds.
.RE
.RS 4
.Sp
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.
.RE
.IP "\fBampm \s-1AM/PM\s0\fR" 4
.IX Item "ampm AM/PM"
Get or set the \s-1AM/PM\s0 attribute of the clock.  Valid values of \s-1AM/PM\s0 must contain the letters \*(L"\s-1AM\*(R"\s0 or \*(L"\s-1PM\*(R"\s0 (case-insensitive), optionally followed by periods.
.Sp
A clock whose hour is greater than 12 cannot be set to \s-1AM.\s0  Any attempt to do so will cause a fatal error.
.Sp
Setting a clock whose hour is less than 12 to \s-1PM\s0 will cause its  hour to be increased by 12.  Example:
.Sp
.Vb 2
\&    $t = Time::Clock\->new(\*(Aq8:00\*(Aq);
\&    print $t\->as_string; # 08:00:00
\&
\&    $t\->ampm(\*(AqPM\*(Aq);
\&    print $t\->as_string; # 20:00:00
.Ve
.Sp
Return the string \*(L"\s-1AM\*(R"\s0 if the hour is less than 12, \*(L"\s-1PM\*(R"\s0 otherwise.
.IP "\fBas_integer_seconds\fR" 4
.IX Item "as_integer_seconds"
Returns the integer number of seconds since 00:00:00.
.IP "\fBas_string\fR" 4
.IX Item "as_string"
Returns a string representation of the clock, formatted according to the clock object's default_format.
.IP "\fBdefault_format \s-1FORMAT\s0\fR" 4
.IX Item "default_format FORMAT"
Set the default format used by the as_string method for this object.  Defaults to \*(L"%H:%M:%S%n\*(R".  See the documentation for the format method for a complete list of format specifiers.
.Sp
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.
.IP "\fBformat \s-1FORMAT\s0\fR" 4
.IX Item "format FORMAT"
Returns the clock value formatted according to the \s-1FORMAT\s0 string containing \*(L"%\*(R"\-prefixed format specifiers.  Valid format specifiers are:
.RS 4
.ie n .IP "%H" 4
.el .IP "\f(CW%H\fR" 4
.IX Item "%H"
The hour as a two-digit, zero-padded integer using a 24\-hour clock (range 00 to 23).
.ie n .IP "%I" 4
.el .IP "\f(CW%I\fR" 4
.IX Item "%I"
The hour as a two-digit, zero-padded integer using a 12\-hour clock (range 01 to 12).
.ie n .IP "%i" 4
.el .IP "\f(CW%i\fR" 4
.IX Item "%i"
The hour as an integer using a 12\-hour clock (range 1 to 12).
.ie n .IP "%k" 4
.el .IP "\f(CW%k\fR" 4
.IX Item "%k"
The hour as an integer using a 24\-hour clock (range 0 to 23).
.ie n .IP "%M" 4
.el .IP "\f(CW%M\fR" 4
.IX Item "%M"
The minute as a two-digit, zero-padded integer (range 00 to 59).
.ie n .IP "%n" 4
.el .IP "\f(CW%n\fR" 4
.IX Item "%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:
.Sp
.Vb 2
\&    $t = Time::Clock\->new(\*(Aq12:34:56\*(Aq);
\&    print $t\->format(\*(Aq%H:%M:%S%n\*(Aq); # 12:34:56
\&
\&    $t\->nanosecond(0);
\&    print $t\->format(\*(Aq%H:%M:%S%n\*(Aq); # 12:34:56
\&
\&    $t\->nanosecond(123000000);
\&    print $t\->format(\*(Aq%H:%M:%S%n\*(Aq); # 12:34:56.123
.Ve
.ie n .IP """%[1\-9]n""" 4
.el .IP "\f(CW%[1\-9]n\fR" 4
.IX Item "%[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:
.Sp
.Vb 2
\&    $t = Time::Clock\->new(\*(Aq12:34:56\*(Aq);
\&    print $t\->format(\*(Aq%H:%M:%S%4n\*(Aq); # 12:34:56
\&
\&    $t\->nanosecond(0);
\&    print $t\->format(\*(Aq%H:%M:%S%4n\*(Aq); # 12:34:56.0000
\&
\&    $t\->nanosecond(123000000);
\&    print $t\->format(\*(Aq%H:%M:%S%4n\*(Aq); # 12:34:56.1230
.Ve
.ie n .IP "%N" 4
.el .IP "\f(CW%N\fR" 4
.IX Item "%N"
Nanoseconds as a nine-digit, zero-padded integer (range 000000000 to 999999999)
.ie n .IP """%[1\-9]N""" 4
.el .IP "\f(CW%[1\-9]N\fR" 4
.IX Item "%[1-9]N"
Fractional seconds as a one\- to nine-digit, zero-padded integer.  Examples:
.Sp
.Vb 2
\&    $t = Time::Clock\->new(\*(Aq12:34:56\*(Aq);
\&    print $t\->format(\*(Aq%H:%M:%S.%4N\*(Aq); # 12:34:56.0000
\&
\&    $t\->nanosecond(123000000);
\&    print $t\->format(\*(Aq%H:%M:%S.%6N\*(Aq); # 12:34:56.123000
\&
\&    $t\->nanosecond(123000000);
\&    print $t\->format(\*(Aq%H:%M:%S.%2N\*(Aq); # 12:34:56.12
.Ve
.ie n .IP "%p" 4
.el .IP "\f(CW%p\fR" 4
.IX Item "%p"
Either \*(L"\s-1AM\*(R"\s0 or \*(L"\s-1PM\*(R"\s0 according to the value return by the ampm method.
.ie n .IP "%P" 4
.el .IP "\f(CW%P\fR" 4
.IX Item "%P"
Like \f(CW%p\fR but lowercase: \*(L"am\*(R" or \*(L"pm\*(R"
.ie n .IP "%S" 4
.el .IP "\f(CW%S\fR" 4
.IX Item "%S"
The second as a two-digit, zero-padded integer (range 00 to 61).
.ie n .IP "%s" 4
.el .IP "\f(CW%s\fR" 4
.IX Item "%s"
The integer number of seconds since 00:00:00.
.ie n .IP "%T" 4
.el .IP "\f(CW%T\fR" 4
.IX Item "%T"
The time in 24\-hour notation (%H:%M:%S).
.ie n .IP """%%""" 4
.el .IP "\f(CW%%\fR" 4
.IX Item "%%"
A literal \*(L"%\*(R" character.
.RE
.RS 4
.RE
.IP "\fBhour \s-1INT\s0\fR" 4
.IX Item "hour INT"
Get or set the hour of the clock.  \s-1INT\s0 must be an integer from 0 to 23.
.IP "\fBminute \s-1INT\s0\fR" 4
.IX Item "minute INT"
Get or set the minute of the clock.  \s-1INT\s0 must be an integer from 0 to 59.
.IP "\fBnanosecond \s-1INT\s0\fR" 4
.IX Item "nanosecond INT"
Get or set the nanosecond of the clock.  \s-1INT\s0 must be an integer from 0 to 999999999.
.IP "\fBparse \s-1STRING\s0\fR" 4
.IX Item "parse STRING"
Set the clock time by parsing \s-1STRING.\s0  The invoking object is returned.
.Sp
Valid string values contain an hour with optional minutes, seconds, fractional seconds, and \s-1AM/PM\s0 string.  There should be a colon (\*(L":\*(R") between hours, minutes, and seconds, and a decimal point (\*(L".\*(R") between the seconds and fractional seconds.  Fractional seconds may contain up to 9 digits.  The \s-1AM/PM\s0 string is case-insensitive and may have periods after each letter.
.Sp
The string \*(L"now\*(R" will initialize the clock object with the current (local) time.  If the Time::HiRes module is installed, this time will have fractional seconds.
.Sp
A time value with an hour of 24 and zero minutes, seconds, and nanoseconds is also accepted by this method.
.Sp
Here are some examples of valid time strings:
.Sp
.Vb 6
\&    12:34:56.123456789
\&    12:34:56.123 PM
\&    24:00
\&    8:30pm
\&    6 A.m.
\&    now
.Ve
.IP "\fBsecond \s-1INT\s0\fR" 4
.IX Item "second INT"
Get or set the second of the clock.  \s-1INT\s0 must be an integer from 0 to 59.
.IP "\fBsubtract \s-1PARAMS\s0\fR" 4
.IX Item "subtract PARAMS"
Subtract the time specified by \s-1PARAMS\s0 from the clock.  Valid \s-1PARAMS\s0 are:
.RS 4
.ie n .IP """hours INT""" 4
.el .IP "\f(CWhours INT\fR" 4
.IX Item "hours INT"
An integer number of hours.
.ie n .IP """minutes INT""" 4
.el .IP "\f(CWminutes INT\fR" 4
.IX Item "minutes INT"
An integer number of minutes.
.ie n .IP """seconds INT""" 4
.el .IP "\f(CWseconds INT\fR" 4
.IX Item "seconds INT"
An integer number of seconds.
.ie n .IP """nanoseconds INT""" 4
.el .IP "\f(CWnanoseconds INT\fR" 4
.IX Item "nanoseconds INT"
An integer number of nanoseconds.
.RE
.RS 4
.Sp
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.
.RE
.SH "AUTHOR"
.IX Header "AUTHOR"
John C. Siracusa (siracusa@gmail.com)
.SH "LICENSE"
.IX Header "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.