/ 
Date-Formatter-0.10
River stage zero No dependents
/ Date::Formatter

NAME

Date::Formatter - A simple Date and Time formatting object

SYNOPSIS

use Date::Formatter;

# create a Date::Formatter object with the current date and time.
my $date = Date::Formatter->now();

# create a formatter routine for this object
# see formatter mini-language documentation below
$date->createDateFormatter("(hh):(mm):(ss) (MM)/(DD)/(YYYY)");   

print $date; # print date in this format -> 12:56:03 4/12/2004

# get the formatter for use with other objects
my $formatter = $date->getDateFormatter();

# create an interval of time
my $interval = Date::Formatter->createTimeInterval(years => 1, days => 2, minutes => 15);

# re-use the formater from above
$interval->setDateFormatter($formatter);

print $interval; # print date in this format -> 12:56:03 4/12/2004 

# use overloaded operators
my $future_date = $date + $interval;

# sort the dates (again with the overload operator)
my @sorted_dates = sort { $a <=> $b } ($date, $interval, $future_date);

DESCRIPTION

This module provides a fast and very flexible mini-language to be used in formatting dates and times. In order to make that useful though, we had to make a fully functioning date & time object. This object looks and smells much like the Java and Javascript Date object on purpose. We also overloaded a number of operators to allow date addition and subtraction as well as comparisons.

METHODS

Constructors

new (%date)

The new constructor will return an new instance representing the current time. It also accepts an optional %date descriptor. The %date can contain the following fields: hour, minutes, seconds, day_of_month, month, and year. The values in %date are then used to construct a new object with that date.

NOTE: You can leave out values in %date, most of the time they will default to 0. For detailed information on how the %date values are handled I suggest consulting the Time::Local documentation. It should be noted though that we handle month values as 1 .. 12 and not the 0 .. 11 that Time::Local does.

now

The now constructor will create a Date::Formatter object with the current time.

createTimeInterval (%date_info)

This is a method for creating intervals of time. This is best used with the overloaded versions of the +, +=, - and -= operator to increment and decrement another Date::Formatter object.

Accepts the following named arguments:

years (365 days)
leap years (366 days)
months (assumes 30 days)
weeks
days
hours
minutes
seconds
refresh

Occasionally you will want to refresh the time to be the current time. This would allow a Date::Formatter object to be used over a long period of time.

Formatted Output Methods

The formatted output methods are means of customizing the string output of the Date::Formatter object. The createDateFormatter is at the heart of this group, it implements a mini-language for formatting dates. The internal parser in createDateFormatter has been optimized to make this a very usable operation, as it will be one of the most common uses of this object.

createDateFormatter ($format_string)

All date tokens must be enclosed in parantheses (or some other seperator for which you must provide the regular expression that split will use to tokenize the string). The formatter will use the current settings for 12 or 24 hour clock as well as the abbreviated day and month names. Here is a description of the available tokens and what they output:

hh is hours
mm is minutes
ss is seconds
single M will print the name of the month
MM will print the numeric month
single D will print the day by name
DD will print the numeric day of the month
YY will print the two digit year
YYYY will print the four digit year 
T will print either "a.m." or "p.m." if you have chosen to use the 12 hour clock
O will print the GMT offset in hours in the standard format

Any character not included in here is deamed a seperator and will pass into the output unchanged. Here are some format strings and some example output they would produce:

(hh):(mm):(ss) (MM)/(DD)/(YYYY)
ex: 12:56:03 12/9/2002

(hh):(mm) (D), (M) (DD), (YYYY)
ex: 12:56 Monday, December 9, 2002

(hh):(mm) (DD)-(MM)-(YY)
ex: 12:56 9-12-02

(MM)/(DD)/(YYYY) (hh):(mm):(ss)
ex: 12/9/2002 12:56:03

(MM).(DD).(YYYY) (hh):(mm):(ss) (T) (O)
ex: 12.9.2002 12:56:03 p.m. -0500

Remember it can be as complex as you want it to be, there is no restrictions:

 Today is the (DD) th of (M)
 the Year of our Lord (YYYY)
 at (ss) seconds past 
	(mm) minutes past 
         the hour of (hh)

 Today is the 9th of December 
 the Year of our Lord 2002
 at 03 seconds past 
	56 minutes past 
	   the hour of 12

here is a format that will exactly mimic the default date format (you must set the date object to useShortNames and use24HourClock)

(D) (M) (DD) (hh):(mm):(ss) (YYYY)
ex: Mon Dec  9 13:02:10 2002
getDateFormatter

Returns the formatter subroutine, so you can share between multiple Date::Formatter objects if you like.

setDateFormatter ($func)

Sets the formatter routine, this is how one would share that formatter routine mentioned above.

setLocale ($locale)

Sets (or resets) the locale. The default is 'en'.

