How to calculate number of days between two Timestamp

[Sam Kumar]

Hi,
Is there any easy way to get "number of days" difference between two java.sql.Timestamp.
Thanks in advance.
SK

[Jon Strayer]

How about using Timestamp.getTime() to get the number of ms, subtracting the two for the difference, and then dividing the difference by 24 * 60 ^ 60 * 1000 to get days?

[Thomas Paul]

I wrote a class to calculate differences in Dates. Feel free to try it and use it.

/*
 * TimeSpan.java
 *
 * Created on January 28, 2003, 11:09 AM
 */
 /* ====================================================================
 *
 * The JavaRanch Software License, Version 1.0
 *
 * Copyright (c) 2003 JavaRanch.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. The name JavaRanch must not be used to endorse or promote products derived
 *    from this software without prior written permission. 
 *
 * 4. Products derived from this software may not be called "JavaRanch"
 *    nor may "JavaRanch" appear in their names without prior written
 *    permission of JavaRanch.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL JAVARANCH OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * ====================================================================
 *
 */
package com.javaranch.util;
/** The value of an instance of TimeSpan represents a period of time.
 *
 * TimeSpan can be used in several ways.
 *
 * To calculate the difference in time between two dates:
 * <PRE>TimeSpan timespan = TimeSpan.subtract(date1, date2);</PRE>
 *
 * To add five days to a TimeSpan:
 * <PRE>timspan.add(TimeSpan.DAYS, 5);</PRE>
 *
 * To subtract another TimeSpan object from this one:
 * <PRE>timspan.subtract(timespan2);</PRE>
 *
 * @author Thomas Paul
 */
public class TimeSpan implements Comparable, java.io.Serializable, Cloneable {
    
    private long time = 0;
    
    /** Constant for milliseconds unit and conversion */
    public static final int MILLISECONDS = 1;    
    /** Constant for seconds unit and conversion */
    public static final int SECONDS = MILLISECONDS * 1000;
    /** Constant for minutes unit and conversion */
    public static final int MINUTES = SECONDS * 60;
    /** Constant for hours unit and conversion */
    public static final int HOURS = MINUTES * 60;    
    /** Constant for days unit and conversion */
    public static final int DAYS = HOURS * 24;
    /** Represents the Maximum TimeSpan value */
    public static final TimeSpan MAX_VALUE = new TimeSpan(Long.MAX_VALUE);
    /** Represents the Minimum TimeSpan value */
    public static final TimeSpan MIN_VALUE = new TimeSpan(Long.MIN_VALUE);
    /** Represents the TimeSpan with a value of zero */
    public static final TimeSpan ZERO = new TimeSpan(0L);
      
    /** Creates a new instance of TimeSpan based on the number of milliseconds
     *  entered.
     *
     * @param time the number of milliseconds for this TimeSpan.
     *
     */
    public TimeSpan(long time) {
        this.time = time;
    }
    /** Creates a new TimeSpan object based on the unit and value entered.
     *
     * @param units the type of unit to use to create a TimeSpan instance.
     * @param value the number of units to use to create a TimeSpan instance.
     *
     */    
    public TimeSpan(int units, long value) {
        this.time = this.toMilliseconds(units, value);
    }   
    
    /** Subtracts two Date objects creating a new TimeSpan object.
     *
     * @param date1 Date to use as the base value.
     * @param date2 Date to subtract from the base value.
     *
     * @return  a TimeSpan object representing the difference bewteen the 
     *          two Date objects.
     *
     */    
    public static TimeSpan subtract(java.util.Date date1, java.util.Date date2) {
        return new TimeSpan(date1.getTime() - date2.getTime());
    }
    
    /** Compares this object with the specified object for order.  Returns a
     *  negative integer, zero, or a positive integer as this object is less
     *  than, equal to, or greater than the specified object. Comparison is 
     *  based on the number of milliseconds in this TimeSpan.
     *
     * @param   o the Object to be compared.
     *
     * @return  a negative integer, zero, or a positive integer as this object
     * is less than, equal to, or greater than the specified object.
     *
     * @throws ClassCastException if the specified object's type prevents it
     *         from being compared to this Object.
     *
     */
    public int compareTo(Object o) {
        TimeSpan compare = (TimeSpan)o;
        if (this.time == compare.time) {
            return 0;
        }
        if (this.time > compare.time) {
            return +1;
        }
        return -1;
    }
    
