diff --git a/docs/docs/reference/contextual/given-imports.md b/docs/docs/reference/contextual/given-imports.md index 6a8eb3baef82..69c2b55e1bf1 100644 --- a/docs/docs/reference/contextual/given-imports.md +++ b/docs/docs/reference/contextual/given-imports.md @@ -4,23 +4,28 @@ title: "Importing Givens" --- A special form of import wildcard selector is used to import given instances. Example: + ```scala object A { class TC given tc as TC def f(using TC) = ??? } + object B { import A._ import A.{given _} } ``` + In the code above, the `import A._` clause of object `B` will import all members of `A` _except_ the given instance `tc`. Conversely, the second import `import A.{given _}` will import _only_ that given instance. The two import clauses can also be merged into one: + ```scala -object B +object B { import A.{given _, _} +} ``` Generally, a normal wildcard selector `_` brings all definitions other than givens or extensions into scope @@ -28,12 +33,12 @@ whereas a `given _` selector brings all givens (including those resulting from e There are two main benefits arising from these rules: - - It is made clearer where givens in scope are coming from. - In particular, it is not possible to hide imported givens in a long list of regular wildcard imports. - - It enables importing all givens - without importing anything else. This is particularly important since givens - can be anonymous, so the usual recourse of using named imports is not - practical. +- It is made clearer where givens in scope are coming from. + In particular, it is not possible to hide imported givens in a long list of regular wildcard imports. +- It enables importing all givens + without importing anything else. This is particularly important since givens + can be anonymous, so the usual recourse of using named imports is not + practical. ### Importing By Type @@ -42,31 +47,40 @@ Since givens can be anonymous it is not always practical to import them by their ```scala import A.{given TC} ``` + This imports any given in `A` that has a type which conforms to `TC`. Importing givens of several types `T1,...,Tn` is expressed by multiple `given` selectors. -``` + +```scala import A.{given T1, ..., given Tn} ``` + Importing all given instances of a parameterized type is expressed by wildcard arguments. For instance, assuming the object + ```scala object Instances { given intOrd as Ordering[Int] - given [T: Ordering] listOrd as Ordering[List[T]] + given listOrd[T: Ordering] as Ordering[List[T]] given ec as ExecutionContext = ... given im as Monoid[Int] } ``` + the import + ```scala import Instances.{given Ordering[?], given ExecutionContext} ``` + would import the `intOrd`, `listOrd`, and `ec` instances but leave out the `im` instance, since it fits none of the specified bounds. By-type imports can be mixed with by-name imports. If both are present in an import clause, by-type imports come last. For instance, the import clause + ```scala import Instances.{im, given Ordering[?]} ``` + would import `im`, `intOrd`, and `listOrd` but leave out `ec`.