view release on metacpan or  search on metacpan

lib/App/datetime.pod  view on Meta::CPAN

#!perl -w
# run this document through perl to check its syntax
use Pod::Checker;
podchecker(\*DATA);
__END__

=head1 NAME

App::datetime - Date and Time Considerations

=head1 INTRODUCTION

Most Enterprise development includes processing of dates and times.
There are many date and time modules on CPAN, and choosing the right
one can be confusing.
There are no special perl data types for dates and times,
so some direction is needed.

The short answer is that we recommend the following
for most common date and time operations.

 Class::Date
 Class::Date::Rel

However, other modules are appropriate in certain circumstances.
So for the longer answer, read on.

=head1 PERL 5 LANGUAGE SUPPORT

The native Perl 5 datetime type is an integer.
It is not different from other integers in any way other than
how it is used.
It represents the number of non-leap seconds since 
January 1, 1970 UTC (the "Epoch" at GMT).  The following internal
Perl function gets the current time.

 $current_time = time;
 $current_time = time();

Other Perl functions that return this "datetime" integer are

 ($dev, $ino, $mode, $nlink, $uid, $gid, $redev, $size,
  $atime, $mtime, $ctime, $blksize, $blocks) = stat($filename);
 ($dev, $ino, $mode, $nlink, $uid, $gid, $redev, $size,
  $atime, $mtime, $ctime, $blksize, $blocks) = lstat($filename);

where $atime, $mtime, and $ctime are the same kind of integers,
representing the access time, modification time, and change time
of a file.

These $time values may be converted to human-readable
form using the following internal perl functions.
(See the "perlfunc" man page for more information.)

 ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = gmtime($time);
 ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime($time);

Furthermore, the current time zone needs to be accessed through
the environment variable, "TZ".

 $timezone = $ENV{TZ};

This leaves the Perl developer with lots of work to do in order to
process dates.

=over

=item * Formatting dates for output

=item * Parsing dates on input

=item * Comparing dates

=item * Date math (addition, subtraction)

=item * Other calendar-specific functions (i.e. holidays, days of week, etc)

=back

Numerous modules have been posted to CPAN allowing the Perl developer
to accomplish these tasks.
However, they have pros and cons related to the
following features.

=over

=item * Internationalization

=item * Speed

=item * Portability

=item * Ranges of Dates Supported

=item * Compliance with Perl Styleguide (function naming)

=back

=head1 FUNCTIONAL SOLUTIONS

Modules exist to allow you to process integers like those
returned by the time() function.  They do not create "date" objects
with methods.  They simply provide functions that allow you do the
required tasks.