/**
 * <code>TimeStamp</code> implements basic time keeping operations.  Times are 
 * kept in hours
 * and minutes only; seconds are not recorded.  Hours are recorded in military
 * time, thus 2:30pm is kept as 14:30.  The user should not use am/pm notation
 * and should enter all hours in 0-23 military format.  
 * <P>
 * The <code>TimeStamp</code> objects are intended only to measure differences
 * during the course of one day (00:00 to 23:59).  You should not subtract 
 * or compare differences across day boundaries.  
 * <P>
 * @author You
 * @version 4/10/2006
 */
public class TimeStamp
{
    private int hour;
    private int minute;
    
    /**
     * A constructor to create a new <code>TimeStamp</code> object with
     * the specified hours and minutes.
     * @param   hr  the hours in military format (00-23).
     * @param   mn  the minutes (00-60).
     */
    public TimeStamp ( int hr, int mn )
    {
        hour = hr % 24;
        minute = mn % 60;
    }
   
    /**
     * A constructor to create a new <code>TimeStamp</code> object
     * with a time specified as a string. 
     * @param  s  the input string must be of the form "hh:mm" where
     * hh is the hours (00-23) in 24hr military form and "mm" is the 
     * minutes (00-60).  
     */
    public TimeStamp ( String s )
    {
        int index = s.indexOf(":");
        String hourString = s.substring(0,index);
        String minuteString = s.substring(index+1);
        hour = Integer.parseInt(hourString) % 24;
        minute = Integer.parseInt(minuteString) % 60;
    }
    
    /**
     * A method to compare two <code>TimeStamp</code> objects.
     * The calling object is compared to the input parameter to generate
     * the following return values: +1 if calling object is bigger,
     * 0 if they are the same, -1 if the calling object is smaller.
     * @param  ts  the second <code>TimeStamp</code> object to be compared
     * to the calling object.
     * @return returns:
     * <ul>
     * <LI> +1 if calling object is larger than parameter <code>ts</code>
     * <LI>  0 if calling object is larger is the same as parameter <code>ts</code>
     * <LI> -1 if calling object is smaller than parameter <code>ts</code>
     */
    public int compareTo ( TimeStamp ts )
    {
        if ( hour > ts.hour || hour == ts.hour && minute > ts.minute )
            return 1;
        if ( hour < ts.hour || hour == ts.hour && minute < ts.minute )
            return -1;
        return 0;
    }
    
    /**
     * A method to compare two <code>TimeStamp</code> objects for equality.
     * @param ts the second <code>TimeStamp</code> object.
     * @return <code>true</code> if <code>ts</code> is the same as the calling
     * object, otherwise <code>false</code>.
     */
    public boolean equals ( TimeStamp ts )
    {
        return ( hour == ts.hour && minute == ts.minute );
    }
    
    /**
     * A method to subtract to <code>TimeStamp</code> objects and return the
     * different in hh:mm format.  The subtraction is performed as 
     * calling <code>TimeStamp</code> object - <code>ts</code> object.
     * This method should be used only when the calling object is larger than
     * the parameter.  If the parameter is larger (or the same value), then 
     * a zero will be returned (00:00) as we do not represent negative
     * values for times.  
     * @param ts the second <code>TimeStamp</code> object which to subtract
     * from the calling object.
     * @return a new <code>TimeStamp</code> object in hh:mm format where
     * the hh is the difference in hours and the mm is the remaining difference
     * in seconds.  
     */
    public TimeStamp difference ( TimeStamp ts )
    {
        if ( compareTo(ts) != 1 ) return new TimeStamp(0,0);
        int time1 = 60*hour + minute;
        int time2 = 60*ts.hour + ts.minute;
        int diff = time1 - time2;
        TimeStamp ret = new TimeStamp(diff/60,diff%60);
        return ret;
    }
    /**
     * A method to convert hh::mm format to an hours format in which 
     * the minutes represent fractional hours.  For example, 8:15 
     * is returned as 8.25 hours.  
     * @return the hours + fractional minutes in decimal format 
     */
    public double toHours ()
    {
        return ( hour + minute/60.0 );
    }
    /**
     * Returns the time as a string in "hh:mm" format.
     * @return <code>TimeStamp</code> object in "hh:mm" String format.
     */
    public String toString ()
    {
        return (hour + ":" + minute);
    }
}