Base object API/semantics

Front page | perl.datetime | Postings from January 2003

Base object API/semantics

Thread Next

From:

Dave Rolsky

Date:

January 10, 2003 21:52

Subject:

Base object API/semantics

Message ID:

Pine.LNX.4.51.0301102326210.25009@urth.org

So I'm starting to work on turning Date::ICal into DateTime.pm.  The first
step was a global search and replace.  That part went well, and I was very
proud of myself.  I felt like a super-hacker ;)

Then I started added some of the simple-to-add Time::Piece methods, like
day_of_year, hms, ymd, and so forth.  All good.

There's a couple of thoughts I wanted to bounce off of people before I go
too much further.  Please take a look at the Time::Piece API if you're not
familiar with it.

First of all, the Time::Piece API was intended to be something suitable
for objects that would replace the value of Perl's localtime() builtin.  I
think it carries some unnecessary baggage because of that.

- There are a lot of _very_ similarly named methods that differ _only_ in
whether they return a 0-based number (for day of the week, for example) or
a 1-based number.  In other words, there's wday, which treats Sunday as 1,
and _wday/day_of_week, which treat Sunday as 0.

Is this _much_ API a good thing?  I'm inclined to say no, since whenever I
use Time::Piece I simply _never_ know which method to use, because I can't
remember which is 1-based, and which 0-based.  And I use Time::Piece a
lot!

Can we simply declare 0-based as the standard for day of week and day of
year, and 1-based for day of month, month of year, and week of year.
FWIW, that's what Date::ICal already had implemented, I believe.

Alternately, how about names like "day_of_week" and "day_of_week_1" or
something like that, so its _really_ clear what each does?


- A similar confusion exists between methods that return numbers and those
that return strings.  This is obviously only an issue for days and months.

Time::Piece has the following:

month/monname - abbreviated name (Jan Feb ...)
fullmonth     - full name
mon           - 1-12
_mon          - 0-11


wdayname/day  - abbreviated name (Mon Tue ...)
fullday       - full name
wday          - 1-7
_wday/day_of_week - 0-6


The fact that month returns a name while mon returns a number makes little
sense to me.

I propose the following:

month           - 1-12
month_name      - full name
month_name_abbr - abbreviated name

day             - _day of month_ (makes sense in context of year() and month() methods)
day_of_week     - 0-6 (or 1-7, see earlier question)
day_name        - full name
day_name_abbr   - abbreviated name

I think this makes more sense than the Time::Piece API.  The "name" is the
full name, not the abbreviation.  If you want the abbreviation, ask for
it.

Also, I'm fine with have aliases like day_of_week/wday and
day_of_month/mday and so on.  But I do want to have a sensible, consistent
method naming scheme for getting numbers, full names, and abbreviations.


And yes, I realize this all needs some sort of localization scheme.  I'm
leaning towards stealing the Date::Language code from Date::Parse right
now, since that'll be needed if the base object includes Date::Parse-style
parsing anyway, and moreover we need it for strftime.


-dave

/*=======================
House Absolute Consulting
www.houseabsolute.com
=======================*/

Thread Next