The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Time-Normalize-0.02
River stage zero No dependents
++
/ Time::Normalize

NAME

Time::Normalize - Convert time and date values into standardized components.

VERSION

This is version 0.02 of Normalize.pm, December 2, 2005.

SYNOPSIS

 use Time::Normalize;

 $hashref = normalize_ymd ($in_yr, $in_mo, $in_d);
 ($year, $mon, $day,
  $dow, $dow_name, $dow_abbr,
  $mon_name, $mon_abbr) = normalize_ymd ($in_yr, $in_mo, $in_dy);

 $hashref = normalize_hms ($in_h, $in_m, $in_s, $in_ampm);
 ($hour, $min, $sec,
  $h12, $ampm, $since_midnight)
          = normalize_hms ($in_h, $in_m, $in_s, $in_ampm);

 $hashref = normalize_time ($time_epoch);
 ($sec, $min, $hour,
  $day, $mon, $year,
  $dow, $yday, $isdst,
  $h12, $ampm, $since_midnight,
  $dow_name, $dow_abbr,
  $mon_name, $mon_abbr) = normalize_time ($time_epoch);

 $hashref = normalize_gmtime ($time_epoch);
 @same_values_as_for_normalize_time = normalize_gmtime ($time_epoch);

DESCRIPTION

Splitting a date into its component pieces is just the beginning.

Human date conventions are quirky (and I'm not just talking about the dates I've had!) Despite the Y2K near-disaster, some people continue to use two-digit year numbers. Months are sometimes specified as a number from 1-12, sometimes as a spelled-out name, sometimes as a abbreviation. Some months have more days than others. Humans sometimes use a 12-hour clock, and sometimes a 24-hour clock.

This module performs simple but tedious (and error-prone) checks on its inputs, and returns the time and/or date components in a sanitized, standardized manner, suitable for use in the remainder of your program.

Even when you get your values from a time-tested library function, such as localtime or gmtime, you need to do routine transformations on the returned values. The year returned is off by 1900 (for historical reasons); the month is in the range 0-11; you may want the month name or day of week name instead of numbers. The "normalize_time" function decodes localtime's values into commonly-needed formats.

FUNCTIONS

normalize_ymd
 $hashref = normalize_ymd ($in_yr, $in_mo, $in_d);

 ($year, $mon, $day,
  $dow, $dow_name, $dow_abbr,
  $mon_name, $mon_abbr) = normalize_ymd ($in_yr, $in_mo, $in_dy);

Takes an arbitrary year, month, and day as input, and returns various data elements in a standard, consistent format. The output may be a hash reference or a list of values. If a hash reference is desired, the keys of that hash will be the same as the variable names given in the above synopsis; that is, day, dow, dow_abbr, dow_name, mon, mon_abbr, mon_name, and year.

Input:

The input year may be either two digits or four digits. If two digits, the century is chosen so that the resulting four-digit year is closest to the current calendar year (i.e., within 50 years).

The input month may either be a number from 1 to 12, or a full month name as defined by the current locale, or a month abbreviation as defined by the current locale. If it's a name or abbreviation, case is not significant.

The input day must be a number from 1 to the number of days in the specified month and year.

If any of the input values do not meet the above criteria, an exception will be thrown. See "DIAGNOSTICS".

Output:

year will always be four digits.

month will always be two digits, 01-12.

day will always be two digits 01-31.

dow will be a number from 0 (Sunday) to 6 (Saturday).

dow_name will be the name of the day of the week, as defined by the current locale, in the locale's preferred case.

dow_abbr will be the standard weekday name abbreviation, as defined by the current locale, in the locale's preferred case.

mon_name will be the month name, as defined by the current locale, in the locale's preferred case.

mon_abbr will be the standard month name abbreviation, as defined by the current locale, in the locale's preferred case.

normalize_hms
 $hashref = normalize_hms ($in_h, $in_m, $in_s, $in_ampm);

 ($hour, $min, $sec,
  $h12, $ampm, $since_midnight)
          = normalize_hms ($in_h, $in_m, $in_s, $in_ampm);

Like "normalize_ymd", normalize_hms takes a variety of possible inputs and returns standardized values. As above, the output may be a hash reference or a list of values. If a hash reference is desired, the keys of that hash will be the same as the variable names given in the above synopsis; that is, ampm, h12, hour, min, sec, and since_midnight. Also, a h24 key is provided as a synonym for hour.

Input:

The input hour may either be a 12-hour or a 24-hour time value. If $in_ampm is specified, $in_h is assumed to be on a 12-hour clock, and if $in_ampm is absent, $in_h is assumed to be on a 24-hour clock.

The input minute must be numeric, and must be in the range 0 to 59.

The input second $in_s is optional. If omitted, it defaults to 0. If specified, it must be in the range 0 to 59.

The AM/PM indicator $in_ampm is optional. If specified, it may be any of the following:

   a   am   a.m.  p   pm   p.m.  A   AM   A.M.  P   PM   P.M.

If any of the input values do not meet the above criteria, an exception will be thrown. See "DIAGNOSTICS".

Output:

hour The first output hour will always be on a 24-hour clock, and will always be two digits, 00-23.

min will always be two digits, 00-59.

sec will always be two digits, 00-59.

h12 is the 12-hour clock equivalent of $hour. It is not zero-padded.

ampm will always be either a lowercase 'a' or a lowercase 'p', no matter what format the input AM/PM indicator was, or even if it was omitted.

