Skip to content
Permalink
Browse files
GEOMETRY-146: adding near/far methods to PointMap and PointSet
  • Loading branch information
darkma773r committed Apr 23, 2022
1 parent 6c6d046 commit ffc9ff964654948aab93438dff8b8a2bbdab03d7
Showing 31 changed files with 3,351 additions and 191 deletions.
@@ -16,6 +16,7 @@
*/
package org.apache.commons.geometry.core.collection;

import java.util.Collection;
import java.util.Map;

import org.apache.commons.geometry.core.Point;
@@ -24,18 +25,58 @@
* use in cases where effectively equivalent (but not necessarily equal) points must
* map to the same entry. As such, this interface breaks the strict contract for
* {@link Map} where key equality is consistent with {@link Object#equals(Object)}.
*
* <p><strong>Distance Ordering</strong></p>
* <p>For methods such as {@link #nearestEntry(Point)} and {@link #entriesNearToFar(Point)}
* that order entries by distance, implementations are free to choose the criteria used to
* break ties in distance. For example, if entries {@code A} and {@code B} have keys at equal
* distances from point {@code P}, implementations may choose to return either {@code A} or
* {@code B} for {@code map.nearestEntry(P)}.
* </p>
* @param <P> Point type
* @param <V> Value type
*/
public interface PointMap<P extends Point<P>, V> extends Map<P, V> {

/** Get the map entry with a key equivalent to {@code pt} or {@code null}
* if no such entry exists. The returned instance supports use of
* the {@link Map.Entry#setValue(Object)} method to modify the
* the {@link Entry#setValue(Object)} method to modify the
* mapping.
* @param pt point to fetch the map entry for
* @return map entry for the given point or null if no such entry
* exists
*/
Map.Entry<P, V> getEntry(P pt);
Entry<P, V> getEntry(P pt);

/** Get the entry from the map with the key nearest to {@code pt} or
* {@code null} if the map is empty.
* @param pt reference point
* @return entry from the map with the key nearest to {@code pt} or
* {@code null} if the map is entry
*/
Entry<P, V> nearestEntry(P pt);

/** Get the entry from the map with the key farthest from {@code pt} or
* {@code null} if the map is empty.
* @param pt reference point
* @return entry from the map with the key farthest to {@code pt} or
* {@code null} if the map is entry
*/
Entry<P, V> farthestEntry(P pt);

/** Get a collection containing the map entries in order of increasing
* distance from {@code pt}.
* @param pt reference point
* @return collection containing the map entries in order of increasing
* distance from {@code pt}
*/
Collection<Entry<P, V>> entriesNearToFar(P pt);

/** Get a collection containing the map entries in order of decreasing
* distance from {@code pt}.
* @param pt reference point
* @return collection containing the map entries in order of decreasing
* distance from {@code pt}
*/
Collection<Entry<P, V>> entriesFarToNear(P pt);
}
@@ -16,6 +16,7 @@
*/
package org.apache.commons.geometry.core.collection;

import java.util.Collection;
import java.util.Set;

import org.apache.commons.geometry.core.Point;
@@ -24,15 +25,55 @@
* use in cases where effectively equivalent (but not necessarily equal) points must
* be considered as equal by the set. As such, this interface breaks the strict contract
* for {@link Set} where membership is consistent with {@link Object#equals(Object)}.
*
* <p><strong>Distance Ordering</strong></p>
* <p>For methods such as {@link #nearest(Point)} and {@link #nearToFar(Point)}
* that order elements by distance, implementations are free to choose the criteria used to
* break ties in distance. For example, if points {@code A} and {@code B} are at equal distances
* from {@code P}, implementations may choose to return either {@code A} or {@code B} for
* {@code map.nearest(P)}.
* </p>
* @param <P> Point type
*/
public interface PointSet<P extends Point<P>> extends Set<P> {

/** Get the set entry equivalent to {@code pt} or null if no
* such entry exists.
/** Get the element equivalent to {@code pt} or null if no
* such an element exists.
* @param pt point to find an equivalent for
* @return set entry equivalent to {@code pt} or null if
* no such entry exists
*/
P get(P pt);

/** Get the element from the set nearest to {@code pt} or {@code null}
* if the set is empty.
* @param pt reference point
* @return the element from the set nearest to {@code pt} or {@code null}
* if the set is empty
*/
P nearest(P pt);

/** Get the element from the set farthest to {@code pt} or {@code null}
* if the set is empty.
* @param pt reference point
* @return the element from the set farthest to {@code pt} or {@code null}
* if the set is empty
*/
P farthest(P pt);

/** Get a collection containing the set elements in order of increasing
* distance from {@code pt}.
* @param pt reference point
* @return collection containing the set elements in order of increasing
* distance from {@code pt}
*/
Collection<P> nearToFar(P pt);

/** Get a collection containing the set elements in order of decreasing
* distance from {@code pt}.
* @param pt reference point
* @return collection containing the set elements in order of decreasing
* distance from {@code pt}
*/
Collection<P> farToNear(P pt);
}

0 comments on commit ffc9ff9

Please sign in to comment.