org.opensha.commons.data
Class Point2DToleranceComparator

java.lang.Object
  org.opensha.commons.data.Point2DToleranceComparator

All Implemented Interfaces:

Serializable, Comparator<Point2D>, Point2DComparator

public class Point2DToleranceComparator
extends Object
implements Point2DComparator, 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(Point2D o1, 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(Point2D o1,
                   Point2D o2)
            throws 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 Comparator<Point2D>

Parameters:

o1 - First DataPoint2D

o2 - Second DataPoint2D

Returns:

-1 if o1 < 02, 0 if o1 = o2, +1 if o1 > o2

Throws:

ClassCastException - Thrown if either passed in arg is not a DataPoint2D