From a8ec5198cb0722fad89ace83d8e167dcd80bfc17 Mon Sep 17 00:00:00 2001
From: Lukas Rytz
- * Indices start a
- * Note the indexing syntax System.arraycopy(src, srcPos, dest, destPos, length)
,
- * except that this works also for polymorphic and boxed arrays.
+ * Equivalent to Java's
+ * `System.arraycopy(src, srcPos, dest, destPos, length)`,
+ * except that this also works for polymorphic and boxed arrays.
+ *
+ * Note that the passed-in `dest` array will be modified by this call.
*
- * @param src ...
- * @param srcPos ...
- * @param dest ...
- * @param destPos ...
- * @param length ...
+ * @param src the source array.
+ * @param srcPos starting position in the source array.
+ * @param dest destination array.
+ * @param destPos starting position in the destination array.
+ * @param length the number of array elements to be copied.
+ *
+ * @see `java.lang.System#arraycopy`
*/
def copy(src: AnyRef, srcPos: Int, dest: AnyRef, destPos: Int, length: Int) {
val srcClass = src.getClass
@@ -83,13 +90,13 @@ object Array extends FallbackArrayBuilding {
slowcopy(src, srcPos, dest, destPos, length)
}
- /** Returns array of length 0 */
+ /** Returns an array of length 0 */
def empty[T: ClassManifest]: Array[T] = new Array[T](0)
- /** Create an array with given elements.
+ /** Creates an array with given elements.
*
* @param xs the elements to put in the array
- * @return the array containing elements xs.
+ * @return an array containing all elements from xs.
*/
def apply[T: ClassManifest](xs: T*): Array[T] = {
val array = new Array[T](xs.length)
@@ -98,6 +105,7 @@ object Array extends FallbackArrayBuilding {
array
}
+ /** Creates an array of `Boolean` objects */
def apply(x: Boolean, xs: Boolean*): Array[Boolean] = {
val array = new Array[Boolean](xs.length + 1)
array(0) = x
@@ -106,6 +114,7 @@ object Array extends FallbackArrayBuilding {
array
}
+ /** Creates an array of `Byte` objects */
def apply(x: Byte, xs: Byte*): Array[Byte] = {
val array = new Array[Byte](xs.length + 1)
array(0) = x
@@ -114,6 +123,7 @@ object Array extends FallbackArrayBuilding {
array
}
+ /** Creates an array of `Short` objects */
def apply(x: Short, xs: Short*): Array[Short] = {
val array = new Array[Short](xs.length + 1)
array(0) = x
@@ -122,6 +132,7 @@ object Array extends FallbackArrayBuilding {
array
}
+ /** Creates an array of `Char` objects */
def apply(x: Char, xs: Char*): Array[Char] = {
val array = new Array[Char](xs.length + 1)
array(0) = x
@@ -130,6 +141,7 @@ object Array extends FallbackArrayBuilding {
array
}
+ /** Creates an array of `Int` objects */
def apply(x: Int, xs: Int*): Array[Int] = {
val array = new Array[Int](xs.length + 1)
array(0) = x
@@ -138,6 +150,7 @@ object Array extends FallbackArrayBuilding {
array
}
+ /** Creates an array of `Long` objects */
def apply(x: Long, xs: Long*): Array[Long] = {
val array = new Array[Long](xs.length + 1)
array(0) = x
@@ -146,6 +159,7 @@ object Array extends FallbackArrayBuilding {
array
}
+ /** Creates an array of `Float` objects */
def apply(x: Float, xs: Float*): Array[Float] = {
val array = new Array[Float](xs.length + 1)
array(0) = x
@@ -154,6 +168,7 @@ object Array extends FallbackArrayBuilding {
array
}
+ /** Creates an array of `Double` objects */
def apply(x: Double, xs: Double*): Array[Double] = {
val array = new Array[Double](xs.length + 1)
array(0) = x
@@ -162,6 +177,7 @@ object Array extends FallbackArrayBuilding {
array
}
+ /** Creates an array of `Unit` objects */
def apply(x: Unit, xs: Unit*): Array[Unit] = {
val array = new Array[Unit](xs.length + 1)
array(0) = x
@@ -170,26 +186,30 @@ object Array extends FallbackArrayBuilding {
array
}
- /** Create array with given dimensions */
+ /** Creates array with given dimensions */
def ofDim[T: ClassManifest](n1: Int): Array[T] =
new Array[T](n1)
+ /** Creates a 2-dimensional array */
def ofDim[T: ClassManifest](n1: Int, n2: Int): Array[Array[T]] = {
val arr: Array[Array[T]] = (new Array[Array[T]](n1): Array[Array[T]])
for (i <- 0 until n1) arr(i) = new Array[T](n2)
arr
// tabulate(n1)(_ => ofDim[T](n2))
}
+ /** Creates a 3-dimensional array */
def ofDim[T: ClassManifest](n1: Int, n2: Int, n3: Int): Array[Array[Array[T]]] =
tabulate(n1)(_ => ofDim[T](n2, n3))
+ /** Creates a 4-dimensional array */
def ofDim[T: ClassManifest](n1: Int, n2: Int, n3: Int, n4: Int): Array[Array[Array[Array[T]]]] =
tabulate(n1)(_ => ofDim[T](n2, n3, n4))
+ /** Creates a 5-dimensional array */
def ofDim[T: ClassManifest](n1: Int, n2: Int, n3: Int, n4: Int, n5: Int): Array[Array[Array[Array[Array[T]]]]] =
tabulate(n1)(_ => ofDim[T](n2, n3, n4, n5))
- /** Concatenate all argument sequences into a single array.
+ /** Concatenates all arrays into a single array.
*
- * @param xs the given argument sequences
- * @return the array created from the concatenated arguments
+ * @param xss the given arrays
+ * @return the array created from concatenating `xss`
*/
def concat[T: ClassManifest](xss: Array[T]*): Array[T] = {
val b = newBuilder[T]
@@ -198,11 +218,19 @@ object Array extends FallbackArrayBuilding {
b.result
}
- /** An array that contains the results of some element computation a number
+ /** Returns an array that contains the results of some element computation a number
* of times.
*
- * @param n the number of elements returned
+ * Note that this means that `elem` is computed a total of n times:
+ * {{{
+ * scala> Array.fill(3){ java.lang.Math.random }
+ * res3: Array[Double] = Array(0.365461167592537, 1.550395944913685E-4, 0.7907242137333306)
+ * }}}
+ *
+ * @param n the number of elements desired
* @param elem the element computation
+ * @return an Array of size n, where each element contains the result of computing
+ * `elem`.
*/
def fill[T: ClassManifest](n: Int)(elem: => T): Array[T] = {
val b = newBuilder[T]
@@ -215,7 +243,7 @@ object Array extends FallbackArrayBuilding {
b.result
}
- /** A two-dimensional array that contains the results of some element
+ /** Returns a two-dimensional array that contains the results of some element
* computation a number of times.
*
* @param n1 the number of elements in the 1st dimension
@@ -225,7 +253,7 @@ object Array extends FallbackArrayBuilding {
def fill[T: ClassManifest](n1: Int, n2: Int)(elem: => T): Array[Array[T]] =
tabulate(n1)(_ => fill(n2)(elem))
- /** A three-dimensional array that contains the results of some element
+ /** Returns a three-dimensional array that contains the results of some element
* computation a number of times.
*
* @param n1 the number of elements in the 1st dimension
@@ -236,7 +264,7 @@ object Array extends FallbackArrayBuilding {
def fill[T: ClassManifest](n1: Int, n2: Int, n3: Int)(elem: => T): Array[Array[Array[T]]] =
tabulate(n1)(_ => fill(n2, n3)(elem))
- /** A four-dimensional array that contains the results of some element
+ /** Returns a four-dimensional array that contains the results of some element
* computation a number of times.
*
* @param n1 the number of elements in the 1st dimension
@@ -248,7 +276,7 @@ object Array extends FallbackArrayBuilding {
def fill[T: ClassManifest](n1: Int, n2: Int, n3: Int, n4: Int)(elem: => T): Array[Array[Array[Array[T]]]] =
tabulate(n1)(_ => fill(n2, n3, n4)(elem))
- /** A five-dimensional array that contains the results of some element
+ /** Returns a five-dimensional array that contains the results of some element
* computation a number of times.
*
* @param n1 the number of elements in the 1st dimension
@@ -261,12 +289,12 @@ object Array extends FallbackArrayBuilding {
def fill[T: ClassManifest](n1: Int, n2: Int, n3: Int, n4: Int, n5: Int)(elem: => T): Array[Array[Array[Array[Array[T]]]]] =
tabulate(n1)(_ => fill(n2, n3, n4, n5)(elem))
- /** An array containing values of a given function over a range of integer
+ /** Returns an array containing values of a given function over a range of integer
* values starting from 0.
*
- * @param n The number of elements in the traversable
+ * @param n The number of elements in the array
* @param f The function computing element values
- * @return A traversable consisting of elements `f(0), ..., f(n -1)`
+ * @return A traversable consisting of elements `f(0),f(1), ..., f(n - 1)`
*/
def tabulate[T: ClassManifest](n: Int)(f: Int => T): Array[T] = {
val b = newBuilder[T]
@@ -279,7 +307,7 @@ object Array extends FallbackArrayBuilding {
b.result
}
- /** A two-dimensional array containing values of a given function over
+ /** Returns a two-dimensional array containing values of a given function over
* ranges of integer values starting from 0.
*
* @param n1 the number of elements in the 1st dimension
@@ -289,7 +317,7 @@ object Array extends FallbackArrayBuilding {
def tabulate[T: ClassManifest](n1: Int, n2: Int)(f: (Int, Int) => T): Array[Array[T]] =
tabulate(n1)(i1 => tabulate(n2)(f(i1, _)))
- /** A three-dimensional array containing values of a given function over
+ /** Returns a three-dimensional array containing values of a given function over
* ranges of integer values starting from 0.
*
* @param n1 the number of elements in the 1st dimension
@@ -300,7 +328,7 @@ object Array extends FallbackArrayBuilding {
def tabulate[T: ClassManifest](n1: Int, n2: Int, n3: Int)(f: (Int, Int, Int) => T): Array[Array[Array[T]]] =
tabulate(n1)(i1 => tabulate(n2, n3)(f(i1, _, _)))
- /** A four-dimensional array containing values of a given function over
+ /** Returns a four-dimensional array containing values of a given function over
* ranges of integer values starting from 0.
*
* @param n1 the number of elements in the 1st dimension
@@ -312,7 +340,7 @@ object Array extends FallbackArrayBuilding {
def tabulate[T: ClassManifest](n1: Int, n2: Int, n3: Int, n4: Int)(f: (Int, Int, Int, Int) => T): Array[Array[Array[Array[T]]]] =
tabulate(n1)(i1 => tabulate(n2, n3, n4)(f(i1, _, _, _)))
- /** A five-dimensional array containing values of a given function over
+ /** Returns a five-dimensional array containing values of a given function over
* ranges of integer values starting from 0.
*
* @param n1 the number of elements in the 1st dimension
@@ -325,20 +353,20 @@ object Array extends FallbackArrayBuilding {
def tabulate[T: ClassManifest](n1: Int, n2: Int, n3: Int, n4: Int, n5: Int)(f: (Int, Int, Int, Int, Int) => T): Array[Array[Array[Array[Array[T]]]]] =
tabulate(n1)(i1 => tabulate(n2, n3, n4, n5)(f(i1, _, _, _, _)))
- /** An array containing a sequence of increasing integers in a range.
+ /** Returns an array containing a sequence of increasing integers in a range.
*
* @param from the start value of the array
- * @param end the end value of the array (the first value NOT returned)
+ * @param end the end value of the array, exclusive (in other words, this is the first value '''not''' returned)
* @return the array with values in range `start, start + 1, ..., end - 1`
- * up to, but exclusding, `end`.
+ * up to, but excluding, `end`.
*/
def range(start: Int, end: Int): Array[Int] = range(start, end, 1)
- /** An array containing equally spaced values in some integer interval.
+ /** Returns an array containing equally spaced values in some integer interval.
*
* @param start the start value of the array
- * @param end the end value of the array (the first value NOT returned)
- * @param step the increment value of the array (must be positive or negative)
+ * @param end the end value of the array, exclusive (in other words, this is the first value '''not''' returned)
+ * @param step the increment value of the array (may not be zero)
* @return the array with values in `start, start + step, ...` up to, but excluding `end`
*/
def range(start: Int, end: Int, step: Int): Array[Int] = {
@@ -354,11 +382,11 @@ object Array extends FallbackArrayBuilding {
b.result
}
- /** An array containing repeated applications of a function to a start value.
+ /** Returns an array containing repeated applications of a function to a start value.
*
* @param start the start value of the array
* @param len the number of elements returned by the array
- * @param f the function that's repeatedly applied
+ * @param f the function that is repeatedly applied
* @return the array returning `len` values in the sequence `start, f(start), f(f(start)), ...`
*/
def iterate[T: ClassManifest](start: T, len: Int)(f: T => T): Array[T] = {
@@ -379,17 +407,17 @@ object Array extends FallbackArrayBuilding {
b.result
}
- /** This method is called in a pattern match { case Seq(...) => }.
+ /** Called in a pattern match like `{ case Array(x,y,z) => println('3 elements')}`.
*
* @param x the selector value
- * @return sequence wrapped in an option, if this is a Seq, otherwise none
+ * @return sequence wrapped in a [[scala.Some]], if x is a Seq, otherwise `None`
*/
def unapplySeq[T](x: Array[T]): Option[IndexedSeq[T]] =
if (x == null) None else Some(x.toIndexedSeq)
// !!! the null check should to be necessary, but without it 2241 fails. Seems to be a bug
// in pattern matcher.
- /** Create an array containing several copies of an element.
+ /** Creates an array containing several copies of an element.
*
* @param n the length of the resulting array
* @param elem the element composing the resulting array
@@ -406,8 +434,8 @@ object Array extends FallbackArrayBuilding {
a
}
- /** Create an array containing the values of a given function f
- * over given range [0..n)
+ /** Creates an array containing the values of a given function `f`
+ * over given range `[0..n)`
*/
@deprecated("use `Array.tabulate' instead")
def fromFunction[T: ClassManifest](f: Int => T)(n: Int): Array[T] = {
@@ -420,37 +448,37 @@ object Array extends FallbackArrayBuilding {
a
}
- /** Create an array containing the values of a given function f
- * over given range [0..n1, 0..n2)
+ /** Creates an array containing the values of a given function `f`
+ * over given range `[0..n1, 0..n2)`
*/
@deprecated("use `Array.tabulate' instead")
def fromFunction[T: ClassManifest](f: (Int, Int) => T)(n1: Int, n2: Int): Array[Array[T]] =
fromFunction(i => fromFunction(f(i, _))(n2))(n1)
- /** Create an array containing the values of a given function f
- * over given range [0..n1, 0..n2, 0..n3)
+ /** Creates an array containing the values of a given function `f`
+ * over given range `[0..n1, 0..n2, 0..n3)`
*/
@deprecated("use `Array.tabulate' instead")
def fromFunction[T: ClassManifest](f: (Int, Int, Int) => T)(n1: Int, n2: Int, n3: Int): Array[Array[Array[T]]] =
fromFunction(i => fromFunction(f(i, _, _))(n2, n3))(n1)
- /** Create an array containing the values of a given function f
- * over given range [0..n1, 0..n2, 0..n3, 0..n4)
+ /** Creates an array containing the values of a given function `f`
+ * over given range `[0..n1, 0..n2, 0..n3, 0..n4)`
*/
@deprecated("use `Array.tabulate' instead")
def fromFunction[T: ClassManifest](f: (Int, Int, Int, Int) => T)(n1: Int, n2: Int, n3: Int, n4: Int): Array[Array[Array[Array[T]]]] =
fromFunction(i => fromFunction(f(i, _, _, _))(n2, n3, n4))(n1)
- /** Create an array containing the values of a given function f
- * over given range [0..n1, 0..n2, 0..n3, 0..n4, 0..n5)
+ /** Creates an array containing the values of a given function `f`
+ * over given range `[0..n1, 0..n2, 0..n3, 0..n4, 0..n5)`
*/
@deprecated("use `Array.tabulate' instead")
def fromFunction[T: ClassManifest](f: (Int, Int, Int, Int, Int) => T)(n1: Int, n2: Int, n3: Int, n4: Int, n5: Int): Array[Array[Array[Array[Array[T]]]]] =
fromFunction(i => fromFunction(f(i, _, _, _, _))(n2, n3, n4, n5))(n1)
}
-/** This class represents polymorphic arrays. Array[T]
is Scala's representation
- * for Java's T[]
.
+/** Represents polymorphic arrays. `Array[T]` is Scala's representation
+ * for Java's `T[]`.
*
* @author Martin Odersky
* @version 1.0
@@ -518,17 +546,17 @@ final class Array[T](_length: Int) {
/** The element at given index.
* 0
; xs.apply(0)
is the first
- * element of array xs
.
+ * Indices start a `0`; `xs.apply(0)` is the first
+ * element of array `xs`.
* xs(i)
is a shorthand for
- * xs.apply(i)
.
+ * Note the indexing syntax `xs(i)` is a shorthand for
+ * `xs.apply(i)`.
* i < 0
or
- * length <= i
+ * @throws ArrayIndexOutOfBoundsException if `i < 0` or
+ * `length <= i`
*/
def apply(i: Int): T = throw new Error()
@@ -536,18 +564,18 @@ final class Array[T](_length: Int) {
* Update the element at given index.
*
- * Indices start a 0
; xs.apply(0)
is the first
- * element of array xs
.
+ * Indices start a `0`; `xs.apply(0)` is the first
+ * element of array `xs`.
*
- * Note the indexing syntax xs(i) = x
is a shorthand
- * for xs.update(i, x)
.
+ * Note the indexing syntax `xs(i) = x` is a shorthand
+ * for `xs.update(i, x)`.
*
i
- * @throws ArrayIndexOutOfBoundsException if i < 0
or
- * length <= i
+ * @param x the value to be written at index `i`
+ * @throws ArrayIndexOutOfBoundsException if `i < 0` or
+ * `length <= i`
*/
def update(i: Int, x: T) { throw new Error() }
--
cgit v1.2.3