sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1448992 - in /sis/branches/JDK7/sis-utility/src: main/java/org/apache/sis/util/collection/RangeSet.java test/java/org/apache/sis/util/collection/RangeSetTest.java
Date Fri, 22 Feb 2013 11:13:21 GMT
Author: desruisseaux
Date: Fri Feb 22 11:13:20 2013
New Revision: 1448992

URL: http://svn.apache.org/r1448992
Log:
Documentation about the java.util.Date case, with corresponding getMin/MaxLong(int) methods.

Modified:
    sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/collection/RangeSet.java
    sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/util/collection/RangeSetTest.java

Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/collection/RangeSet.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/collection/RangeSet.java?rev=1448992&r1=1448991&r2=1448992&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/collection/RangeSet.java
(original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/collection/RangeSet.java
Fri Feb 22 11:13:20 2013
@@ -63,34 +63,41 @@ import static org.apache.sis.util.Number
  * this {@code RangeSet} class and override the {@link #add(Range)}, {@link #remove(Object)}
and
  * {@link newRange(Comparable, Comparable)} methods.
  *
- * {@note Current implementation does not yet support open intervals. The intervals shall
be either
+ * {@note Current implementation does not yet support open intervals. The ranges shall be
either
  * closed intervals, or half-open. This limitation exists because supporting open intervals
implies
  * that the internal array shall support duplicated values.}
  *
  * {@section Extensions to <code>SortedSet</code> API}
- * This class contains some methods not found in standard {@link SortedSet} API:
+ * This class contains some methods not found in standard {@link SortedSet} API.
+ * Some of those methods look like {@link java.util.List} API, in that they work
+ * with the index of a {@code Range} instance in the sequence of ranges returned
+ * by the iterator.
+ *
  * <ul>
- *   <li>{@link java.util.List}-like methods, provided for performance reasons:
- *     <ul>
- *       <li>{@link #getMinDouble(int)} and {@link #getMaxDouble(int)}, which return
the
- *           {@code double} value of the end point in the range at the given index.</li>
- *       <li>{@link #indexOfRange(Comparable)}, which returns the index of the range
- *           containing the given value (if any).</li>
- *     </ul></li>
- *   <li>Other methods:
- *     <ul>
- *       <li>{@link #intersect(Range)}, which provides a more convenient way than
- *           {@code subSet(…)}, {@code headSet(…)} and {@code tailSet(…)}
for creating
- *           views over subsets of a {@code RangeSet}.</li>
- *     </ul></li>
+ *   <li>{@link #indexOfRange(Comparable)} returns the index of the range containing
+ *       the given value (if any).</li>
+ *   <li>{@link #getMinDouble(int)} and {@link #getMaxDouble(int)} return the endpoint
values
+ *       in the range at the given index as a {@code double} without the cost of creating
a
+ *       {@link Number} instance.</li>
+ *   <li>{@link #getMinLong(int)} and {@link #getMaxLong(int)} are equivalent to the
above
+ *       methods for the {@code long} primitive type, used mostly for {@link java.util.Date}
+ *       values (see implementation note below).</li>
+ *   <li>{@link #intersect(Range)} provides a more convenient way than {@code subSet(…)},
+ *       {@code headSet(…)} and {@code tailSet(…)} for creating views over subsets
of a
+ *       {@code RangeSet}.</li>
+ *   <li>{@link #trimToSize()} frees unused space.</li>
  * </ul>
  *
  * {@section Implementation note}
  * For efficiency reasons, this set stores the range values in a Java array of primitive
type if
- * possible. The instances given in argument to the {@link #add(Range)} method are not retained
by
- * this class. Ranges are recreated during iterations by calls to the {@link #newRange(Comparable,
- * Comparable)} method. Subclasses can override that method if they need to customize the
range
- * objects to be created.
+ * possible. The {@code Range} instances given in argument to the {@link #add(Range)} method
are
+ * not retained by this class. Ranges are recreated during iterations by calls to the
+ * {@link #newRange(Comparable, Comparable)} method. Subclasses can override that method
if they
+ * need to customize the range objects to be created.
+ *
+ * <p>While it is possible to create {@code RangeSet<Date>} instances, is is
more efficient to
+ * use {@code RangeSet<Long>} with millisecond values because {@code RangeSet} will
internally
+ * use {@code long[]} arrays in the later case.</p>
  *
  * @param <E> The type of range elements.
  *
@@ -1281,9 +1288,28 @@ public class RangeSet<E extends Comparab
     }
 
     /**
+     * Returns a {@linkplain Range#getMinValue() range minimum value} as a {@code long}.
+     * The {@code index} can be any value from 0 inclusive to the set {@link #size() size}
+     * exclusive. The returned values always increase with {@code index}.
+     * Widening conversions are performed as needed.
+     *
+     * @param  index The range index, from 0 inclusive to {@link #size() size} exclusive.
+     * @return The minimum value for the range at the specified index, inclusive.
+     * @throws IndexOutOfBoundsException if {@code index} is out of bounds.
+     * @throws ClassCastException if range elements are not convertible to {@code long}.
+     */
+    public long getMinLong(int index) throws IndexOutOfBoundsException, ClassCastException
{
+        if ((index *= 2) >= length) {
+            throw new IndexOutOfBoundsException();
+        }
+        return Array.getLong(array, index);
+    }
+
+    /**
      * Returns a {@linkplain Range#getMinValue() range minimum value} as a {@code double}.
      * The {@code index} can be any value from 0 inclusive to the set {@link #size() size}
      * exclusive. The returned values always increase with {@code index}.
+     * Widening conversions are performed as needed.
      *
      * @param  index The range index, from 0 inclusive to {@link #size() size} exclusive.
      * @return The minimum value for the range at the specified index, inclusive.
@@ -1300,9 +1326,28 @@ public class RangeSet<E extends Comparab
     }
 
     /**
+     * Returns a {@linkplain Range#getMaxValue() range maximum value} as a {@code long}.
+     * The {@code index} can be any value from 0 inclusive to the set {@link #size() size}
+     * exclusive. The returned values always increase with {@code index}.
+     * Widening conversions are performed as needed.
+     *
+     * @param  index The range index, from 0 inclusive to {@link #size() size} exclusive.
+     * @return The maximum value for the range at the specified index, inclusive.
+     * @throws IndexOutOfBoundsException if {@code index} is out of bounds.
+     * @throws ClassCastException if range elements are not convertible to {@code long}.
+     */
+    public long getMaxLong(int index) throws IndexOutOfBoundsException, ClassCastException
{
+        if ((index *= 2) >= length) {
+            throw new IndexOutOfBoundsException();
+        }
+        return Array.getLong(array, index + 1);
+    }
+
+    /**
      * Returns a {@linkplain Range#getMaxValue() range maximum value} as a {@code double}.
      * The {@code index} can be any value from 0 inclusive to the set's {@link #size size}
      * exclusive. The returned values always increase with {@code index}.
+     * Widening conversions are performed as needed.
      *
      * @param  index The range index, from 0 inclusive to {@link #size size} exclusive.
      * @return The maximum value for the range at the specified index, exclusive.

Modified: sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/util/collection/RangeSetTest.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/util/collection/RangeSetTest.java?rev=1448992&r1=1448991&r2=1448992&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/util/collection/RangeSetTest.java
(original)
+++ sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/util/collection/RangeSetTest.java
Fri Feb 22 11:13:20 2013
@@ -236,6 +236,25 @@ public final strictfp class RangeSetTest
     }
 
     /**
+     * Tests the {@link RangeSet#getMinLong(int)}, {@link RangeSet#getMaxLong(int)},
+     * {@link RangeSet#getMinDouble(int)} and {@link RangeSet#getMaxDouble(int)} methods.
+     */
+    @Test
+    public void testGetAsPrimitiveType() {
+        final RangeSet<Integer> ranges = RangeSet.create(Integer.class, true, false);
+        assertTrue(ranges.add( -5,  25));
+        assertTrue(ranges.add(-20, -10));
+        assertEquals(-20L,  ranges.getMinLong(0));
+        assertEquals(-10L,  ranges.getMaxLong(0));
+        assertEquals( -5L,  ranges.getMinLong(1));
+        assertEquals( 25L,  ranges.getMaxLong(1));
+        assertEquals(-20.0, ranges.getMinDouble(0), 0.0);
+        assertEquals(-10.0, ranges.getMaxDouble(0), 0.0);
+        assertEquals( -5.0, ranges.getMinDouble(1), 0.0);
+        assertEquals( 25.0, ranges.getMaxDouble(1), 0.0);
+    }
+
+    /**
      * Tests the {@link RangeSet#intersect(Range)} method. The {@code subSet(…)}, {@code
headSet(…)}
      * and {@code tailSet(…)} methods delegate their work to that {@code intersect(…)}
method.
      */



Mime
View raw message