commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From er...@apache.org
Subject svn commit: r1409475 - in /commons/proper/math/trunk/src: main/java/org/apache/commons/math3/util/ResizableDoubleArray.java test/java/org/apache/commons/math3/util/ResizableDoubleArrayTest.java
Date Wed, 14 Nov 2012 22:13:54 GMT
Author: erans
Date: Wed Nov 14 22:13:54 2012
New Revision: 1409475

URL: http://svn.apache.org/viewvc?rev=1409475&view=rev
Log:
MATH-894
Added new "protected" (and not "synchronized") methods to allow access to
the internal array for subclasses only.
Javadoc formatting.

Modified:
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/util/ResizableDoubleArray.java
    commons/proper/math/trunk/src/test/java/org/apache/commons/math3/util/ResizableDoubleArrayTest.java

Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/util/ResizableDoubleArray.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/util/ResizableDoubleArray.java?rev=1409475&r1=1409474&r2=1409475&view=diff
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/util/ResizableDoubleArray.java
(original)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/util/ResizableDoubleArray.java
Wed Nov 14 22:13:54 2012
@@ -33,19 +33,20 @@ import org.apache.commons.math3.exceptio
  * are added and removed.
  * </p>
  * <p>
- *  The internal storage array starts with capacity determined by the
- * <code>initialCapacity</code> property, which can be set by the constructor.
+ * The internal storage array starts with capacity determined by the
+ * {@code initialCapacity} property, which can be set by the constructor.
  * The default initial capacity is 16.  Adding elements using
