Skip to content

Commit 8ced261

Browse files
authored
Backport changes to reference docs from 3.2.0 (#16202)
did a rebase of `release-3.2.0` onto `language-reference-stable` and fixed conflicts fixes #16201
2 parents 5b81f19 + 8372014 commit 8ced261

24 files changed

+430
-408
lines changed

docs/_docs/reference/changed-features/pattern-bindings.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/pattern-b
77
In Scala 2, pattern bindings in `val` definitions and `for` expressions are
88
loosely typed. Potentially failing matches are still accepted at compile-time,
99
but may influence the program's runtime behavior.
10-
From Scala 3.1 on, type checking rules will be tightened so that warnings are reported at compile-time instead.
10+
From Scala 3.2 on, type checking rules will be tightened so that warnings are reported at compile-time instead.
1111

1212
## Bindings in Pattern Definitions
1313

@@ -16,7 +16,7 @@ val xs: List[Any] = List(1, 2, 3)
1616
val (x: String) :: _ = xs // error: pattern's type String is more specialized
1717
// than the right-hand side expression's type Any
1818
```
19-
This code gives a compile-time warning in Scala 3.1 (and also in Scala 3.0 under the `-source future` setting) whereas it will fail at runtime with a `ClassCastException` in Scala 2. In Scala 3.1, a pattern binding is only allowed if the pattern is _irrefutable_, that is, if the right-hand side's type conforms to the pattern's type. For instance, the following is OK:
19+
This code gives a compile-time warning in Scala 3.2 (and also earlier Scala 3.x under the `-source future` setting) whereas it will fail at runtime with a `ClassCastException` in Scala 2. In Scala 3.2, a pattern binding is only allowed if the pattern is _irrefutable_, that is, if the right-hand side's type conforms to the pattern's type. For instance, the following is OK:
2020
```scala
2121
val pair = (1, true)
2222
val (x, y) = pair
@@ -25,7 +25,7 @@ Sometimes one wants to decompose data anyway, even though the pattern is refutab
2525
```scala
2626
val first :: rest = elems // error
2727
```
28-
This works in Scala 2. In fact it is a typical use case for Scala 2's rules. But in Scala 3.1 it will give a warning. One can avoid the warning by marking the right-hand side with an [`@unchecked`](https://scala-lang.org/api/3.x/scala/unchecked.html) annotation:
28+
This works in Scala 2. In fact it is a typical use case for Scala 2's rules. But in Scala 3.2 it will give a warning. One can avoid the warning by marking the right-hand side with an [`@unchecked`](https://scala-lang.org/api/3.x/scala/unchecked.html) annotation:
2929
```scala
3030
val first :: rest = elems: @unchecked // OK
3131
```
@@ -40,7 +40,7 @@ val elems: List[Any] = List((1, 2), "hello", (3, 4))
4040
for (x, y) <- elems yield (y, x) // error: pattern's type (Any, Any) is more specialized
4141
// than the right-hand side expression's type Any
4242
```
43-
This code gives a compile-time warning in Scala 3.1 whereas in Scala 2 the list `elems`
43+
This code gives a compile-time warning in Scala 3.2 whereas in Scala 2 the list `elems`
4444
is filtered to retain only the elements of tuple type that match the pattern `(x, y)`.
4545
The filtering functionality can be obtained in Scala 3 by prefixing the pattern with `case`:
4646
```scala
@@ -56,4 +56,4 @@ Generator ::= [‘case’] Pattern1 ‘<-’ Expr
5656

5757
## Migration
5858

59-
The new syntax is supported in Scala 3.0. However, to enable smooth cross compilation between Scala 2 and Scala 3, the changed behavior and additional type checks are only enabled under the `-source future` setting. They will be enabled by default in version 3.1 of the language.
59+
The new syntax is supported in Scala 3.0. However, to enable smooth cross compilation between Scala 2 and Scala 3, the changed behavior and additional type checks are only enabled under the `-source future` setting. They will be enabled by default in version 3.2 of the language.

docs/_docs/reference/changed-features/pattern-matching.md

Lines changed: 13 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,15 @@ title: "Option-less pattern matching"
44
movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/pattern-matching.html
55
---
66

7-
The implementation of pattern matching in Scala 3 was greatly simplified compared to Scala 2. From a user perspective, this means that Scala 3 generated patterns are a *lot* easier to debug, as variables all show up in debug modes and positions are correctly preserved.
7+
The implementation of pattern matching in Scala 3 was greatly simplified compared to Scala 2. From a user perspective, this means that Scala 3 generated patterns are a _lot_ easier to debug, as variables all show up in debug modes and positions are correctly preserved.
88

99
Scala 3 supports a superset of Scala 2 [extractors](https://www.scala-lang.org/files/archive/spec/2.13/08-pattern-matching.html#extractor-patterns).
1010

1111
## Extractors
1212

1313
Extractors are objects that expose a method `unapply` or `unapplySeq`:
1414

15-
```Scala
15+
```scala
1616
def unapply[A](x: T)(implicit x: B): U
1717
def unapplySeq[A](x: T)(implicit x: B): U
1818
```
@@ -25,7 +25,7 @@ called variadic extractors, which enables variadic patterns.
2525

2626
Fixed-arity extractors expose the following signature:
2727

28-
```Scala
28+
```scala
2929
def unapply[A](x: T)(implicit x: B): U
3030
```
3131

@@ -36,7 +36,7 @@ The type `U` conforms to one of the following matches:
3636

3737
Or `U` conforms to the type `R`:
3838

39-
```Scala
39+
```scala
4040
type R = {
4141
def isEmpty: Boolean
4242
def get: S
@@ -62,7 +62,7 @@ A usage of a fixed-arity extractor is irrefutable if one of the following condit
6262

6363
Variadic extractors expose the following signature:
6464

65-
```Scala
65+
```scala
6666
def unapplySeq[A](x: T)(implicit x: B): U
6767
```
6868

@@ -73,7 +73,7 @@ The type `U` conforms to one of the following matches:
7373

7474
Or `U` conforms to the type `R`:
7575

76-
```Scala
76+
```scala
7777
type R = {
7878
def isEmpty: Boolean
7979
def get: S
@@ -167,7 +167,7 @@ object Nat:
167167
- `N > 1` is the maximum number of consecutive (parameterless `def` or `val`) `_1: P1 ... _N: PN` members in `U`
168168
- Pattern-matching on exactly `N` patterns with types `P1, P2, ..., PN`
169169

170-
```Scala
170+
```scala
171171
object ProdEmpty:
172172
def _1: Int = ???
173173
def _2: String = ???
@@ -180,12 +180,11 @@ object ProdEmpty:
180180
case _ => ()
181181
```
182182

183-
184183
## Sequence Match
185184

186185
- `U <: X`, `T2` and `T3` conform to `T1`
187186

188-
```Scala
187+
```scala
189188
type X = {
190189
def lengthCompare(len: Int): Int // or, `def length: Int`
191190
def apply(i: Int): T1
@@ -221,18 +220,18 @@ object CharList:
221220
the type of the remaining patterns are determined as in Seq Pattern.
222221

223222
```Scala
224-
class Foo(val name: String, val children: Int *)
223+
class Foo(val name: String, val children: Int*)
225224
object Foo:
226225
def unapplySeq(f: Foo): Option[(String, Seq[Int])] =
227226
Some((f.name, f.children))
228227

229228
def foo(f: Foo) = f match
230-
case Foo(name, ns : _*) =>
231-
case Foo(name, x, y, ns : _*) =>
229+
case Foo(name, x, y, ns*) => ">= two children."
230+
case Foo(name, ns*) => => "< two children."
232231
```
233232

234-
There are plans for further simplification, in particular to factor out *product
235-
match* and *name-based match* into a single type of extractor.
233+
There are plans for further simplification, in particular to factor out _product match_
234+
and _name-based match_ into a single type of extractor.
236235

237236
## Type testing
238237

docs/_docs/reference/contextual/context-bounds.md

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,14 @@ A context bound is a shorthand for expressing the common pattern of a context pa
1010
def maximum[T: Ord](xs: List[T]): T = xs.reduceLeft(max)
1111
```
1212

13-
A bound like `: Ord` on a type parameter `T` of a method or class indicates a context parameter `using Ord[T]`. The context parameter(s) generated from context bounds come last in the definition of the containing method or class. For instance,
13+
A bound like `: Ord` on a type parameter `T` of a method or class indicates a context parameter `using Ord[T]`. The context parameter(s) generated from context bounds
14+
are added as follows:
15+
16+
- If the method parameters end in an implicit parameter list or using clause,
17+
context parameters are added in front of that list.
18+
- Otherwise they are added as a separate parameter clause at the end.
19+
20+
Example:
1421

1522
```scala
1623
def f[T: C1 : C2, U: C3](x: T)(using y: U, z: V): R
@@ -19,7 +26,7 @@ def f[T: C1 : C2, U: C3](x: T)(using y: U, z: V): R
1926
would expand to
2027

2128
```scala
22-
def f[T, U](x: T)(using y: U, z: V)(using C1[T], C2[T], C3[U]): R
29+
def f[T, U](x: T)(using _: C1[T], _: C2[T], _: C3[U], y: U, z: V): R
2330
```
2431

2532
Context bounds can be combined with subtype bounds. If both are present, subtype bounds come first, e.g.

docs/_docs/reference/contextual/derivation-macro.md

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -31,12 +31,12 @@ given derived[T: Type](using Quotes): Expr[Eq[T]]
3131
and for comparison reasons we give the same signature we had with `inline`:
3232

3333
```scala
34-
inline given derived[T]: (m: Mirror.Of[T]) => Eq[T] = ???
34+
inline given derived[T](using Mirror.Of[T]): Eq[T] = ???
3535
```
3636

3737
Note, that since a type is used in a subsequent stage it will need to be lifted
38-
to a `Type` by using the corresponding context bound. Also, not that we can
39-
summon the quoted `Mirror` inside the body of the `derived` this we can omit it
38+
to a `Type` by using the corresponding context bound. Also, note that we can
39+
summon the quoted `Mirror` inside the body of the `derived` thus we can omit it
4040
from the signature. The body of the `derived` method is shown below:
4141

4242

@@ -49,15 +49,16 @@ given derived[T: Type](using Quotes): Expr[Eq[T]] =
4949
ev match
5050
case '{ $m: Mirror.ProductOf[T] { type MirroredElemTypes = elementTypes }} =>
5151
val elemInstances = summonAll[elementTypes]
52-
val eqProductBody: (Expr[T], Expr[T]) => Expr[Boolean] = (x, y) =>
53-
elemInstances.zipWithIndex.foldLeft(Expr(true: Boolean)) {
54-
case (acc, (elem, index)) =>
55-
val e1 = '{$x.asInstanceOf[Product].productElement(${Expr(index)})}
56-
val e2 = '{$y.asInstanceOf[Product].productElement(${Expr(index)})}
57-
'{ $acc && $elem.asInstanceOf[Eq[Any]].eqv($e1, $e2) }
58-
}
59-
60-
'{ eqProduct((x: T, y: T) => ${eqProductBody('x, 'y)}) }
52+
def eqProductBody(x: Expr[Product], y: Expr[Product])(using Quotes): Expr[Boolean] = {
53+
elemInstances.zipWithIndex.foldLeft(Expr(true)) {
54+
case (acc, ('{ $elem: Eq[t] }, index)) =>
55+
val indexExpr = Expr(index)
56+
val e1 = '{ $x.productElement($indexExpr).asInstanceOf[t] }
57+
val e2 = '{ $y.productElement($indexExpr).asInstanceOf[t] }
58+
'{ $acc && $elem.eqv($e1, $e2) }
59+
}
60+
}
61+
'{ eqProduct((x: T, y: T) => ${eqProductBody('x.asExprOf[Product], 'y.asExprOf[Product])}) }
6162

6263
// case for Mirror.ProductOf[T]
6364
// ...

docs/_docs/reference/contextual/derivation.md

Lines changed: 32 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -19,27 +19,38 @@ The `derives` clause generates the following given instances for the `Eq`, `Orde
1919
companion object of `Tree`,
2020

2121
```scala
22-
given [T: Eq] : Eq[Tree[T]] = Eq.derived
23-
given [T: Ordering] : Ordering[Tree] = Ordering.derived
24-
given [T: Show] : Show[Tree] = Show.derived
22+
given [T: Eq] : Eq[Tree[T]] = Eq.derived
23+
given [T: Ordering] : Ordering[Tree[T]] = Ordering.derived
24+
given [T: Show] : Show[Tree[T]] = Show.derived
2525
```
2626

2727
We say that `Tree` is the _deriving type_ and that the `Eq`, `Ordering` and `Show` instances are _derived instances_.
2828

2929
### Types supporting `derives` clauses
3030

3131
All data types can have a `derives` clause. This document focuses primarily on data types which also have a given instance
32-
of the `Mirror` type class available. Instances of the `Mirror` type class are generated automatically by the compiler
33-
for,
34-
35-
+ enums and enum cases
36-
+ case classes and case objects
37-
+ sealed classes or traits that have only case classes and case objects as children
32+
of the `Mirror` type class available.
3833

3934
`Mirror` type class instances provide information at the type level about the components and labelling of the type.
4035
They also provide minimal term level infrastructure to allow higher level libraries to provide comprehensive
4136
derivation support.
4237

38+
Instances of the `Mirror` type class are generated automatically by the compiler
39+
unconditionally for:
40+
- enums and enum cases,
41+
- case objects.
42+
43+
Instances for `Mirror` are also generated conditionally for:
44+
- case classes where the constructor is visible at the callsite (always true if the companion is not a case object)
45+
- sealed classes and sealed traits where:
46+
- there exists at least one child case,
47+
- each child case is reachable from the parent's definition,
48+
- if the sealed trait/class has no companion, then each child case is reachable from the callsite through the prefix of the type being mirrored,
49+
- and where the compiler can generate a `Mirror` type class instance for each child case.
50+
51+
52+
The `Mirror` type class definition is as follows:
53+
4354
```scala
4455
sealed trait Mirror:
4556

@@ -119,10 +130,21 @@ new Mirror.Product:
119130
new Leaf(...)
120131
```
121132

133+
If a Mirror cannot be generated automatically for a given type, an error will appear explaining why it is neither a supported
134+
sum type nor a product type. For example, if `A` is a trait that is not sealed,
135+
136+
```
137+
No given instance of type deriving.Mirror.Of[A] was found for parameter x of method summon in object Predef. Failed to synthesize an instance of type deriving.Mirror.Of[A]:
138+
* trait A is not a generic product because it is not a case class
139+
* trait A is not a generic sum because it is not a sealed trait
140+
```
141+
142+
122143
Note the following properties of `Mirror` types,
123144

124145
+ Properties are encoded using types rather than terms. This means that they have no runtime footprint unless used and
125146
also that they are a compile time feature for use with Scala 3's metaprogramming facilities.
147+
+ There is no restriction against the mirrored type being a local or inner class.
126148
+ The kinds of `MirroredType` and `MirroredElemTypes` match the kind of the data type the mirror is an instance for.
127149
This allows `Mirror`s to support ADTs of all kinds.
128150
+ There is no distinct representation type for sums or products (ie. there is no `HList` or `Coproduct` type as in
@@ -145,7 +167,7 @@ following form,
145167
```scala
146168
import scala.deriving.Mirror
147169

148-
def derived[T](using Mirror.Of[T]): TC[T] = ...
170+
inline def derived[T](using Mirror.Of[T]): TC[T] = ...
149171
```
150172

151173
That is, the `derived` method takes a context parameter of (some subtype of) type `Mirror` which defines the shape of

docs/_docs/reference/dropped-features/nonlocal-returns.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ title: "Deprecated: Nonlocal Returns"
55
movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features/nonlocal-returns.html
66
---
77

8-
Returning from nested anonymous functions has been deprecated.
8+
Returning from nested anonymous functions has been deprecated, and will produce a warning from version `3.2`.
99

1010
Nonlocal returns are implemented by throwing and catching `scala.runtime.NonLocalReturnException`-s. This is rarely what is intended by the programmer. It can be problematic because of the hidden performance cost of throwing and catching exceptions. Furthermore, it is a leaky implementation: a catch-all exception handler can intercept a `NonLocalReturnException`.
1111

docs/_docs/reference/dropped-features/this-qualifier.md

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,5 +29,3 @@ This can cause problems if a program tries to access the missing private field v
2929
// [C] needed if `field` is to be accessed through reflection
3030
val retained = field * field
3131
```
32-
33-
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: index
33
title: "Enums"
4-
movedTo: https://docs.scala-lang.org/scala3/reference/enums.html
4+
movedTo: https://docs.scala-lang.org/scala3/reference/enums/index.html
55
---
66

77
This chapter documents enums in Scala 3.

docs/_docs/reference/experimental/explicit-nulls.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -480,7 +480,7 @@ The program in [`unsafeNulls`](https://scala-lang.org/api/3.x/scala/runtime/stdL
480480
For example, the following code cannot be compiled even using unsafe nulls. Because of the
481481
Java interoperation, the type of the get method becomes `T | Null`.
482482

483-
```Scala
483+
```scala
484484
def head[T](xs: java.util.List[T]): T = xs.get(0) // error
485485
```
486486

0 commit comments

Comments
 (0)