Pitonyak::DateUtil - Format and convert Time/Date strings


use Pitonyak::DateUtil;


A time is formatted based on a format string. The number of times that a special character exists indicates the number of digits that will be used. The format character 'YYYYMMDD.hhmmss' yields a four digit year, two digit month, two digit day, a period, two digit hour, etc... Characters that are not considered special are inserted verbatim. Characters that are escaped with a backslash '\' are also inserted verbatim. Use '\\' to insert a backslash.

The special format characters are as follows:

h = hour (0-24)
m = minute (0-59)
s = second (0-59)
Y = year

In Perl, the earliest year is 1900.

M = Month (1-12)

Perl uses (0-11)


I really should allow these to be in other languages as well.

y = year day (0-364)
D = month day (0-30)
w = week day (1=Sunday, ..., 7=Saturday)

Perl uses (0=Sunday, ... , 6=Saturday)


Convert time and date information between different formats. This can convert between text representations and an integer.


time_date_str($format_string, [$time_integer])

Ignoring the time to make the call, both of the following calls are equivalent.

time_date_str($format_string); time_date_str($format_string, time());

This will return a formatted string with the specified time.


invert_time_date_str($format_string, $formatted_time_date_string)

Convert a formatted time/date string to the same output as timelocal().

returns ($sec, $min, $hours, $mday, $mon, $year) where the $year will be -1 on error. December is mapped to 11 and the year 1900 is mapped to 0. One digit years are always mapped to 200y and two digit years are windowed so that 00-79 map to 20xx and 80-99 map to 19xx. Three digit years are obvious


time_date_str_to_int($format_string, $formatted_time_date_string)

Convert a formatted time/date string to an integer. -1 is returned on error. The integer can be used as input to other routines.


change_time_date_str($desired_format, $current_format, $formatted_time_date_string)

Change a formatted time/date string to a different format.

This is nothing more than a shortcut to using time_date_str($desired_format, time_date_str_to_int($current_format, $formatted_time_date_string));


Return a date object corresponding to a specified instance of a specific week day in a given year and month.

change_time_date_str($year, $month, $day_of_month, $instance)

An example is worth a thousand words. The call change_time_date_str(2007, 3, 1, 2) returns the second monday in March 2007. The day of the month must be in the range 0=Sunday to 6=Saturday. No error checking is performed to verify that there are two Mondays in March.


Convert a date/time string in EST to a date/time string in UTC.

est_str_to_utc_str($date_time, $input_fmt, $output_fmt)



Return 1 if the specified date/time value is during daylight savings time in EST. most of the U.S. will begin Daylight Saving Time at 2:00 a.m. on the second Sunday in March and revert to standard time on the first Sunday in November. In the U.S., each time zone switches at a different time.

At 2:00 AM on the second Sunday in March, the time immediately turns into 3:00 AM. It is, therefore, easy to determine if these times use DST. It is more difficult to determine when the time ends. Times from 1:00 AM until 2:00 AM are repeated, which is a very real problem. Luckily, this routine is based on the number of seconds since a specific point in time.


Copyright 1998-2007, Andrew Pitonyak

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Modification History

March 13, 1998

Version 1.00 First release

September 10, 2002

Version 1.01 Changed internal documentation to POD documentation. Added parameter checking.