diff options
author | Heather Miller <heather.miller@epfl.ch> | 2012-11-01 21:51:36 +0100 |
---|---|---|
committer | Heather Miller <heather.miller@epfl.ch> | 2012-11-02 15:00:19 +0100 |
commit | 71f02cd041e9c20d309686fcccf830a0f919f641 (patch) | |
tree | e219dbec99fe2cbb68f55f1ab2a45dee074ac488 /src/library | |
parent | 59149579aec4b3d26a4cb849d80535a36b90ad30 (diff) | |
download | scala-71f02cd041e9c20d309686fcccf830a0f919f641.tar.gz scala-71f02cd041e9c20d309686fcccf830a0f919f641.tar.bz2 scala-71f02cd041e9c20d309686fcccf830a0f919f641.zip |
SI-6399 Adds API docs for Any and AnyVal
- Updates AnyVal docs to address value classes.
- Updates Any docs to address universal traits.
Diffstat (limited to 'src/library')
-rw-r--r-- | src/library/scala/AnyVal.scala | 37 |
1 files changed, 32 insertions, 5 deletions
diff --git a/src/library/scala/AnyVal.scala b/src/library/scala/AnyVal.scala index d637527b30..ebdc963946 100644 --- a/src/library/scala/AnyVal.scala +++ b/src/library/scala/AnyVal.scala @@ -9,8 +9,8 @@ package scala /** `AnyVal` is the root class of all ''value types'', which describe values - * not implemented as objects in the underlying host system. The value classes - * are specified in SLS 12.2. + * not implemented as objects in the underlying host system. Value classes + * are specified in Scala Language Specification, section 12.2. * * The standard implementation includes nine `AnyVal` subtypes: * @@ -21,9 +21,36 @@ package scala * * Other groupings: * - * The ''subrange types'' are [[scala.Byte]], [[scala.Short]], and [[scala.Char]]. - * The ''integer types'' include the subrange types as well as [[scala.Int]] and [[scala.Long]]. - * The ''floating point types'' are [[scala.Float]] and [[scala.Double]]. + * - The ''subrange types'' are [[scala.Byte]], [[scala.Short]], and [[scala.Char]]. + * - The ''integer types'' include the subrange types as well as [[scala.Int]] and [[scala.Long]]. + * - The ''floating point types'' are [[scala.Float]] and [[scala.Double]]. + * + * Prior to Scala 2.10, `AnyVal` was a sealed trait. Beginning with Scala 2.10, + * however, it is possible to define a subclass of `AnyVal` called a ''user-defined value class'' + * which is treated specially by the compiler. Properly-defined user value classes provide a way + * to improve performance on user-defined types by avoiding object allocation at runtime, and by + * replacing virtual method invocations with static method invocations. + * + * User-defined value classes which avoid object allocation... + * + * - must have a single, public `val` parameter that is the underlying runtime representation. + * - can define `def`s, but no `val`s, `var`s, or nested `traits`s, `class`es or `object`s. + * - typically extend no other trait apart from `AnyVal`. + * - cannot be used in type tests or pattern matching. + * - may not override `equals` or `hashCode` methods. + * + * A minimal example: + * {{{ + * class Wrapper(val underlying: Int) extends AnyVal { + * def foo: Wrapper = new Wrapper(underlying * 19) + * } + * }}} + * + * It's important to note that user-defined value classes are limited, and in some circumstances, + * still must allocate a value class instance at runtime. These limitations and circumstances are + * explained in greater detail in the [[http://docs.scala-lang.org/overviews/core/value-classes.html Value Classes Guide]] + * as well as in [[http://docs.scala-lang.org/sips/pending/value-classes.html SIP-15: Value Classes]], + * the Scala Improvement Proposal. */ abstract class AnyVal extends Any with NotNull { def getClass(): Class[_ <: AnyVal] = null |