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

FreeBSD Manual Pages


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

       Time::Format - Easy-to-use date/time formatting.

       This is version 1.12 of Time::Format, September 27, 2012.

	use Time::Format qw(%time %strftime %manip);

	$time{$format, $unixtime}

	print "Today is	$time{'yyyy/mm/dd'}\n";
	print "Yesterday was $time{'yyyy/mm/dd', time-24*60*60}\n";
	print "The time	is $time{'hh:mm:ss'}\n";
	print "Another time is $time{'H:mm am tz', $another_time}\n";
	print "Timestamp: $time{'yyyymmdd.hhmmss.mmm'}\n";

       %time also accepts Date::Manip strings and DateTime objects:

	$dm = Date::Manip::ParseDate('last monday');
	print "Last monday was $time{'Month d, yyyy', $dm}";
	$dt = DateTime->new (....);
	print "Here's another date: $time{'m/d/yy', $dt}";

       It also accepts most ISO-8601 date/time strings:

	$t = '2005/10/31T17:11:09';   #	date separator:	/ or - or .
	$t = '2005-10-31 17.11.09';   #	in-between separator: T	or _ or	space
	$t = '20051031_171109';	      #	time separator:	: or .
	$t = '20051031171109';	      #	separators may be omitted
	$t = '2005/10/31';	      #	date-only is okay
	$t = '17:11:09';	      #	time-only is okay
	# But not:
	$t = '20051031';	      #	date-only without separators
	$t = '171109';		      #	time-only without separators
	# ...because those look	like epoch time	numbers.

       %strftime works like POSIX's "strftime",	if you like those "%"-formats.

	$strftime{$format, $unixtime}
	$strftime{$format, $sec,$min,$hour, $mday,$mon,$year, $wday,$yday,$isdst}

	print "POSIXish: $strftime{'%A,	%B %d, %Y', 0,0,0,12,11,95,2}\n";
	print "POSIXish: $strftime{'%A,	%B %d, %Y', 1054866251}\n";
	print "POSIXish: $strftime{'%A,	%B %d, %Y'}\n";	      #	current	time

       %manip works like Date::Manip's "UnixDate" function.

	$manip{$format,	$when};

	print "Date::Manip: $manip{'%m/%d/%Y'}\n";	      #	current	time
	print "Date::Manip: $manip{'%m/%d/%Y','last Tuesday'}\n";

       These can also be used as standalone functions:

	use Time::Format qw(time_format	time_strftime time_manip);

	print "Today is	", time_format('yyyy/mm/dd', $some_time), "\n";
	print "POSIXish: ", time_strftime('%A %B %d, %Y',$some_time), "\n";
	print "Date::Manip: ", time_manip('%m/%d/%Y',$some_time), "\n";

       This module creates global pseudovariables which	format dates and
       times, according	to formatting codes you	pass to	them in	strings.

       The %time formatting codes are designed to be easy to remember and use,
       and to take up just as many characters as the output time value
       whenever	possible.  For example,	the four-digit year code is ""yyyy"",
       the three-letter	month abbreviation is ""Mon"".

       The nice	thing about having a variable-like interface instead of
       function	calls is that the values can be	used inside of strings (as
       well as outside of strings in ordinary expressions).  Dates are
       frequently used within strings (log messages, output, data records,
       etc.), so having	the ability to interpolate them	directly is handy.

       Perl allows arbitrary expressions within	curly braces of	a hash,	even
       when that hash is being interpolated into a string.  This allows	you to
       do computations on the fly while	formatting times and inserting them
       into strings.  See the "yesterday" example above.

       The format strings are designed with programmers	in mind.  What do you
       need most frequently?  4-digit year, month, day,	24-based hour, minute,
       second -- usually with leading zeroes.  These six are the easiest
       formats to use and remember in Time::Format: "yyyy", "mm", "dd",	"hh",
       "mm", "ss".  Variants on	these formats follow a simple and consistent
       formula.	 This module is	for everyone who is weary of trying to
       remember	strftime(3)'s arcane codes, or of endlessly writing "$t[4]++;
       $t[5]+=1900" as you manually format times or dates.

       Note that "mm" (and related codes) are used both	for months and
       minutes.	 This is a feature.  %time resolves the	ambiguity by examining
       other nearby formatting codes.  If it's in the context of a year	or a
       day, "month" is assumed.	 If in the context of an hour or a second,
       "minute"	is assumed.

       The format strings are not meant	to encompass every date/time need ever
       conceived.  But how often do you	need the day of	the year (strftime's
       %j) or the week number (strftime's %W)?

       For capabilities	that %time does	not provide, %strftime provides	an
       interface to POSIX's "strftime",	and %manip provides an interface to
       the Date::Manip module's	"UnixDate" function.

       If the companion	module Time::Format_XS is also installed, Time::Format
       will detect and use it.	This will result in a significant speed
       increase	for %time and "time_format".


	   Formats a unix time number (seconds since the epoch), DateTime
	   object, stringified DateTime, Date::Manip string, or	ISO-8601
	   string, according to	the specified format.  If the time expression
	   is omitted, the current time	is used.  The format string may
	   contain any of the following:

	       yyyy	  4-digit year
	       yy	  2-digit year

	       m	  1- or	2-digit	month, 1-12
	       mm	  2-digit month, 01-12
	       ?m	  month	with leading space if <	10

	       Month	  full month name, mixed-case
	       MONTH	  full month name, uppercase
	       month	  full month name, lowercase
	       Mon	  3-letter month abbreviation, mixed-case
	       MON  mon	  ditto, uppercase and lowercase versions

	       d	  day number, 1-31
	       dd	  day number, 01-31
	       ?d	  day with leading space if < 10
	       th	  day suffix (st, nd, rd, or th)
	       TH	  uppercase suffix

	       Weekday	  weekday name,	mixed-case
	       WEEKDAY	  weekday name,	uppercase
	       weekday	  weekday name,	lowercase
	       Day	  3-letter weekday name, mixed-case
	       DAY  day	  ditto, uppercase and lowercase versions

	       h	  hour,	0-23
	       hh	  hour,	00-23
	       ?h	  hour,	0-23 with leading space	if < 10

	       H	  hour,	1-12
	       HH	  hour,	01-12
	       ?H	  hour,	1-12 with leading space	if < 10

	       m	  minute, 0-59
	       mm	  minute, 00-59
	       ?m	  minute, 0-59 with leading space if < 10

	       s	  second, 0-59
	       ss	  second, 00-59
	       ?s	  second, 0-59 with leading space if < 10
	       mmm	  millisecond, 000-999
	       uuuuuu	  microsecond, 000000-999999

	       am   a.m.  The string "am" or "pm" (second form with periods)
	       pm   p.m.  same as "am" or "a.m."
	       AM   A.M.  same as "am" or "a.m." but uppercase
	       PM   P.M.  same as "AM" or "A.M."

	       tz	  time zone abbreviation

	   Millisecond and microsecond require Time::HiRes, otherwise they'll
	   always be zero.  Timezone requires POSIX, otherwise it'll be	the
	   empty string.  The second codes ("s", "ss", "?s") can be 60 or 61
	   in rare circumstances (leap seconds,	if your	system supports	such).

	   Anything in the format string other than the	above patterns is left
	   intact.  Any	character preceded by a	backslash is left alone	and
	   not used for	any part of a format code.  See	the "QUOTING" section
	   for more details.

	   For the most	part, each of the above	formatting codes takes up as
	   much	space as the output string it generates.  The exceptions are
	   the codes whose output is variable length: "Weekday", "Month", time
	   zone, and the single-character codes.

	   The mixed-case "Month", "Mon", "Weekday", and "Day" codes return
	   the name of the month or weekday in the preferred case
	   representation for the locale currently in effect.  Thus in an
	   English-speaking locale, the	seventh	month would be "July"
	   (uppercase first letter, lowercase rest); while in a	French-
	   speaking locale, it would be	"juillet" (all lowercase).  See	the
	   "QUOTING" section for ways to control the case of month/weekday

	   Note	that the ""mm"", ""m"",	and ""?m"" formats are ambiguous.
	   %time tries to guess	whether	you meant "month" or "minute" based on
	   nearby characters in	the format string.  Thus, a format of
	   ""yyyy/mm/dd	hh:mm:ss"" is correctly	parsed as "year	month day,
	   hour	minute second".	 If %time cannot determine whether you meant
	   "month" or "minute",	it leaves the "mm", "m", or "?m" untranslated.
	   To remove the ambiguity, you	can use	the following codes:

	       m{on}	    month, 1-12
	       mm{on}	    month, 01-12
	       ?m{on}	    month, 1-12	with leading space if <	10

	       m{in}	    minute, 0-59
	       mm{in}	    minute, 00-59
	       ?m{in}	    minute, 0-59 with leading space if < 10

	   In other words, append ""{on}"" or ""{in}"" to make ""m"", ""mm"",
	   or ""?m"" unambiguous.

	    $strftime{$format, $sec,$min,$hour,	$mday,$mon,$year, $wday,$yday,$isdst}
	    $strftime{$format, $unixtime}

	   For those who prefer	strftime's weird % formats, or who need	POSIX
	   compliance, or who need week	numbers	or other features %time	does
	   not provide.


	   Provides an interface to the	Date::Manip module's "UnixDate"
	   function.  This function is rather slow, but	can parse a very wide
	   variety of date input.  See the Date::Manip module for details
	   about the inputs accepted.

	   If you want to use the %time	codes, but need	the input flexibility
	   of %manip, you can use Date::Manip's	"ParseDate" function:

	    print "$time{'yyyymmdd', ParseDate('last sunday')}";

	    time_format($format, $unix_time);

	   This	is a function interface	to %time.  It accepts the same
	   formatting codes and	everything.  This is provided for people who
	   want	their function calls to	look like function calls, not hashes.
	   :-) The following two are equivalent:

	    $x = $time{'yyyy/mm/dd'};
	    $x = time_format('yyyy/mm/dd');

	    time_strftime($format, $sec,$min,$hour, $mday,$mon,$year, $wday,$yday,$isdst);
	    time_strftime($format, $unixtime);

	   This	is a function interface	to %strftime.  It simply calls
	   POSIX::"strftime", but it does provide a bit	of an advantage	over
	   calling "strftime" directly,	in that	you can	pass the time as a
	   unix	time (seconds since the	epoch),	or omit	it in order to get the
	   current time.


	   This	is a function interface	to %manip.  It calls
	   Date::Manip::"UnixDate" under the hood.  It does not	provide	much
	   of an advantage over	calling	"UnixDate" directly, except that you
	   can omit the	$when parameter	in order to get	the current time.

       This section applies to the format strings used by %time	and
       "time_format" only.

       Sometimes it is necessary to suppress expansion of some format
       characters in a format string.  For example:

	   $time{'Hour:	hh; Minute: mm{in}; Second: ss'};

       In the above expression,	the "H"	in "Hour" would	be expanded, as	would
       the "d" in "Second".  The result	would be something like:

	   8our: 08; Minute: 10; Secon17: 30

       It would	not be a good solution to break	the above statement out	into
       three calls to %time:

	   "Hour: $time{hh}; Minute: $time{'mm{in}'}; Second: $time{ss}"

       because the time	could change from one call to the next,	which would be
       a problem when the numbers roll over (for example, a split second after

       For this	reason,	you can	escape individual format codes with a

	   $time{'\Hour: hh; Minute: mm{in}; Secon\d: ss'};

       Note that with double-quoted (and qq//) strings,	the backslash must be
       doubled,	because	Perl first interpolates	the string:

	   $time{"\\Hour: hh; Minute: mm{in}; Secon\\d:	ss"};

       For added convenience, Time::Format simulates Perl's built-in \Q	and \E
       inline quoting operators.  Anything in a	string between a \Q and	\E
       will not	be interpolated	as any part of any formatting code:

	   $time{'\QHour:\E hh;	\QMinute:\E mm{in}; \QSecond:\E	ss'};

       Again, within interpolated strings, the backslash must be doubled, or
       else Perl will interpret	and remove the \Q...\E sequence	before
       Time::Format gets it:

	   $time{"\\QHour:\\E hh; \\QMinute:\\E	mm{in};	\\QSecond\\E: ss"};

       Time::Format also recognizes and	simulates the \U, \L, \u, and \l
       sequences.  This	is really only useful for finer	control	of the Month,
       Mon, Weekday, and Day formats.  For example, in some locales, the month
       names are all-lowercase by convention.  At the start of a sentence, you
       may want	to ensure that the first character is uppercase:

	   $time{'\uMonth \Qis the finest month	of all.'};

       Again, be sure to use \Q, and be	sure to	double the backslashes in
       interpolated strings, otherwise you'll get something ugly like:

	   July	i37 ste	fine37t	july of	all.

	$time{'Weekday Month d,	yyyy'}	 Thursday June 5, 2003
	$time{'Day Mon d, yyyy'}	 Thu Jun 5, 2003
	$time{'dd/mm/yyyy'}		 05/06/2003
	$time{yymmdd}			 030605
	$time{'yymmdd',time-86400}	 030604
	$time{'dth of Month'}		 5th of	June

	$time{'H:mm:ss am'}		 1:02:14 pm
	$time{'hh:mm:ss.uuuuuu'}	 13:02:14.171447

	$time{'yyyy/mm{on}/dd hh:mm{in}:ss.mmm'}  2003/06/05 13:02:14.171
	$time{'yyyy/mm/dd hh:mm:ss.mmm'}	  2003/06/05 13:02:14.171

	$time{"It's H:mm."}		 It'14 1:02.	# OOPS!
	$time{"It'\\s H:mm."}		 It's 1:02.	# Backslash fixes it.
	# Rename a file	based on today's date:
	rename $file, "$file_$time{yyyymmdd}";

	# Rename a file	based on its last-modify date:
	rename $file, "$file_$time{'yyyymmdd',(stat $file)[9]}";

	# stftime examples
	$strftime{'%A %B %d, %Y'}		  Thursday June	05, 2003
	$strftime{'%A %B %d, %Y',time+86400}	  Friday June 06, 2003

	# manip	examples
	$manip{'%m/%d/%Y'}				     06/05/2003
	$manip{'%m/%d/%Y','yesterday'}			     06/04/2003
	$manip{'%m/%d/%Y','first monday	in November 2000'}   11/06/2000

       If the I18N::Langinfo module is available, Time::Format will return
       weekday and month names in the language appropriate for the current
       locale.	If not,	English	names will be used.

       Programmers in non-English locales may want to provide an alias to
       %time in	their own preferred language.  This can	be done	by assigning
       "\%time"	to a typeglob:

	   # French
	   use Time::Format;
	   use vars '%temps';  *temps =	\%time;
	   print "C'est	aujourd'hui le $temps{'d Month'}\n";

	   # German
	   use Time::Format;
	   use vars '%zeit';   *zeit = \%time;
	   print "Heutiger Tag ist $zeit{'d.m.yyyy'}\n";

       The following symbols are exported into your namespace by default:


       The following symbols are available for import into your	namespace:


       The ":all" tag will import all of these into your namespace.  Example:

	use Time::Format ':all';

       The format string used by %time must not	have $;	as a substring
       anywhere.  $; (by default, ASCII	character 28, or 1C hex) is used to
       separate	values passed to the tied hash,	and thus Time::Format will
       interpret your format string to be two or more arguments	if it contains
       $;.  The	"time_format" function does not	have this limitation.

	I18N::Langinfo,	if you want non-English	locales	to work.
	POSIX, if you choose to	use %strftime or want the C<tz>	format to work.
	Time::HiRes, if	you want the C<mmm> and	C<uuuuuu> time formats to work.
	Date::Manip, if	you choose to use %manip.

	Time::Format_XS	is optional but	will make C<%time> and C<time_format>
	    much faster.  The version of Time::Format_XS installed must	match
	    the	version	of Time::Format	installed; otherwise Time::Format will
	    not	use it (and will issue a warning).

       Copyright A(C) 2003-2012	by Eric	J. Roode, ROODE	-at- cpan -dot-	org

       All rights reserved.

       To avoid	my spam	filter,	please include "Perl", "module", or this
       module's	name in	the message's subject line, and/or GPG-sign your

       This module is copyrighted only to ensure proper	attribution of
       authorship and to ensure	that it	remains	available to all.  This	module
       is free,	open-source software.  This module may be freely used for any
       purpose,	commercial, public, or private,	provided that proper credit is
       given, and that no more-restrictive license is applied to derivative
       (not dependent) works.

       Substantial efforts have	been made to ensure that this software meets
       high quality standards; however,	no guarantee can be made that there
       are no undiscovered bugs, and no	warranty is made as to suitability to
       any given use, including	merchantability.  Should this module cause
       your house to burn down,	your dog to collapse, your heart-lung machine
       to fail,	your spouse to desert you, or George Bush to be	re-elected, I
       can offer only my sincere sympathy and apologies, and promise to
       endeavor	to improve the software.

perl v5.32.1			  2012-09-27		       Time::Format(3)


Want to link to this manual page? Use this URL:

home | help