develooper Front page | perl.datetime | Postings from January 2003

Base object API/semantics

Thread Next
Dave Rolsky
January 10, 2003 21:52
Base object API/semantics
Message ID:
So I'm starting to work on turning Date::ICal into  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

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

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.


House Absolute Consulting

Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About