since_midnight is the number of seconds since midnight represented by this time.

h24 is a key created if you request a hashref as the output; it's a synonym for hour.

normalize_time
 $hashref = normalize_time($time_epoch);

 ($sec, $min, $hour,
  $day, $mon, $year,
  $dow, $yday, $isdst,
  $h12, $ampm, $since_midnight,
  $dow_name, $dow_abbr,
  $mon_name, $mon_abbr) = normalize_time($time_epoch);

Takes a number in the usual perl epoch, passes it to localtime, and transforms the results. If $time_epoch is omitted, the current time is used instead.

The output values (or hash values) are exactly as for "normalize_ymd" and "normalize_hms", above.

normalize_gmtime

Exactly the same as normalize_time, but uses gmtime internally instead of localtime.

DIAGNOSTICS

The functions in this module throw exceptions (that is, they croak) whenever invalid arguments are passed to them. Therefore, it is generally a Good Idea to trap these exceptions with an eval block.

The error messages are meant to be easy to parse, if you need to. There are two kinds of errors thrown: data errors, and programming errors.

Data errors are caused by invalid data values; that is, values that do not conform to the expectations listed above. These messages all look like:

Time::Normalize: Invalid thing: "value"

Programming errors are caused by you--passing the wrong number of parameters to a function. These messages all look like:

Too {many|few} arguments to function_name

EXAMPLES

 $h = normalize_ymd (2005, 'january', 4);
 #
 # Returns:
 #         $h{day}        "04"
 #         $h{dow}        2
 #         $h{dow_abbr}   "Tue"
 #         $h{dow_name}   "Tuesday"
 #         $h{mon}        "01"
 #         $h{mon_abbr}   "Jan"
 #         $h{mon_name}   "January"
 #         $h{year}       2005
 # ------------------------------------------------

 $h = normalize_ymd ('05', 12, 31);
 #
 # Returns:
 #         $h{day}        31
 #         $h{dow}        6
 #         $h{dow_abbr}   "Sat"
 #         $h{dow_name}   "Saturday"
 #         $h{mon}        12
 #         $h{mon_abbr}   "Dec"
 #         $h{mon_name}   "December"
 #         $h{year}       2005
 # ------------------------------------------------

 $h = normalize_ymd (2005, 2, 29);
 #
 # Throws an exception:
 #         Time::Normalize: Invalid day: "29"
 # ------------------------------------------------

 $h = normalize_hms (9, 10, 0, 'AM');
 #
 # Returns:
 #         $h{ampm}       "a"
 #         $h{h12}        9
 #         $h{h24}        "09"
 #         $h{hour}       "09"
 #         $h{min}        10
 #         $h{sec}        "00"
 #         $h{since_midnight}    33000
 # ------------------------------------------------

 $h = normalize_hms (9, 10, undef, 'p.m.');
 #
 # Returns:
 #         $h{ampm}       "p"
 #         $h{h12}        9
 #         $h{h24}        21
 #         $h{hour}       21
 #         $h{min}        10
 #         $h{sec}        "00"
 #         $h{since_midnight}    76200
 # ------------------------------------------------

 $h = normalize_hms (1, 10);
 #
 # Returns:
 #         $h{ampm}       "a"
 #         $h{h12}        1
 #         $h{h24}        "01"
 #         $h{hour}       "01"
 #         $h{min}        10
 #         $h{sec}        "00"
 #         $h{since_midnight}    4200
 # ------------------------------------------------

 $h = normalize_hms (13, 10);
 #
 # Returns:
 #         $h{ampm}       "p"
 #         $h{h12}        1
 #         $h{h24}        13
 #         $h{hour}       13
 #         $h{min}        10
 #         $h{sec}        "00"
 #         $h{since_midnight}    47400
 # ------------------------------------------------

 $h = normalize_hms (13, 10, undef, 'pm');
 #
 # Throws an exception:
 #         Time::Normalize: Invalid hour: "13"
 # ------------------------------------------------

 $h = normalize_gmtime(1131725587);
 #
 # Returns:
 #         $h{ampm}       "p"
 #         $h{sec}        "07",
 #         $h{min}        13,
 #         $h{hour}       16,
 #         $h{day}        11,
 #         $h{mon}        11,
 #         $h{year}       2005,
 #         $h{dow}        5,
 #         $h{yday}       314,
 #         $h{isdst}      0,
 #         $h{h12}        4
 #         $h{ampm}       "p"
 #         $h{since_midnight}        58_387,
 #         $h{dow_name}   "Friday",
 #         $h{dow_abbr}   "Fri",
 #         $h{mon_name}   "November",
 #         $h{mon_abbr}   "Nov",
 # ------------------------------------------------

EXPORTS

This module exports the following symbols into the caller's namespace:

 normalize_ymd
 normalize_hms
 normalize_time
 normalize_gmtime

REQUIREMENTS

This module requires POSIX.

If I18N::Langinfo is available, this module will use it; otherwise, it will use hardcoded English values for month and weekday names.

Test::More is required for the test suite.

SEE ALSO

See Regexp::Common::time for a Regexp::Common plugin that matches nearly any date format imaginable.

BUGS

  • Uses Gregorian rules for computing whether a year is a leap year, no matter how long ago the year was.

NOT A BUG

  • By convention, noon is 12:00 pm; midnight is 12:00 am.

AUTHOR / COPYRIGHT

Eric J. Roode, roode@cpan.org

Copyright (c) 2005 by Eric J. Roode. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

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.