NAME

Newcomen::Util::Time - Date and time related utility functions.

SYNOPSIS

use Newcomen::Util::Time;

# Parse a time string:
my $time = Newcomen::Util::Time::parse_time ($time, $parse_format, $output_format);

DESCRIPTION

This package provides utility functions dealing with dates and times. Note that all functions may be imported into the package using Newcomen::Util::Time:

use Newcomen::Util::List qw( parse_time );

No function is exported by default.

FUNCTIONS

parse_time

Toggle source: parse_time

sub parse_time {

   my $time    = shift;
   my $parse   = shift;
   my $format  = shift;
   my $piece   = Time::Piece -> strptime ($time, $parse);
   my $tz_offs = $piece -> localtime -> tzoffset () -> minutes ();
   my $tz_sign = $tz_offs < 0 ? '-' : '+';
   my $tz_hour = sprintf ('%02d', POSIX::floor (abs ($tz_offs) / 60));
   my $tz_min  = sprintf ('%02d', abs ($tz_offs) - $tz_hour * 60);

   my $result = {

      'year'        => $piece -> year        (),
      'month'       => $piece -> mon         (),
      'day'         => $piece -> mday        (),
      'hour'        => $piece -> hour        (),
      'minute'      => $piece -> min         (),
      'second'      => $piece -> sec         (),
      'day_of_week' => $piece -> day_of_week (),
      'day_of_year' => $piece -> day_of_year (),
      'week'        => $piece -> week        (),
      'month_short' => $piece -> monname     (),
      'month_name'  => $piece -> fullmonth   (),
      'day_short'   => $piece -> wdayname    (),
      'day_name'    => $piece -> fullday     (),
      'is_dst'      => $piece -> isdst       (),
      'epoch'       => $piece -> epoch       (),
      'iso'         => $piece -> datetime    (),

      'offset'      => "$tz_sign$tz_hour:$tz_min",

      'Month'       => sprintf ('%02d', $piece -> mon  ()),
      'Day'         => sprintf ('%02d', $piece -> mday ()),
      'Hour'        => sprintf ('%02d', $piece -> hour ()),
      'Minute'      => sprintf ('%02d', $piece -> min  ()),
      'Second'      => sprintf ('%02d', $piece -> sec  ()),

   };

   $result -> {'string'} = $piece -> strftime ($format) if $format;

   return $result;

}

my $time = parse_time ($time, $parse_format, $output_format);

Expects three parameters: the first one has to be the string to be parsed, the second one the time format specification to be used for parsing the string (see Time::Piece's strptime() method, which is used to parse the string, for more details). The third parameter is optional. If it is provided, it is used as date format specification for Time::Piece's strftime() method, and the result of this is included in the return values.

The function returns a hashref that contains information about the parsed date/time. The keys are: year, month, day, hour, minute, second, day_of_week, day_of_year, week, month_name, month_short, day_name, day_short, is_dst, epoch, iso, Day, Month, Hour, Minute, Second. The values for the keys starting with a capital letter will include a leading zero for values less than ten. The *_short values will contain the abbreviated names, while *_name values will be full names. If the third parameter is used, the value of the reformatted date/time will be available under the key string, otherwise this key is omitted. The key offset will contain the timezone offset in the format <+/-><hours>:<minutes>, e.g. '+04:00', for the local timezone to GMT.

VERSION

This is version 2014052501.

AUTHOR

Stefan Goebel - newcomen {at} subtype {dot} de

COPYRIGHT AND LICENSE

This file is part of Newcomen.

Newcomen is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the license, or (at your option) any later version.

Newcomen is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Newcomen. If not, see <http://www.gnu.org/licenses/>.

Newcomen

Index