Skip to content

Commit 849484d

Browse files
committed
Update the relationship-implicits.md to use up to date concept names
1 parent bc8a132 commit 849484d

File tree

1 file changed

+40
-8
lines changed

1 file changed

+40
-8
lines changed

docs/docs/reference/contextual/relationship-implicits.md

Lines changed: 40 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -12,34 +12,45 @@ Many, but not all, of the new contextual abstraction features in Scala 3 can be
1212
Given instances can be mapped to combinations of implicit objects, classes and implicit methods.
1313

1414
1. Given instances without parameters are mapped to implicit objects. E.g.,
15+
1516
```scala
1617
given intOrd as Ord[Int] { ... }
1718
```
19+
1820
maps to
21+
1922
```scala
2023
implicit object IntOrd extends Ord[Int] { ... }
2124
```
25+
2226
2. Parameterized givens are mapped to combinations of classes and implicit methods. E.g.,
27+
2328
```scala
2429
given listOrd[T](using ord: Ord[T]) as Ord[List[T]] { ... }
2530
```
31+
2632
maps to
33+
2734
```scala
2835
class ListOrd[T](implicit ord: Ord[T]) extends Ord[List[T]] { ... }
2936
final implicit def ListOrd[T](implicit ord: Ord[T]): ListOrd[T] = new ListOrd[T]
3037
```
38+
3139
3. Alias givens map to implicit methods or implicit lazy vals. If an alias has neither type nor context parameters,
3240
it is treated as a lazy val, unless the right hand side is a simple reference, in which case we can use a forwarder to
3341
that reference without caching it.
3442

3543
Examples:
44+
3645
```scala
3746
given global as ExecutionContext = new ForkJoinContext()
3847

3948
val ctx: Context
4049
given Context = ctx
4150
```
51+
4252
would map to
53+
4354
```scala
4455
final implicit lazy val global: ExecutionContext = new ForkJoinContext()
4556
final implicit def given_Context = ctx
@@ -48,29 +59,35 @@ final implicit def given_Context = ctx
4859
### Anonymous Given Instances
4960

5061
Anonymous given instances get compiler synthesized names, which are generated in a reproducible way from the implemented type(s). For example, if the names of the `IntOrd` and `ListOrd` givens above were left out, the following names would be synthesized instead:
62+
5163
```scala
5264
given given_Ord_Int as Ord[Int] { ... }
5365
given given_Ord_List_T[T](using ord: Ord[T]) as Ord[List[T]] { ... }
5466
```
67+
5568
The synthesized type names are formed from
5669

57-
- the prefix `given_`,
58-
- the simple name(s) of the implemented type(s), leaving out any prefixes,
59-
- the simple name(s) of the toplevel argument type constructors to these types.
70+
1. the prefix `given_`,
71+
2. the simple name(s) of the implemented type(s), leaving out any prefixes,
72+
3. the simple name(s) of the toplevel argument type constructors to these types.
6073

6174
Tuples are treated as transparent, i.e. a type `F[(X, Y)]` would get the synthesized name
6275
`F_X_Y`. Directly implemented function types `A => B` are represented as `A_to_B`. Function types used as arguments to other type constructors are represented as `Function`.
6376

64-
### Given Clauses
77+
### Using Clauses
78+
79+
Using clauses correspond largely to Scala-2's implicit parameter clauses. E.g.
6580

66-
Given clauses correspond largely to Scala-2's implicit parameter clauses. E.g.
6781
```scala
6882
def max[T](x: T, y: T)(using ord: Ord[T]): T
6983
```
84+
7085
would be written
86+
7187
```scala
7288
def max[T](x: T, y: T)(implicit ord: Ord[T]): T
7389
```
90+
7491
in Scala 2. The main difference concerns applications of such parameters.
7592
Explicit arguments to parameters of using clauses _must_ be written using `(using ...)`,
7693
mirroring the definition syntax. E.g, `max(2, 3)(using IntOrd)`.
@@ -88,29 +105,33 @@ Context bounds are the same in both language versions. They expand to the respec
88105

89106
**Note:** To ease migration, context bounds in Dotty map for a limited time to old-style implicit parameters for which arguments can be passed either in a using clause or
90107
in a normal argument list. Once old-style implicits are deprecated, context bounds
91-
will map to with clauses instead.
108+
will map to using clauses instead.
92109

93110
### Extension Methods
94111

95112
Extension methods have no direct counterpart in Scala 2, but they can be simulated with implicit classes. For instance, the extension method
113+
96114
```scala
97115
extension (c: Circle) def circumference: Double = c.radius * math.Pi * 2
98116
```
117+
99118
could be simulated to some degree by
119+
100120
```scala
101121
implicit class CircleDecorator(c: Circle) extends AnyVal {
102122
def circumference: Double = c.radius * math.Pi * 2
103123
}
104124
```
125+
105126
Abstract extension methods in traits that are implemented in given instances have no direct counterpart in Scala-2. The only way to simulate these is to make implicit classes available through imports. The Simulacrum macro library can automate this process in some cases.
106127

107128
### Type class Derivation
108129

109130
Type class derivation has no direct counterpart in the Scala 2 language. Comparable functionality can be achieved by macro-based libraries such as Shapeless, Magnolia, or scalaz-deriving.
110131

111-
### Implicit Function Types
132+
### Context Function Types
112133

113-
Implicit function types have no analogue in Scala 2.
134+
Context function types have no analogue in Scala 2.
114135

115136
### Implicit By-Name Parameters
116137

@@ -121,16 +142,21 @@ Implicit by-name parameters are not supported in Scala 2, but can be emulated to
121142
### Implicit Conversions
122143

123144
Implicit conversion methods in Scala 2 can be expressed as given instances of the `scala.Conversion` class in Dotty. E.g. instead of
145+
124146
```scala
125147
implicit def stringToToken(str: String): Token = new Keyword(str)
126148
```
149+
127150
one can write
151+
128152
```scala
129153
given stringToToken as Conversion[String, Token] {
130154
def apply(str: String): Token = KeyWord(str)
131155
}
132156
```
157+
133158
or
159+
134160
```scala
135161
given stringToToken as Conversion[String, Token] = KeyWord(_)
136162
```
@@ -143,10 +169,13 @@ Implicit classes in Scala 2 are often used to define extension methods, which ar
143169

144170
Implicit `val` definitions in Scala 2 can be expressed in Dotty using a regular `val` definition and an alias given.
145171
E.g., Scala 2's
172+
146173
```scala
147174
lazy implicit val pos: Position = tree.sourcePos
148175
```
176+
149177
can be expressed in Dotty as
178+
150179
```scala
151180
lazy val pos: Position = tree.sourcePos
152181
given Position = pos
@@ -155,10 +184,13 @@ given Position = pos
155184
### Abstract Implicits
156185

157186
An abstract implicit `val` or `def` in Scala 2 can be expressed in Dotty using a regular abstract definition and an alias given. E.g., Scala 2's
187+
158188
```scala
159189
implicit def symDecorator: SymDecorator
160190
```
191+
161192
can be expressed in Dotty as
193+
162194
```scala
163195
def symDecorator: SymDecorator
164196
given SymDecorator = symDecorator

0 commit comments

Comments
 (0)