Proposal for Date-class

We need a commonly accepted interface for a Date-class if we are to use it in PEAR. This is my draft for the public interface. It defines three classes: Date, Time and DateTime where DateTime is a subclass of Date. The internal representation will be handled by something not dependant upon timestamps. Notice the diff() and FormatPeriod() methods, I think they will come in handy. Anyhow, this is my draft. I need your help with which methods we should add (or remove). And which From* methods should we add (ie. what different date or time formats are there?)? Date, Time and DateTime public interface draft 0.9 @author Erik Hjortsberg class Date extends Pear {

    void Date($year = null, $month = null, $day = null)
    string toDate()
    string toShortDate()
    int toDayInWeek()
    int toWeekNumber()
    boolean addWeeks($intWeeks)
    string toTextualDay()
    int compareTo(&$objDate)
    object(Date) &clone()
    boolean setToBeginningOfWeek($weekStart =  1)
    object(DateTime) &withTime(&$objTime)
    int diff(&$objDate, $format = 'days|months|years') //Date::FormatPeriod($date1->diff($date2), '%W &%D') => '4 weeks and 3 days'
    string format($strFormat)

//---------mutators and accessors

    int getYear()
    boolean setYear($value)
    int getMonth()
    boolean setMonth($value)
    int getDay()
    boolean setDay($value)

//---------static methods

    object(Date)|boolean &FromISO($inputDate)
    object(Date)|boolean &FromTimestamp($inputTimestamp)
    object(Date)|boolean &FromDatetime($inputDatetime)
    string FormatPeriod($intSeconds, $strFormat)

} class Time extends Pear {

    void Time($hour = null, $minute = null, $second = null)
    string toTime($withSeconds = true)
    int compareTo(&$objTime)
    object(DateTime) &withDate(&$objDate)
    object(Time) &clone()
    string format($strFormat)

//---------mutators and accessors

    int getHour()
    boolean setHour($value)
    int getMinute()
    boolean setMinute($value)
    int getSecond()
    boolean setSecond($value)
    int diff(&$objTime, $format = 'seconds|hours|minutes') //Time::FormatPeriod($time1->diff($time2), '%H %S') => '15 hours 201 seconds'

//---------static methods

    object(Time)|boolean &FromISO($strDate)
    object(Time)|boolean &FromTimestamp($strTimestamp)
    object(Time)|boolean &FromDatetime($strDatetime)
    string FormatPeriod($intDays, $strFormat)

} class DateTime extends Date {

    void DateTime($year = null, $month = null, $day = null, $hour = null, $minute = null, $second = null)
    string toTime($withSeconds = true)
    string toISO()
    string toDatetime()
    int compareTo(&$objDateTime)
    object(DateTime) &clone()
    object(Date) &asDate()
    object(Time) &asTime()
    int diff(&$objDateTime, $format = 'seconds|days|months|years|hours|minutes')
    string format($strFormat)

//---------mutators and accessors

    function getTimestamp()

//---------static methods

    object(DateTime)|boolean &FromISO($strDate)
    object(DateTime)|boolean &FromTimestamp($strTimestamp)
    object(DateTime)|boolean &FromDatetime($strDatetime)
    string FormatPeriod($intSeconds, $strFormat)

}