    /** Indicates whether some other object is "equal to" this one. 
     *  Comparison is based on the number of milliseconds in this TimeSpan.
     *
     *  @param   obj   the reference object with which to compare.
     *
     *  @return  <code>true</code> if the obj argument is a TimeSpan object
     *           with the exact same number of milliseconds. 
     *  <code>false</code> otherwise.
     *
     */
    public boolean equals(Object obj) {
        if (obj instanceof TimeSpan) {
            TimeSpan compare = (TimeSpan)obj;
            if (this.time == compare.time) {
                return true;
            }
        }
        return false;
    }
    
    /** Returns a hash code value for the object. This method is
     *  supported for the benefit of hashtables such as those provided by
     *  <code>java.util.Hashtable</code>. The method uses the same 
     *  algorithm as found in the Long class.
     *
     * @return  a hash code value for this object.
     *
     * @see     java.lang.Object#equals(java.lang.Object)
     * @see     java.util.Hashtable
     *
     */
    public int hashCode() {
        return new Long(this.time).hashCode();
    }
    
    /** Returns a string representation of the object in the format 
     *  "[-]d.hh:mm:ss.ff" where "-" is an optional sign for negative TimeSpan 
     *  values, the "d" component is days, "hh" is hours, "mm" is minutes, 
     *  "ss" is seconds, and "ff" is milliseconds
     *
     * @return  a string containing the number of milliseconds.
     *
     */
    public String toString() {
        StringBuffer sb = new StringBuffer();
        long millis = this.time;
        if (millis < 0) {
            sb.append("-");
            millis = -millis;
        }
        
        long day = millis / this.DAYS;
        
        if (day != 0) {
            sb.append(day);
            sb.append("d.");
            millis = millis % this.DAYS;
        }
             
        sb.append(millis / this.HOURS);
        millis = millis % this.HOURS;
        sb.append("h:");
        sb.append(millis / this.MINUTES);
        millis = millis % this.MINUTES;
        sb.append("m:");
        sb.append(millis / this.SECONDS);
        sb.append("s");
        millis = millis % this.SECONDS;
        if (millis != 0) {
            sb.append(".");
            sb.append(millis);
            sb.append("ms");
        }
        return sb.toString();
    }
    /** Returns a clone of this TimeSpan. 
     *
     * @return  a clone of this TimeSpan.
     */    
    public Object clone() {
        try {
             return super.clone();
        } catch (CloneNotSupportedException e) {
            throw new InternalError();
        }
    }
    /** Indicates whether the value of the TimeSpan is positive. 
     *
     *  @return  <code>true</code> if the value of the TimeSpan is greater 
     *          than zero.
     *  <code>false</code> otherwise.
     *
     */
    public boolean isPositive() {
        return this.compareTo(TimeSpan.ZERO)>0?true:false;
    }
    
    /** Indicates whether the value of the TimeSpan is negative. 
     *
     *  @return  <code>true</code> if the value of the TimeSpan is less 
     *          than zero.
     *  <code>false</code> otherwise.
     *
     */
    public boolean isNegative() {
        return this.compareTo(TimeSpan.ZERO)<0?true:false;
    }
    
    /** Indicates whether the value of the TimeSpan is zero. 
     *
     *  @return  <code>true</code> if the value of the TimeSpan is equal to zero.
     *  <code>false</code> otherwise.
     *
     */
    public boolean isZero() {
        return this.equals(TimeSpan.ZERO);
    }
    /** Gets the number of milliseconds.
     *
     * @return the number of milliseconds.
     */    
    public long getMilliseconds() {
        return this.time;
    }
      
    /** Gets the number of seconds (truncated).
     *
     * @return the number of seconds.
     */    
    public long getSeconds() {
        return this.time/1000;
    }
    
    /** Gets the number of seconds including fractional seconds.
     *
     * @return the number of seconds.
     */    
    public double getTotalSeconds() {
        return this.time/1000.0d;
    }
    
    /** Gets the number of minutes (truncated).
     *
     * @return the number of minutes.
     */    
    public long getMinutes() {
        return (this.time/1000)/60;
    }
    
    /** Gets the number of minutes including fractional minutes.
     *
     * @return the number of minutes.
     */    
    public double getTotalMinutes() {
        return (this.time/1000.0d)/60.0d;
    }
        
