Provided by: libtime-format-perl_1.16-2_all bug

NAME

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

VERSION

       This is version 1.16 of Time::Format, February 19, 2020.

SYNOPSIS

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

        $time{$format}
        $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}
        $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};
        $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";

DESCRIPTION

       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".

VARIABLES

       time
            $time{$format}
            $time{$format,$time_value};

           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
           names.

           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
            $strftime{$format, $sec,$min,$hour, $mday,$mon,$year, $wday,$yday,$isdst}
            $strftime{$format, $unixtime}
            $strftime{$format}

           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.

       manip
            $manip{$format};
            $manip{$format,$when};

           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')}";

FUNCTIONS

       time_format
            time_format($format);
            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
            time_strftime($format, $sec,$min,$hour, $mday,$mon,$year, $wday,$yday,$isdst);
            time_strftime($format, $unixtime);
            time_strftime($format);

           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.

       time_manip
            manip($format);
            manip($format,$when);

           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.

QUOTING

       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 7:59:59).

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

           $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.

EXAMPLES

        $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

INTERNATIONALIZATION

       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";

EXPORTS

       The following symbols are exported into your namespace by default:

        %time
        time_format

       The following symbols are available for import into your namespace:

        %strftime
        %manip
        time_strftime
        time_manip

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

        use Time::Format ':all';

LIMITATIONS

       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.

REQUIREMENTS

        Time::Local
        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).

AUTHOR / COPYRIGHT

       Copyright (c) 2003-2020 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 message.

       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.