GEOMETRY-146: adding near/far methods to PointMap and PointSet

commons-geometry-core/src/main/java/org/apache/commons/geometry/core/collection/PointMap.java

@@ -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);
 }

commons-geometry-core/src/main/java/org/apache/commons/geometry/core/collection/PointSet.java

@@ -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);
 }