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

FreeBSD Manual Pages

  
 
  

home | help
Rose::DateTime::Util(3User Contributed Perl DocumentatiRose::DateTime::Util(3)

NAME
       Rose::DateTime::Util - Some simple DateTime wrapper functions.

SYNOPSIS
	   use Rose::DateTime::Util qw(:all);

	   $now	 = parse_date('now');
	   $then = parse_date('12/25/2001 11pm');

	   print $now->day_of_week; # e.g., "Monday"

	   # "December 25th 2001 at 11:00:00 PM"
	   $date_text =	format_date($then, "%B %E %Y at	%t");

DESCRIPTION
       Rose::DateTime::Util is a thin wrapper around DateTime that provides a
       very simple date	parser and a few extra date formatting options.

EXPORTS
       Rose::DateTime::Util does not export any	function names by default.

       The 'all' tag:

	   use Rose::DateTime::Util qw(:all);

       will cause the following	function names to be imported:

	   format_date()
	   parse_date()
	   parse_epoch()
	   parse_european_date()

CLASS METHODS
       error
	   Returns a message describing	the last error that occurred.

       european_dates [BOOL]
	   Get or set a	boolean	flag that determines how "xx/xx/xxxx" dates
	   are parsed by the parse_date	function.  If set to a false-but-
	   defined value, then such dates are parsed as	"mm/dd/yyyy".  If set
	   to true, then they're parsed	as "dd/mm/yyyy".  If set to undef,
	   then	the attribute resets to	its initial value, which is determined
	   as described	below.

	   The initial value of	this attribute is chosen based on the current
	   locale as stored in DateTime's DefaultLocale	setting.  This
	   initial value is looked up only once.  Any subsequent changes to
	   DateTime's DefaultLocale setting will be ignored until/unless this
	   attribute is	reset to undef.

       time_zone [TZ]
	   Get or set the default time zone.  This value is passed to
	   DateTime->new(...) as the value of the "time_zone" parameter	when
	   parse_date()	creates	the DateTime object that it returns. The
	   default value is "floating".

FUNCTIONS
       format_date DATETIME, FORMAT1, FORMAT2 ...
	   Takes a DateTime object and a list of format	strings.  In list
	   context, it returns a list of strings with the formats
	   interpolated.  In scalar context, it	returns	a single string
	   constructed by joining all of the list-context return values	with
	   single spaces.  Examples:

	     # $s = 'Friday 5PM'
	     $s	= format_date(parse_date('1/23/2004 17:00'), '%A, %I%p');

	     # @s = ('Friday', 5, 'PM')
	     @s	= format_date(parse_date('1/23/2004 17:00'), '%A', '%I', '%p');

	     # $s = 'Friday 5 PM'
	     $s	= format_date(parse_date('1/23/2004 17:00'), '%A', '%I', '%p');

	   Returns undef on failure, or	if passed an undefined value for
	   DATETIME.  An exception will	be raised if the DATETIME argument is
	   defined, but	is not a DateTime object.

	   The supported formats are mostly based on those supported by
	   DateTime's "strftime()" method.  Rose::DateTime::Util calls
	   DateTime's "strftime()" method when interpolating these formats.

	   Note	that the %t and	%F formats are not passed to "strftime()", but
	   are handled by Rose::DateTime::Util instead.	 See the "Non-standard
	   formats" section below.

	   The "strftime()"-compatible formats listed below have been
	   transcribed from the	DateTime documentation for the sake of
	   convenience,	but the	DateTime documentation is the definitive
	   source.

	   Using any format strings not	in the "strftime()"-compatible set
	   will	be slightly slower.

	   "strftime()"-compatible formats

	   o   %a

	       The abbreviated weekday name.

	   o   %A

	       The full	weekday	name.

	   o   %b

	       The abbreviated month name.

	   o   %B

	       The full	month name.

	   o   %c

	       The default datetime format for the object's locale.

	   o   %C

	       The century number (year/100) as	a 2-digit integer.

	   o   %d

	       The day of the month as a decimal number	(range 01 to 31).

	   o   %D

	       Equivalent to %m/%d/%y.	This is	not a good standard format if
	       you have	want both Americans and	Europeans to understand	the
	       date!

	   o   %e

	       Like %d,	the day	of the month as	a decimal number, but a
	       leading zero is replaced	by a space.

	   o   %G

	       The ISO 8601 year with century as a decimal number.  The
	       4-digit year corresponding to the ISO week number (see %V).
	       This has	the same format	and value as %y, except	that if	the
	       ISO week	number belongs to the previous or next year, that year
	       is used instead.	(TZ)

	   o   %g

	       Like %G,	but without century, i.e., with	a 2-digit year
	       (00-99).

	   o   %h

	       Equivalent to %b.

	   o   %H

	       The hour	as a decimal number using a 24-hour clock (range 00 to
	       23).

	   o   %I

	       The hour	as a decimal number using a 12-hour clock (range 01 to
	       12).

	   o   %j

	       The day of the year as a	decimal	number (range 001 to 366).

	   o   %k

	       The hour	(24-hour clock)	as a decimal number (range 0 to	23);
	       single digits are preceded by a blank. (See also	%H.)

	   o   %l

	       The hour	(12-hour clock)	as a decimal number (range 1 to	12);
	       single digits are preceded by a blank. (See also	%I.)

	   o   %m

	       The month as a decimal number (range 01 to 12).

	   o   %M

	       The minute as a decimal number (range 00	to 59).

	   o   %n

	       A newline character.

	   o   %N

	       The fractional seconds digits. Default is 9 digits
	       (nanoseconds).

		 %3N   milliseconds (3 digits)
		 %6N   microseconds (6 digits)
		 %9N   nanoseconds  (9 digits)

	   o   %p

	       Either `AM' or `PM' according to	the given time value, or the
	       corresponding strings for the current locale.  Noon is treated
	       as `pm' and midnight as `am'.

	   o   %P

	       Like %p but in lowercase: `am' or `pm' or a corresponding
	       string for the current locale.

	   o   %r

	       The time	in a.m.	 or p.m. notation.  In the POSIX locale	this
	       is equivalent to	`%I:%M:%S %p'.

	   o   %R

	       The time	in 24-hour notation (%H:%M). (SU) For a	version
	       including the seconds, see %T below.

	   o   %s

	       The number of seconds since the epoch.

	   o   %S

	       The second as a decimal number (range 00	to 61).

	   o   %T

	       The time	in 24-hour notation (%H:%M:%S).

	   o   %u

	       The day of the week as a	decimal, range 1 to 7, Monday being 1.
	       See also	%w.

	   o   %U

	       The week	number of the current year as a	decimal	number,	range
	       00 to 53, starting with the first Sunday	as the first day of
	       week 01.	See also %V and	%W.

	   o   %V

	       The ISO 8601:1988 week number of	the current year as a decimal
	       number, range 01	to 53, where week 1 is the first week that has
	       at least	4 days in the current year, and	with Monday as the
	       first day of the	week. See also %U and %W.

	   o   %w

	       The day of the week as a	decimal, range 0 to 6, Sunday being 0.
	       See also	%u.

	   o   %W

	       The week	number of the current year as a	decimal	number,	range
	       00 to 53, starting with the first Monday	as the first day of
	       week 01.

	   o   %x

	       The default date	format for the object's	locale.

	   o   %X

	       The default time	format for the object's	locale.

	   o   %y

	       The year	as a decimal number without a century (range 00	to
	       99).

	   o   %Y

	       The year	as a decimal number including the century.

	   o   %z

	       The time-zone as	hour offset from UTC.  Required	to emit
	       RFC822-conformant dates (using "%a, %d %b %Y %H:%M:%S %z").

	   o   %Z

	       The time	zone or	name or	abbreviation.

	   o   %%

	       A literal `%' character.

	   o   %{method}

	       Any method name may be specified	using the format "%{method}"
	       name where "method" is a	valid DateTime object method.

	   Non-standard	formats

	   o   %E

	       Day of the month	word (1st, 2nd,	3rd, ... 31st)

	   o   %f

	       Month number (1,	2, 3, ... 12)

	   o   %F

	       "%A, %B %E %Y" (Wednesday, April	4th 2001)

	   o   %i

	       Hour, 12-hour (1, 2, 3, ... 12)

	   o   %t

	       Time as "%l:%M:%S %p" (1:23:45 PM)

       parse_european_date TEXT	[, TIMEZONE]
	   This	function works the same	as the parse_date function, except it
	   forces Eurpoean-style date parsing.	In other words,	this:

	       parse_european_date($date, $tz);

	   is equivalent to this:

	       # Save old value	of the European	date setting
	       my $save	= Rose::DateTime::Util->european_dates;

	       # Turn European date parsing on
	       Rose::DateTime::Util->european_dates(1);

	       # Parse the date
	       parse_date($date, $tz);

	       # Restore the old European date setting
	       Rose::DateTime::Util->european_dates($save);

       parse_date TEXT [, TIMEZONE]
	   Attempts to parse the date described	by TEXT.  Returns a DateTime
	   object, or undef on failure,	with an	error message available	via
	   Rose::DateTime::Util->error().

	   If a	DateTime object	is passed in place of the TEXT argument, it is
	   returned as-is if there is no TIMEZONE argument, or after having
	   set_time_zone(TIMEZONE) called on it	if there is a TIMEZONE
	   argument.

	   Since the time zone is not part of any of the supported date	string
	   formats, parse_date() takes an optional TIMEZONE argument which is
	   passed to the DateTime constructor as the value of the "time_zone"
	   parameter.  In the absence of a TIMEZONE argument to
	   "parwse_date()", the	time zone defaults to the value	returned by
	   the time_zone() class method	("floating", by	default)

	   The formats understood and their interpretations are	listed below.
	   Square brackets are used to indicate	optional portions of the
	   formats.

	   now Right now.  Also	valid with an exclamation point: "now!"

	   today
	       Today, at 00:00:00.

	   yyyy	mm dd
	   yyyy	mm dd [hh? am/pm]
	   yyyy	mm dd [hh?:mm [am/pm]]
	   yyyy	mm dd [hh?:mm:ss [am/pm]]
	   yyyy	mm dd [hh?:mm:ss.nnnnnnnnn [am/pm]]
	       Exact date and time.  Also valid	without	spaces,	with hyphens
	       ("-"), periods ("."), or	underscores ("_") between the year,
	       month, and day, and with	a "T", hyphen, period, or underscore
	       between the date	and time.  The time is optional	and defaults
	       to 00:00:00.  The am/pm part is optional	unless only the	"hh"
	       (hours) part of the time	is specified.  Fractional seconds take
	       a maximum of 9 digits, but fewer	are also acceptable.

	   mm/dd/yyyy [hh[:mm[:ss[.nnnnnnnnn]]]] [am/pm]
	       Exact date and time.  Also valid	with hyphens ("-"), periods
	       ("."), or underscores ("_") instead of slashes ("/"), and with
	       a "T", hyphen, period, or underscore between the	date and time.
	       The time	is optional and	defaults to 00:00:00.  The am/pm part
	       is optional.  Fractional	seconds	take a maximum of 9 digits,
	       but fewer are also acceptable.

	       This format is only valid when european_dates is	set to false
	       (which is the default).

	   dd/mm/yyyy [hh[:mm[:ss[.nnnnnnnnn]]]] [am/pm]
	       Exact date and time.  Also valid	with hyphens ("-"), periods
	       ("."), or underscores ("_") instead of slashes ("/").  The time
	       is optional and defaults	to 00:00:00.  The am/pm	part is
	       optional.  Fractional seconds take a maximum of 9 digits, but
	       fewer are also acceptable.

	       This format is only valid when european_dates is	set to true.

	   [-]infinity
	       Positive	or negative infinity.  Case insensitive.

	   [-]dddddddddd[.nnnnnnnnn] seconds)
	       A positive or negative number with optional fractional seconds
	       is interpreted as seconds since the Unix	epoch.	Fractional
	       seconds take a maximum of 9 digits, but fewer are also
	       acceptable.

       parse_epoch TEXT	[, TIMEZONE]
	   This	function is the	same as	parse_date except that it prefers Unix
	   epoch values	in cases where this format conflicts with another.
	   Example:

	       $arg = '19991231';

	       $dt = parse_date($arg);	# Dec 31, 1999
	       $dt = parse_epoch($arg);	# Aug 20, 1970

SEE ALSO
       DateTime, DateTime::TimeZone

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.32.1			  2013-12-08	       Rose::DateTime::Util(3)

NAME | SYNOPSIS | DESCRIPTION | EXPORTS | CLASS METHODS | FUNCTIONS | SEE ALSO | AUTHOR | LICENSE

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

home | help