Merge pull request #7213 from dotty-staging/dual-docs

Revert docs to 0.18 state

Author: odersky

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

@@ -0,0 +1,30 @@
+---
+layout: doc-page
+title: "Context Bounds"
+---
+
+## Context Bounds
+
+A context bound is a shorthand for expressing the common pattern of an implicit parameter that depends on a type parameter. Using a context bound, the `maximum` function of the last section can be written like this:
+```scala
+def maximum[T: Ord](xs: List[T]): T = xs.reduceLeft(max)
+```
+A bound like `: Ord` on a type parameter `T` of a method or class indicates an implicit parameter `(given Ord[T])`. The implicit parameter(s) generated from context bounds come last in the definition of the containing method or class. E.g.,
+```scala
+def f[T: C1 : C2, U: C3](x: T)(given y: U, z: V): R
+```
+would expand to
+```scala
+def f[T, U](x: T)(given y: U, z: V)(given C1[T], C2[T], C3[U]): R
+```
+Context bounds can be combined with subtype bounds. If both are present, subtype bounds come first, e.g.
+```scala
+def g[T <: B : C](x: T): R = ...
+```
+
+## Syntax
+
+```
+TypeParamBounds   ::=  [SubtypeBounds] {ContextBound}
+ContextBound      ::=  ‘:’ Type
+```

docs/docs/reference/contextual-new/conversions.md

@@ -0,0 +1,75 @@
+---
+layout: doc-page
+title: "Implicit Conversions"
+---
+
+Implicit conversions are defined by given instances of the `scala.Conversion` class.
+This class is defined in package `scala` as follows:
+```scala
+abstract class Conversion[-T, +U] extends (T => U)
+```
+For example, here is an implicit conversion from `String` to `Token`:
+```scala
+given Conversion[String, Token] {
+  def apply(str: String): Token = new KeyWord(str)
+}
+```
+Using an alias this can be expressed more concisely as:
+```scala
+given Conversion[String, Token] = new KeyWord(_)
+```
+An implicit conversion is applied automatically by the compiler in three situations:
+
+1. If an expression `e` has type `T`, and `T` does not conform to the expression's expected type `S`.
+2. In a selection `e.m` with `e` of type `T`, but `T` defines no member `m`.
+3. In an application `e.m(args)` with `e` of type `T`, if `T` does define
+   some member(s) named `m`, but none of these members can be applied to the arguments `args`.
+
+In the first case, the compiler looks for a given `scala.Conversion` that maps
+an argument of type `T` to type `S`. In the second and third
+case, it looks for a given `scala.Conversion` that maps an argument of type `T`
+to a type that defines a member `m` which can be applied to `args` if present.
+If such an instance `C` is given, the expression `e` is replaced by `C.apply(e)`.
+
+## Examples
+
+1. The `Predef` package contains "auto-boxing" conversions that map
+primitive number types to subclasses of `java.lang.Number`. For instance, the
+conversion from `Int` to `java.lang.Integer` can be defined as follows:
+```scala
+given int2Integer: Conversion[Int, java.lang.Integer] =
+ java.lang.Integer.valueOf(_)
+```
+
+2. The "magnet" pattern is sometimes used to express many variants of a method. Instead of defining overloaded versions of the method, one can also let the method take one or more arguments of specially defined "magnet" types, into which various argument types can be converted. E.g.
+```scala
+object Completions {
+
+  // The argument "magnet" type
+  enum CompletionArg {
+    case Error(s: String)
+    case Response(f: Future[HttpResponse])
+    case Status(code: Future[StatusCode])
+  }
+  object CompletionArg {
+
+    // conversions defining the possible arguments to pass to `complete`
+    // these always come with CompletionArg
+    // They can be invoked explicitly, e.g.
+    //
+    //   CompletionArg.fromStatusCode(statusCode)
+
+    given fromString     : Conversion[String, CompletionArg]               = Error(_)
+    given fromFuture     : Conversion[Future[HttpResponse], CompletionArg] = Response(_)
+    given fromStatusCode : Conversion[Future[StatusCode], CompletionArg]   = Status(_)
+  }
+  import CompletionArg._
+
+  def complete[T](arg: CompletionArg) = arg match {
+    case Error(s) => ...
+    case Response(f) => ...
+    case Status(code) => ...
+  }
+}
+```
+This setup is more complicated than simple overloading of `complete`, but it can still be useful if normal overloading is not available (as in the case above, since we cannot have two overloaded methods that take `Future[...]` arguments), or if normal overloading would lead to a combinatorial explosion of variants.

