Skip to content

Commit c207fa8

Browse files
committed
Replace the implicitly with summon in the code example for NotGiven
1 parent 2a32d6a commit c207fa8

File tree

1 file changed

+20
-7
lines changed

1 file changed

+20
-7
lines changed

docs/docs/reference/contextual/givens.md

Lines changed: 20 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ given listOrd[T](using ord: Ord[T]): Ord[List[T]] with
2727
if fst != 0 then fst else compare(xs1, ys1)
2828

2929
```
30+
3031
This code defines a trait `Ord` with two given instances. `intOrd` defines
3132
a given for the type `Ord[Int]` whereas `listOrd[T]` defines givens
3233
for `Ord[List[T]]` for all types `T` that come with a given instance for `Ord[T]`
@@ -39,20 +40,24 @@ parameters](./using-clauses.md).
3940

4041
The name of a given can be left out. So the definitions
4142
of the last section can also be expressed like this:
43+
4244
```scala
4345
given Ord[Int] with
4446
...
4547
given [T](using Ord[T]): Ord[List[T]] with
4648
...
4749
```
50+
4851
If the name of a given is missing, the compiler will synthesize a name from
4952
the implemented type(s).
5053

5154
**Note** The name synthesized by the compiler is chosen to be readable and reasonably concise. For instance, the two instances above would get the names:
55+
5256
```scala
5357
given_Ord_Int
5458
given_Ord_List_T
5559
```
60+
5661
The precise rules for synthesizing names are found [here](./relationship-implicits.html#anonymous-given-instances). These rules do not guarantee absence of name conflicts between
5762
given instances of types that are "too similar". To avoid conflicts one can
5863
use named instances.
@@ -62,15 +67,18 @@ use named instances.
6267
## Alias Givens
6368

6469
An alias can be used to define a given instance that is equal to some expression. E.g.:
70+
6571
```scala
6672
given global: ExecutionContext = ForkJoinPool()
6773
```
74+
6875
This creates a given `global` of type `ExecutionContext` that resolves to the right
6976
hand side `ForkJoinPool()`.
7077
The first time `global` is accessed, a new `ForkJoinPool` is created, which is then
7178
returned for this and all subsequent accesses to `global`. This operation is thread-safe.
7279

7380
Alias givens can be anonymous as well, e.g.
81+
7482
```scala
7583
given Position = enclosingTree.position
7684
given (using config: Config): Factory = MemoizingFactory(config)
@@ -83,11 +91,13 @@ but it can only implement a single type.
8391

8492
Given aliases can have the `inline` and `transparent` modifiers.
8593
Example:
94+
8695
```scala
8796
transparent inline given mkAnnotations[A, T]: Annotations[A, T] = ${
8897
// code producing a value of a subtype of Annotations
8998
}
9099
```
100+
91101
Since `mkAnnotations` is `transparent`, the type of an application is the type of its right hand side, which can be a proper subtype of the declared result type `Annotations[A, T]`.
92102

93103
## Pattern-Bound Given Instances
@@ -100,14 +110,17 @@ for given Context <- applicationContexts do
100110
pair match
101111
case (ctx @ given Context, y) => ...
102112
```
113+
103114
In the first fragment above, anonymous given instances for class `Context` are established by enumerating over `applicationContexts`. In the second fragment, a given `Context`
104115
instance named `ctx` is established by matching against the first half of the `pair` selector.
105116

106117
In each case, a pattern-bound given instance consists of `given` and a type `T`. The pattern matches exactly the same selectors as the type ascription pattern `_: T`.
107118

108119
## Negated Givens
109120

110-
Scala 2's somewhat puzzling behavior with respect to ambiguity has been exploited to implement the analogue of a "negated" search in implicit resolution, where a query Q1 fails if some other query Q2 succeeds and Q1 succeeds if Q2 fails. With the new cleaned up behavior these techniques no longer work. But the new special type `scala.util.NotGiven` now implements negation directly.
121+
Scala 2's somewhat puzzling behavior with respect to ambiguity has been exploited to implement the analogue of a "negated" search in implicit resolution,
122+
where a query Q1 fails if some other query Q2 succeeds and Q1 succeeds if Q2 fails. With the new cleaned up behavior these techniques no longer work.
123+
But the new special type `scala.util.NotGiven` now implements negation directly.
111124

112125
For any query type `Q`, `NotGiven[Q]` succeeds if and only if the implicit
113126
search for `Q` fails, for example:
@@ -124,8 +137,8 @@ object Foo:
124137

125138
@main def test() =
126139
given Tagged[Int] with {}
127-
assert(implicitly[Foo[Int]].value) // fooTagged is found
128-
assert(!implicitly[Foo[String]].value) // fooNotTagged is found
140+
assert(summon[Foo[Int]].value) // fooTagged is found
141+
assert(!summon[Foo[String]].value) // fooNotTagged is found
129142
```
130143

131144
## Given Instance Initialization
@@ -152,7 +165,7 @@ A given instance starts with the reserved word `given` and an optional _signatur
152165
defines a name and/or parameters for the instance. It is followed by `:`. There are three kinds
153166
of given instances:
154167

155-
- A _structural instance_ contains one or more types or constructor applications, followed by `with` and a template body
156-
that contains member definitions of the instance.
157-
- An _alias instance_ contains a type, followed by `=` and a right hand side expression.
158-
- An _abstract instance_ contains just the type, which is not followed by anything.
168+
- A _structural instance_ contains one or more types or constructor applications,
169+
followed by `with` and a template body that contains member definitions of the instance.
170+
- An _alias instance_ contains a type, followed by `=` and a right hand side expression.
171+
- An _abstract instance_ contains just the type, which is not followed by anything.

0 commit comments

Comments
 (0)