sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1793548 - /sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/geometry/AbstractEnvelope.java
Date Tue, 02 May 2017 16:01:10 GMT
Author: desruisseaux
Date: Tue May  2 16:01:09 2017
New Revision: 1793548

URL: http://svn.apache.org/viewvc?rev=1793548&view=rev
Log:
Remove the warning in the documentation. Instead, document 'intersects(Envelope, boolean)'
in terms of "intersects" and "touches" operation.
https://issues.apache.org/jira/browse/SIS-172

Modified:
    sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/geometry/AbstractEnvelope.java

Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/geometry/AbstractEnvelope.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/geometry/AbstractEnvelope.java?rev=1793548&r1=1793547&r2=1793548&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/geometry/AbstractEnvelope.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/geometry/AbstractEnvelope.java
[UTF-8] Tue May  2 16:01:09 2017
@@ -730,6 +730,9 @@ public abstract class AbstractEnvelope i
 
     /**
      * Returns {@code true} if this envelope completely encloses the specified envelope.
+     * The default implementation delegates to:
+     *
+     * <blockquote><pre>{@linkplain #contains(Envelope, boolean) contains}(envelope,
<b>true</b>)</pre></blockquote>
      *
      * <div class="section">Pre-conditions</div>
      * This method assumes that the specified envelope uses the same CRS than this envelope.
@@ -764,10 +767,6 @@ public abstract class AbstractEnvelope i
      * <p>This method is subject to the same pre-conditions than {@link #contains(Envelope)},
      * and handles envelopes spanning the anti-meridian in the same way.</p>
      *
-     * <div class="warning"><b>Warning:</b> This method may change or be
removed in a future SIS version.
-     * For API stability, use the {@link #contains(Envelope)} method instead.
-     * See <a href="http://issues.apache.org/jira/browse/SIS-172">SIS-172</a>
for more information.</div>
-     *
      * @param  envelope        the envelope to test for inclusion.
      * @param  edgesInclusive  {@code true} if this envelope edges are inclusive.
      * @return {@code true} if this envelope completely encloses the specified one.
@@ -848,6 +847,11 @@ public abstract class AbstractEnvelope i
 
     /**
      * Returns {@code true} if this envelope intersects the specified envelope.
+     * This method returns {@code true} if two envelope <em>interiors</em> have
at least one point in common
+     * (in other words, their intersection is non-{@linkplain #isEmpty() empty}).
+     * The default implementation delegates to:
+     *
+     * <blockquote><pre>{@linkplain #intersects(Envelope, boolean) intersects}(envelope,
<b>false</b>)</pre></blockquote>
      *
      * <div class="section">Pre-conditions</div>
      * This method assumes that the specified envelope uses the same CRS than this envelope.
@@ -867,31 +871,36 @@ public abstract class AbstractEnvelope i
      * @since 0.4
      */
     public boolean intersects(final Envelope envelope) throws MismatchedDimensionException
{
-        return intersects(envelope, true);
+        return intersects(envelope, false);
     }
 
     /**
-     * Returns {@code true} if this envelope intersects the specified envelope.
-     * If one or more edges from the specified envelope coincide with an edge from this envelope,
-     * then this method returns {@code true} only if {@code edgesInclusive} is {@code true}.
-     *
-     * <p>This method is subject to the same pre-conditions than {@link #intersects(Envelope)},
-     * and handles envelopes spanning the anti-meridian in the same way.</p>
+     * Returns {@code true} if this envelope intersects or (optionally) touches the specified
envelope.
+     * The {@code touch} argument controls the value to return if only the envelope boundaries
+     * (not the interiors) have a point in common:
+     *
+     * <ul>
+     *   <li>If {@code false}, this method returns {@code true} if the intersection
between the two envelopes
+     *       is non-{@linkplain #isEmpty() empty} (i.e. the envelope <em>interiors</em>
have points in common).
+     *       This is the usual definition of {@code intersects} operation.</li>
+     *   <li>If {@code true}, this method returns {@code true} if the two envelopes
intersect each other
+     *       <em>or</em> touch each other.</li>
+     * </ul>
      *
-     * <div class="warning"><b>Warning:</b> This method may change or be
removed in a future SIS version.
-     * For API stability, use the {@link #intersects(Envelope)} method instead.
-     * See <a href="http://issues.apache.org/jira/browse/SIS-172">SIS-172</a>
for more information.</div>
+     * This method is subject to the same pre-conditions than {@link #intersects(Envelope)},
+     * and handles envelopes spanning the anti-meridian in the same way.
      *
-     * @param  envelope        the envelope to test for intersection.
-     * @param  edgesInclusive  {@code true} if this envelope edges are inclusive.
-     * @return {@code true} if this envelope intersects the specified one.
-     * @throws MismatchedDimensionException if the specified envelope doesn't have the expected
dimension.
+     * @param  envelope  the envelope to test for intersection.
+     * @param  touch     the value to return if the two envelopes touch each other.
+     * @return {@code true} if this envelope intersects the specified envelope, or
+     *         {@code touch} if this envelope touches the specified envelope, or {@code false}
otherwise.
+     * @throws MismatchedDimensionException if the specified envelope does not have the expected
dimension.
      * @throws AssertionError if assertions are enabled and the envelopes have mismatched
CRS.
      *
      * @see #contains(Envelope, boolean)
      * @see #equals(Envelope, double, boolean)
      */
-    public boolean intersects(final Envelope envelope, final boolean edgesInclusive) throws
MismatchedDimensionException {
+    public boolean intersects(final Envelope envelope, final boolean touch) throws MismatchedDimensionException
{
         ensureNonNull("envelope", envelope);
         final int dimension = getDimension();
         ensureDimensionMatches("envelope", dimension, envelope);
@@ -905,7 +914,7 @@ public abstract class AbstractEnvelope i
             final double lower1 = lowerCorner.getOrdinate(i);
             final double upper1 = upperCorner.getOrdinate(i);
             final boolean lowerCondition, upperCondition;
-            if (edgesInclusive) {
+            if (touch) {
                 lowerCondition = (lower1 <= upper0);
                 upperCondition = (upper1 >= lower0);
             } else {
@@ -937,7 +946,7 @@ public abstract class AbstractEnvelope i
             }
             // The check for ArrayEnvelope.class is for avoiding never-ending callbacks.
             assert envelope.getClass() == ArrayEnvelope.class || hasNaN(envelope) ||
-                    !contains(new ArrayEnvelope(envelope), edgesInclusive) : envelope;
+                    !contains(new ArrayEnvelope(envelope), touch) : envelope;
             return false;
         }
         return true;



Mime
View raw message