    /** Gets the number of hours (truncated).
     *
     * @return the number of hours.
     */    
    public long getHours() {
        return ((this.time/1000)/60)/60;
    }
    
    /** Gets the number of hours including fractional hours.
     *
     * @return the number of hours.
     */    
    public double getTotalHours() {
        return ((this.time/1000.0d)/60.0d)/60.0d;
    }
    
    /** Gets the number of days (truncated).
     *
     * @return the number of days.
     */    
    public long getDays() {
        return (((this.time/1000)/60)/60)/24;
    }
    
    /** Gets the number of days including fractional days.
     *
     * @return the number of days.
     */    
    public double getTotalDays() {
        return (((this.time/1000.0d)/60.0d)/60.0d)/24.0d;
    }
    
    /** Adds a TimeSpan to this TimeSpan.
     *
     * @param timespan the TimeSpan to add to this TimeSpan.
     */    
    public void add(TimeSpan timespan) {
        add(this.MILLISECONDS, timespan.time);
    }
    
    /** Adds a number of units to this TimeSpan.
     *
     * @param units the type of unit to add to this TimeSpan.
     * @param value the number of units to add to this TimeSpan.
     */    
    public void add(int units, long value) {
       this.time += this.toMilliseconds(units, value);
    }
    /** Compares two TimeSpan objects.
     *
     * @param first first TimeSpan to use in the compare.
     * @param second second TimeSpan to use in the compare.
     *
     * @return  a negative integer, zero, or a positive integer as the first
     *          TimeSpan is less than, equal to, or greater than the 
     *          second TimeSpan.
     *
     */    
    public static int compare(TimeSpan first, TimeSpan second) {
        if (first.time == second.time) {
            return 0;
        }
        if (first.time > second.time) {
            return +1;
        }
        return -1;
    }
    
    /** Returns a TimeSpan whose value is the absolute value of this TimeSpan. 
     *
     * @return  a TimeSpan whose value is the absolute value of this TimeSpan. 
     */
    public TimeSpan duration() {
        return new TimeSpan(Math.abs(this.time));
    }
    
    /** Returns a TimeSpan whose value is the negated value of this TimeSpan. 
     *
     * @return  a TimeSpan whose value is the negated value of this TimeSpan. 
     */
    public TimeSpan negate() {
        return new TimeSpan(-this.time);
    }
    /** Subtracts a TimeSpan from this TimeSpan.
     *
     * @param timespan the TimeSpan to subtract from this TimeSpan.
     */    
    public void subtract(TimeSpan timespan) {
        subtract(this.MILLISECONDS, timespan.time);
    }
    
    /** Subtracts a number of units from this TimeSpan.
     *
     * @param units the type of unit to subtract from this TimeSpan.
     * @param value the number of units to subtract from this TimeSpan.
     */    
    public void subtract(int units, long value) {
        add(units, -value);
    }
    
    private static long toMilliseconds(int units, long value) {
        long millis;
        switch (units) {
            case TimeSpan.MILLISECONDS:
            case TimeSpan.SECONDS:
            case TimeSpan.MINUTES:
            case TimeSpan.HOURS:
            case TimeSpan.DAYS:
                millis = value * units;
                break;
            default:
                throw new IllegalArgumentException("Unrecognized units: " + units);
        }
        return millis;
    }
}

It's pretty simple to use. Assuming you have two Date objects and you want to find out the difference in days, for example:
TimeSpan ts = TimeSpan.subtract(d1, d2);
System.out.println(ts.getDays());
Suggestions for improvements are welcome.
[ January 30, 2003: Message edited by: Thomas Paul ]

[Jim Yingst]

Cool.
Suggestions for improvements are welcome.
OK, you asked for it.
Inside getInstance(), I think
return new TimeSpan(value);
should be
return new TimeSpan(time);
Other stuff:
It looks like someone's using a tool which imports javadoc comments from overridden methods. Unfortunately they aren't always correct for the new class. (E.g. the toString() method.) And even if they're correct, they're often dead weight - there's no need to repeat the general contract of equals() and hashCode(); javadoc will provide a link to the overridden methods anyway. In general, the current comments tell you nothing that's not apparent from reading the method names. My feeling is that when that's the case, they might as well be deleted for readability, or replaced.
The javadoc should probably explain the difference between something like getDays() and getTotalDays(). And provide some usage examples, since some of it's not immediately apparent.
It seems that sometimes a TimeSpan represents a difference in times, and sometimes it represents an absolute time. Clarification might be appropriate.
As long as time can be a long, I'd modify the add(int, int) and subtract(int, int) methods to use longs as well. Also might be nice to check for overflow - though once you're using longs the incidence of that should be a lot rarer. (And I admit it will be pretty rare for ints as well.)
And wouldn't

 
    public void subtract(int units, int value) {
        add(units, -value);    
    }

