Datetime module revamp

Please add your requirements or feature requests for this module as comments to this bug.

My plan is to use an internal date representation (possibly just a 7-tuple of year/month/day/hour/minute/second/timezone items) and to have all datetime functions handle these.

Unix timestamps and other formats can be converted to this internal representation when these are provided (this should only need to happen internally).

The Datetime functions will mostly be static and will use the current date if no date was given. Example:

print DateTime::year(); // prints 2005
print DateTime::year('2003-01-01'); // prints 2003
print DateTime::year(12345678); // prints year associated to this unix timestamp

Similarly, month(), day(), hour(), minute() and second() functions will exist. These functions may also accept the internally used date representation (the 7-tuple in my design)

Additionally, DateTime will provide formatting functions: DateTime::format() should take a string specifying the format (strftime syntax) and (optionally) a date.

Other convenient date and time formatting functions will also be included: DateTime::short_date(), short_date_with_optional_year() and more like these (please file your requests).

Does this proposal cover all use cases?

Oh, I plan to support MySQL's DATETIME format as well (duh), both as input and output.

To what extend are timezones needed? I've never needed them, but maybe others do.

I need RFC2822 styled dates for use in RSS feeds. The RSS library should be updated to use the DateTime module (it currently does not).

I am missing DateTime::is_valid_date().

I have three usecases with datetime:

- get a readable date during development as fast as possible. ISO 8601 is nice enough.
- fancy pants formatting of date when fixing presentation/markup in final development fase. strftime is sufficient here.
- Working with date ranges and selecting DB entries therein, but this ventures on SQL's domain and I've been unwilling to learn the query syntax. (help I'm lazy!)

The 7-tuple and API design sounds very nice for quick access. Probably should need more specific usecases though.

print DateTime::day();

Will the upper function give me:
02 (day of the week),
25 (day of the month),
"Thursday",
"Thu".

What about Locales?

O and what about the Internet time?

DateTime::day() will return the day number, for a date like Oct 25, 2005 this will yield 25. Should we use integers or zero-padded strings?

Regarding internet time, please point me to a specification or a free (as in speech) reference implementation. One beat is approximately 84 seconds (from the top of my head), but does it also have another subdivision (like seconds?)

date('B');
Gives the Swatch internet time. it's a number from 000 to 999. No
other subdivision.

Internet time is marketed by Swatch. Cool idea, but impracticle in most applications and 'tainted' with commercial promotion. Usefull for geek features though.. ;)

As for ISO dates:
http://del.icio.us/mpe/iso+date

Functions like year(), day(), etc. should return values as displayed in ISO format. This has two advantages:

1). expected behaviour, eg. day should return calender day, not and an unexpected day of week/year or 0 to length-1 range or other strangeness.
2). zero-padded string to integer is easier than other way around... right?

I thought about this and I think that returning integers is saner than returning strings. The day of the month IS a number, actually, so why not treat it as such? If you want advanced number formatting you should use sprintf() and friends. And since the module will also feature functions to convert a date to YYYY-MM-DD format (for which the zero padded month and day numbers are required), I think a zero padded string is not needed at all.

So, I've been hacking on this lately. There's some small refactoring needed for a clean is_valid_date() implementation, but at this moment my DateTime module can parse any of the following formats:

- unix timestamps
- ISO 8601: 2005
- ISO 8601: 2005-10
- ISO 8601: 2005-10-31
- SQL92 DATETIME: 2005-10-31 12:00:00
- ISO 8601: 2005-10-31T12:00:00
- ISO 8601: 2005-10-31T12:00:00

Output is possible in these formats:

- year()
- month()
- day()
- hour()
- minute()
- second()
- timestamp()
- date()
- time()
- iso8601()
- iso8601_week()
- iso8601_week_day()
- iso8601_day_of_year()
- iso8601_week_of_year()
- rfc2822()
- sql()
- sql_date()
- sql_time()
- beat()

Of course, other formats can be specified in strftime() notation using this function:

- format($f)

All output functions optionally accept a date string, date instance. They will default to the current date and time if omitted.

Oops, typo in one of the parseable formats:

- ISO 8601: 2005-10-31T12:00

ISO 8601 Week-day constructions are _not_ supported at the moment:

- ISO 8601: 2005-W02
- ISO 8601: 2005-W02-5
- ISO 8601: 2005025

Feel free to write support for these formats if you need it :)

This is the patch I described.

I blogged about this: http://uwstopia.nl/blog/2005/10/anewt-datetime-module

I'm closing this bug, since all comments and requirements have found their way into the revamped module. Please file separate bug reports if you find bugs or if you are missing features.