Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Time::Clock(3)	      User Contributed Perl Documentation	Time::Clock(3)

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.

perl v5.24.1			  2014-02-14			Time::Clock(3)

NAME | SYNOPSIS | DESCRIPTION | CLASS METHODS | CONSTRUCTOR | OBJECT METHODS | AUTHOR | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Time::Clock&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help