be easier to maintain? Or for that matter, helper method like

    private static long toMilliseconds(int units, long value int) {
        long millis;
        switch (units) {
            case TimeSpan.MILLISECONDS:
                millis = value;
                break;
            case TimeSpan.SECONDS:
                millis = value * 1000;
                break;
            case TimeSpan.MINUTES:
                millis = value * 1000 * 60;
                break;
            case TimeSpan.HOURS:
                millis = value * 1000 * 60 * 60;
                break;
            case TimeSpan.DAYS:
                millis = value * 1000 * 60 * 60 * 24;
                break;
            default:
                throw new IllegalArgumentException("Unrecognized units: " + units);
        }
        return millis;
    }

would simplify 3 other methods, and add some useful validation. Alternately the conversion factors could be put into a nice array, eliminating the switch entirely. Or, heck, the int values for DAYS, HOURS, etc. could be the conversion factors. Though that's probably a bit more confusing to others reading the code.
Is there a reason to have getInstance(int, int) as a factory method, and also public constructors TimeSpan(long) and TimeSpan(Date)? Seems like the API would be cleaner if either they were all three constructors, or all three factory methods (with a single private constructor elsewhere).
It's tempting to add units of WEEKS and YEARS, too. I admit YEARS is a bit of a problem though since the desired conversion factor is not obvious. (Which is why I don't mention MONTHS here.) Perhaps NONLEAP_YEARS (365 days), LEAP_YEARS (366), and STANDARD_YEARS (365.24...)? OK no one would have a good reason to make a TimeSpan of more than one consecutive leap year. :roll: But offering the option encourages people to decide what they really mean, which I think is good.
[ January 28, 2003: Message edited by: Jim Yingst ]

[Thomas Paul]

I updated it based on Jim's advice and my own ideas.
More comments welcome!

[Jim Yingst]

