diff options
author | michelou <michelou@epfl.ch> | 2008-02-21 16:55:26 +0000 |
---|---|---|
committer | michelou <michelou@epfl.ch> | 2008-02-21 16:55:26 +0000 |
commit | af87ca71663434b513d3799798828ce00a73b4a7 (patch) | |
tree | 99ec47f2d326a19316e529d14f4e2df980df84a6 | |
parent | 8bd9521d8a12107c03868c262ea29c1f77674257 (diff) | |
download | scala-af87ca71663434b513d3799798828ce00a73b4a7.tar.gz scala-af87ca71663434b513d3799798828ce00a73b4a7.tar.bz2 scala-af87ca71663434b513d3799798828ce00a73b4a7.zip |
added scaladoc comments
-rw-r--r-- | src/library/scala/StringBuilder.scala | 318 | ||||
-rw-r--r-- | src/library/scala/collection/immutable/HashSet.scala | 8 |
2 files changed, 310 insertions, 16 deletions
diff --git a/src/library/scala/StringBuilder.scala b/src/library/scala/StringBuilder.scala index 7a51e3a07a..3bed5d5fec 100644 --- a/src/library/scala/StringBuilder.scala +++ b/src/library/scala/StringBuilder.scala @@ -6,7 +6,7 @@ ** |/ ** \* */ -// $Id: $ +// $Id$ package scala @@ -34,8 +34,18 @@ extends (Int => Char) with Proxy { /** The count is the number of characters used. */ private var count: Int = 0 + /** Constructs a string builder with no characters in it and an + * initial capacity of 16 characters. + */ def this() = this(16, "") + /** Constructs a string builder with no characters in it and an + * initial capacity specified by the <code>capacity</code> argument. + * + * @param capacity the initial capacity. + * @throws NegativeArraySizeException if the <code>capacity</code> + * argument is less than <code>0</code>. + */ def this(capacity: Int) = this(capacity, "") @throws(classOf[NullPointerException]) @@ -51,6 +61,11 @@ extends (Int => Char) with Proxy { def length_=(n: Int) { setLength(n) } + /** Sets the length of the character sequence. + * + * @param newLength the new length + * @throws IndexOutOfBoundsException if the <code>n</code> argument is negative. + */ @throws(classOf[StringIndexOutOfBoundsException]) def setLength(n: Int) { if (n < 0) @@ -64,10 +79,33 @@ extends (Int => Char) with Proxy { count = n } + /** Returns the current capacity. The capacity is the amount of storage + * available for newly inserted characters, beyond which an allocation + * will occur. + * + * @return the current capacity + */ def capacity: Int = value.length + /** Same as <code>ensureCapacity</code>. */ def capacity_=(n: Int) { ensureCapacity(n) } + /** <p> + * Ensures that the capacity is at least equal to the specified minimum. + * If the current capacity is less than the argument, then a new internal + * array is allocated with greater capacity. The new capacity is the larger of: + * </p> + * <ul> + * <li>The <code>n</code> argument. + * <li>Twice the old capacity, plus <code>2</code>. + * </ul> + * <p> + * If the <code>n</code> argument is non-positive, this + * method takes no action and simply returns. + * </p> + * + * @param n the minimum desired capacity. + */ def ensureCapacity(n: Int) { if (n > value.length) expandCapacity(n) } @@ -80,6 +118,21 @@ extends (Int => Char) with Proxy { ) } + /** <p> + * Returns the <code>Char</code> value in this sequence at the specified index. + * The first <code>Char</code> value is at index <code>0</code>, the next at index + * <code>1</code>, and so on, as in array indexing. + * </p> + * <p> + * The index argument must be greater than or equal to + * <code>0</code>, and less than the length of this sequence. + * </p> + * + * @param index the index of the desired <code>Char</code> value. + * @return the <code>Char</code> value at the specified index. + * @throws IndexOutOfBoundsException if <code>index</code> is + * negative or greater than or equal to <code>length()</code>. + */ @throws(classOf[StringIndexOutOfBoundsException]) def charAt(index: Int): Char = { if (index < 0 || index >= count) @@ -87,9 +140,20 @@ extends (Int => Char) with Proxy { value(index) } + /** Same as <code>charAt</code>. */ @throws(classOf[StringIndexOutOfBoundsException]) def apply(i: Int): Char = charAt(i) + /** <p> + * Removes the <code>Char</code> at the specified position in this + * sequence. This sequence is shortened by one <code>Char</code>. + * </p> + * + * @param index Index of <code>Char</code> to remove + * @return This object. + * @throws StringIndexOutOfBoundsException if the <code>index</code> + * is negative or greater than or equal to <code>length()</code>. + */ @throws(classOf[StringIndexOutOfBoundsException]) def deleteCharAt(index: Int): StringBuilder = { if (index < 0 || index >= count) @@ -99,19 +163,59 @@ extends (Int => Char) with Proxy { this } + /** <p> + * The character at the specified index is set to <code>ch</code>. This + * sequence is altered to represent a new character sequence that is + * identical to the old character sequence, except that it contains the + * character <code>ch</code> at position <code>index</code>. + * </p> + * <p> + * The index argument must be greater than or equal to + * <code>0</code>, and less than the length of this sequence. + * </p> + * + * @param index the index of the character to modify. + * @param ch the new character. + * @throws IndexOutOfBoundsException if <code>index</code> is + * negative or greater than or equal to <code>length()</code>. + */ @throws(classOf[StringIndexOutOfBoundsException]) - def setCharAt(index: Int, c: Char) { + def setCharAt(index: Int, ch: Char) { if (index < 0 || index >= count) throw new StringIndexOutOfBoundsException(index) - value(index) = c + value(index) = ch } + /** Same as <code>setCharAt</code>. */ @throws(classOf[StringIndexOutOfBoundsException]) def update(i: Int, c: Char) { setCharAt(i, c) } + /** Returns a new <code>String</code> that contains a subsequence of + * characters currently contained in this character sequence. The + * substring begins at the specified index and extends to the end of + * this sequence. + * + * @param start The beginning index, inclusive. + * @return The new string. + * @throws StringIndexOutOfBoundsException if <code>start</code> is + * less than zero, or greater than the length of this object. + */ @throws(classOf[StringIndexOutOfBoundsException]) def substring(start: Int): String = substring(start, count) + /** Returns a new <code>String</code> that contains a subsequence of + * characters currently contained in this sequence. The + * substring begins at the specified <code>start</code> and + * extends to the character at index <code>end - 1</code>. + * + * @param start The beginning index, inclusive. + * @param end The ending index, exclusive. + * @return The new string. + * @throws StringIndexOutOfBoundsException if <code>start</code> + * or <code>end</code> are negative or greater than + * <code>length()</code>, or <code>start</code> is + * greater than <code>end</code>. + */ @throws(classOf[StringIndexOutOfBoundsException]) def substring(start: Int, end: Int): String = { if (start < 0) @@ -123,13 +227,26 @@ extends (Int => Char) with Proxy { new String(value, start, end - start) } + /** <p> + * Appends the string representation of the <code>Any</code> + * argument. + * </p> + * <p> + * The argument is converted to a string as if by the method + * <code>String.valueOf</code>, and the characters of that + * string are then appended to this sequence. + * </p> + * + * @param x an <code>Any</code> object. + * @return a reference to this object. + */ def append(x: Any): StringBuilder = append(String.valueOf(x)) /** Appends the specified string to this character sequence. * - * @param s - * @return + * @param s a string. + * @return a reference to this object. */ def append(s: String): StringBuilder = { val str = if (s == null) "null" else s @@ -160,9 +277,38 @@ extends (Int => Char) with Proxy { this } + /** <p> + * Appends the string representation of the <code>Char</code> array + * argument to this sequence. + * </p> + * <p> + * The characters of the array argument are appended, in order, to + * the contents of this sequence. The length of this sequence + * increases by the length of the argument. + * </p> + * + * @param x the characters to be appended. + * @return a reference to this object. + */ def append(x: Array[Char]): StringBuilder = append(x, 0, x.length) + /** <p> + * Appends the string representation of a subarray of the + * <code>char</code> array argument to this sequence. + * </p> + * <p> + * Characters of the <code>Char</code> array <code>x</code>, starting at + * index <code>offset</code>, are appended, in order, to the contents + * of this sequence. The length of this sequence increases + * by the value of <code>len</code>. + * </p> + * + * @param x the characters to be appended. + * @param offset the index of the first <code>Char</code> to append. + * @param len the number of <code>Char</code>s to append. + * @return a reference to this object. + */ def append(x: Array[Char], offset: Int, len: Int): StringBuilder = { val newCount = count + len if (newCount > value.length) expandCapacity(newCount) @@ -171,6 +317,19 @@ extends (Int => Char) with Proxy { this } + /** <p> + * Appends the string representation of the <code>Boolean</code> + * argument to the sequence. + * </p> + * <p> + * The argument is converted to a string as if by the method + * <code>String.valueOf</code>, and the characters of that + * string are then appended to this sequence. + * </p> + * + * @param x a <code>Boolean</code>. + * @return a reference to this object. + */ def append(x: Boolean): StringBuilder = { if (x) { val newCount = count + 4 @@ -210,6 +369,19 @@ extends (Int => Char) with Proxy { def append(x: Double): StringBuilder = append(String.valueOf(x)) + /** Removes the characters in a substring of this sequence. + * The substring begins at the specified <code>start</code> and extends to + * the character at index <code>end - 1</code> or to the end of the + * sequence if no such character exists. If + * <code>start</code> is equal to <code>end</code>, no changes are made. + * + * @param start The beginning index, inclusive. + * @param end The ending index, exclusive. + * @return This object. + * @throws StringIndexOutOfBoundsException if <code>start</code> + * is negative, greater than <code>length()</code>, or + * greater than <code>end</code>. + */ @throws(classOf[StringIndexOutOfBoundsException]) def delete(start: Int, end: Int): StringBuilder = { if (start < 0 || start > end) @@ -223,6 +395,21 @@ extends (Int => Char) with Proxy { this } + /** Replaces the characters in a substring of this sequence + * with characters in the specified <code>String</code>. The substring + * begins at the specified <code>start</code> and extends to the character + * at index <code>end - 1</code> or to the end of the sequence if no such + * character exists. First the characters in the substring are removed and + * then the specified <code>String</code> is inserted at <code>start</code>. + * + * @param start The beginning index, inclusive. + * @param end The ending index, exclusive. + * @param str String that will replace previous contents. + * @return This object. + * @throws StringIndexOutOfBoundsException if <code>start</code> + * is negative, greater than <code>length()</code>, or + * greater than <code>end</code>. + */ @throws(classOf[StringIndexOutOfBoundsException]) def replace(start: Int, end: Int, str: String) { if (start < 0 || start > count || start > end) @@ -239,6 +426,26 @@ extends (Int => Char) with Proxy { this } + /** Inserts the string representation of a subarray of the <code>str</code> + * array argument into this sequence. The subarray begins at the specified + * <code>offset</code> and extends <code>len</code> <code>char</code>s. + * The characters of the subarray are inserted into this sequence at + * the position indicated by <code>index</code>. The length of this + * sequence increases by <code>len</code> <code>Char</code>s. + * + * @param index position at which to insert subarray. + * @param str a <code>Char</code> array. + * @param offset the index of the first <code>char</code> in subarray to + * be inserted. + * @param len the number of <code>Char</code>s in the subarray to + * be inserted. + * @return This object + * @throws StringIndexOutOfBoundsException if <code>index</code> + * is negative or greater than <code>length()</code>, or + * <code>offset</code> or <code>len</code> are negative, or + * <code>(offset+len)</code> is greater than + * <code>str.length</code>. + */ @throws(classOf[StringIndexOutOfBoundsException]) def insert(index: Int, str: Array[Char], offset: Int, len: Int): StringBuilder = { if (index < 0 || index > count) @@ -255,10 +462,38 @@ extends (Int => Char) with Proxy { this } + /** <p> + * Inserts the string representation of the <code>Any</code> + * argument into this character sequence. + * </p> + * <p> + * The second argument is converted to a string as if by the method + * <code>String.valueOf</code>, and the characters of that + * string are then inserted into this sequence at the indicated + * offset. + * </p> + * <p> + * The offset argument must be greater than or equal to + * <code>0</code>, and less than or equal to the length of this + * sequence. + * </p> + * + * @param offset the offset. + * @param x an <code>Any</code> value. + * @return a reference to this object. + * @throws StringIndexOutOfBoundsException if the offset is invalid. + */ @throws(classOf[StringIndexOutOfBoundsException]) def insert(at: Int, x: Any): StringBuilder = insert(at, String.valueOf(x)) + /** Inserts the string into this character sequence. + * + * @param at the offset position. + * @param x a string. + * @return a reference to this object. + * @throws StringIndexOutOfBoundsException if the offset is invalid. + */ @throws(classOf[StringIndexOutOfBoundsException]) def insert(at: Int, x: String): StringBuilder = { if (at < 0 || at > count) @@ -273,6 +508,14 @@ extends (Int => Char) with Proxy { this } + /** Inserts the string representation of the <code>Char</code> array + * argument into this sequence. + * + * @param at the offset position. + * @param x a character array. + * @return a reference to this object. + * @throws StringIndexOutOfBoundsException if the offset is invalid. + */ @throws(classOf[StringIndexOutOfBoundsException]) def insert(at: Int, x: Array[Char]): StringBuilder = { if (at < 0 || at > count) @@ -318,6 +561,21 @@ extends (Int => Char) with Proxy { def insert(at: Int, x: Double): StringBuilder = insert(at, String.valueOf(x)) + /** Returns the index within this string of the first occurrence of the + * specified substring. The integer returned is the smallest value + * <i>k</i> such that: + * <blockquote><pre> + * this.toString().startsWith(str, <i>k</i>) + * </pre></blockquote> + * is <code>true</code>. + * + * @param str any string. + * @return if the string argument occurs as a substring within this + * object, then the index of the first character of the first + * such substring is returned; if it does not occur as a + * substring, <code>-1</code> is returned. + * @throws NullPointerException if <code>str</code> is <code>null</code>. + */ @throws(classOf[NullPointerException]) def indexOf(str: String): Int = indexOf(str, 0) @@ -325,6 +583,22 @@ extends (Int => Char) with Proxy { def indexOf(str: String, fromIndex: Int): Int = StringBuilder.indexOf(value, 0, count, str.toArray, 0, str.length(), fromIndex) + /** Returns the index within this string of the rightmost occurrence + * of the specified substring. The rightmost empty string "" is + * considered to occur at the index value <code>this.length()</code>. + * The returned index is the largest value <i>k</i> such that + * <blockquote><pre> + * this.toString().startsWith(str, k) + * </pre></blockquote> + * is true. + * + * @param str the substring to search for. + * @return if the string argument occurs one or more times as a substring + * within this object, then the index of the first character of + * the last such substring is returned. If it does not occur as + * a substring, <code>-1</code> is returned. + * @throws NullPointerException if <code>str</code> is <code>null</code>. + */ @throws(classOf[NullPointerException]) def lastIndexOf(str: String): Int = lastIndexOf(str, count) @@ -332,6 +606,23 @@ extends (Int => Char) with Proxy { def lastIndexOf(str: String, fromIndex: Int): Int = StringBuilder.lastIndexOf(value, 0, count, str.toArray, 0, str.length(), fromIndex) + /** <p> + * Causes this character sequence to be replaced by the reverse of the + * sequence. If there are any surrogate pairs included in the sequence, + * these are treated as single characters for the reverse operation. + * Thus, the order of the high-low surrogates is never reversed. + * </p> + * <p> + * Let <i>n</i> be the character length of this character sequence + * (not the length in <code>Char</code> values) just prior to + * execution of the <code>reverse</code> method. Then the + * character at index <i>k</i> in the new character sequence is + * equal to the character at index <i>n-k-1</i> in the old + * character sequence. + * </p> + * + * @return a reference to this object. + */ def reverse(): StringBuilder = { var hasSurrogate = false val n = count - 1 @@ -365,6 +656,15 @@ extends (Int => Char) with Proxy { this } + /** Returns a string representing the data in this sequence. + * A new <code>String</code> object is allocated and initialized to + * contain the character sequence currently represented by this + * object. This <code>String</code> is then returned. Subsequent + * changes to this sequence do not affect the contents of the + * <code>String</code>. + * + * @return a string representation of this sequence of characters. + */ override def toString(): String = new String(value, 0, count) @throws(classOf[java.io.IOException]) @@ -407,13 +707,7 @@ object StringBuilder { // method <code>java.util.Arrays.copyOf</code> exists since 1.6 private def copyOf(src: Array[Char], newLength: Int): Array[Char] = { val dest = new Array[Char](newLength) - val (start, end) = - if (src.length < newLength) (src.length, newLength) - else (newLength, src.length) - compat.Platform.arraycopy(src, 0, dest, 0, start) - // For any indices that are valid in the copy but not the original, - // the copy will contain '\\u000'. - for (i <- start until end) dest(i) = '\0' + compat.Platform.arraycopy(src, 0, dest, 0, Math.min(src.length, newLength)) dest } diff --git a/src/library/scala/collection/immutable/HashSet.scala b/src/library/scala/collection/immutable/HashSet.scala index 5e6dd10f50..850f00658c 100644 --- a/src/library/scala/collection/immutable/HashSet.scala +++ b/src/library/scala/collection/immutable/HashSet.scala @@ -1,6 +1,6 @@ /* __ *\ ** ________ ___ / / ___ Scala API ** -** / __/ __// _ | / / / _ | (c) 2003-2007, LAMP/EPFL ** +** / __/ __// _ | / / / _ | (c) 2003-2008, LAMP/EPFL ** ** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** ** /____/\___/_/ |_/____/_/ | | ** ** |/ ** @@ -44,7 +44,7 @@ class HashSet[A] extends Set[A] with mutable.FlatHashTable[A] { var cnt = 0 while (m.later != null) { if (elem == m.changedElem) return m.deleted - cnt = cnt + 1 + cnt += 1 m = m.later } if (cnt > logLimit) makeCopy(m) @@ -76,8 +76,8 @@ class HashSet[A] extends Set[A] with mutable.FlatHashTable[A] { var cnt = 0 var s = tableSize while (m.later != null) { - if (m.deleted) s = s + 1 else s = s - 1 - cnt = cnt + 1 + if (m.deleted) s += 1 else s -= 1 + cnt += 1 m = m.later } if (cnt > logLimit) makeCopy(m) |