Provided by: librose-datetime-perl_0.540-2_all bug

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

           •   %a

               The abbreviated weekday name.

           •   %A

               The full weekday name.

           •   %b

               The abbreviated month name.

           •   %B

               The full month name.

           •   %c

               The default datetime format for the object's locale.

           •   %C

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

           •   %d

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

           •   %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!

           •   %e

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

           •   %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)

           •   %g

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

           •   %h

               Equivalent to %b.

           •   %H

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

           •   %I

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

           •   %j

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

           •   %k

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

           •   %l

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

           •   %m

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

           •   %M

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

           •   %n

               A newline character.

           •   %N

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

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

           •   %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'.

           •   %P

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

           •   %r

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

           •   %R

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

           •   %s

               The number of seconds since the epoch.

           •   %S

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

           •   %T

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

           •   %u

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

           •   %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.

           •   %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.

           •   %w

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

           •   %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.

           •   %x

               The default date format for the object's locale.

           •   %X

               The default time format for the object's locale.

           •   %y

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

           •   %Y

               The year as a decimal number including the century.

           •   %z

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

           •   %Z

               The time zone or name or abbreviation.

           •   %%

               A literal `%' character.

           •   %{method}

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

           Non-standard formats

           •   %E

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

           •   %f

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

           •   %F

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

           •   %i

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

           •   %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.