Well, heck - might as well take advantage of the redefined units values to eliminate more redundant code:

    private static long toMilliseconds(int units, long value) {
        long millis;
        switch (units) {
            case TimeSpan.MILLISECONDS:
            case TimeSpan.SECONDS:
            case TimeSpan.MINUTES:
            case TimeSpan.HOURS:
            case TimeSpan.DAYS:
                millis = value * units;
                break;
            default:
                throw new IllegalArgumentException("Unrecognized units: " + units);
        }

OK, not a big deal - I jut can't resist the need to remove redundancy.
[ January 29, 2003: Message edited by: Jim Yingst ]

[Thomas Paul]

Good catch, Jim!
By the way, you were right about using an IDE. I have the new NetBeans book from O'Rourke to review so I have been working with NetBeans to get an idea of how the thing works.
Ok, so what is the easiest way to check for overflow or underflow? With the redesign there is only one place in the code where this can happen:

public void add(int units, long value) {
    this.time += this.toMilliseconds(units, value);
}

It seems to me that if both numbers are positive and the result is not positive then we had overflow and if both numbers are negative and the result is not negative we had underflow. Make sense?
By the way, the GregorianCalendar class does not test for overflow.
[ January 30, 2003: Message edited by: Thomas Paul ]

[Jim Yingst]

It seems to me that if both numbers are positive and the result is not positive then we had overflow and if both numbers are negative and the result is not negative we had underflow. Make sense?
Yeah, good call - that seems sufficient to catch any overflow that might occur as the result of an addition. However the toMilliseconds() method could have overflow from multiplication too. And I don't believe this method will work as well for multiplication overflow, as an overflow result may be positive or negative.
Here's code I came up with to check for overflow:

  /**
   *  Compute the sum of two longs, and throw an ArithmeticException if this
   *  sum is outside the legal range of a long.
   *
   *  @return sum of a + b
   *  @exception ArithmeticException if overflow occurs
   */
  public static long add(long a, long b)
  {
    long sum = a + b;
    if (a < 0)
    {
      if (b < 0 && sum > 0)
        throw new ArithmeticException(
            "Long overflow: " + a + " + " + b + " = " + sum);
    }
    if (a > 0)
    {
      if (b > 0 && sum < 0)
        throw new ArithmeticException(
            "Long overflow: " + a + " + " + b + " = " + sum);
    }
    return sum;
  }
  /**
   *  Compute the product of two longs, and throw an ArithmeticException if this
   *  product is outside the legal range of a long.
   *
   *  @return product of a * b
   *  @exception ArithmeticException if overflow occurs
   */
  public static long multiply(long a, long b)
  {
    long product = a * b;
    if (product / a != b)
      throw new ArithmeticException("Long overflow: " + a + " * " + b + " = " + product);
    return product;
  }

I went ahead and optimized the checks as much as possible - didn't see a way to create a single if statement in the add() method without some redundant checks. For the multiply version, I couldn't think of a better way than to just reverse the operation to see if it works. From limited testing it appears that these are significantly slower than traditional + or * due to method call overhead. You can improve performance substantially by manually inlining the method bodies into the calling code. Which means HotSpot doesn't do as good a job as I'd hoped at inlining for you. Ah well - for most applications the error checking is more useful than speed, I think.
I think I may make a SafeMath class collecting utility methods like this. Perhaps I'll start a separate thread so y'all can review that too.
By the way, the GregorianCalendar class does not test for overflow.
Add this to the list of reasons not to like GregorianCalendar. Though at least this one is correctable without changing the API. And to be fair, once we're using longs the chance of overflow is pretty small for practical matters. I probably would've overlooked it in your class too if I hadn't noticed you were using ints in the first version; that's what got me thinking about it.
[ February 09, 2003: Message edited by: Jim Yingst ]

[Jasper Vader]

an inspiring process to observe, thanks guys!

[Thomas Paul]

OK, I have made an update in order to turn the units into a typesafe enum:

/*
 * TimeSpan.java
 *
 * Created on January 28, 2003, 11:09 AM
 */
 /* ====================================================================
 *
 * The JavaRanch Software License, Version 1.0
 *
 * Copyright (c) 2003 JavaRanch.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. The name JavaRanch must not be used to endorse or promote products derived
 *    from this software without prior written permission. 
 *
 * 4. Products derived from this software may not be called "JavaRanch"
 *    nor may "JavaRanch" appear in their names without prior written
 *    permission of JavaRanch.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL JAVARANCH OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * ====================================================================
 *
 */
package com.javaranch.util;
/** The value of an instance of TimeSpan represents a period of time.
 *
 * TimeSpan can be used in several ways.
 *
 * To calculate the difference in time between two dates:
 * <PRE>TimeSpan timespan = TimeSpan.subtract(date1, date2);</PRE>
 *
 * To add five days to a TimeSpan:
 * <PRE>timspan.add(TimeSpanUnit.DAYS, 5);</PRE>
 *
 * To subtract another TimeSpan object from this one:
 * <PRE>timspan.subtract(timespan2);</PRE>
 *
 * @author Thomas Paul
 */
public class TimeSpan implements Comparable, java.io.Serializable, Cloneable {
    
    private long time = 0;
    
    /** Represents the Maximum TimeSpan value */
    public static final TimeSpan MAX_VALUE = new TimeSpan(Long.MAX_VALUE);
    /** Represents the Minimum TimeSpan value */
    public static final TimeSpan MIN_VALUE = new TimeSpan(Long.MIN_VALUE);
    /** Represents the TimeSpan with a value of zero */
    public static final TimeSpan ZERO = new TimeSpan(0L);
     
    /** Creates a new instance of TimeSpan based on the number of milliseconds
     *  entered.
     *
     * @param time the number of milliseconds for this TimeSpan.
     *
     */
    public TimeSpan(long time) {
        this.time = time;
    }
    /** Creates a new TimeSpan object based on the unit and value entered.
     *
     * @param units the type of unit to use to create a TimeSpan instance.
     * @param value the number of units to use to create a TimeSpan instance.
     *
     */    
    public TimeSpan(TimeSpanUnit unit, long value) {
        this.time = this.toMilliseconds(unit, value);
    }   
    
    /** Subtracts two Date objects creating a new TimeSpan object.
     *
     * @param date1 Date to use as the base value.
     * @param date2 Date to subtract from the base value.
     *
     * @return  a TimeSpan object representing the difference bewteen the 
     *          two Date objects.
     *
     */    
    public static TimeSpan subtract(java.util.Date date1, java.util.Date date2) {
        return new TimeSpan(date1.getTime() - date2.getTime());
    }
    
    /** Compares this object with the specified object for order.  Returns a
     *  negative integer, zero, or a positive integer as this object is less
     *  than, equal to, or greater than the specified object. Comparison is 
     *  based on the number of milliseconds in this TimeSpan.
     *
     * @param   o the Object to be compared.
     *
     * @return  a negative integer, zero, or a positive integer as this object
     * is less than, equal to, or greater than the specified object.
     *
     * @throws ClassCastException if the specified object's type prevents it
     *         from being compared to this Object.
     *
     */
    public int compareTo(Object o) {
        TimeSpan compare = (TimeSpan)o;
        if (this.time == compare.time) {
            return 0;
        }
        if (this.time > compare.time) {
            return +1;
        }
        return -1;
    }
    
    /** Indicates whether some other object is "equal to" this one. 
     *  Comparison is based on the number of milliseconds in this TimeSpan.
     *
     *  @param   obj   the reference object with which to compare.
     *
     *  @return  <code>true</code> if the obj argument is a TimeSpan object
     *           with the exact same number of milliseconds. 
     *  <code>false</code> otherwise.
     *
     */
    public boolean equals(Object obj) {
        if (obj instanceof TimeSpan) {
            TimeSpan compare = (TimeSpan)obj;
            if (this.time == compare.time) {
                return true;
            }
        }
        return false;
    }
    
    /** Returns a hash code value for the object. This method is
     *  supported for the benefit of hashtables such as those provided by
     *  <code>java.util.Hashtable</code>. The method uses the same 
     *  algorithm as found in the Long class.
     *
     * @return  a hash code value for this object.
     *
     * @see     java.lang.Object#equals(java.lang.Object)
     * @see     java.util.Hashtable
     *
     */
    public int hashCode() {
        return new Long(this.time).hashCode();
    }
    
    /** Returns a string representation of the object in the format 
     *  "[-]d.hh:mm:ss.ff" where "-" is an optional sign for negative TimeSpan 
     *  values, the "d" component is days, "hh" is hours, "mm" is minutes, 
     *  "ss" is seconds, and "ff" is milliseconds
     *
     * @return  a string containing the number of milliseconds.
     *
     */
    public String toString() {
        StringBuffer sb = new StringBuffer();
        long millis = this.time;
        if (millis < 0) {
            sb.append("-");
            millis = -millis;
        }
        
        long day = millis / TimeSpanUnit.TimeSpanConstants.DAYS;
        
        if (day != 0) {
            sb.append(day);
            sb.append("d.");
            millis = millis % TimeSpanUnit.TimeSpanConstants.DAYS;
        }
             
        sb.append(millis / TimeSpanUnit.TimeSpanConstants.HOURS);
        millis = millis % TimeSpanUnit.TimeSpanConstants.HOURS;
        sb.append("h:");
        sb.append(millis / TimeSpanUnit.TimeSpanConstants.MINUTES);
        millis = millis % TimeSpanUnit.TimeSpanConstants.MINUTES;
        sb.append("m:");
        sb.append(millis / TimeSpanUnit.TimeSpanConstants.SECONDS);
        sb.append("s");
        millis = millis % TimeSpanUnit.TimeSpanConstants.SECONDS;
        if (millis != 0) {
            sb.append(".");
            sb.append(millis);
            sb.append("ms");
        }
        return sb.toString();
    }
    /** Returns a clone of this TimeSpan. 
     *
     * @return  a clone of this TimeSpan.
     */    
    public Object clone() {
        try {
             return super.clone();
        } catch (CloneNotSupportedException e) {
            throw new InternalError();
        }
    }
    /** Indicates whether the value of the TimeSpan is positive. 
     *
     *  @return  <code>true</code> if the value of the TimeSpan is greater 
     *          than zero.
     *  <code>false</code> otherwise.
     *
     */
    public boolean isPositive() {
        return this.compareTo(TimeSpan.ZERO)>0?true:false;
    }
    
    /** Indicates whether the value of the TimeSpan is negative. 
     *
     *  @return  <code>true</code> if the value of the TimeSpan is less 
     *          than zero.
     *  <code>false</code> otherwise.
     *
     */
    public boolean isNegative() {
        return this.compareTo(TimeSpan.ZERO)<0?true:false;
    }
    
    /** Indicates whether the value of the TimeSpan is zero. 
     *
     *  @return  <code>true</code> if the value of the TimeSpan is equal to zero.
     *  <code>false</code> otherwise.
     *
     */
    public boolean isZero() {
        return this.equals(TimeSpan.ZERO);
    }
    /** Gets the number of milliseconds.
     *
     * @return the number of milliseconds.
     */    
    public long getMilliseconds() {
        return this.time;
    }
      
    /** Gets the number of seconds (truncated).
     *
     * @return the number of seconds.
     */    
    public long getSeconds() {
        return this.time/1000;
    }
    
    /** Gets the number of seconds including fractional seconds.
     *
     * @return the number of seconds.
     */    
    public double getTotalSeconds() {
        return this.time/1000.0d;
    }
    
    /** Gets the number of minutes (truncated).
     *
     * @return the number of minutes.
     */    
    public long getMinutes() {
        return (this.time/1000)/60;
    }
    
    /** Gets the number of minutes including fractional minutes.
     *
     * @return the number of minutes.
     */    
    public double getTotalMinutes() {
        return (this.time/1000.0d)/60.0d;
    }
        
    /** Gets the number of hours (truncated).
     *
     * @return the number of hours.
     */    
    public long getHours() {
        return ((this.time/1000)/60)/60;
    }
    
    /** Gets the number of hours including fractional hours.
     *
     * @return the number of hours.
     */    
    public double getTotalHours() {
        return ((this.time/1000.0d)/60.0d)/60.0d;
    }
    
    /** Gets the number of days (truncated).
     *
     * @return the number of days.
     */    
    public long getDays() {
        return (((this.time/1000)/60)/60)/24;
    }
    
    /** Gets the number of days including fractional days.
     *
     * @return the number of days.
     */    
    public double getTotalDays() {
        return (((this.time/1000.0d)/60.0d)/60.0d)/24.0d;
    }
    
    /** Adds a TimeSpan to this TimeSpan.
     *
     * @param timespan the TimeSpan to add to this TimeSpan.
     */    
    public void add(TimeSpan timespan) {
        add(TimeSpanUnit.MILLISECONDS, timespan.time);
    }
    
    /** Adds a number of units to this TimeSpan.
     *
     * @param units the type of unit to add to this TimeSpan.
     * @param value the number of units to add to this TimeSpan.
     */    
    public void add(TimeSpanUnit unit, long value) {
       this.time += this.toMilliseconds(unit, value);
    }
    /** Compares two TimeSpan objects.
     *
     * @param first first TimeSpan to use in the compare.
     * @param second second TimeSpan to use in the compare.
     *
     * @return  a negative integer, zero, or a positive integer as the first
     *          TimeSpan is less than, equal to, or greater than the 
     *          second TimeSpan.
     *
     */    
    public static int compare(TimeSpan first, TimeSpan second) {
        if (first.time == second.time) {
            return 0;
        }
        if (first.time > second.time) {
            return +1;
        }
        return -1;
    }
    
    /** Returns a TimeSpan whose value is the absolute value of this TimeSpan. 
     *
     * @return  a TimeSpan whose value is the absolute value of this TimeSpan. 
     */
    public TimeSpan duration() {
        return new TimeSpan(Math.abs(this.time));
    }
    
    /** Returns a TimeSpan whose value is the negated value of this TimeSpan. 
     *
     * @return  a TimeSpan whose value is the negated value of this TimeSpan. 
     */
    public TimeSpan negate() {
        return new TimeSpan(-this.time);
    }
    /** Subtracts a TimeSpan from this TimeSpan.
     *
     * @param timespan the TimeSpan to subtract from this TimeSpan.
     */    
    public void subtract(TimeSpan timespan) {
        subtract(TimeSpanUnit.MILLISECONDS, timespan.time);
    }
    
    /** Subtracts a number of units from this TimeSpan.
     *
     * @param units the type of unit to subtract from this TimeSpan.
     * @param value the number of units to subtract from this TimeSpan.
     */    
    public void subtract(TimeSpanUnit unit, long value) {
        add(unit, -value);
    }
   
    private static long toMilliseconds(TimeSpanUnit unit, long value) {
        return value * unit.getValue();
    }
}

/*
 * TimeSpanUnit.java
 *
 * Created on March 26, 2003, 3:46 PM
 */
 /* ====================================================================
 *
 * The JavaRanch Software License, Version 1.0
 *
 * Copyright (c) 2003 JavaRanch.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. The name JavaRanch must not be used to endorse or promote products derived
 *    from this software without prior written permission. 
 *
 * 4. Products derived from this software may not be called "JavaRanch"
 *    nor may "JavaRanch" appear in their names without prior written
 *    permission of JavaRanch.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL JAVARANCH OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * ====================================================================
 *
 */
 
package com.javaranch.util;
/** The TimeSpanUnit defines a standard set of units to be used with the TimeSpan
 *  class.  The methods of the TimeSpan class require the use of TimeSpanUnit
 *  objects for certain methods.  The purpose of this class is to provide a 
 *  typesafe enum. (see <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/Level.html">
 *  java.util.logging.Level</a> for an example from the Java API.)
 *  <p>
 *  The TimeSpanUnit objects are:
 *  <ul>
 *  <li>MILLISECONDS</li>
 *  <li>SECONDS</li>
 *  <li>MINUTES</li>
 *  <li>HOURS</li>
 *  <li>DAYS</li>
 *  </UL>
 *
 * @author Thomas Paul
 */
public final class TimeSpanUnit {
    
    private String name;
    private int value;
        
    /** MILLISECONDS indicates that milliseconds are being used */
    public static final TimeSpanUnit MILLISECONDS = new TimeSpanUnit("MILLISECONDS", TimeSpanConstants.MILLISECONDS);
    /** SECONDS indicates that seconds are being used */
    public static final TimeSpanUnit SECONDS = new TimeSpanUnit("SECONDS", TimeSpanConstants.SECONDS);
    /** MINUTES indicates that minutes are being used */
    public static final TimeSpanUnit MINUTES = new TimeSpanUnit("MINUTES", TimeSpanConstants.MINUTES);
    /** HOURS indicates that hours are being used */
    public static final TimeSpanUnit HOURS = new TimeSpanUnit("HOURS", TimeSpanConstants.HOURS);
    /** DAYS indicates that days are being used */
    public static final TimeSpanUnit DAYS = new TimeSpanUnit("DAYS", TimeSpanConstants.DAYS);   
    
    /** No TimeSpanUnit objects should be created outside of this class */
    private TimeSpanUnit(String name, int value) {
        this.name = name;
        this.value = value;
    }
    /** Gets the number of milliseconds this TimeSpanUnit represents.
     *
     * @return the number of milliseconds.
     */        
    public int getValue() {
        return value;
    }
    
    /** Gets the name of this TimeSpanUnit.
     *
     * @return the name of this TimeSpanUnit.
     */        
    public int getName() {
        return value;
    }
    /** Returns a string representation of the object in the format 
     *  "name:value" 
     *
     * @return  a string containing the name and value of this TimeSpanUnit object.
     *
     */
    public String toString() {
        return name + ":" + value;
    }
    /** Returns a hash code value for the object. This method is
     *  supported for the benefit of hashtables such as those provided by
     *  <code>java.util.Hashtable</code>. The method returns the value 
     *  of the TimeSpanUnit.
     *
     * @return  a hash code value for this object.
     *
     * @see     java.lang.Object#equals(java.lang.Object)
     * @see     java.util.Hashtable
     *
     */
    public int hashCode() {
        return value;
    }
    interface TimeSpanConstants {
        /** Constant for milliseconds unit and conversion */
        int MILLISECONDS = 1;    
        /** Constant for seconds unit and conversion */
        int SECONDS = MILLISECONDS * 1000;
        /** Constant for minutes unit and conversion */
        int MINUTES = SECONDS * 60;
        /** Constant for hours unit and conversion */
        int HOURS = MINUTES * 60;    
        /** Constant for days unit and conversion */
        int DAYS = HOURS * 24;
    }
}

[ March 26, 2003: Message edited by: Thomas Paul ]