docs/docs/reference/contextual-new/delegates.md

@@ -0,0 +1,87 @@
+---
+layout: doc-page
+title: "Given Instances"
+---
+
+Given instances (or, simply, "givens") define "canonical" values of certain types
+that serve for synthesizing arguments to [given clauses](./given-clauses.md). Example:
+
+```scala
+trait Ord[T] {
+  def compare(x: T, y: T): Int
+  def (x: T) < (y: T) = compare(x, y) < 0
+  def (x: T) > (y: T) = compare(x, y) > 0
+}
+
+given intOrd: Ord[Int] {
+  def compare(x: Int, y: Int) =
+    if (x < y) -1 else if (x > y) +1 else 0
+}
+
+given listOrd[T](given ord: Ord[T]): Ord[List[T]] {
+
+  def compare(xs: List[T], ys: List[T]): Int = (xs, ys) match {
+    case (Nil, Nil) => 0
+    case (Nil, _) => -1
+    case (_, Nil) => +1
+    case (x :: xs1, y :: ys1) =>
+      val fst = ord.compare(x, y)
+      if (fst != 0) fst else xs1.compareTo(ys1)
+  }
+}
+```
+This code defines a trait `Ord` with two given instances. `intOrd` defines
+a given for the type `Ord[Int]` whereas `listOrd[T]` defines givens
+for `Ord[List[T]]` for all types `T` that come with a given instance for `Ord[T]` themselves.
+The `(given ord: Ord[T])` clause in `listOrd` defines an implicit parameter.
+Given clauses are further explained in the [next section](./given-clauses.md).
+
+## Anonymous Given Instances
+
+The name of a given instance can be left out. So the definitions
+of the last section can also be expressed like this:
+```scala
+given Ord[Int] { ... }
+given [T](given Ord[T]): Ord[List[T]] { ... }
+```
+If the name of a given is missing, the compiler will synthesize a name from
+the type(s) in the `as` clause.
+
+## Alias Givens
+
+An alias can be used to define a given instance that is equal to some expression. E.g.:
+```scala
+given global: ExecutionContext = new ForkJoinPool()
+```
+This creates a given `global` of type `ExecutionContext` that resolves to the right
+hand side `new ForkJoinPool()`.
+The first time `global` is accessed, a new `ForkJoinPool` is created, which is then
+returned for this and all subsequent accesses to `global`.
+
+Alias givens can be anonymous, e.g.
+```scala
+given Position = enclosingTree.position
+given (given outer: Context): Context = outer.withOwner(currentOwner)
+```
+An alias given can have type parameters and given clauses just like any other given instance, but it can only implement a single type.
+
+## Given Instance Initialization
+
+A given instance without type parameters or given clause is initialized on-demand, the first
+time it is accessed. It is not required to ensure safe publication, which means that
+different threads might create different instances for the same `given` definition.
+If a `given` definition has type parameters or a given clause, a fresh instance is created for each reference.
+
+## Syntax
+
+Here is the new syntax of given instances, seen as a delta from the [standard context free syntax of Scala 3](../../internals/syntax.md).
+```
+TmplDef          ::=  ...
+                  |   ‘given’ GivenDef
+GivenDef         ::=  [GivenSig (‘:’ | <:)] Type ‘=’ Expr
+                  |   [GivenSig ‘:’] [ConstrApp {‘,’ ConstrApp }] [TemplateBody]
+GivenSig         ::=  [id] [DefTypeParamClause] {GivenParamClause}
+GivenParamClause ::=  ‘(’ ‘given’ (DefParams | GivenTypes) ‘)’
+GivenTypes       ::=  AnnotType {‘,’ AnnotType}
+```
+The identifier `id` can be omitted only if some types are implemented or the template body defines at least one extension method.