harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From qi...@apache.org
Subject svn commit: r768698 [17/18] - in /harmony/enhanced/classlib/branches/java6: ./ modules/annotation/src/main/java/java/lang/annotation/ modules/archive/src/main/java/java/util/jar/ modules/archive/src/main/java/java/util/zip/ modules/auth/src/main/java/c...
Date Sun, 26 Apr 2009 12:30:06 GMT
Modified: harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/BigInteger.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/BigInteger.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/BigInteger.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/BigInteger.java Sun Apr 26 12:30:01 2009
@@ -25,9 +25,24 @@
 
 import org.apache.harmony.math.internal.nls.Messages;
 
+/**
+ * This class represents immutable integer numbers of arbitrary length. Large
+ * numbers are typically used in security applications and therefore BigIntegers
+ * offer dedicated functionality like the generation of large prime numbers or
+ * the computation of modular inverse.
+ * <p>
+ * Since the class was modeled to offer all the functionality as the {@link Integer}
+ * class does, it provides even methods that operate bitwise on a two's
+ * complement representation of large integers. Note however that the
+ * implementations favors an internal representation where magnitude and sign
+ * are treated separately. Hence such operations are inefficient and should be
+ * discouraged. In simple words: Do NOT implement any bit fields based on
+ * BigInteger.
+ */
 public class BigInteger extends Number implements Comparable<BigInteger>,
         Serializable {
 
+    /** This is the serialVersionUID used by the sun implementation. */
     private static final long serialVersionUID = -8287574255936472291L;
 
     /* Fields used for the internal representation. */
@@ -41,12 +56,21 @@
     /** The sign of this. */
     transient int sign;
 
+    /**
+     * The {@code BigInteger} constant 0.
+     */
+    public static final BigInteger ZERO = new BigInteger(0, 0);
+
+    /**
+     * The {@code BigInteger} constant 1.
+     */
     public static final BigInteger ONE = new BigInteger(1, 1);
 
+    /**
+     * The {@code BigInteger} constant 10.
+     */
     public static final BigInteger TEN = new BigInteger(1, 10);
 
-    public static final BigInteger ZERO = new BigInteger(0, 0);
-
     /** The {@code BigInteger} constant -1. */
     static final BigInteger MINUS_ONE = new BigInteger(-1, 1);
 
@@ -59,7 +83,7 @@
     /** The {@code BigInteger} constant -1 used for comparison. */
     static final int LESS = -1;
 
-    /** All the {@ BigInteger} numbers in the range [0,10] are cached. */
+    /** All the {@code BigInteger} numbers in the range [0,10] are cached. */
     static final BigInteger[] SMALL_VALUES = { ZERO, ONE, new BigInteger(1, 2),
             new BigInteger(1, 3), new BigInteger(1, 4), new BigInteger(1, 5),
             new BigInteger(1, 6), new BigInteger(1, 7), new BigInteger(1, 8),
@@ -76,16 +100,26 @@
 
     private transient int firstNonzeroDigit = -2;
 
-    /* Serialized Fields */
-
+    /** sign field, used for serialization. */
     private int signum;
 
+    /** absolute value field, used for serialization */
     private byte[] magnitude;
 
+    /** Cache for the hash code. */
     private transient int hashCode = 0;
 
-    /* Public Constructors */
-
+    /**
+     * Constructs a random non-negative {@code BigInteger} instance in the range
+     * [0, 2^(numBits)-1].
+     *
+     * @param numBits
+     *            maximum length of the new {@code BigInteger} in bits.
+     * @param rnd
+     *            is an optional random generator to be used.
+     * @throws IllegalArgumentException
+     *             if {@code numBits} < 0.
+     */
     public BigInteger(int numBits, Random rnd) {
         if (numBits < 0) {
             // math.1B=numBits must be non-negative
@@ -108,6 +142,20 @@
         }
     }
 
+    /**
+     * Constructs a random {@code BigInteger} instance in the range [0,
+     * 2^(bitLength)-1] which is probably prime. The probability that the
+     * returned {@code BigInteger} is prime is beyond (1-1/2^certainty).
+     *
+     * @param bitLength
+     *            length of the new {@code BigInteger} in bits.
+     * @param certainty
+     *            tolerated primality uncertainty.
+     * @param rnd
+     *            is an optional random generator to be used.
+     * @throws ArithmeticException
+     *             if {@code bitLength} < 2.
+     */
     public BigInteger(int bitLength, int certainty, Random rnd) {
         if (bitLength < 2) {
             // math.1C=bitLength < 2
@@ -119,10 +167,41 @@
         digits = me.digits;
     }
 
+    /**
+     * Constructs a new {@code BigInteger} instance from the string
+     * representation. The string representation consists of an optional minus
+     * sign followed by a non-empty sequence of decimal digits.
+     *
+     * @param val
+     *            string representation of the new {@code BigInteger}.
+     * @throws NullPointerException
+     *             if {@code val == null}.
+     * @throws NumberFormatException
+     *             if {@code val} is not a valid representation of a {@code
+     *             BigInteger}.
+     */
     public BigInteger(String val) {
         this(val, 10);
     }
 
+    /**
+     * Constructs a new {@code BigInteger} instance from the string
+     * representation. The string representation consists of an optional minus
+     * sign followed by a non-empty sequence of digits in the specified radix.
+     * For the conversion the method {@code Character.digit(char, radix)} is
+     * used.
+     *
+     * @param val
+     *            string representation of the new {@code BigInteger}.
+     * @param radix
+     *            the base to be used for the conversion.
+     * @throws NullPointerException
+     *             if {@code val == null}.
+     * @throws NumberFormatException
+     *             if {@code val} is not a valid representation of a {@code
+     *             BigInteger} or if {@code radix < Character.MIN_RADIX} or
+     *             {@code radix > Character.MAX_RADIX}.
+     */
     public BigInteger(String val, int radix) {
         if (val == null) {
             throw new NullPointerException();
@@ -138,6 +217,24 @@
         setFromString(this, val, radix);
     }
 
+    /**
+     * Constructs a new {@code BigInteger} instance with the given sign and the
+     * given magnitude. The sign is given as an integer (-1 for negative, 0 for
+     * zero, 1 for positive). The magnitude is specified as a byte array. The
+     * most significant byte is the entry at index 0.
+     *
+     * @param signum
+     *            sign of the new {@code BigInteger} (-1 for negative, 0 for
+     *            zero, 1 for positive).
+     * @param magnitude
+     *            magnitude of the new {@code BigInteger} with the most
+     *            significant byte first.
+     * @throws NullPointerException
+     *             if {@code magnitude == null}.
+     * @throws NumberFormatException
+     *             if the sign is not one of -1, 0, 1 or if the sign is zero and
+     *             the magnitude contains non-zero entries.
+     */
     public BigInteger(int signum, byte[] magnitude) {
         if (magnitude == null) {
             throw new NullPointerException();
@@ -166,6 +263,19 @@
         }
     }
 
+    /**
+     * Constructs a new {@code BigInteger} from the given two's complement
+     * representation. The most significant byte is the entry at index 0. The
+     * most significant bit of this entry determines the sign of the new {@code
+     * BigInteger} instance. The given array must not be empty.
+     *
+     * @param val
+     *            two's complement representation of the new {@code BigInteger}.
+     * @throws NullPointerException
+     *             if {@code val == null}.
+     * @throws NumberFormatException
+     *             if the length of {@code val} is zero.
+     */
     public BigInteger(byte[] val) {
         if (val.length == 0) {
             // math.12=Zero length BigInteger
@@ -181,8 +291,6 @@
         cutOffLeadingZeroes();
     }
 
-    /* Package Constructors */
-
     /**
      * Constructs a number which array is of size 1.
      * 
@@ -272,6 +380,12 @@
         }
     }
 
+    /**
+     * Returns the two's complement representation of this BigInteger in a byte
+     * array.
+     *
+     * @return two's complement representation of {@code this}.
+     */
     public byte[] toByteArray() {
         if (this.sign == 0) {
             return new byte[] { 0 };
@@ -395,27 +509,76 @@
         bi.cutOffLeadingZeroes();
     }
 
+    /**
+     * Returns a (new) {@code BigInteger} whose value is the absolute value of
+     * {@code this}.
+     *
+     * @return {@code abs(this)}.
+     */
     public BigInteger abs() {
         return ((sign < 0) ? new BigInteger(1, numberLength, digits) : this);
     }
 
+    /**
+     * Returns a new {@code BigInteger} whose value is the {@code -this}.
+     *
+     * @return {@code -this}.
+     */
     public BigInteger negate() {
         return ((sign == 0) ? this
                 : new BigInteger(-sign, numberLength, digits));
     }
 
+    /**
+     * Returns a new {@code BigInteger} whose value is {@code this + val}.
+     *
+     * @param val
+     *            value to be added to {@code this}.
+     * @return {@code this + val}.
+     * @throws NullPointerException
+     *             if {@code val == null}.
+     */
     public BigInteger add(BigInteger val) {
         return Elementary.add(this, val);
     }
 
+    /**
+     * Returns a new {@code BigInteger} whose value is {@code this - val}.
+     *
+     * @param val
+     *            value to be subtracted from {@code this}.
+     * @return {@code this - val}.
+     * @throws NullPointerException
+     *             if {@code val == null}.
+     */
     public BigInteger subtract(BigInteger val) {
         return Elementary.subtract(this, val);
     }
 
+    /**
+     * Returns the sign of this {@code BigInteger}.
+     *
+     * @return {@code -1} if {@code this < 0},
+     *         {@code 0} if {@code this == 0},
+     *         {@code 1} if {@code this > 0}.
+     */
     public int signum() {
         return sign;
     }
 
+    /**
+     * Returns a new {@code BigInteger} whose value is {@code this >> n}. For
+     * negative arguments, the result is also negative. The shift distance may
+     * be negative which means that {@code this} is shifted left.
+     * <p>
+     * <b>Implementation Note:</b> Usage of this method on negative values is
+     * not recommended as the current implementation is not efficient.
+     *
+     * @param n
+     *            shift distance
+     * @return {@code this >> n} if {@code n >= 0}; {@code this << (-n)}
+     *         otherwise
+     */
     public BigInteger shiftRight(int n) {
         if ((n == 0) || (sign == 0)) {
             return this;
@@ -424,6 +587,20 @@
                 this, -n));
     }
 
+    /**
+     * Returns a new {@code BigInteger} whose value is {@code this << n}. The
+     * result is equivalent to {@code this * 2^n} if n >= 0. The shift distance
+     * may be negative which means that {@code this} is shifted right. The
+     * result then corresponds to {@code floor(this / 2^(-n))}.
+     * <p>
+     * <b>Implementation Note:</b> Usage of this method on negative values is
+     * not recommended as the current implementation is not efficient.
+     *
+     * @param n
+     *            shift distance.
+     * @return {@code this << n} if {@code n >= 0}; {@code this >> (-n)}.
+     *         otherwise
+     */
     public BigInteger shiftLeft(int n) {
         if ((n == 0) || (sign == 0)) {
             return this;
@@ -436,10 +613,37 @@
         return (sign == 0) ? this : BitLevel.shiftLeftOneBit(this);
     }
 
+    /**
+     * Returns the length of the value's two's complement representation without
+     * leading zeros for positive numbers / without leading ones for negative
+     * values.
+     * <p>
+     * The two's complement representation of {@code this} will be at least
+     * {@code bitLength() + 1} bits long.
+     * <p>
+     * The value will fit into an {@code int} if {@code bitLength() < 32} or
+     * into a {@code long} if {@code bitLength() < 64}.
+     *
+     * @return the length of the minimal two's complement representation for
+     *         {@code this} without the sign bit.
+     */
     public int bitLength() {
         return BitLevel.bitLength(this);
     }
 
+    /**
+     * Tests whether the bit at position n in {@code this} is set. The result is
+     * equivalent to {@code this & (2^n) != 0}.
+     * <p>
+     * <b>Implementation Note:</b> Usage of this method is not recommended as
+     * the current implementation is not efficient.
+     *
+     * @param n
+     *            position where the bit in {@code this} has to be inspected.
+     * @return {@code this & (2^n) != 0}.
+     * @throws ArithmeticException
+     *             if {@code n < 0}.
+     */
     public boolean testBit(int n) {
         if (n == 0) {
             return ((digits[0] & 1) != 0);
@@ -467,6 +671,20 @@
         return ((digit & n) != 0);
     }
 
+    /**
+     * Returns a new {@code BigInteger} which has the same binary representation
+     * as {@code this} but with the bit at position n set. The result is
+     * equivalent to {@code this | 2^n}.
+     * <p>
+     * <b>Implementation Note:</b> Usage of this method is not recommended as
+     * the current implementation is not efficient.
+     *
+     * @param n
+     *            position where the bit in {@code this} has to be set.
+     * @return {@code this | 2^n}.
+     * @throws ArithmeticException
+     *             if {@code n < 0}.
+     */
     public BigInteger setBit(int n) {
         if (!testBit(n)) {
             return BitLevel.flipBit(this, n);
@@ -474,6 +692,20 @@
         return this;
     }
 
+    /**
+     * Returns a new {@code BigInteger} which has the same binary representation
+     * as {@code this} but with the bit at position n cleared. The result is
+     * equivalent to {@code this & ~(2^n)}.
+     * <p>
+     * <b>Implementation Note:</b> Usage of this method is not recommended as
+     * the current implementation is not efficient.
+     *
+     * @param n
+     *            position where the bit in {@code this} has to be cleared.
+     * @return {@code this & ~(2^n)}.
+     * @throws ArithmeticException
+     *             if {@code n < 0}.
+     */
     public BigInteger clearBit(int n) {
         if (testBit(n)) {
             return BitLevel.flipBit(this, n);
@@ -481,6 +713,20 @@
         return this;
     }
 
+    /**
+     * Returns a new {@code BigInteger} which has the same binary representation
+     * as {@code this} but with the bit at position n flipped. The result is
+     * equivalent to {@code this ^ 2^n}.
+     * <p>
+     * <b>Implementation Note:</b> Usage of this method is not recommended as
+     * the current implementation is not efficient.
+     *
+     * @param n
+     *            position where the bit in {@code this} has to be flipped.
+     * @return {@code this ^ 2^n}.
+     * @throws ArithmeticException
+     *             if {@code n < 0}.
+     */
     public BigInteger flipBit(int n) {
         if (n < 0) {
             // math.15=Negative bit address
@@ -489,6 +735,16 @@
         return BitLevel.flipBit(this, n);
     }
 
+    /**
+     * Returns the position of the lowest set bit in the two's complement
+     * representation of this {@code BigInteger}. If all bits are zero (this=0)
+     * then -1 is returned as result.
+     * <p>
+     * <b>Implementation Note:</b> Usage of this method is not recommended as
+     * the current implementation is not efficient.
+     *
+     * @return position of lowest bit if {@code this != 0}, {@code -1} otherwise
+     */
     public int getLowestSetBit() {
         if (sign == 0) {
             return -1;
@@ -498,35 +754,122 @@
         return ((i << 5) + Integer.numberOfTrailingZeros(digits[i]));
     }
 
+    /**
+     * Use {@code bitLength(0)} if you want to know the length of the binary
+     * value in bits.
+     * <p>
+     * Returns the number of bits in the binary representation of {@code this}
+     * which differ from the sign bit. If {@code this} is positive the result is
+     * equivalent to the number of bits set in the binary representation of
+     * {@code this}. If {@code this} is negative the result is equivalent to the
+     * number of bits set in the binary representation of {@code -this-1}.
+     * <p>
+     * <b>Implementation Note:</b> Usage of this method is not recommended as
+     * the current implementation is not efficient.
+     *
+     * @return number of bits in the binary representation of {@code this} which
+     *         differ from the sign bit
+     */
     public int bitCount() {
         return BitLevel.bitCount(this);
     }
 
+    /**
+     * Returns a new {@code BigInteger} whose value is {@code ~this}. The result
+     * of this operation is {@code -this-1}.
+     * <p>
+     * <b>Implementation Note:</b> Usage of this method is not recommended as
+     * the current implementation is not efficient.
+     *
+     * @return {@code ~this}.
+     */
     public BigInteger not() {
         return Logical.not(this);
     }
 
+    /**
+     * Returns a new {@code BigInteger} whose value is {@code this & val}.
+     * <p>
+     * <b>Implementation Note:</b> Usage of this method is not recommended as
+     * the current implementation is not efficient.
+     *
+     * @param val
+     *            value to be and'ed with {@code this}.
+     * @return {@code this & val}.
+     * @throws NullPointerException
+     *             if {@code val == null}.
+     */
     public BigInteger and(BigInteger val) {
         return Logical.and(this, val);
     }
 
+    /**
+     * Returns a new {@code BigInteger} whose value is {@code this | val}.
+     * <p>
+     * <b>Implementation Note:</b> Usage of this method is not recommended as
+     * the current implementation is not efficient.
+     *
+     * @param val
+     *            value to be or'ed with {@code this}.
+     * @return {@code this | val}.
+     * @throws NullPointerException
+     *             if {@code val == null}.
+     */
     public BigInteger or(BigInteger val) {
         return Logical.or(this, val);
     }
 
+    /**
+     * Returns a new {@code BigInteger} whose value is {@code this ^ val}.
+     * <p>
+     * <b>Implementation Note:</b> Usage of this method is not recommended as
+     * the current implementation is not efficient.
+     *
+     * @param val
+     *            value to be xor'ed with {@code this}
+     * @return {@code this ^ val}
+     * @throws NullPointerException
+     *             if {@code val == null}
+     */
     public BigInteger xor(BigInteger val) {
         return Logical.xor(this, val);
     }
 
+    /**
+     * Returns a new {@code BigInteger} whose value is {@code this & ~val}.
+     * Evaluating {@code x.andNot(val)} returns the same result as {@code
+     * x.and(val.not())}.
+     * <p>
+     * <b>Implementation Note:</b> Usage of this method is not recommended as
+     * the current implementation is not efficient.
+     *
+     * @param val
+     *            value to be not'ed and then and'ed with {@code this}.
+     * @return {@code this & ~val}.
+     * @throws NullPointerException
+     *             if {@code val == null}.
+     */
     public BigInteger andNot(BigInteger val) {
         return Logical.andNot(this, val);
     }
 
+    /**
+     * Returns this {@code BigInteger} as an int value. If {@code this} is too
+     * big to be represented as an int, then {@code this} % 2^32 is returned.
+     *
+     * @return this {@code BigInteger} as an int value.
+     */
     @Override
     public int intValue() {
         return (sign * digits[0]);
     }
 
+    /**
+     * Returns this {@code BigInteger} as an long value. If {@code this} is too
+     * big to be represented as an long, then {@code this} % 2^64 is returned.
+     *
+     * @return this {@code BigInteger} as a long value.
+     */
     @Override
     public long longValue() {
         long value = (numberLength > 1) ? (((long) digits[1]) << 32)
@@ -534,16 +877,48 @@
         return (sign * value);
     }
 
+    /**
+     * Returns this {@code BigInteger} as an float value. If {@code this} is too
+     * big to be represented as an float, then {@code Float.POSITIVE_INFINITY}
+     * or {@code Float.NEGATIVE_INFINITY} is returned. Note, that not all
+     * integers x in the range [-Float.MAX_VALUE, Float.MAX_VALUE] can be
+     * represented as a float. The float representation has a mantissa of length
+     * 24. For example, 2^24+1 = 16777217 is returned as float 16777216.0.
+     *
+     * @return this {@code BigInteger} as a float value.
+     */
     @Override
     public float floatValue() {
         return (float) doubleValue();
     }
 
+    /**
+     * Returns this {@code BigInteger} as an double value. If {@code this} is
+     * too big to be represented as an double, then {@code
+     * Double.POSITIVE_INFINITY} or {@code Double.NEGATIVE_INFINITY} is
+     * returned. Note, that not all integers x in the range [-Double.MAX_VALUE,
+     * Double.MAX_VALUE] can be represented as a double. The double
+     * representation has a mantissa of length 53. For example, 2^53+1 =
+     * 9007199254740993 is returned as double 9007199254740992.0.
+     *
+     * @return this {@code BigInteger} as a double value
+     */
     @Override
     public double doubleValue() {
         return Conversion.bigInteger2Double(this);
     }
 
+    /**
+     * Compares this {@code BigInteger} with {@code val}. Returns one of the
+     * three values 1, 0, or -1.
+     *
+     * @param val
+     *            value to be compared with {@code this}.
+     * @return {@code 1} if {@code this > val}, {@code -1} if {@code this < val}
+     *         , {@code 0} if {@code this == val}.
+     * @throws NullPointerException
+     *             if {@code val == null}.
+     */
     public int compareTo(BigInteger val) {
         if (sign > val.sign) {
             return GREATER;
@@ -562,14 +937,37 @@
                 numberLength));
     }
 
+    /**
+     * Returns the minimum of this {@code BigInteger} and {@code val}.
+     *
+     * @param val
+     *            value to be used to compute the minimum with {@code this}.
+     * @return {@code min(this, val)}.
+     * @throws NullPointerException
+     *             if {@code val == null}.
+     */
     public BigInteger min(BigInteger val) {
         return ((this.compareTo(val) == LESS) ? this : val);
     }
 
+    /**
+     * Returns the maximum of this {@code BigInteger} and {@code val}.
+     *
+     * @param val
+     *            value to be used to compute the maximum with {@code this}
+     * @return {@code max(this, val)}
+     * @throws NullPointerException
+     *             if {@code val == null}
+     */
     public BigInteger max(BigInteger val) {
         return ((this.compareTo(val) == GREATER) ? this : val);
     }
 
+    /**
+     * Returns a hash code for this {@code BigInteger}.
+     *
+     * @return hash code for {@code this}.
+     */
     @Override
     public int hashCode() {
         if (hashCode != 0) {
@@ -582,6 +980,15 @@
         return hashCode;
     }
 
+    /**
+     * Returns {@code true} if {@code x} is a BigInteger instance and if this
+     * instance is equal to this {@code BigInteger}.
+     *
+     * @param x
+     *            object to be compared with {@code this}.
+     * @return true if {@code x} is a BigInteger and {@code this == x},
+     *          {@code false} otherwise.
+     */
     @Override
     public boolean equals(Object x) {
         if (this == x) {
@@ -603,15 +1010,43 @@
         return i < 0;
     }
 
+    /**
+     * Returns a string representation of this {@code BigInteger} in decimal
+     * form.
+     *
+     * @return a string representation of {@code this} in decimal form.
+     */
     @Override
     public String toString() {
         return Conversion.toDecimalScaledString(this, 0);
     }
 
+    /**
+     * Returns a string containing a string representation of this {@code
+     * BigInteger} with base radix. If {@code radix < Character.MIN_RADIX} or
+     * {@code radix > Character.MAX_RADIX} then a decimal representation is
+     * returned. The characters of the string representation are generated with
+     * method {@code Character.forDigit}.
+     *
+     * @param radix
+     *            base to be used for the string representation.
+     * @return a string representation of this with radix 10.
+     */
     public String toString(int radix) {
         return Conversion.bigInteger2String(this, radix);
     }
 
+    /**
+     * Returns a new {@code BigInteger} whose value is greatest common divisor
+     * of {@code this} and {@code val}. If {@code this==0} and {@code val==0}
+     * then zero is returned, otherwise the result is positive.
+     *
+     * @param val
+     *            value with which the greatest common divisor is computed.
+     * @return {@code gcd(this, val)}.
+     * @throws NullPointerException
+     *             if {@code val == null}.
+     */
     public BigInteger gcd(BigInteger val) {
         BigInteger val1 = this.abs();
         BigInteger val2 = val.abs();
@@ -634,6 +1069,15 @@
 
     }
 
+    /**
+     * Returns a new {@code BigInteger} whose value is {@code this * val}.
+     *
+     * @param val
+     *            value to be multiplied with {@code this}.
+     * @return {@code this * val}.
+     * @throws NullPointerException
+     *             if {@code val == null}.
+     */
     public BigInteger multiply(BigInteger val) {
         // This let us to throw NullPointerException when val == null
         if (val.sign == 0) {
@@ -645,6 +1089,15 @@
         return Multiplication.multiply(this, val);
     }
 
+    /**
+     * Returns a new {@code BigInteger} whose value is {@code this ^ exp}.
+     *
+     * @param exp
+     *            exponent to which {@code this} is raised.
+     * @return {@code this ^ exp}.
+     * @throws ArithmeticException
+     *             if {@code exp < 0}.
+     */
     public BigInteger pow(int exp) {
         if (exp < 0) {
             // math.16=Negative exponent
@@ -668,6 +1121,20 @@
         return Multiplication.pow(this, exp);
     }
 
+    /**
+     * Returns a {@code BigInteger} array which contains {@code this / divisor}
+     * at index 0 and {@code this % divisor} at index 1.
+     *
+     * @param divisor
+     *            value by which {@code this} is divided.
+     * @return {@code [this / divisor, this % divisor]}.
+     * @throws NullPointerException
+     *             if {@code divisor == null}.
+     * @throws ArithmeticException
+     *             if {@code divisor == 0}.
+     * @see #divide
+     * @see #remainder
+     */
     public BigInteger[] divideAndRemainder(BigInteger divisor) {
         int divisorSign = divisor.sign;
         if (divisorSign == 0) {
@@ -704,6 +1171,17 @@
         return new BigInteger[] { result0, result1 };
     }
 
+    /**
+     * Returns a new {@code BigInteger} whose value is {@code this / divisor}.
+     *
+     * @param divisor
+     *            value by which {@code this} is divided.
+     * @return {@code this / divisor}.
+     * @throws NullPointerException
+     *             if {@code divisor == null}.
+     * @throws ArithmeticException
+     *             if {@code divisor == 0}.
+     */
     public BigInteger divide(BigInteger divisor) {
         if (divisor.sign == 0) {
             // math.17=BigInteger divide by zero
@@ -747,6 +1225,19 @@
         return result;
     }
 
+    /**
+     * Returns a new {@code BigInteger} whose value is {@code this % divisor}.
+     * Regarding signs this methods has the same behavior as the % operator on
+     * int's, i.e. the sign of the remainder is the same as the sign of this.
+     *
+     * @param divisor
+     *            value by which {@code this} is divided.
+     * @return {@code this % divisor}.
+     * @throws NullPointerException
+     *             if {@code divisor == null}.
+     * @throws ArithmeticException
+     *             if {@code divisor == 0}.
+     */
     public BigInteger remainder(BigInteger divisor) {
         if (divisor.sign == 0) {
             // math.17=BigInteger divide by zero
@@ -773,6 +1264,21 @@
         return result;
     }
 
+    /**
+     * Returns a new {@code BigInteger} whose value is {@code 1/this mod m}. The
+     * modulus {@code m} must be positive. The result is guaranteed to be in the
+     * interval {@code [0, m)} (0 inclusive, m exclusive). If {@code this} is
+     * not relatively prime to m, then an exception is thrown.
+     *
+     * @param m
+     *            the modulus.
+     * @return {@code 1/this mod m}.
+     * @throws NullPointerException
+     *             if {@code m == null}
+     * @throws ArithmeticException
+     *             if {@code m < 0 or} if {@code this} is not relatively prime
+     *             to {@code m}
+     */
     public BigInteger modInverse(BigInteger m) {
         if (m.sign <= 0) {
             // math.18=BigInteger: modulus not positive
@@ -799,6 +1305,25 @@
 
     }
 
+    /**
+     * Returns a new {@code BigInteger} whose value is {@code this^exponent mod
+     * m}. The modulus {@code m} must be positive. The result is guaranteed to
+     * be in the interval {@code [0, m)} (0 inclusive, m exclusive). If the
+     * exponent is negative, then {@code this.modInverse(m)^(-exponent) mod m)}
+     * is computed. The inverse of this only exists if {@code this} is
+     * relatively prime to m, otherwise an exception is thrown.
+     *
+     * @param exponent
+     *            the exponent.
+     * @param m
+     *            the modulus.
+     * @return {@code this^exponent mod val}.
+     * @throws NullPointerException
+     *             if {@code m == null} or {@code exponent == null}.
+     * @throws ArithmeticException
+     *             if {@code m < 0} or if {@code exponent<0} and this is not
+     *             relatively prime to {@code m}.
+     */
     public BigInteger modPow(BigInteger exponent, BigInteger m) {
         if (m.sign <= 0) {
             // math.18=BigInteger: modulus not positive
@@ -827,6 +1352,21 @@
         return res;
     }
 
+    /**
+     * Returns a new {@code BigInteger} whose value is {@code this mod m}. The
+     * modulus {@code m} must be positive. The result is guaranteed to be in the
+     * interval {@code [0, m)} (0 inclusive, m exclusive). The behavior of this
+     * function is not equivalent to the behavior of the % operator defined for
+     * the built-in {@code int}'s.
+     *
+     * @param m
+     *            the modulus.
+     * @return {@code this mod m}.
+     * @throws NullPointerException
+     *             if {@code m == null}.
+     * @throws ArithmeticException
+     *             if {@code m < 0}.
+     */
     public BigInteger mod(BigInteger m) {
         if (m.sign <= 0) {
             // math.18=BigInteger: modulus not positive
@@ -836,10 +1376,31 @@
         return ((rem.sign < 0) ? rem.add(m) : rem);
     }
 
+    /**
+     * Tests whether this {@code BigInteger} is probably prime. If {@code true}
+     * is returned, then this is prime with a probability beyond
+     * (1-1/2^certainty). If {@code false} is returned, then this is definitely
+     * composite. If the argument {@code certainty} <= 0, then this method
+     * returns true.
+     *
+     * @param certainty
+     *            tolerated primality uncertainty.
+     * @return {@code true}, if {@code this} is probably prime, {@code false}
+     *         otherwise.
+     */
     public boolean isProbablePrime(int certainty) {
         return Primality.isProbablePrime(abs(), certainty);
     }
 
+    /**
+     * Returns the smallest integer x > {@code this} which is probably prime as
+     * a {@code BigInteger} instance. The probability that the returned {@code
+     * BigInteger} is prime is beyond (1-1/2^80).
+     *
+     * @return smallest integer > {@code this} which is robably prime.
+     * @throws ArithmeticException
+     *             if {@code this < 0}.
+     */
     public BigInteger nextProbablePrime() {
         if (sign < 0) {
             // math.1A=start < 0: {0}
@@ -848,6 +1409,21 @@
         return Primality.nextProbablePrime(this);
     }
 
+    /**
+     * Returns a random positive {@code BigInteger} instance in the range [0,
+     * 2^(bitLength)-1] which is probably prime. The probability that the
+     * returned {@code BigInteger} is prime is beyond (1-1/2^80).
+     * <p>
+     * <b>Implementation Note:</b> Currently {@code rnd} is ignored.
+     *
+     * @param bitLength
+     *            length of the new {@code BigInteger} in bits.
+     * @param rnd
+     *            random generator used to generate the new {@code BigInteger}.
+     * @return probably prime random {@code BigInteger} instance.
+     * @throws IllegalArgumentException
+     *             if {@code bitLength < 2}.
+     */
     public static BigInteger probablePrime(int bitLength, Random rnd) {
         return new BigInteger(bitLength, 100, rnd);
     }

Modified: harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/BitLevel.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/BitLevel.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/BitLevel.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/BitLevel.java Sun Apr 26 12:30:01 2009
@@ -31,16 +31,12 @@
  * </ul>
  * All operations are provided in immutable way, and some in both mutable and
  * immutable.
- * 
- * @author Intel Middleware Product Division
- * @author Instituto Tecnologico de Cordoba
  */
 class BitLevel {
 
     /** Just to denote that this class can't be instantiated. */
     private BitLevel() {}
 
-
     /** @see BigInteger#bitLength() */
     static int bitLength(BigInteger val) {
         if (val.sign == 0) {

Modified: harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Conversion.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Conversion.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Conversion.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Conversion.java Sun Apr 26 12:30:01 2009
@@ -20,9 +20,6 @@
 /**
  * Static library that provides {@link BigInteger} base conversion from/to any
  * integer represented in an {@link java.lang.String} Object.
- * 
- * @author Intel Middleware Product Division
- * @author Instituto Tecnologico de Cordoba
  */
 class Conversion {
 

Modified: harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Division.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Division.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Division.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Division.java Sun Apr 26 12:30:01 2009
@@ -39,9 +39,6 @@
  * </ul>
  * </li>
  *</ul>
- * 
- * @author Intel Middleware Product Division
- * @author Instituto Tecnologico de Cordoba
  */
 class Division {
 

Modified: harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Elementary.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Elementary.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Elementary.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Elementary.java Sun Apr 26 12:30:01 2009
@@ -26,9 +26,6 @@
  * <li>Comparison.</li>
  * </ul>
  * In addition to this, some <i><b>Inplace</b></i> (mutable) methods are provided.
- * 
- * @author Intel Middleware Product Division
- * @author Instituto Tecnologico de Cordoba
  */
 class Elementary {
 

Modified: harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Logical.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Logical.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Logical.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Logical.java Sun Apr 26 12:30:01 2009
@@ -27,8 +27,6 @@
  * <li>or</li>
  * <li>xor</li>
  * </ul>
- * @author Intel Middleware Product Division
- * @author Instituto Tecnologico de Cordoba
  */
 class Logical {
 

Modified: harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/MathContext.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/MathContext.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/MathContext.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/MathContext.java Sun Apr 26 12:30:01 2009
@@ -25,86 +25,136 @@
 import org.apache.harmony.math.internal.nls.Messages;
 
 /**
- * @author Intel Middleware Product Division
- * @author Instituto Tecnologico de Cordoba
+ * Immutable objects describing settings such as rounding mode and digit
+ * precision for the numerical operations provided by class {@link BigDecimal}.
  */
 public final class MathContext implements Serializable {
 
-    /* Fields */
-
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * A {@code MathContext} which corresponds to the IEEE 754r quadruple
+     * decimal precision format: 34 digit precision and
+     * {@link RoundingMode#HALF_EVEN} rounding.
+     */
     public static final MathContext DECIMAL128 = new MathContext(34,
             RoundingMode.HALF_EVEN);
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * A {@code MathContext} which corresponds to the IEEE 754r single decimal
+     * precision format: 7 digit precision and {@link RoundingMode#HALF_EVEN}
+     * rounding.
+     */
     public static final MathContext DECIMAL32 = new MathContext(7,
             RoundingMode.HALF_EVEN);
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * A {@code MathContext} which corresponds to the IEEE 754r double decimal
+     * precision format: 16 digit precision and {@link RoundingMode#HALF_EVEN}
+     * rounding.
+     */
     public static final MathContext DECIMAL64 = new MathContext(16,
             RoundingMode.HALF_EVEN);
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * A {@code MathContext} for unlimited precision with
+     * {@link RoundingMode#HALF_UP} rounding.
+     */
     public static final MathContext UNLIMITED = new MathContext(0,
             RoundingMode.HALF_UP);
 
-    /** @ar.org.fitc.spec_ref */
+    /** This is the serialVersionUID used by the sun implementation */
     private static final long serialVersionUID = 5579720004786848255L;
 
     /**
-     * The number of digits to be used for an operation; 
-     * results are rounded to this precision.
+     * The number of digits to be used for an operation; results are rounded to
+     * this precision.
      */
     private int precision;
 
     /**
-     * A {@code RoundingMode} object which specifies 
-     * the algorithm to be used for rounding.
+     * A {@code RoundingMode} object which specifies the algorithm to be used
+     * for rounding.
      */
     private RoundingMode roundingMode;
 
-    /** 
-     * An array of {@code char} containing: 
-     * {@code 'p','r','e','c','i','s','i','o','n','='}.
-     * It's used to improve the methods related to {@code String} conversion.
+    /**
+     * An array of {@code char} containing: {@code
+     * 'p','r','e','c','i','s','i','o','n','='}. It's used to improve the
+     * methods related to {@code String} conversion.
+     *
      * @see #MathContext(String)
-     * @see #toString() 
+     * @see #toString()
      */
     private final static char[] chPrecision = { 'p', 'r', 'e', 'c', 'i', 's',
             'i', 'o', 'n', '=' };
 
-    /** 
-     * An array of {@code char} containing: 
-     * {@code 'r','o','u','n','d','i','n','g','M','o','d','e','='}.
-     * It's used to improve the methods related to {@code String} conversion.
+    /**
+     * An array of {@code char} containing: {@code
+     * 'r','o','u','n','d','i','n','g','M','o','d','e','='}. It's used to
+     * improve the methods related to {@code String} conversion.
+     *
      * @see #MathContext(String)
-     * @see #toString() 
+     * @see #toString()
      */
     private final static char[] chRoundingMode = { 'r', 'o', 'u', 'n', 'd',
             'i', 'n', 'g', 'M', 'o', 'd', 'e', '=' };
 
-    /* Constructors */
-
-    /** @ar.org.fitc.spec_ref */
-    public MathContext(int setPrecision) {
-        this(setPrecision, RoundingMode.HALF_UP);
+    /**
+     * Constructs a new {@code MathContext} with the specified precision and
+     * with the rounding mode {@link RoundingMode#HALF_UP HALF_UP}. If the
+     * precision passed is zero, then this implies that the computations have to
+     * be performed exact, the rounding mode in this case is irrelevant.
+     *
+     * @param precision
+     *            the precision for the new {@code MathContext}.
+     * @throws IllegalArgumentException
+     *             if {@code precision < 0}.
+     */
+    public MathContext(int precision) {
+        this(precision, RoundingMode.HALF_UP);
     }
 
-    /** @ar.org.fitc.spec_ref */
-    public MathContext(int setPrecision, RoundingMode setRoundingMode) {
-        if (setPrecision < 0) {
+    /**
+     * Constructs a new {@code MathContext} with the specified precision and
+     * with the specified rounding mode. If the precision passed is zero, then
+     * this implies that the computations have to be performed exact, the
+     * rounding mode in this case is irrelevant.
+     *
+     * @param precision
+     *            the precision for the new {@code MathContext}.
+     * @param roundingMode
+     *            the rounding mode for the new {@code MathContext}.
+     * @throws IllegalArgumentException
+     *             if {@code precision < 0}.
+     * @throws NullPointerException
+     *             if {@code roundingMode} is {@code null}.
+     */
+    public MathContext(int precision, RoundingMode roundingMode) {
+        if (precision < 0) {
             // math.0C=Digits < 0
             throw new IllegalArgumentException(Messages.getString("math.0C")); //$NON-NLS-1$
         }
-        if (setRoundingMode == null) {
+        if (roundingMode == null) {
             // math.0D=null RoundingMode
             throw new NullPointerException(Messages.getString("math.0D")); //$NON-NLS-1$
         }
-        precision = setPrecision;
-        roundingMode = setRoundingMode;
+        this.precision = precision;
+        this.roundingMode = roundingMode;
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Constructs a new {@code MathContext} from a string. The string has to
+     * specify the precision and the rounding mode to be used and has to follow
+     * the following syntax: "precision=&lt;precision&gt; roundingMode=&lt;roundingMode&gt;"
+     * This is the same form as the one returned by the {@link #toString}
+     * method.
+     *
+     * @param val
+     *            a string describing the precision and rounding mode for the
+     *            new {@code MathContext}.
+     * @throws IllegalArgumentException
+     *             if the string is not in the correct format or if the
+     *             precision specified is < 0.
+     */
     public MathContext(String val) {
         char[] charVal = val.toCharArray();
         int i; // Index of charVal
@@ -170,17 +220,48 @@
 
     /* Public Methods */
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns the precision. The precision is the number of digits used for an
+     * operation. Results are rounded to this precision. The precision is
+     * guaranteed to be non negative. If the precision is zero, then the
+     * computations have to be performed exact, results are not rounded in this
+     * case.
+     *
+     * @return the precision.
+     */
     public int getPrecision() {
         return precision;
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns the rounding mode. The rounding mode is the strategy to be used
+     * to round results.
+     * <p>
+     * The rounding mode is one of
+     * {@link RoundingMode#UP},
+     * {@link RoundingMode#DOWN},
+     * {@link RoundingMode#CEILING},
+     * {@link RoundingMode#FLOOR},
+     * {@link RoundingMode#HALF_UP},
+     * {@link RoundingMode#HALF_DOWN},
+     * {@link RoundingMode#HALF_EVEN}, or
+     * {@link RoundingMode#UNNECESSARY}.
+     *
+     * @return the rounding mode.
+     */
     public RoundingMode getRoundingMode() {
         return roundingMode;
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns true if x is a {@code MathContext} with the same precision
+     * setting and the same rounding mode as this {@code MathContext} instance.
+     *
+     * @param x
+     *            object to be compared.
+     * @return {@code true} if this {@code MathContext} instance is equal to the
+     *         {@code x} argument; {@code false} otherwise.
+     */
     @Override
     public boolean equals(Object x) {
         return ((x instanceof MathContext)
@@ -188,14 +269,28 @@
                 .getRoundingMode() == roundingMode));
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns the hash code for this {@code MathContext} instance.
+     *
+     * @return the hash code for this {@code MathContext}.
+     */
     @Override
     public int hashCode() {
         // Make place for the necessary bits to represent 8 rounding modes
         return ((precision << 3) | roundingMode.ordinal());
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Returns the string representation for this {@code MathContext} instance.
+     * The string has the form
+     * {@code
+     * "precision=&lt;precision&gt; roundingMode=&lt;roundingMode&gt;"
+     * } where {@code &lt;precision&gt;} is an integer describing the number
+     * of digits used for operations and {@code &lt;roundingMode&gt;} is the
+     * string representation of the rounding mode.
+     *
+     * @return a string representation for this {@code MathContext} instance
+     */
     @Override
     public String toString() {
         StringBuffer sb = new StringBuffer(45);
@@ -208,7 +303,15 @@
         return sb.toString();
     }
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Makes checks upon deserialization of a {@code MathContext} instance.
+     * Checks whether {@code precision >= 0} and {@code roundingMode != null}
+     *
+     * @throws StreamCorruptedException
+     *             if {@code precision < 0}
+     * @throws StreamCorruptedException
+     *             if {@code roundingMode == null}
+     */
     private void readObject(ObjectInputStream s) throws IOException,
             ClassNotFoundException {
         s.defaultReadObject();

Modified: harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Multiplication.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Multiplication.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Multiplication.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Multiplication.java Sun Apr 26 12:30:01 2009
@@ -21,9 +21,6 @@
 
 /**
  * Static library that provides all multiplication of {@link BigInteger} methods.
- *
- * @author Intel Middleware Product Division
- * @author Instituto Tecnologico de Cordoba
  */
 class Multiplication {
 

Modified: harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Primality.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Primality.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Primality.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/Primality.java Sun Apr 26 12:30:01 2009
@@ -22,16 +22,12 @@
 
 /**
  * Provides primality probabilistic methods.
- * @author Intel Middleware Product Division
- * @author Instituto Tecnologico de Cordoba
  */
 class Primality {
 
     /** Just to denote that this class can't be instantiated. */
     private Primality() {}
 
-    /* Private Fields */
-
     /** All prime numbers with bit length lesser than 10 bits. */
     private static final int primes[] = { 2, 3, 5, 7, 11, 13, 17, 19, 23, 29,
             31, 37, 41, 43, 47, 53, 59, 61, 67, 71, 73, 79, 83, 89, 97, 101,
@@ -79,8 +75,6 @@
         }
     }
 
-    /* Package Methods */
-
     /**
      * It uses the sieve of Eratosthenes to discard several composite numbers in
      * some appropriate range (at the moment {@code [this, this + 1024]}). After
@@ -227,8 +221,6 @@
         return millerRabin(n, certainty);
     }
 
-    /* Private Methods */
-
     /**
      * The Miller-Rabin primality test.
      * 

Modified: harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/RoundingMode.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/RoundingMode.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/RoundingMode.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/math/src/main/java/java/math/RoundingMode.java Sun Apr 26 12:30:01 2009
@@ -20,33 +20,67 @@
 import org.apache.harmony.math.internal.nls.Messages;
 
 /**
- * @author Intel Middleware Product Division
- * @author Instituto Tecnologico de Cordoba
+ * Specifies the rounding behavior for operations whose results cannot be
+ * represented exactly.
  */
 public enum RoundingMode {
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Rounding mode where positive values are rounded towards positive infinity
+     * and negative values towards negative infinity.
+     * <br>
+     * Rule: {@code x.round().abs() >= x.abs()}
+     */
     UP(BigDecimal.ROUND_UP),
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Rounding mode where the values are rounded towards zero.
+     * <br>
+     * Rule: {@code x.round().abs() <= x.abs()}
+     */
     DOWN(BigDecimal.ROUND_DOWN),
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Rounding mode to round towards positive infinity. For positive values
+     * this rounding mode behaves as {@link #UP}, for negative values as
+     * {@link #DOWN}.
+     * <br>
+     * Rule: {@code x.round() >= x}
+     */
     CEILING(BigDecimal.ROUND_CEILING),
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Rounding mode to round towards negative infinity. For positive values
+     * this rounding mode behaves as {@link #DOWN}, for negative values as
+     * {@link #UP}.
+     * <br>
+     * Rule: {@code x.round() <= x}
+     */
     FLOOR(BigDecimal.ROUND_FLOOR),
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Rounding mode where values are rounded towards the nearest neighbor. Ties
+     * are broken by rounding up.
+     */
     HALF_UP(BigDecimal.ROUND_HALF_UP),
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Rounding mode where values are rounded towards the nearest neighbor. Ties
+     * are broken by rounding down.
+     */
     HALF_DOWN(BigDecimal.ROUND_HALF_DOWN),
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Rounding mode where values are rounded towards the nearest neighbor. Ties
+     * are broken by rounding to the even neighbor.
+     */
     HALF_EVEN(BigDecimal.ROUND_HALF_EVEN),
 
-    /** @ar.org.fitc.spec_ref */
+    /**
+     * Rounding mode where the rounding operations throws an ArithmeticException
+     * for the case that rounding is necessary, i.e. for the case that the value
+     * cannot be represented exactly.
+     */
     UNNECESSARY(BigDecimal.ROUND_UNNECESSARY);
 
     /** The old constant of <code>BigDecimal</code>. */
@@ -57,9 +91,16 @@
         bigDecimalRM = rm;
     }
 
-    /** @ar.org.fitc.spec_ref */
-    public static RoundingMode valueOf(int rM) {
-        switch (rM) {
+    /**
+     * Converts rounding mode constants from class {@code BigDecimal} into
+     * {@code RoundingMode} values.
+     *
+     * @param mode
+     *            rounding mode constant as defined in class {@code BigDecimal}
+     * @return corresponding rounding mode object
+     */
+    public static RoundingMode valueOf(int mode) {
+        switch (mode) {
             case BigDecimal.ROUND_CEILING:
                 return CEILING;
             case BigDecimal.ROUND_DOWN:

Modified: harmony/enhanced/classlib/branches/java6/modules/prefs/src/main/java/java/util/prefs/AbstractPreferences.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/prefs/src/main/java/java/util/prefs/AbstractPreferences.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/prefs/src/main/java/java/util/prefs/AbstractPreferences.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/prefs/src/main/java/java/util/prefs/AbstractPreferences.java Sun Apr 26 12:30:01 2009
@@ -28,7 +28,6 @@
 import java.util.LinkedList;
 import java.util.List;
 import java.util.Map;
-import java.util.StringTokenizer;
 import java.util.TreeSet;
 
 import org.apache.harmony.luni.util.Base64;
@@ -560,18 +559,23 @@
 
     private AbstractPreferences nodeImpl(String path, boolean createNew)
             throws BackingStoreException {
-        StringTokenizer st = new StringTokenizer(path, "/"); //$NON-NLS-1$
+        String[] names = path.split("/");//$NON-NLS-1$
         AbstractPreferences currentNode = this;
         AbstractPreferences temp = null;
-        while (st.hasMoreTokens() && null != currentNode) {
-            String name = st.nextToken();
-            synchronized (currentNode.lock) {
-                temp = currentNode.cachedNode.get(name);
-                if (temp == null) {
-                    temp = getNodeFromBackend(createNew, currentNode, name);
+        if (null != currentNode) {
+            for (int i = 0; i < names.length; i++) {
+                String name = names[i];
+                synchronized (currentNode.lock) {
+                    temp = currentNode.cachedNode.get(name);
+                    if (temp == null) {
+                        temp = getNodeFromBackend(createNew, currentNode, name);
+                    }
+                }
+                currentNode = temp;
+                if (null == currentNode) {
+                    break;
                 }
             }
-            currentNode = temp;
         }
         return currentNode;
     }

Modified: harmony/enhanced/classlib/branches/java6/modules/regex/.settings/org.eclipse.jdt.core.prefs
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/regex/.settings/org.eclipse.jdt.core.prefs?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/regex/.settings/org.eclipse.jdt.core.prefs (original)
+++ harmony/enhanced/classlib/branches/java6/modules/regex/.settings/org.eclipse.jdt.core.prefs Sun Apr 26 12:30:01 2009
@@ -1,7 +1,7 @@
-#Wed May 03 13:10:22 BST 2006
+#Sat Apr 18 12:50:15 CST 2009
 eclipse.preferences.version=1
 org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode=enabled
-org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.4
+org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.5
 org.eclipse.jdt.core.compiler.codegen.unusedLocal=preserve
 org.eclipse.jdt.core.compiler.compliance=1.5
 org.eclipse.jdt.core.compiler.debug.lineNumber=generate

Modified: harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/AbstractSet.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/AbstractSet.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/AbstractSet.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/AbstractSet.java Sun Apr 26 12:30:01 2009
@@ -120,7 +120,6 @@
      */
     public int findBack(int stringIndex, int startSearch,
             CharSequence testString, MatchResultImpl matchResult) {
-        int shift;
         while (startSearch >= stringIndex) {
             if (matches(startSearch, testString, matchResult) >= 0) {
                 return startSearch;

Modified: harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/IntArrHash.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/IntArrHash.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/IntArrHash.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/IntArrHash.java Sun Apr 26 12:30:01 2009
@@ -21,22 +21,20 @@
  * Hashtable implementation for int arrays.
  */
 class IntArrHash {
-        int[] table;
+        final int[] table;
         
-        Object [] values;
+        final Object[] values;
                 
-        int mask;
-
-        int size; // maximum shift
+        final int mask;
 
         public IntArrHash(int size) {
-            while (size >= mask) {
-                mask = (mask << 1) | 1;
+            int tmpMask = 0;
+            while (size >= tmpMask) {
+                tmpMask = (tmpMask << 1) | 1;
             }
-            mask = (mask << 1) | 1;
+            mask = (tmpMask << 1) | 1;
             table = new int[mask + 1];
             values = new Object [mask + 1];
-            this.size = size;
         }
 
         public void put(int key, int [] value) {

Modified: harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/Lexer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/Lexer.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/Lexer.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/Lexer.java Sun Apr 26 12:30:01 2009
@@ -1028,14 +1028,13 @@
      * Process octal integer.
      */
     private int readOctals() {
-        char ch;
         int max = 3;
         int i = 1;
         int first;
         int res;
         int length = pattern.length - 2;
 
-        switch (first = Character.digit((ch = pattern[index]), 8)) {
+        switch (first = Character.digit(pattern[index], 8)) {
         case -1:
             throw new PatternSyntaxException(Messages.getString("regex.19") //$NON-NLS-1$
                     , this.toString(), index);
@@ -1048,7 +1047,7 @@
         }
 
         while (i < max && index < length
-                && (first = Character.digit((ch = pattern[index]), 8)) >= 0) {
+                && (first = Character.digit(pattern[index], 8)) >= 0) {
             res = res * 8 + first;
             nextIndex();
             i++;

Modified: harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/MatchResult.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/MatchResult.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/MatchResult.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/MatchResult.java Sun Apr 26 12:30:01 2009
@@ -22,45 +22,83 @@
 package java.util.regex;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * Holds the results of a successful match of a {@link Pattern} against a
+ * given string. The result is divided into groups, with one group for each
+ * pair of parentheses in the regular expression and an additional group for
+ * the whole regular expression. The start, end, and contents of each group
+ * can be queried.
+ *
+ * @see Matcher
+ * @see Matcher#toMatchResult()
+ *
  * @author Nikolay A. Kuznetsov
  * @version $Revision: 1.6.2.2 $
  */
 public interface MatchResult {
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the index of the first character following the text that matched
+     * the whole regular expression.
+     *
+     * @return the character index.
      */
     int end();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the index of the first character following the text that matched
+     * a given group.
+     *
+     * @param group
+     *            the group, ranging from 0 to groupCount() - 1, with 0
+     *            representing the whole pattern.
+     *
+     * @return the character index.
      */
     int end(int group);
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the text that matched the whole regular expression.
+     *
+     * @return the text.
      */
     String group();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the text that matched a given group of the regular expression.
+     *
+     * @param group
+     *            the group, ranging from 0 to groupCount() - 1, with 0
+     *            representing the whole pattern.
+     *
+     * @return the text that matched the group.
      */
     String group(int group);
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the number of groups in the result, which is always equal to
+     * the number of groups in the original regular expression.
+     *
+     * @return the number of groups.
      */
     int groupCount();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the index of the first character of the text that matched
+     * the whole regular expression.
+     *
+     * @return the character index.
      */
     int start();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the index of the first character of the text that matched a given
+     * group.
+     *
+     * @param group
+     *            the group, ranging from 0 to groupCount() - 1, with 0
+     *            representing the whole pattern.
+     *
+     * @return the character index.
      */
     int start(int group);
 }

Modified: harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/Matcher.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/Matcher.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/Matcher.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/regex/src/main/java/java/util/regex/Matcher.java Sun Apr 26 12:30:01 2009
@@ -22,7 +22,31 @@
 import org.apache.harmony.regex.internal.nls.Messages;
 
 /**
- * Note: main functionality of this class is hidden into nodes match methods. 
+ * Provides a means of matching regular expressions against a given input,
+ * finding occurrences of regular expressions in a given input, or replacing
+ * parts of a given input. A {@code Matcher} instance has an associated {@link
+ * Pattern} instance and an input text. A typical use case is to
+ * iteratively find all occurrences of the {@code Pattern}, until the end of
+ * the input is reached, as the following example illustrates:
+ *
+ * <p/>
+ *
+ * <pre>
+ * Pattern p = Pattern.compile("[A-Za-z]+");
+ *
+ * Matcher m = p.matcher("Hello, Android!");
+ * while (m.find()) {
+ *     System.out.println(m.group()); // prints "Hello" and "Android"
+ * }
+ * </pre>
+ *
+ * <p/>
+ *
+ * The {@code Matcher} has a state that results from the previous operations.
+ * For example, it knows whether the most recent attempt to find the
+ * {@code Pattern} was successful and at which position the next attempt would
+ * resume the search. Depending on the application's needs, it may become
+ * necessary to explicitly {@link #reset()} this state from time to time.
  */
 public final class Matcher implements MatchResult {
 
@@ -53,12 +77,25 @@
     private ArrayList replacementParts = null;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Appends a literal part of the input plus a replacement for the current
+     * match to a given {@link StringBuffer}. The literal part is exactly the
+     * part of the input between the previous match and the current match. The
+     * method can be used in conjunction with {@link #find()} and
+     * {@link #appendTail(StringBuffer)} to walk through the input and replace
+     * all occurrences of the {@code Pattern} with something else.
+     *
+     * @param buffer
+     *            the {@code StringBuffer} to append to.
+     * @param replacement
+     *            the replacement text.
+     * @return the {@code Matcher} itself.
+     * @throws IllegalStateException
+     *             if no successful match has been made.
      */
-    public Matcher appendReplacement(StringBuffer sb, String replacement) {
+    public Matcher appendReplacement(StringBuffer buffer, String replacement) {
         processedRepl = processReplacement(replacement);
-        sb.append(string.subSequence(appendPos, start()));
-        sb.append(processedRepl);
+        buffer.append(string.subSequence(appendPos, start()));
+        buffer.append(processedRepl);
         appendPos = end();
         return this;
     }
@@ -148,18 +185,31 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Provides a new input and resets the {@code Matcher}. This results in the
+     * region being set to the whole input. Results of a previous find get lost.
+     * The next attempt to find an occurrence of the {@link Pattern} in the
+     * string will start at the beginning of the input.
+     *
+     * @param input
+     *            the new input sequence.
+     *
+     * @return the {@code Matcher} itself.
      */
-    public Matcher reset(CharSequence newSequence) {
-        if (newSequence == null) {
+    public Matcher reset(CharSequence input) {
+        if (input == null) {
             throw new NullPointerException(Messages.getString("regex.01")); //$NON-NLS-1$
         }
-        this.string = newSequence;
+        this.string = input;
         return reset();
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Resets the {@code Matcher}. This results in the region being set to the
+     * whole input. Results of a previous find get lost. The next attempt to
+     * find an occurrence of the {@link Pattern} in the string will start at the
+     * beginning of the input.
+     *
+     * @return the {@code Matcher} itself.
      */
     public Matcher reset() {
         this.leftBound = 0;
@@ -172,44 +222,57 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Resets this matcher and sets a region. Only characters inside the region
+     * are considered for a match.
+     *
+     * @param start
+     *            the first character of the region.
+     * @param end
+     *            the first character after the end of the region.
+     * @return the {@code Matcher} itself.
      */
-    public Matcher region(int leftBound, int rightBound) {
+    public Matcher region(int start, int end) {
 
-        if (leftBound > rightBound || leftBound < 0 || rightBound < 0
-                || leftBound > string.length() || rightBound > string.length()) {
+        if (start > end || start < 0 || end < 0
+                || start > string.length() || end > string.length()) {
             throw new IndexOutOfBoundsException( Messages.getString("regex.02", //$NON-NLS-1$
-                            Integer.toString(leftBound), Integer.toString(rightBound)));
+                            Integer.toString(start), Integer.toString(end)));
         }
 
-        this.leftBound = leftBound;
-        this.rightBound = rightBound;
-        matchResult.reset(null, leftBound, rightBound);
+        this.leftBound = start;
+        this.rightBound = end;
+        matchResult.reset(null, start, end);
         appendPos = 0;
         replacement = null;
 
         return this;
     }
 
-	/**
-	 * TODO: appendTail(StringBuffer) javadoc
-	 * 
-	 * @param sb
-	 * @return
-	 */
-    public StringBuffer appendTail(StringBuffer sb) {
-        return sb.append(string.subSequence(appendPos, string.length()));
-    }
-
-	/**
-	 * This is very similar to replaceAll except only the first occurrence of a
-	 * sequence matching the pattern is replaced.
-	 * 
-	 * @param replacement
-	 *            A string to replace occurrences of character sequences
-	 *            matching the pattern.
-	 * @return A new string with replacements inserted
-	 */
+    /**
+     * Appends the (unmatched) remainder of the input to the given
+     * {@link StringBuffer}. The method can be used in conjunction with
+     * {@link #find()} and {@link #appendReplacement(StringBuffer, String)} to
+     * walk through the input and replace all matches of the {@code Pattern}
+     * with something else.
+     *
+     * @param buffer
+     *            the {@code StringBuffer} to append to.
+     * @return the {@code StringBuffer}.
+     * @throws IllegalStateException
+     *             if no successful match has been made.
+     */
+    public StringBuffer appendTail(StringBuffer buffer) {
+        return buffer.append(string.subSequence(appendPos, string.length()));
+    }
+
+    /**
+     * Replaces the first occurrence of this matcher's pattern in the input with
+     * a given string.
+     *
+     * @param replacement
+     *            the replacement text.
+     * @return the modified input string.
+     */
     public String replaceFirst(String replacement) {
         reset();
         if (find()) {
@@ -222,16 +285,14 @@
 
     }
 
-	/**
-	 * Replace all occurrences of character sequences which match the pattern
-	 * with the given replacement string. The replacement string may refer to
-	 * capturing groups using the syntax "$<group number>".
-	 * 
-	 * @param replacement
-	 *            A string to replace occurrences of character sequences
-	 *            matching the pattern.
-	 * @return A new string with replacements inserted
-	 */
+    /**
+     * Replaces all occurrences of this matcher's pattern in the input with a
+     * given string.
+     *
+     * @param replacement
+     *            the replacement text.
+     * @return the modified input string.
+     */
     public String replaceAll(String replacement) {
         StringBuffer sb = new StringBuffer();
         reset();
@@ -242,40 +303,60 @@
         return appendTail(sb).toString();
     }
 
-	/**
-	 * Return a reference to the pattern used by this Matcher.
-	 * 
-	 * @return A reference to the pattern used by this Matcher.
-	 */
+    /**
+     * Returns the {@link Pattern} instance used inside this matcher.
+     *
+     * @return the {@code Pattern} instance.
+     */
     public Pattern pattern() {
         return pat;
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     */
-    public String group(int groupIndex) {
-        return matchResult.group(groupIndex);
+     * Returns the text that matched a given group of the regular expression.
+     *
+     * @param group
+     *            the group, ranging from 0 to groupCount() - 1, with 0
+     *            representing the whole pattern.
+     * @return the text that matched the group.
+     * @throws IllegalStateException
+     *             if no successful match has been made.
+     */
+    public String group(int group) {
+        return matchResult.group(group);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the text that matched the whole regular expression.
+     *
+     * @return the text.
+     * @throws IllegalStateException
+     *             if no successful match has been made.
      */
     public String group() {
         return group(0);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the next occurrence of the {@link Pattern} in the input. The
+     * method starts the search from the given character in the input.
+     *
+     * @param start
+     *            The index in the input at which the find operation is to
+     *            begin. If this is less than the start of the region, it is
+     *            automatically adjusted to that value. If it is beyond the end
+     *            of the region, the method will fail.
+     * @return true if (and only if) a match has been found.
      */
-    public boolean find(int startIndex) {
+    public boolean find(int start) {
         int stringLength = string.length();
-        if (startIndex < 0 || startIndex > stringLength)
+        if (start < 0 || start > stringLength) {
             throw new IndexOutOfBoundsException(Messages.getString("regex.03", //$NON-NLS-1$ 
-                    new Integer(startIndex)));
+                    Integer.valueOf(start)));
+        }
 
-        startIndex = findAt(startIndex);
-        if (startIndex >= 0 && matchResult.isValid()) {
+        start = findAt(start);
+        if (start >= 0 && matchResult.isValid()) {
             matchResult.finalizeMatch();
             return true;
         }
@@ -294,14 +375,14 @@
         return foundIndex;
     }
 
-	/**
-	 * The find() method matches the pattern against the character sequence
-	 * beginning at the character after the last match or at the beginning of
-	 * the sequence if called immediately after reset(). The method returns true
-	 * if and only if a match is found.
-	 * 
-	 * @return A boolean indicating if the pattern was matched.
-	 */
+    /**
+     * Returns the next occurrence of the {@link Pattern} in the input. If a
+     * previous match was successful, the method continues the search from the
+     * first character following that match in the input. Otherwise it searches
+     * either from the region start (if one has been set), or from position 0.
+     *
+     * @return true if (and only if) a match has been found.
+     */
     public boolean find() {
         int length = string.length();
         if (!hasTransparentBounds())
@@ -321,45 +402,66 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     */
-    public int start(int groupIndex) {
-        return matchResult.start(groupIndex);
+     * Returns the index of the first character of the text that matched a given
+     * group.
+     *
+     * @param group
+     *            the group, ranging from 0 to groupCount() - 1, with 0
+     *            representing the whole pattern.
+     * @return the character index.
+     * @throws IllegalStateException
+     *             if no successful match has been made.
+     */
+    public int start(int group) {
+        return matchResult.start(group);
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     */
-    public int end(int groupIndex) {
-        return matchResult.end(groupIndex);
+     * Returns the index of the first character following the text that matched
+     * a given group.
+     *
+     * @param group
+     *            the group, ranging from 0 to groupCount() - 1, with 0
+     *            representing the whole pattern.
+     * @return the character index.
+     * @throws IllegalStateException
+     *             if no successful match has been made.
+     */
+    public int end(int group) {
+        return matchResult.end(group);
     }
 
-	/**
-	 * This method is identical in function to the Pattern.matches() method. It
-	 * returns true if and only if the regular expression pattern matches the
-	 * entire input character sequence.
-	 * 
-	 * @return A boolean indicating if the pattern matches the entire input
-	 *         character sequence.
-	 */
+    /**
+     * Tries to match the {@link Pattern} against the entire region (or the
+     * entire input, if no region has been set).
+     *
+     * @return true if (and only if) the {@code Pattern} matches the entire
+     *         region.
+     */
     public boolean matches() {
         return lookingAt(leftBound, Matcher.MODE_MATCH);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a replacement string for the given one that has all backslashes
+     * and dollar signs escaped.
+     *
+     * @param s
+     *            the input string.
+     * @return the input string, with all backslashes and dollar signs having
+     *         been escaped.
      */
-    public static String quoteReplacement(String string) {
+    public static String quoteReplacement(String s) {
         // first check whether we have smth to quote
-        if (string.indexOf('\\') < 0 && string.indexOf('$') < 0)
-            return string;
-        StringBuffer res = new StringBuffer(string.length() * 2);
+        if (s.indexOf('\\') < 0 && s.indexOf('$') < 0)
+            return s;
+        StringBuffer res = new StringBuffer(s.length() * 2);
         char ch;
-        int len = string.length();
+        int len = s.length();
 
         for (int i = 0; i < len; i++) {
 
-            switch (ch = string.charAt(i)) {
+            switch (ch = s.charAt(i)) {
             case '$':
                 res.append('\\');
                 res.append('$');
@@ -392,15 +494,13 @@
         return false;
     }
 
-	/**
-	 * This method attempts to match the pattern against the character sequence
-	 * starting at the beginning. If the pattern matches even a prefix of the
-	 * input character sequence, lookingAt() will return true. Otherwise it will
-	 * return false.
-	 * 
-	 * @return A boolean indicating if the pattern matches a prefix of the input
-	 *         character sequence.
-	 */
+    /**
+     * Tries to match the {@link Pattern}, starting from the beginning of the
+     * region (or the beginning of the input, if no region has been set).
+     * Doesn't require the {@code Pattern} to match against the whole region.
+     *
+     * @return true if (and only if) the {@code Pattern} matches.
+     */
     public boolean lookingAt() {
         return lookingAt(leftBound, Matcher.MODE_FIND);
     }
@@ -413,37 +513,61 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the index of the first character of the text that matched the
+     * whole regular expression.
+     *
+     * @return the character index.
+     * @throws IllegalStateException
+     *             if no successful match has been made.
      */
     public int start() {
         return start(0);
     }
 
-	/**
-	 * Return the number of capturing groups in the pattern.
-	 * 
-	 * @return The number of capturing groups in the pattern.
-	 */
+    /**
+     * Returns the number of groups in the results, which is always equal to
+     * the number of groups in the original regular expression.
+     *
+     * @return the number of groups.
+     */
     public int groupCount() {
         return matchResult.groupCount();
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the index of the first character following the text that matched
+     * the whole regular expression.
+     *
+     * @return the character index.
+     * @throws IllegalStateException
+     *             if no successful match has been made.
      */
     public int end() {
         return end(0);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Converts the current match into a separate {@link MatchResult} instance
+     * that is independent from this matcher. The new object is unaffected when
+     * the state of this matcher changes.
+     *
+     * @return the new {@code MatchResult}.
+     * @throws IllegalStateException
+     *             if no successful match has been made.
      */
     public MatchResult toMatchResult() {
         return this.matchResult.cloneImpl();
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Determines whether this matcher has anchoring bounds enabled or not. When
+     * anchoring bounds are enabled, the start and end of the input match the
+     * '^' and '$' meta-characters, otherwise not. Anchoring bounds are enabled
+     * by default.
+     *
+     * @param value
+     *            the new value for anchoring bounds.
+     * @return the {@code Matcher} itself.
      */
     public Matcher useAnchoringBounds(boolean value) {
         matchResult.useAnchoringBounds(value);
@@ -451,14 +575,26 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Indicates whether this matcher has anchoring bounds enabled. When
+     * anchoring bounds are enabled, the start and end of the input match the
+     * '^' and '$' meta-characters, otherwise not. Anchoring bounds are enabled
+     * by default.
+     *
+     * @return true if (and only if) the {@code Matcher} uses anchoring bounds.
      */
     public boolean hasAnchoringBounds() {
         return matchResult.hasAnchoringBounds();
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Determines whether this matcher has transparent bounds enabled or not.
+     * When transparent bounds are enabled, the parts of the input outside the
+     * region are subject to lookahead and lookbehind, otherwise they are not.
+     * Transparent bounds are disabled by default.
+     *
+     * @param value
+     *            the new value for transparent bounds.
+     * @return the {@code Matcher} itself.
      */
     public Matcher useTransparentBounds(boolean value) {
         matchResult.useTransparentBounds(value);
@@ -466,53 +602,77 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Indicates whether this matcher has transparent bounds enabled. When
+     * transparent bounds are enabled, the parts of the input outside the region
+     * are subject to lookahead and lookbehind, otherwise they are not.
+     * Transparent bounds are disabled by default.
+     *
+     * @return true if (and only if) the {@code Matcher} uses anchoring bounds.
      */
     public boolean hasTransparentBounds() {
         return matchResult.hasTransparentBounds();
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns this matcher's region start, that is, the first character that is
+     * considered for a match.
+     *
+     * @return the start of the region.
      */
     public int regionStart() {
         return matchResult.getLeftBound();
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns this matcher's region end, that is, the first character that is
+     * not considered for a match.
+     *
+     * @return the end of the region.
      */
     public int regionEnd() {
         return matchResult.getRightBound();
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Indicates whether more input might change a successful match into an
+     * unsuccessful one.
+     *
+     * @return true if (and only if) more input might change a successful match
+     *         into an unsuccessful one.
      */
     public boolean requireEnd() {
         return matchResult.requireEnd;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Indicates whether the last match hit the end of the input.
+     *
+     * @return true if (and only if) the last match hit the end of the input.
      */
     public boolean hitEnd() {
         return matchResult.hitEnd;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Sets a new pattern for the {@code Matcher}. Results of a previous find
+     * get lost. The next attempt to find an occurrence of the {@link Pattern}
+     * in the string will start at the beginning of the input.
+     *
+     * @param pattern
+     *            the new {@code Pattern}.
+     *
+     * @return the {@code Matcher} itself.
      */
-    public Matcher usePattern(Pattern pat) {
-    	if (pat == null) {
+    public Matcher usePattern(Pattern pattern) {
+    	if (pattern == null) {
     		throw new IllegalArgumentException(Messages.getString("regex.1B"));
     	}
         int startIndex = matchResult.getPreviousMatchEnd();
         int mode = matchResult.mode();
-        this.pat = pat;
-        this.start = pat.start;
+        this.pat = pattern;
+        this.start = pattern.start;
         matchResult = new MatchResultImpl(this.string, leftBound, rightBound,
-                pat.groupCount(), pat.compCount(), pat.consCount());
+                pattern.groupCount(), pattern.compCount(), pattern.consCount());
         matchResult.setStartIndex(startIndex);
         matchResult.setMode(mode);
         return this;



Mime
View raw message