- * {@link #addElement(double)} appends elements to the end of the array.  When
- * there are no open entries at the end of the internal storage array, the
- * array is expanded.  The size of the expanded array depends on the
- * <code>expansionMode</code> and <code>expansionFactor</code> properties.
- * The <code>expansionMode</code> determines whether the size of the array is
- * multiplied by the <code>expansionFactor</code> (MULTIPLICATIVE_MODE) or if
- * the expansion is additive (ADDITIVE_MODE -- <code>expansionFactor</code>
- * storage locations added).  The default <code>expansionMode</code> is
- * MULTIPLICATIVE_MODE and the default <code>expansionFactor</code>
- * is 2.0.
+ * {@link #addElement(double)} appends elements to the end of the array.
+ * When there are no open entries at the end of the internal storage array,
+ * the array is expanded.  The size of the expanded array depends on the
+ * {@code expansionMode} and {@code expansionFactor} properties.
+ * The {@code expansionMode} determines whether the size of the array is
+ * multiplied by the {@code expansionFactor}
+ * ({@link ExpansionMode#MULTIPLICATIVE}) or if the expansion is additive
+ * ({@link ExpansionMode#ADDITIVE} -- {@code expansionFactor} storage
+ * locations added).
+ * The default {@code expansionMode} is {@code MULTIPLICATIVE} and the default
+ * {@code expansionFactor} is 2.
  * </p>
  * <p>
  * The {@link #addElementRolling(double)} method adds a new element to the end
@@ -56,23 +57,23 @@ import org.apache.commons.math3.exceptio
  * the storage locations at the beginning of the internal storage array.  To
  * reclaim this storage, each time one of these methods is activated, the size
  * of the internal storage array is compared to the number of addressable
- * elements (the <code>numElements</code> property) and if the difference
+ * elements (the {@code numElements} property) and if the difference
  * is too large, the internal array is contracted to size
- * <code>numElements + 1.</code>  The determination of when the internal
- * storage array is "too large" depends on the <code>expansionMode</code> and
- * <code>contractionFactor</code> properties.  If  the <code>expansionMode</code>
- * is <code>MULTIPLICATIVE</code>, contraction is triggered when the
- * ratio between storage array length and <code>numElements</code> exceeds
- * <code>contractionFactor.</code>  If the <code>expansionMode</code>
- * is <code>ADDITIVE</code>, the number of excess storage locations
- * is compared to <code>contractionFactor.</code>
+ * {@code numElements + 1}.  The determination of when the internal
+ * storage array is "too large" depends on the {@code expansionMode} and
+ * {@code contractionFactor} properties.  If  the {@code expansionMode}
+ * is {@code MULTIPLICATIVE}, contraction is triggered when the
+ * ratio between storage array length and {@code numElements} exceeds
+ * {@code contractionFactor.}  If the {@code expansionMode}
+ * is {@code ADDITIVE}, the number of excess storage locations
+ * is compared to {@code contractionFactor}.
  * </p>
  * <p>
  * To avoid cycles of expansions and contractions, the
- * <code>expansionFactor</code> must not exceed the
- * <code>contractionFactor.</code> Constructors and mutators for both of these
- * properties enforce this requirement, throwing IllegalArgumentException if it
- * is violated.
+ * {@code expansionFactor} must not exceed the {@code contractionFactor}.
+ * Constructors and mutators for both of these properties enforce this
+ * requirement, throwing a {@code MathIllegalArgumentException} if it is
+ * violated.
  * </p>
  * @version $Id$
  */
@@ -105,15 +106,15 @@ public class ResizableDoubleArray implem
     /**
      * The expansion factor of the array.  When the array needs to be expanded,
      * the new array size will be
-     * <code>internalArray.length * expansionFactor</code>
-     * if <code>expansionMode</code> is set to MULTIPLICATIVE_MODE, or
-     * <code>internalArray.length + expansionFactor</code> if
-     * <code>expansionMode</code> is set to ADDITIVE_MODE.
+     * {@code internalArray.length * expansionFactor}
+     * if {@code expansionMode} is set to MULTIPLICATIVE_MODE, or
+     * {@code internalArray.length + expansionFactor} if
+     * {@code expansionMode} is set to ADDITIVE_MODE.
      */
     private float expansionFactor = 2.0f;
 
     /**
-     * Determines whether array expansion by <code>expansionFactor</code>
+     * Determines whether array expansion by {@code expansionFactor}
      * is additive or multiplicative.
      */
     private ExpansionMode expansionMode = ExpansionMode.MULTIPLICATIVE;
@@ -137,9 +138,8 @@ public class ResizableDoubleArray implem
 
     /**
      * The position of the first addressable element in the internal storage
-     * array.  The addressable elements in the array are <code>
-     * internalArray[startIndex],...,internalArray[startIndex + numElements -1]
-     * </code>
+     * array.  The addressable elements in the array are
+     * {@code internalArray[startIndex],...,internalArray[startIndex + numElements - 1]}.
      */
     private int startIndex = 0;
 
@@ -162,8 +162,7 @@ public class ResizableDoubleArray implem
      *  <li>{@code contractionFactor = 2.5}</li>
      * </ul>
      */
-    public ResizableDoubleArray()
-        throws MathIllegalArgumentException {
+    public ResizableDoubleArray() {
         this(DEFAULT_INITIAL_CAPACITY);
     }
 
@@ -761,6 +760,44 @@ public class ResizableDoubleArray implem
     }
 
     /**
+     * Provides <em>direct</em> access to the internal storage array.
+     * Please note that this method returns a reference to this object's
+     * storage array, not a copy.
+     * <br/>
+     * To correctly address elements of the array, the "start index" is
+     * required (available via the {@link #getStartIndex() getStartIndex}
+     * method.
+     * <br/>
+     * This method should only be used to avoid copying the internal array.
+     * The returned value <em>must</em> be used for reading only; other
+     * uses could lead to this object becoming inconsistent.
+     * <br/>
+     * The {@link #getElements} method has no such limitation since it
+     * returns a copy of this array's addressable elements.
+     *
+     * @return the internal storage array used by this object.
+     * @since 3.1
+     */
+    protected double[] getArrayRef() {
+        return internalArray;
+    }
+
+    /**
+     * Returns the "start index" of the internal array.
+     * This index is the position of the first addressable element in the
+     * internal storage array.
+     * The addressable elements in the array are at indices contained in
+     * the interval [{@link #getStartIndex()},
+     *               {@link #getStartIndex()} + {@link #getNumElements()} - 1].
+     *
+     * @return the start index.
+     * @since 3.1
+     */
+    protected int getStartIndex() {
+        return startIndex;
+    }
+
+    /**
      * Sets the contraction criteria.
      *
      * @param contractionCriteria contraction criteria

Modified: commons/proper/math/trunk/src/test/java/org/apache/commons/math3/util/ResizableDoubleArrayTest.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/test/java/org/apache/commons/math3/util/ResizableDoubleArrayTest.java?rev=1409475&r1=1409474&r2=1409475&view=diff
==============================================================================
--- commons/proper/math/trunk/src/test/java/org/apache/commons/math3/util/ResizableDoubleArrayTest.java
(original)
+++ commons/proper/math/trunk/src/test/java/org/apache/commons/math3/util/ResizableDoubleArrayTest.java
Wed Nov 14 22:13:54 2012
@@ -541,6 +541,23 @@ public class ResizableDoubleArrayTest ex
 
     }
 
+    @Test
+    public void testGetArrayRef() {
+        final ResizableDoubleArray a = new ResizableDoubleArray();
+
+        // Modify "a" through the public API.
+        final int index = 20;
+        final double v1 = 1.2;
+        a.setElement(index, v1);
+
+        // Modify the internal storage through the protected API.
+        final double v2 = v1 + 3.4;
+        final double[] aInternalArray = a.getArrayRef();
+        aInternalArray[a.getStartIndex() + index] = v2;
+
+        Assert.assertEquals(v2, a.getElement(index), 0d);
+    }
+
     private void verifyEquality(ResizableDoubleArray a, ResizableDoubleArray b) {
         Assert.assertTrue(b.equals(a));
         Assert.assertTrue(a.equals(b));



Mime
View raw message