diff options
| -rw-r--r-- | 03-lexical-syntax.md | 21 | ||||
| -rw-r--r-- | 04-identifiers-names-and-scopes.md | 3 | ||||
| -rw-r--r-- | 05-types.md | 34 | ||||
| -rw-r--r-- | 06-basic-declarations-and-definitions.md | 90 | ||||
| -rw-r--r-- | 07-classes-and-objects.md | 63 | ||||
| -rw-r--r-- | 08-expressions.md | 31 | ||||
| -rw-r--r-- | 09-implicit-parameters-and-views.md | 2 | ||||
| -rw-r--r-- | 10-pattern-matching.md | 6 | ||||
| -rw-r--r-- | 13-user-defined-annotations.md | 196 | ||||
| -rw-r--r-- | 14-the-scala-standard-library.md | 224 | ||||
| -rw-r--r-- | 15-scala-syntax-summary.md | 12 |
11 files changed, 395 insertions, 287 deletions
diff --git a/03-lexical-syntax.md b/03-lexical-syntax.md index 7f4614f387..f40e0f6d86 100644 --- a/03-lexical-syntax.md +++ b/03-lexical-syntax.md @@ -42,7 +42,7 @@ plainid ::= upper idrest | varid | op id ::= plainid - | ‘`’ stringLit ‘`’ + | ‘`’ stringLiteral ‘`’ idrest ::= {letter | digit} [‘_’ op] ``` @@ -347,15 +347,15 @@ is _pt_. The numeric ranges given by these types are: (@) Here are some integer literals: - ``` - 0 21 0xFFFFFFFF 0777L - ``` +``` +0 21 0xFFFFFFFF -42L +``` ### Floating Point Literals ``` -floatingPointLiteral ::= digit {digit} ‘.’ {digit} [exponentPart] [floatType] +floatingPointLiteral ::= digit {digit} ‘.’ digit {digit} [exponentPart] [floatType] | ‘.’ digit {digit} [exponentPart] [floatType] | digit {digit} exponentPart [floatType] | digit {digit} [exponentPart] floatType @@ -381,11 +381,10 @@ whitespace character between the two tokens. ``` (@) The phrase `1.toString` parses as three different tokens: - `1`, `.`, and `toString`. On the - other hand, if a space is inserted after the period, the phrase - `1. toString` parses as the floating point literal - `1.` followed by the identifier `toString`. + the integer literal `1`, a `.`, and the identifier `toString`. +(@) `1.` is not a valid floating point literal, because the + mandatory digit after the `.` is missing. ### Boolean Literals @@ -479,8 +478,8 @@ The expression ``` """the present string - spans three - lines.""".stripMargin + |spans three + |lines.""".stripMargin ``` evaluates to diff --git a/04-identifiers-names-and-scopes.md b/04-identifiers-names-and-scopes.md index a102043691..1e74e52b5f 100644 --- a/04-identifiers-names-and-scopes.md +++ b/04-identifiers-names-and-scopes.md @@ -54,8 +54,7 @@ is bound by a definition or declaration, then $x$ refers to the entity introduced by that binding. In that case, the type of $x$ is the type of the referenced entity. -(@) Assume the following two definitions of a objects named -`X` in packages `P` and `Q`. +(@) Assume the following two definitions of a objects named `X` in packages `P` and `Q`. ``` package P { diff --git a/05-types.md b/05-types.md index 9dd5ed9690..25210294ea 100644 --- a/05-types.md +++ b/05-types.md @@ -637,6 +637,40 @@ the corresponding type parameter clause. `newType` type constructor parameter in `flatMap`. +<!-- ### Overloaded Types + +More than one values or methods are defined in the same scope with the +same name, we model + +An overloaded type consisting of type alternatives $T_1 \commadots T_n (n \geq 2)$ is denoted internally $T_1 \overload \ldots \overload T_n$. + +(@) The definitions +``` +def println: Unit +def println(s: String): Unit = $\ldots$ +def println(x: Float): Unit = $\ldots$ +def println(x: Float, width: Int): Unit = $\ldots$ +def println[A](x: A)(tostring: A => String): Unit = $\ldots$ +``` +define a single function `println` which has an overloaded +type. +``` +println: => Unit $\overload$ + (String) Unit $\overload$ + (Float) Unit $\overload$ + (Float, Int) Unit $\overload$ + [A] (A) (A => String) Unit +``` + +(@) The definitions +``` +def f(x: T): T = $\ldots$ +val f = 0 +``` +define a function `f} which has type `(x: T)T $\overload$ Int`. +--> + + ## Base Types and Member Definitions Types of class members depend on the way the members are referenced. diff --git a/06-basic-declarations-and-definitions.md b/06-basic-declarations-and-definitions.md index 21a3956916..5d8f6aee78 100644 --- a/06-basic-declarations-and-definitions.md +++ b/06-basic-declarations-and-definitions.md @@ -35,6 +35,65 @@ between and including $s_i$ and $s_j$, - If $s_k$ is a value definition, it must be lazy. +<!-- +Every basic definition may introduce several defined names, separated +by commas. These are expanded according to the following scheme: +\bda{lcl} +\VAL;x, y: T = e && \VAL; x: T = e \\ + && \VAL; y: T = x \\[0.5em] + +\LET;x, y: T = e && \LET; x: T = e \\ + && \VAL; y: T = x \\[0.5em] + +\DEF;x, y (ps): T = e &\tab\mbox{expands to}\tab& \DEF; x(ps): T = e \\ + && \DEF; y(ps): T = x(ps)\\[0.5em] + +\VAR;x, y: T := e && \VAR;x: T := e\\ + && \VAR;y: T := x\\[0.5em] + +\TYPE;t,u = T && \TYPE; t = T\\ + && \TYPE; u = t\\[0.5em] +\eda + +All definitions have a ``repeated form`` where the initial +definition keyword is followed by several constituent definitions +which are separated by commas. A repeated definition is +always interpreted as a sequence formed from the +constituent definitions. E.g.\ the function definition +`def f(x) = x, g(y) = y` expands to +`def f(x) = x; def g(y) = y` and +the type definition +`type T, U <: B` expands to +`type T; type U <: B`. +} +\comment{ +If an element in such a sequence introduces only the defined name, +possibly with some type or value parameters, but leaves out any +additional parts in the definition, then those parts are implicitly +copied from the next subsequent sequence element which consists of +more than just a defined name and parameters. Examples: + + +- [] +The variable declaration `var x, y: Int` +expands to `var x: Int; var y: Int`. +- [] +The value definition `val x, y: Int = 1` +expands to `val x: Int = 1; val y: Int = 1`. +- [] +The class definition `case class X(), Y(n: Int) extends Z` expands to +`case class X extends Z; case class Y(n: Int) extends Z`. +- The object definition `case object Red, Green, Blue extends Color`~ +expands to +``` +case object Red extends Color +case object Green extends Color +case object Blue extends Color . +``` +--> + + + ## Value Declarations and Definitions ``` @@ -428,6 +487,7 @@ changes at the following constructs. - The variance position of the lower bound of a type declaration or type parameter is the opposite of the variance position of the type declaration or parameter. - The type of a mutable variable is always in invariant position. +- The right-hand side of a type alias is always in invariant position. - The prefix $S$ of a type selection `$S$#$T$` is always in invariant position. - For a type argument $T$ of a type `$S$[$\ldots T \ldots$ ]`: If the corresponding type parameter is invariant, then $T$ is in @@ -438,7 +498,7 @@ changes at the following constructs. <!-- TODO: handle type aliases --> References to the type parameters in -[object-private or object-protected values, variables, or methods](#modifiers) of the class are not +[object-private or object-protected values, types, variables, or methods](#modifiers) of the class are not checked for their variance position. In these members the type parameter may appear anywhere without restricting its legal variance annotations. @@ -573,12 +633,9 @@ user programs. The scope of a formal value parameter name $x$ comprises all subsequent parameter clauses, as well as the method return type and the function body, if -they are given [^5]. Both type parameter names and value parameter names must +they are given. Both type parameter names and value parameter names must be pairwise distinct. -[^5]: However, at present singleton types of method parameters may only appear - in the method body; so _dependent method types_ are not supported. - (@) In the method ``` @@ -700,7 +757,7 @@ FunDcl ::= FunSig FunDef ::= FunSig [nl] ‘{’ Block ‘}’ ``` -Special syntax exists for procedures, i.e.\ functions that return the +Special syntax exists for procedures, i.e. functions that return the `Unit` value `()`. A procedure declaration is a function declaration where the result type is omitted. The result type is then implicitly completed to the @@ -761,6 +818,24 @@ as $R$ conforms to $R'$. in `C`, even though the method is recursive. + +<!-- ## Overloaded Definitions +\label{sec:overloaded-defs} +\todo{change} + +An overloaded definition is a set of $n > 1$ value or function +definitions in the same statement sequence that define the same name, +binding it to types `$T_1 \commadots T_n$`, respectively. +The individual definitions are called _alternatives_. Overloaded +definitions may only appear in the statement sequence of a template. +Alternatives always need to specify the type of the defined entity +completely. It is an error if the types of two alternatives $T_i$ and +$T_j$ have the same erasure (\sref{sec:erasure}). + +\todo{Say something about bridge methods.} +%This must be a well-formed +%overloaded type --> + ## Import Clauses ``` @@ -776,8 +851,7 @@ An import clause has the form `import $p$.$I$` where $p$ is a The import expression determines a set of names of importable members of $p$ which are made available without qualification. A member $m$ of $p$ is _importable_ if it is not [object-private](#modifiers). -The most general form of an import expression is a list of {\em import -selectors} +The most general form of an import expression is a list of _import selectors_ ``` { $x_1$ => $y_1 , \ldots , x_n$ => $y_n$, _ } diff --git a/07-classes-and-objects.md b/07-classes-and-objects.md index e212e56ada..292f6eaa53 100644 --- a/07-classes-and-objects.md +++ b/07-classes-and-objects.md @@ -46,20 +46,6 @@ always assume that this implicit extension has been performed, so that the first parent class of a template is a regular superclass constructor, not a trait reference. -The list of parents of every class is also always implicitly extended -by a reference to the `scala.ScalaObject` trait as last -mixin. E.g. - -``` -$sc$ with $mt_1$ with $\ldots$ with $mt_n$ { $\mathit{stats}$ } -``` - -becomes - -``` -$mt_1$ with $\ldots$ with $mt_n$ with ScalaObject { $\mathit{stats}$ }. -``` - The list of parents of a template must be well-formed. This means that the class denoted by the superclass constructor $sc$ must be a subclass of the superclasses of all the traits $mt_1 , \ldots , mt_n$. @@ -229,12 +215,9 @@ linearization of this graph is defined as follows. Then the linearization of class `Iter` is ``` - { Iter, RichIterator, StringIterator, AbsIterator, ScalaObject, AnyRef, Any } + { Iter, RichIterator, StringIterator, AbsIterator, AnyRef, Any } ``` - Trait `ScalaObject` appears in this list because it - is added as last mixin to every Scala class ( [see here](#templates) ). - Note that the linearization of a class refines the inheritance relation: if $C$ is a subclass of $D$, then $C$ precedes $D$ in any linearization where both $C$ and $D$ occur. @@ -244,7 +227,7 @@ linearization of this graph is defined as follows. `StringIterator` is ``` - { StringIterator, AbsIterator, ScalaObject, AnyRef, Any } + { StringIterator, AbsIterator, AnyRef, Any } ``` which is a suffix of the linearization of its subclass `Iter`. @@ -252,7 +235,7 @@ linearization of this graph is defined as follows. For instance, the linearization of `RichIterator` is ``` - { RichIterator, AbsIterator, ScalaObject, AnyRef, Any } + { RichIterator, AbsIterator, AnyRef, Any } ``` which is not a suffix of the linearization of `Iter`. @@ -284,10 +267,13 @@ following definition of _matching_ on members: > 4. $M$ and $M'$ define both polymorphic methods with > equal number of argument types $\overline T$, $\overline T'$ > and equal numbers of type parameters -> $\overline t$, $\overline t'$, say, and -> $\overline T' = [\overline t'/\overline t]\overline T$. -> by the corresponding type parameter $t$ of $M$. +> $\overline t$, $\overline t'$, say, and $\overline T' = [\overline t'/\overline t]\overline T$. +<!-- +every argument type +$T_i$ of $M$ is equal to the corresponding argument type $T`_i$ of +$M`$ where every occurrence of a type parameter $t`$ of $M`$ has been replaced by the corresponding type parameter $t$ of $M$. +--> Member definitions fall into two categories: concrete and abstract. Members of class $C$ are either _directly defined_ (i.e.\ they appear in @@ -517,8 +503,7 @@ the validity and meaning of a modifier are as follows. enclosing the definition. Members labeled with such a modifier are accessible respectively only from code inside the package $C$ or only from code inside the class $C$ and its - [companion module](#object-definitions). Such members are also inherited only - from templates inside $C$. + [companion module](#object-definitions). An different form of qualification is `private[this]`. A member $M$ marked with this modifier is called _object-protected_; it can be accessed only from within @@ -560,7 +545,7 @@ the validity and meaning of a modifier are as follows. class which contains the access. A different form of qualification is `protected[this]`. A member - $M$ marked with this modifier can be accessed only from within + $M$ marked with this modifier is called _object-protected_; it can be accessed only from within the object in which it is defined. That is, a selection $p.M$ is only legal if the prefix is `this` or `$O$.this`, for some class $O$ enclosing the reference. In addition, the restrictions for @@ -908,18 +893,19 @@ but the `apply` and `unapply` methods are added to the existing object instead. A method named `copy` is implicitly added to every case class unless the -class already has a member (directly defined or inherited) with that name. The -method is defined as follows: +class already has a member (directly defined or inherited) with that name, or the +class has a repeated parameter. The method is defined as follows: ``` def copy[$\mathit{tps}\,$]($\mathit{ps}'_1\,$)$\ldots$($\mathit{ps}'_n$): $c$[$\mathit{tps}\,$] = new $c$[$\mathit{Ts}\,$]($\mathit{xs}_1\,$)$\ldots$($\mathit{xs}_n$) ``` -Again, $\mathit{Ts}$ stands for the vector of types defined in the type parameter section $\mathit{tps}$ -and each $\mathit{xs}_i$ denotes the parameter names of the parameter section $\mathit{ps}'_i$. Every value -parameter $\mathit{ps}'_{i,j}$ of the `copy` method has the form `$x_{i,j}$:$T_{i,j}$=this.$x_{i,j}$`, -where $x_{i,j}$ and $T_{i,j}$ refer to the name and type of the corresponding class parameter -$\mathit{ps}_{i,j}$. +Again, `$\mathit{Ts}$` stands for the vector of types defined in the type parameter section `$\mathit{tps}$` +and each `$\xs_i$` denotes the parameter names of the parameter section `$\ps'_i$`. The value +parameters `$\ps'_{1,j}$` of first parameter list have the form `$x_{1,j}$:$T_{1,j}$=this.$x_{1,j}$`, +the other parameters `$\ps'_{i,j}$` of the `copy` method are defined as `$x_{i,j}$:$T_{i,j}$`. +In all cases `$x_{i,j}$` and `$T_{i,j}$` refer to the name and type of the corresponding class parameter +`$\mathit{ps}_{i,j}$`. Every case class implicitly overrides some method definitions of class [`scala.AnyRef`](#root-classes) unless a definition of the same @@ -1157,8 +1143,11 @@ top-level objects are translated to static fields. as a pair of a Scala class that contains all instance members of $C$ and a Scala object that contains all static members of $C$. - Generally, a _companion module_ of a class is an object which has - the same name as the class and is defined in the same scope and - compilation unit. Conversely, the class is called the _companion class_ - of the module. +Generally, a _companion module_ of a class is an object which has +the same name as the class and is defined in the same scope and +compilation unit. Conversely, the class is called the _companion class_ +of the module. +Very much like a concrete class definition, an object definition may +still contain declarations of abstract type members, but not of +abstract term members. diff --git a/08-expressions.md b/08-expressions.md index 140dad39b9..1fe82e9b95 100644 --- a/08-expressions.md +++ b/08-expressions.md @@ -92,9 +92,8 @@ implements methods in class `scala.AnyRef` as follows: - `ne($x\,$)` and `!=($x\,$)` return true iff the argument x is not also the ``null'' object. - `isInstanceOf[$T\,$]` always returns `false`. -- `asInstanceOf[$T\,$]` returns the ``null'' object itself if - $T$ conforms to `scala.AnyRef`, and throws a - `NullPointerException` otherwise. +- `asInstanceOf[$T\,$]` returns the [default value](#value-declarations-and-definitions) of type $T$. +- `##` returns ``0``. A reference to any other member of the ``null'' object causes a `NullPointerException` to be thrown. @@ -122,6 +121,10 @@ If $r$ is a [stable identifier](#paths) of type $T$, the selection $r.x$ refers statically to a term member $m$ of $r$ that is identified in $T$ by the name $x$. +<!-- There might be several such members, in which +case overloading resolution (\sref{overloading-resolution}) is applied +to pick a unique one.} --> + For other expressions $e$, $e.x$ is typed as if it was `{ val $y$ = $e$; $y$.$x$ }`, for some fresh name $y$. @@ -181,7 +184,7 @@ in the least proper supertype of the innermost template containing the reference. It evaluates to the member $m'$ in the actual supertype of that template which is equal to $m$ or which overrides $m$. The statically referenced member $m$ must be a type or a -method. +method. <!-- explanation: so that we need not create several fields for overriding vals --> If it is a method, it must be concrete, or the template @@ -345,8 +348,9 @@ of the caller. If an application might uses named arguments $p = e$ or default arguments, the following conditions must hold. -- The named arguments form a suffix of the argument list $e_1 , \ldots , e_m$, - i.e.\ no positional argument follows a named one. +- For every named argument $p_i = e_i$ which appears left of a positional argument + in the argument list $e_1 \ldots e_m$, the argument position $i$ coincides with + the position of parameter $p_i$ in the parameter list of the applied function. - The names $x_i$ of all named arguments are pairwise distinct and no named argument defines a parameter which is already specified by a positional argument. @@ -920,7 +924,7 @@ Expr1 ::= `for' (`(' Enumerators `)' | `{' Enumerators `}') Enumerators ::= Generator {semi Enumerator} Enumerator ::= Generator | Guard - | `val' Pattern1 `=' Expr + | Pattern1 `=' Expr Generator ::= Pattern1 `<-' Expr [Guard] Guard ::= `if' PostfixExpr ``` @@ -1342,7 +1346,7 @@ Implicit conversions can be applied to expressions whose type does not match their expected type, to qualifiers in selections, and to unapplied methods. The available implicit conversions are given in the next two sub-sections. -We say, a type $T$ is _compatible_ to a type $U$ if $T$ conforms +We say, a type $T$ is _compatible_ to a type $U$ if $T$ weakly conforms to $U$ after applying [eta-expansion](#eta-expansion) and [view applications](#views). @@ -1466,6 +1470,17 @@ Otherwise, one chooses the _most specific_ alternative among the alternatives in $\mathscr{CC}$, according to the following definition of being ``as specific as'', and ``more specific than'': +<!-- +question: given + def f(x: Int) + val f: { def apply(x: Int) } + f(1) // the value is chosen in our current implementation + why? + - method is as specific as value, because value is applicable to method`s argument types (item 1) + - value is as specific as method (item 3, any other type is always as specific..) + so the method is not more specific than the value. +--> + - A parameterized method $m$ of type `($p_1:T_1, \ldots , p_n:T_n$)$U$` is _as specific as_ some other member $m'$ of type $S$ if $m'$ is applicable to arguments `($p_1 , \ldots , p_n\,$)` of diff --git a/09-implicit-parameters-and-views.md b/09-implicit-parameters-and-views.md index 5f41d25e34..845d21e579 100644 --- a/09-implicit-parameters-and-views.md +++ b/09-implicit-parameters-and-views.md @@ -264,7 +264,7 @@ Views are applied in three situations. such a view is found, the expression $e$ is converted to `$v$($e$)`. 1. In a selection $e.m$ with $e$ of type $T$, if the selector $m$ does - not denote a member of $T$. In this case, a view $v$ is searched + not denote an accessible member of $T$. In this case, a view $v$ is searched which is applicable to $e$ and whose result contains a member named $m$. The search proceeds as in the case of implicit parameters, where the implicit scope is the one of $T$. If such a view is found, the diff --git a/10-pattern-matching.md b/10-pattern-matching.md index 04bc6e857d..2d1c79e538 100644 --- a/10-pattern-matching.md +++ b/10-pattern-matching.md @@ -364,11 +364,7 @@ compiler will issue an ``unchecked'' warning for these patterns to flag the possible loss of type-safety. A _type variable pattern_ is a simple identifier which starts with -a lower case letter. However, the predefined primitive type aliases -`unit`, `boolean`, `byte`, -`short`, `char`, `int`, -`long`, `float`, and `double` are not -classified as type variable patterns. +a lower case letter. ## Type Parameter Inference in Patterns diff --git a/13-user-defined-annotations.md b/13-user-defined-annotations.md index 717a6dcb1f..3d7fba6746 100644 --- a/13-user-defined-annotations.md +++ b/13-user-defined-annotations.md @@ -21,130 +21,132 @@ does not matter. Examples: ``` -@serializable class C { ... } // A class annotation. -@transient @volatile var m: Int // A variable annotation -String @local // A type annotation -(e: @unchecked) match { ... } // An expression annotation +@deprecated("Use D", "1.0") class C { ... } // Class annotation +@transient @volatile var m: Int // Variable annotation +String @local // Type annotation +(e: @unchecked) match { ... } // Expression annotation ``` The meaning of annotation clauses is implementation-dependent. On the Java platform, the following annotations have a standard meaning. * `@transient` \ - Marks a field to be non-persistent; this is - equivalent to the `transient` - modifier in Java. - + Marks a field to be non-persistent; this is + equivalent to the `transient` + modifier in Java. * `@volatile` \ - Marks a field which can change its value - outside the control of the program; this - is equivalent to the `volatile` - modifier in Java. - - * `@serializable` \ - Marks a class to be serializable; this is - equivalent to inheriting from the - `java.io.Serializable` interface - in Java. - + Marks a field which can change its value + outside the control of the program; this + is equivalent to the `volatile` + modifier in Java. * `@SerialVersionUID(<longlit>)` \ - Attaches a serial version identifier (a - `long` constant) to a class. - This is equivalent to a the following field - definition in Java: + Attaches a serial version identifier (a + `long` constant) to a class. + This is equivalent to a the following field + definition in Java: - ``` - private final static SerialVersionUID = <longlit> - ``` + ``` + private final static SerialVersionUID = <longlit> + ``` * `@throws(<classlit>)` \ - A Java compiler checks that a program contains handlers for checked exceptions - by analyzing which checked exceptions can result from execution of a method or - constructor. For each checked exception which is a possible result, the - `throws` - clause for the method or constructor must mention the class of that exception - or one of the superclasses of the class of that exception. + A Java compiler checks that a program contains handlers for checked exceptions + by analyzing which checked exceptions can result from execution of a method or + constructor. For each checked exception which is a possible result, the + `throws` + clause for the method or constructor must mention the class of that exception + or one of the superclasses of the class of that exception. + +## Java Beans Annotations + + * `@scala.beans.BeanProperty` \ + When prefixed to a definition of some variable `X`, this + annotation causes getter and setter methods `getX`, `setX` + in the Java bean style to be added in the class containing the + variable. The first letter of the variable appears capitalized after + the `get` or `set`. When the annotation is added to the + definition of an immutable value definition `X`, only a getter is + generated. The construction of these methods is part of + code-generation; therefore, these methods become visible only once a + classfile for the containing class is generated. + + * `@scala.beans.BooleanBeanProperty` \ + This annotation is equivalent to `scala.reflect.BeanProperty`, but + the generated getter method is named `isX` instead of `getX`. + +## Deprecation Annotations * `@deprecated(<stringlit>)` \ - Marks a definition as deprecated. Accesses to the - defined entity will then cause a deprecated warning mentioning the - message `<stringlit>` to be issued from the compiler. Deprecated - warnings are suppressed in code that belongs itself to a definition - that is labeled deprecated. - - * `@scala.reflect.BeanProperty` \ - When prefixed to a definition of some variable `X`, this - annotation causes getter and setter methods `getX`, `setX` - in the Java bean style to be added in the class containing the - variable. The first letter of the variable appears capitalized after - the `get` or `set`. When the annotation is added to the - definition of an immutable value definition `X`, only a getter is - generated. The construction of these methods is part of - code-generation; therefore, these methods become visible only once a - classfile for the containing class is generated. - - * `@scala.reflect.BooleanBeanProperty` \ - This annotation is equivalent to `scala.reflect.BeanProperty`, but - the generated getter method is named `isX` instead of `getX`. + Marks a definition as deprecated. Accesses to the + defined entity will then cause a deprecated warning mentioning the + message `<stringlit>` to be issued from the compiler. Deprecated + warnings are suppressed in code that belongs itself to a definition + that is labeled deprecated. + + * `@deprecatedName(name: <symbollit>)` \ + Marks a formal parameter name as deprecated. Invocations of this entity + using named parameter syntax refering to the deprecated parameter name cause a deprecation warning. + +## Scala Compiler Annotations * `@unchecked` \ - When applied to the selector of a `match` expression, - this attribute suppresses any warnings about non-exhaustive pattern - matches which would otherwise be emitted. For instance, no warnings - would be produced for the method definition below. + When applied to the selector of a `match` expression, + this attribute suppresses any warnings about non-exhaustive pattern + matches which would otherwise be emitted. For instance, no warnings + would be produced for the method definition below. - ``` - def f(x: Option[Int]) = (x: @unchecked) match { - case Some(y) => y - } - ``` + ``` + def f(x: Option[Int]) = (x: @unchecked) match { + case Some(y) => y + } + ``` - Without the `@unchecked` annotation, a Scala compiler could - infer that the pattern match is non-exhaustive, and could produce a - warning because `Option` is a `sealed` class. + Without the `@unchecked` annotation, a Scala compiler could + infer that the pattern match is non-exhaustive, and could produce a + warning because `Option` is a `sealed` class. * `@uncheckedStable` \ - When applied a value declaration or definition, it allows the defined - value to appear in a path, even if its type is [volatile](#volatile-types). - For instance, the following member definitions are legal: + When applied a value declaration or definition, it allows the defined + value to appear in a path, even if its type is [volatile](#volatile-types). + For instance, the following member definitions are legal: - ``` - type A { type T } - type B - @uncheckedStable val x: A with B // volatile type - val y: x.T // OK since `x' is still a path - ``` + ``` + type A { type T } + type B + @uncheckedStable val x: A with B // volatile type + val y: x.T // OK since `x' is still a path + ``` - Without the `@uncheckedStable` annotation, the designator `x` - would not be a path since its type `A with B` is volatile. Hence, - the reference `x.T` would be malformed. + Without the `@uncheckedStable` annotation, the designator `x` + would not be a path since its type `A with B` is volatile. Hence, + the reference `x.T` would be malformed. - When applied to value declarations or definitions that have non-volatile - types, the annotation has no effect. + When applied to value declarations or definitions that have non-volatile + types, the annotation has no effect. * `@specialized` \ - When applied to the definition of a type parameter, this annotation causes - the compiler - to generate specialized definitions for primitive types. An optional list of - primitive - types may be given, in which case specialization takes into account only - those types. - For instance, the following code would generate specialized traits for - `Unit`, `Int` and `Double` - - ``` - trait Function0[@specialized(Unit, Int, Double) T] { - def apply: T - } - ``` - - Whenever the static type of an expression matches a specialized variant of - a definition, - the compiler will instead use the specialized version. See \cite{spec-sid} - for more details of the implementation. + When applied to the definition of a type parameter, this annotation causes + the compiler + to generate specialized definitions for primitive types. An optional list of + primitive + types may be given, in which case specialization takes into account only + those types. + For instance, the following code would generate specialized traits for + `Unit`, `Int` and `Double` + + ``` + trait Function0[@specialized(Unit, Int, Double) T] { + def apply: T + } + ``` + + Whenever the static type of an expression matches a specialized variant of + a definition, + the compiler will instead use the specialized version. See \cite{spec-sid} + for more details of the implementation. Other annotations may be interpreted by platform- or diff --git a/14-the-scala-standard-library.md b/14-the-scala-standard-library.md index d6bb9eca52..59927f4e98 100644 --- a/14-the-scala-standard-library.md +++ b/14-the-scala-standard-library.md @@ -17,17 +17,17 @@ indirectly from this class. Class `Any` has two direct subclasses: `AnyRef` and AnyVal`. The subclass `AnyRef` represents all values which are represented -as objects in the underlying host system. Every user-defined Scala -class inherits directly or indirectly from this class. Furthermore, -every user-defined Scala class also inherits the trait -`scala.ScalaObject`. Classes written in other languages still -inherit from `scala.AnyRef`, but not from -`scala.ScalaObject`. - -The class `AnyVal` has a fixed number of subclasses, which describe +as objects in the underlying host system. Classes written in other languages +inherit from `scala.AnyRef`. + +The predefined subclasses of class `AnyVal` describe values which are not implemented as objects in the underlying host system. +User-defined Scala classes which do not explicitly inherit from +`AnyVal` inherit directly or indirectly from `AnyRef`. They can +not inherit from both `AnyRef` and `AnyVal`. + Classes `AnyRef` and `AnyVal` are required to provide only the members declared in class `Any`, but implementations may add host-specific methods to these classes (for instance, an @@ -84,8 +84,6 @@ class AnyRef extends Any { def synchronized[T](body: => T): T // execute `body` in while locking `this`. } -/** A mixin class for every user-defined Scala class */ -trait ScalaObject extends AnyRef ``` The type test `$x$.isInstanceOf[$T$]` is equivalent to a typed @@ -356,12 +354,12 @@ right operand. ### The `Tuple` classes -Scala defines tuple classes `Tuple$n$` for $n = 2 , \ldots , 9$. +Scala defines tuple classes `Tuple$n$` for $n = 2 , \ldots , 22$. These are defined as follows. ``` package scala -case class Tuple$n$[+A_1, ..., +A_n](_1: A_1, ..., _$n$: A_$n$) { +case class Tuple$n$[+T_1, ..., +T_n](_1: T_1, ..., _$n$: T_$n$) { def toString = "(" ++ _1 ++ "," ++ $\ldots$ ++ "," ++ _$n$ ++ ")" } ``` @@ -372,13 +370,13 @@ as an alias for `Tuple3`. ### The `Function` Classes -Scala defines function classes `Function$n$` for $n = 1 , \ldots , 9$. +Scala defines function classes `Function$n$` for $n = 1 , \ldots , 22$. These are defined as follows. ``` package scala -trait Function$n$[-A_1, ..., -A_$n$, +B] { - def apply(x_1: A_1, ..., x_$n$: A_$n$): B +trait Function$n$[-T_1, ..., -T_$n$, +R] { + def apply(x_1: T_1, ..., x_$n$: T_$n$): R def toString = "<function>" } ``` @@ -400,29 +398,33 @@ The implicitly imported [`Predef`](#the-predef-object) object defines the name ### Class `Array` -The class of generic arrays is given as follows. +All operations on arrays desugar to the corresponding operations of the +underlying platform. Therefore, the following class definition is given for +informational purposes only: -``` -final class Array[A](len: Int) extends Seq[A] { - def length: Int = len - def apply(i: Int): A = $\ldots$ - def update(i: Int, x: A): Unit = $\ldots$ - def elements: Iterator[A] = $\ldots$ - def subArray(from: Int, end: Int): Array[A] = $\ldots$ - def filter(p: A => Boolean): Array[A] = $\ldots$ - def map[B](f: A => B): Array[B] = $\ldots$ - def flatMap[B](f: A => Array[B]): Array[B] = $\ldots$ +``` +final class Array[T](_length: Int) +extends java.io.Serializable with java.lang.Cloneable { + def length: Int = $\ldots$ + def apply(i: Int): T = $\ldots$ + def update(i: Int, x: T): Unit = $\ldots$ + override def clone(): Array[T] = $\ldots$ } ``` -If $T$ is not a type parameter or abstract type, the type Array[$T$] -is represented as the native array type `[]$T$` in the -underlying host system. In that case `length` returns -the length of the array, `apply` means subscripting, and -`update` means element update. Because of the syntactic sugar for -`apply` and -`update` [operations](#implicit-conversions), -we have the following correspondences between Scala and Java/C\# code for +If $T$ is not a type parameter or abstract type, the type `Array[T]` +is represented as the array type `|T|[]` in the +underlying host system, where `|T|` is the erasure of `T`. +If $T$ is a type parameter or abstract type, a different representation might be +used (it is `Object` on the Java platform). + +#### Operations + +`length` returns the length of the array, `apply` means subscripting, +and `update` means element update. + +Because of the syntactic sugar for `apply` and `update` operations, +we have the following correspondences between Scala and Java/C# code for operations on an array `xs`: ------------------ ---------------------- @@ -432,16 +434,24 @@ _Scala_ _Java/C#_ `xs(i) = e` `xs[i] = e` ------------------ ---------------------- -Arrays also implement the sequence trait `scala.Seq` -by defining an `elements` method which returns -all elements of the array in an `Iterator`. +Two implicit conversions exist in `Predef` that are frequently applied to arrays: +a conversion to `scala.collection.mutable.ArrayOps` and a conversion to +`scala.collection.mutable.WrappedArray` (a subtype of `scala.collection.Seq`). + +Both types make many of the standard operations found in the Scala +collections API available. The conversion to `ArrayOps` is temporary, as all operations +defined on `ArrayOps` return a value of type `Array`, while the conversion to `WrappedArray` +is permanent as all operations return a value of type `WrappedArray`. +The conversion to `ArrayOps` takes priority over the conversion to `WrappedArray`. Because of the tension between parametrized types in Scala and the ad-hoc implementation of arrays in the host-languages, some subtle points need to be taken into account when dealing with arrays. These are explained in the following. -First, unlike arrays in Java or C\#, arrays in Scala are _not_ +#### Variance + +Unlike arrays in Java or C#, arrays in Scala are _not_ co-variant; That is, $S <: T$ does not imply `Array[$S$] $<:$ Array[$T$]` in Scala. However, it is possible to cast an array @@ -460,103 +470,95 @@ val xs = new Array[String](2) val ys: Array[Object] = xs.asInstanceOf[Array[Object]] // OK ``` -Second, for _polymorphic arrays_, that have a type parameter or -abstract type $T$ as their element type, a representation different -from -`[]T` might be used. However, it is guaranteed that -`isInstanceOf` and `asInstanceOf` still work as if the array -used the standard representation of monomorphic arrays: - -``` -val ss = new Array[String](2) - -def f[T](xs: Array[T]): Array[String] = - if (xs.isInstanceOf[Array[String]]) xs.asInstanceOf[Array[String]) - else throw new Error("not an instance") - -f(ss) // returns ss -``` - -The representation chosen for polymorphic arrays also guarantees that -polymorphic array creations work as expected. An example is the +The instantiation of an array with a polymorphic element type $T$ requires +information about type $T$ at runtime. +This information is synthesized by adding a [context bound](#context-bounds-and-view-bounds) +of `scala.reflect.ClassTag` to type $T$. +An example is the following implementation of method `mkArray`, which creates -an array of an arbitrary type $T$, given a sequence of $T$'s which -defines its elements. +an array of an arbitrary type $T$, given a sequence of $T$`s which +defines its elements: -``` -def mkArray[T](elems: Seq[T]): Array[T] = { +``` +import reflect.ClassTag +def mkArray[T : ClassTag](elems: Seq[T]): Array[T] = { val result = new Array[T](elems.length) var i = 0 for (elem <- elems) { result(i) = elem i += 1 } + result } ``` -Note that under Java's erasure model of arrays the method above would -not work as expected -- in fact it would always return an array of -`Object`. - -Third, in a Java environment there is a method `System.arraycopy` -which takes two objects as parameters together with start indices and -a length argument, and copies elements from one object to the other, -provided the objects are arrays of compatible element -types. `System.arraycopy` will not work for Scala's polymorphic -arrays because of their different representation. One should instead -use method `Array.copy` which is defined in the companion object -of class `Array`. This companion object also defines various -constructor methods for arrays, as well as -the [extractor method](#extractor-patterns) `unapplySeq` -which enables pattern matching over arrays. +If type $T$ is a type for which the host platform offers a specialized array +representation, this representation is used. -``` +(@) On the Java Virtual Machine, an invocation of + ``` + mkArray(List(1,2,3)) + ``` + will return a primitive array of `int`s, written as `int[]` in Java. + +#### Companion object + +`Array`'s companion object provides various factory methods for the +instantiation of single- and multi-dimensional arrays, an extractor method +[`unapplySeq`](#extractor-patterns) which enables pattern matching +over arrays and additional utility methods: + +``` package scala object Array { - /** copies array elements from `src' to `dest'. */ - def copy(src: AnyRef, srcPos: Int, + /** copies array elements from `src` to `dest`. */ + def copy(src: AnyRef, srcPos: Int, dest: AnyRef, destPos: Int, length: Int): Unit = $\ldots$ - /** Concatenate all argument arrays into a single array. */ - def concat[T](xs: Array[T]*): Array[T] = $\ldots$ + /** Returns an array of length 0 */ + def empty[T: ClassTag]: Array[T] = + + /** Create an array with given elements. */ + def apply[T: ClassTag](xs: T*): Array[T] = $\ldots$ - /** Create a an array of successive integers. */ + /** Creates array with given dimensions */ + def ofDim[T: ClassTag](n1: Int): Array[T] = $\ldots$ + /** Creates a 2-dimensional array */ + def ofDim[T: ClassTag](n1: Int, n2: Int): Array[Array[T]] = $\ldots$ + $\ldots$ + + /** Concatenate all argument arrays into a single array. */ + def concat[T: ClassTag](xss: Array[T]*): Array[T] = $\ldots$ + + /** Returns an array that contains the results of some element computation a number + * of times. */ + def fill[T: ClassTag](n: Int)(elem: => T): Array[T] = $\ldots$ + /** Returns a two-dimensional array that contains the results of some element + * computation a number of times. */ + def fill[T: ClassTag](n1: Int, n2: Int)(elem: => T): Array[Array[T]] = $\ldots$ + $\ldots$ + + /** Returns an array containing values of a given function over a range of integer + * values starting from 0. */ + def tabulate[T: ClassTag](n: Int)(f: Int => T): Array[T] = $\ldots$ + /** Returns a two-dimensional array containing values of a given function + * over ranges of integer values starting from `0`. */ + def tabulate[T: ClassTag](n1: Int, n2: Int)(f: (Int, Int) => T): Array[Array[T]] = $\ldots$ + $\ldots$ + + /** Returns an array containing a sequence of increasing integers in a range. */ def range(start: Int, end: Int): Array[Int] = $\ldots$ + /** Returns an array containing equally spaced values in some integer interval. */ + def range(start: Int, end: Int, step: Int): Array[Int] = $\ldots$ - /** Create an array with given elements. */ - def apply[A <: AnyRef](xs: A*): Array[A] = $\ldots$ - - /** Analogous to above. */ - def apply(xs: Boolean*): Array[Boolean] = $\ldots$ - def apply(xs: Byte*) : Array[Byte] = $\ldots$ - def apply(xs: Short*) : Array[Short] = $\ldots$ - def apply(xs: Char*) : Array[Char] = $\ldots$ - def apply(xs: Int*) : Array[Int] = $\ldots$ - def apply(xs: Long*) : Array[Long] = $\ldots$ - def apply(xs: Float*) : Array[Float] = $\ldots$ - def apply(xs: Double*) : Array[Double] = $\ldots$ - def apply(xs: Unit*) : Array[Unit] = $\ldots$ - - /** Create an array containing several copies of an element. */ - def make[A](n: Int, elem: A): Array[A] = { + /** Returns an array containing repeated applications of a function to a start value. */ + def iterate[T: ClassTag](start: T, len: Int)(f: T => T): Array[T] = $\ldots$ /** Enables pattern matching over arrays */ - def unapplySeq[A](x: Array[A]): Option[Seq[A]] = Some(x) + def unapplySeq[A](x: Array[A]): Option[IndexedSeq[A]] = Some(x) } ``` -(@) The following method duplicates a given argument array and returns a pair - consisting of the original and the duplicate: - - ``` - def duplicate[T](xs: Array[T]) = { - val ys = new Array[T](xs.length) - Array.copy(xs, 0, ys, 0, xs.length) - (xs, ys) - } - ``` - - ## Class Node ``` diff --git a/15-scala-syntax-summary.md b/15-scala-syntax-summary.md index 8e17360622..0a5a8f73a0 100644 --- a/15-scala-syntax-summary.md +++ b/15-scala-syntax-summary.md @@ -19,19 +19,17 @@ plainid ::= upper idrest | varid | op id ::= plainid - | ‘\`’ stringLit ‘\`’ + | ‘\`’ stringLiteral ‘\`’ idrest ::= {letter | digit} [‘_’ op] -integerLiteral ::= (decimalNumeral | hexNumeral | octalNumeral) [‘L’ | ‘l’] +integerLiteral ::= (decimalNumeral | hexNumeral) [‘L’ | ‘l’] decimalNumeral ::= ‘0’ | nonZeroDigit {digit} hexNumeral ::= ‘0’ ‘x’ hexDigit {hexDigit} -octalNumeral ::= ‘0’ octalDigit {octalDigit} digit ::= ‘0’ | nonZeroDigit nonZeroDigit ::= ‘1’ | … | ‘9’ -octalDigit ::= ‘0’ | … | ‘7’ floatingPointLiteral - ::= digit {digit} ‘.’ {digit} [exponentPart] [floatType] + ::= digit {digit} ‘.’ digit {digit} [exponentPart] [floatType] | ‘.’ digit {digit} [exponentPart] [floatType] | digit {digit} exponentPart [floatType] | digit {digit} [exponentPart] floatType @@ -157,7 +155,7 @@ grammar. Enumerators ::= Generator {semi Enumerator} Enumerator ::= Generator | Guard - | ‘val’ Pattern1 ‘=’ Expr + | Pattern1 ‘=’ Expr Generator ::= Pattern1 ‘<-’ Expr [Guard] CaseClauses ::= CaseClause { CaseClause } @@ -198,7 +196,7 @@ grammar. ClassParamClauses ::= {ClassParamClause} [[nl] ‘(’ ‘implicit’ ClassParams ‘)’] ClassParamClause ::= [nl] ‘(’ [ClassParams] ‘)’ - ClassParams ::= ClassParam {‘’ ClassParam} + ClassParams ::= ClassParam {‘,’ ClassParam} ClassParam ::= {Annotation} [{Modifier} (‘val’ | ‘var’)] id ‘:’ ParamType [‘=’ Expr] Bindings ::= ‘(’ Binding {‘,’ Binding ‘)’ |