Improves documentation of scala.Predef. Contributed by Iain McGinniss during the Aug 20 Docspree. Review by phaller.

git-svn-id: http://lampsvn.epfl.ch/svn-repos/scala/scala/trunk@25530 5e8d7ff9-d8ef-0310-90f0-a4852d11357a
This commit is contained in:
heathermiller 2011-08-20 19:52:30 +00:00
parent 51805d5782
commit 9df857c88a
1 changed files with 62 additions and 4 deletions

View File

@ -17,12 +17,70 @@ import annotation.elidable.ASSERTION
/** The `Predef` object provides definitions that are accessible in all Scala
* compilation units without explicit qualification.
*
* === Commonly Used Types ===
* Predef provides type aliases for types which are commonly used, such as
* the immutable collection types [[scala.collection.immutable.Map]],
* [[scala.collection.immutable.Set]], and the [[scala.collection.immutable.List]]
* constructors ([[scala.collection.immutable.::]] and
* [[scala.collection.immutable.Nil]]).
* The types `Pair` (a [[scala.Tuple2]]) and `Triple` (a [[scala.Tuple3]]), with
* simple constructors, are also provided.
*
* === Console I/O ===
* Predef provides a number of simple functions for console I/O, such as
* `print`, `println`, `readLine`, `readInt`, etc. These functions are all
* aliases of the functions provided by [[scala.Console]].
*
* === Assertions ===
*
* A set of `assert` functions are provided for use as a way to document
* and dynamically check invariants in code. `assert` statements can be elided
* at runtime by providing the command line argument `-Xdisable-assertions` to
* the `scala` command.
*
* Variants of `assert` intended for use with static analysis tools are also
* provided: `assume`, `require` and `ensuring`. `require` and `ensuring` are
* intended for use as a means of design-by-contract style specification
* of pre- and post-conditions on functions, with the intention that these
* specifications could be consumed by a static analysis tool. For instance,
*
* {{{
* def addNaturals(nats: List[Int]): Int = {
* require(nats forall (_ >= 0), "List contains negative numbers")
* nats.foldLeft(0)(_ + _)
* } ensuring(_ >= 0)
* }}}
*
* The declaration of `addNaturals` states that the list of integers passed should
* only contain natural numbers (i.e. non-negative), and that the result returned
* will also be natural. `require` is distinct from `assert` in that if the
* condition fails, then the caller of the function is to blame rather than a
* logical error having been made within `addNaturals` itself. `ensures` is a
* form of `assert` that declares the guarantee the function is providing with
* regards to it's return value.
*
* === Implicit Conversions ===
* A number of commonly applied implicit conversions are also defined here, and
* in the parent type [[scala.LowPriorityImplicits]]. Implicit conversions
* are provided for the "widening" of numeric values, for instance, converting a
* Short value to a Long value as required, and to add additional higher-order
* functions to Array values. These are described in more detail in the documentation of [[scala.Array]].
*/
object Predef extends LowPriorityImplicits {
/** Return the runtime representation of a class type. This is a stub method.
* The actual implementation is filled in by the compiler.
/**
* Retrieve the runtime representation of a class type. `classOf[T]` is equivalent to
* the class literal `T.class` in Java.
*
* @example {{{
* val listClass = classOf[List[_]]
* // listClass is java.lang.Class[List[_]] = class scala.collection.immutable.List
*
* val mapIntString = classOf[Map[Int,String]]
* // mapIntString is java.lang.Class[Map[Int,String]] = interface scala.collection.immutable.Map
* }}}
*/
def classOf[T]: Class[T] = null
def classOf[T]: Class[T] = null // This is a stub method. The actual implementation is filled in by the compiler.
type String = java.lang.String
type Class[T] = java.lang.Class[T]