Configuration methods

Most of the configuration methods are pretty self explanitory. They act only on the current Date::Formatter object instance they are applied against.

use24HourClock
use12HourClock
useLongNames
useLongMonthNames
useLongDayNames
useShortNames
useShortMonthNames
useShortDayNames

NOTE: Short names means we show the first 3 letters of the word only.

Informational Methods

The informational method are also self-explanitory, and in cases where further clarification is either neccesary or helpful it is provided.

isAMorPM

Returns 'a.m.' or 'p.m.' respectively.

getSeconds
getMinutes
getHours
getGMTOffsetHours
getGMTOffsetMinutes
getGMTOffset

This method formats the GMT hour offset in the standard way.

ex: -0500 for EST
getDayOfMonth
getMonth
getNumericMonth
getMonthIndex
getFullYear
getYear
getDayOfWeek
getDayOfWeekIndex
getDayOfYear

Overloaded Operators

Addition and subtraction operators are best used in conjunction with a Date::Formatter object that has been create using the createTimeInterval pseudo-constructor.

add
subtract

These methods overload the + and - operators respectively.

toString

This method returns the formatted string as specified by the createDateFormatter method. This is used to overload the '""' stringification operator.

compare

Compare two dates using the compare method or the overloaded <=> operator.

equal

Compare two dates using the compare method or the overloaded == operator.

notEqual

The inverse of equal.

Misc Methods

clone

Optimized clone method, this is a good way to make multiple objects all with the same time.

pack
unpack

The normal pack and unpack methods are provided and will serialize the Date::Formatter object to a 32 bit integer which represents the number of seconds from the epoch (a.k.a. UnixTime).

stringValue

Returns the non-overloaded string representation of the object.

LIMITATIONS

The Date::Formatter class is epoch limited. Below is a note about this from perl.com.

"... on most current systems, epochs are represented by a 32 bit signed integer, 
which only lets you represent datetimes with a range of about 136 years.  On most 
UNIX systems currently in use, this means that the latest date you can represent 
right now is sometime in the year 2038, and the earliest is around 1902."

TO DO

Using date formatters on time intervals does not always make sense, as it will just give you a representation of the interval past after the epoch. Possibly consider an alternate format for intervals. This would likely require some reworking of the way intervals are handled so it is only an idea for now.

This documentation needs some work.

BUGS

None that I am aware of. The code is pretty thoroughly tested (see "CODE COVERAGE" below) and is based on an (non-publicly released) module which I had used in production systems for over 2 years without incident. Of course, if you find a bug, let me know, and I will be sure to fix it.

CODE COVERAGE

I use Devel::Cover to test the code coverage of my tests, below is the Devel::Cover report on this module's test suite.

------------------------ ------ ------ ------ ------ ------ ------ ------
File                       stmt branch   cond    sub    pod   time  total
------------------------ ------ ------ ------ ------ ------ ------ ------
Date/Formatter.pm         100.0   95.8   74.5  100.0  100.0  100.0   96.4
------------------------ ------ ------ ------ ------ ------ ------ ------
Total                     100.0   95.8   74.5  100.0  100.0  100.0   96.4
------------------------ ------ ------ ------ ------ ------ ------ ------

SEE ALSO

The accessor interface to this module was inspired by and at times directly ripped off from the Javascript and Java Date objects.

This module uses Time::Local when creating dates with the %date parameter to new().

For serious date/time involved work, skip my module and go straight to the DateTime project at http://datetime.perl.org. Don't even waste your time with anything else.

Also here is a good article on the state of Perl's date-time world. It is a glimpse into the chaos - http://www.perl.com/pub/a/2003/03/13/datetime.html.

Below is a list of other Date/Time modules I have looked over in the past, and my opinions regarding the differences between them and my module here.

Class::Date

This module seems pretty nice, I have never used it. It is much more ambitious than my module, but in my opinion provides inferior formatting capabilties.

Date::Simple

If you have to manipulate just dates (it doesnt handle time), then this is a pretty good module. It provides an XS as well as a Pure Perl version.

Time::Format

This module is available as both an XS or a Pure perl version. It provides a funky global hash which can be used to easily format a UNIX time value. It does seem quite extensive, and is a nice way of going about this. But it is not OO at all, which is much of where it differs from my module.

Date::Format

A pretty nice formatting module, but purely functional in style. Not that thatis bad, just that its not the same as our OO version.

Time::Object
Time::localtime

Are both wrappers/helpers/extensions around the localtime and gmttime functions.

AUTHORS

Stevan Little, <stevan@iinteractive.com>

Rob Kinyon, <rob@iinteractive.com>

COPYRIGHT AND LICENSE

Copyright (C) 2004-2007 Infinity Interactive, Inc.

http://www.iinteractive.com

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