From a8ec5198cb0722fad89ace83d8e167dcd80bfc17 Mon Sep 17 00:00:00 2001 From: Lukas Rytz Date: Mon, 16 Aug 2010 17:29:40 +0000 Subject: documentation for scala.Array. --- src/library/scala/Array.scala | 160 +++++++++++++++++++++++++----------------- 1 file changed, 94 insertions(+), 66 deletions(-) diff --git a/src/library/scala/Array.scala b/src/library/scala/Array.scala index 250fd09602..e7ee280cef 100644 --- a/src/library/scala/Array.scala +++ b/src/library/scala/Array.scala @@ -16,7 +16,7 @@ import compat.Platform.arraycopy import scala.reflect.ClassManifest import scala.runtime.ScalaRunTime.{array_apply, array_update} -/** A class containing a fall back builder for arrays where the element type +/** Contains a fallback builder for arrays when the element type * does not have a class manifest. In that case a generic array is built. */ class FallbackArrayBuilding { @@ -35,7 +35,7 @@ class FallbackArrayBuilding { } } -/** This object contains utility methods operating on arrays. +/** Utility methods for operating on arrays. * * @author Martin Odersky * @version 1.0 @@ -47,6 +47,9 @@ object Array extends FallbackArrayBuilding { def apply() = ArrayBuilder.make[T]()(m) } + /** + * Returns a new [[scala.collection.mutable.ArrayBuilder]]. + */ def newBuilder[T](implicit m: ClassManifest[T]): ArrayBuilder[T] = ArrayBuilder.make[T]()(m) private def slowcopy(src : AnyRef, @@ -65,15 +68,19 @@ object Array extends FallbackArrayBuilding { } /** Copy one array to another. - * Equivalent to - * 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. *

- * 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) is a shorthand for - * xs.apply(i). + * Note the indexing syntax `xs(i)` is a shorthand for + * `xs.apply(i)`. *

* * @param i the index - * @throws ArrayIndexOutOfBoundsException if 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)`. *

* * @param i the index - * @param x the value to be written at index 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