org.opensha.commons.data
Class Point2DToleranceComparator

java.lang.Object
  extended by org.opensha.commons.data.Point2DToleranceComparator
All Implemented Interfaces:
java.io.Serializable, java.util.Comparator<java.awt.geom.Point2D>, Point2DComparator

public class Point2DToleranceComparator
extends java.lang.Object
implements Point2DComparator, java.io.Serializable

Title: DataPoint2DComparatorAPI

Description: Implementing comparator of DataPoint2d. The comparator uses a tolerance to specify that when two values are within tolerance of each other, they are equal

This class sounds more complicated that it really is. The whole purpose is for calling the function compare(Object o1, Object o2). The x-coordinates are obtained from each, then this algorythmn determines if the x-values are equal:

Math.abs( x1 - x2 ) <= tolerance)

A tolerance=0 is actually abaout 1e-16 due to the numerical precision of floating point arithmetic (1.0 + 1e-16 = 1.0 )

Note: In general comparators are created so that you can have more than one sorting for a class. Imagine that you have a Javabean with 4 fields, id, first name, last name, date created. Typical for a user record in a database. Now you can build the compareTo() function inside this Javabean, nut then you can only sort on 1 column. What if you present these javabeans in a GUI List, and you want to sort on any field by clicking on the header. You simply make 4 comparators, one for each field. Each header would use the particular comparator for the sorting function. Very nice design pattern.

Now let's say you add another field. You simply make a new Comparator ( almost copy and paste). You don't have to change youre Javabean or your sorting function. Just pass in this new comparator.

Version:
1.0
Author:
Steven W. Rock
See Also:
Point2DComparator, Serialized Form

Field Summary
protected  double tolerance
          The tolerance for determining whether two x values are different.
 
Constructor Summary
Point2DToleranceComparator()
          No-Argument constructor.
Point2DToleranceComparator(double tolerance)
          Constructor that sets the tolerance when created.
 
Method Summary
 int compare(java.awt.geom.Point2D o1, java.awt.geom.Point2D o2)
          Returns 0 if the two Objects are equal, -1 if the first object is less than the second, or +1 if it's greater.
 double getTolerance()
          Tolerance indicates the distance two values can be apart, but still considered equal.
 void setTolerance(double newTolerance)
          Tolerance indicates the distance two values can be apart, but still considered equal.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface java.util.Comparator
equals
 

Field Detail

tolerance

protected double tolerance
The tolerance for determining whether two x values are different. A tolerance of 0.0 (the default) is really about 1e-16 due to the numerical precision of floating point arithmetic ( 1.0 - (1.0+1e-16) = 0.0 ). Note that the tolerance must be smaller than 1/2 of any desired delta between data points. If the tolerance is less than zero an InvalidRangeException is thrown

Constructor Detail

Point2DToleranceComparator

public Point2DToleranceComparator()
                           throws InvalidRangeException
No-Argument constructor. Does nothing but construct the class instance.

Throws:
InvalidRangeException

Point2DToleranceComparator

public Point2DToleranceComparator(double tolerance)
                           throws InvalidRangeException
Constructor that sets the tolerance when created. Throws an InvalidRangeException if the tolerance is less than zero. Negative tolerance makes no sense.

Parameters:
tolerance - The distance two values can be apart and still considered equal
Throws:
InvalidRangeException - Thrown if tolerance is negative
Method Detail

setTolerance

public void setTolerance(double newTolerance)
                  throws InvalidRangeException
Tolerance indicates the distance two values can be apart, but still considered equal. This function returns the tolerance. Any tolerance less than about 1e-16 is about 1e-16 due to the numerical precision of floating point arithmetic.

Specified by:
setTolerance in interface Point2DComparator
Parameters:
newTolerance - The new tolerance value
Throws:
InvalidRangeException - Thrown if tolerance is negative

getTolerance

public double getTolerance()
Tolerance indicates the distance two values can be apart, but still considered equal. This function returns the tolerance.

Specified by:
getTolerance in interface Point2DComparator
Returns:
The tolerance value

compare

public int compare(java.awt.geom.Point2D o1,
                   java.awt.geom.Point2D o2)
            throws java.lang.ClassCastException
Returns 0 if the two Objects are equal, -1 if the first object is less than the second, or +1 if it's greater. This function throws a ClassCastException if the two values are not DataPoint2Ds. Only the X-Value is compared, the Y-Value is ignored. If the distance between the two X-Values are less than or equal to the tolerance, they are considered equal.

One use for this class is to sort a DiscretizedFunction by it's X-Values (independent variable) ascending, to prepare the function for plotting.

Specified by:
compare in interface java.util.Comparator<java.awt.geom.Point2D>
Parameters:
o1 - First DataPoint2D
o2 - Second DataPoint2D
Returns:
-1 if o1 < 02, 0 if o1 = o2, +1 if o1 > o2
Throws:
java.lang.ClassCastException - Thrown if either passed in arg is not a DataPoint2D