/ 
Maplat-0.92
River stage zero No dependents
/ Maplat::Helpers::DateStrings

NAME

Maplat::Helpers::DateStrings - generation and parsing of common date strings

SYNOPSIS

use Maplat::Helpers::DateStrings;

my $datestring = getISODate();
my $datestring = getISODate_nDaysOffset($days);
my $datestring = getFileDate();
my $datestring = getShortFiledate();
my $datestring = getUniqueFileDate();
my $datestring = getCurrentHour();
my $datestring = getCurrentDay();
my ($date, $time) = getDateAndTime();
my $isodate = parseNaturalDate($naturalDate);
my $datestring = fixDateField($brokendate);

DESCRIPTION

This module provides a host of date functions required in commercial environments. Most of them return the current date in some form or other, while at least one of them (getUniqueFileDate) cheats when it has to.

getISODate()

Returns the current date and time in the short ISO format with space instead of "T" as delimeter betweeen date and time, e.g.

"$year-$mon-$mday $hour:$min:$sec"

getISODate_nDaysOffset($offset)

Similar to getISODate, but offsets the date with the given number of days.

getFileDate()

Returns the date and time in a format suiteable for filenames, e.g.:

"$year$mon$mday$hour$min$sec"

getShortFiledate()

Returns only the current date (without time) in a format suiteable for filenames, e.g.:

"$year$mon$mday"

getUniqueFileDate()

Returns the date and time in the same format as getFileDate, with one exception: It cheats.

Only one unique filedate can naturally produced per second in this format, so the seconds are actually a counter that resets at when the minute value changes. Seconds don't even end at 59, they run to 99. If the counter reaches 99, the function waits till the minute marker changes.

This function may or not be useless to you, i needed it for communication with legacy software that expects the filename to start with a filedate string, which must be unique but doesn't check if the seconds are valid. My software produced the data files in bursts with about 20-80 files per second. If you don't have similar requirements, you're better of using getFileDate() instead.

getCurrentHour()

A bit of a misnomer. This function returns a date string thats exact to the hour, e.g.:

"$year$mon$mday$hour"

This is quite usefull to check if the hour changed since your last check, something like this:

my $hour = "";
sub cyclicFuntion {
  my $newhour = getCurrentHour();
  if($newhour ne $hour) {
    # Do some cyclic job at the start of every hour
    ...
    $hour = $newhour;
  }
}

Checking the full string instead of only the hour value makes it possible to start correctly even if the program somehow skipped some 23 odd hours.

getCurrentDay()

Very similar to getCurrentHour(), except it is only accurate to the day, e.g.:

"$year$mon$mday"

getDateAndTime()

Similar to getISODate, except it returns an array with two values, the date and time:

my @date = getDateAndTime();
print $date[0]; # Date
print $date[1]; # Time

Altough you might prefer to use it in a proper list context in the first place:

my ($date, $time) = getDateAndTime();

parseNaturalDate($datetext)

This function provides a bit of "magic date/time string parsing".

If you give it an ISO date or something similar, it just pretty-prints it to the same format as getISODate().

But you can also supply it with date "descriptions", for example:

"tomorrow morning"
"sunday night"
"new years eve afternoon"
"renes birthday morning" (The authors birthday, which is 9th of November)
"now"

The values of morning, afternoon and evening are currently hardcoded to "06:00", "14:00", and "22:00" respectively (the workshift model my employer uses). You can also add a "pre" to the timestring which takes off 15 minutes, for example "premorning" meaning "05:45"

fixDateField($datestring)

For easier handling, some Maplat tables have date fields ("timestamp without timezone" to be precise) that are NOT NULL and have a default of "1970-01-01 23:59:59".

For display on the web interface, all dates get parsed through this function, default dates are replaced by empty strings. Also, the datestring is trimmed of unnessecary whitespace.

AUTHOR

Rene Schickbauer, <rene.schickbauer@magnapowertrain.com>

COPYRIGHT AND LICENSE

Copyright (C) 2009 by Rene Schickbauer

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.