Refactor: Talk about boundary/break instead of scala.util.control.NonLocalReturns

Author: Dedelweiss

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

@@ -9,21 +9,18 @@ Returning from nested anonymous functions has been deprecated, and will produce
 
 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`.
 
-A drop-in library replacement is provided in [`scala.util.control.NonLocalReturns`](https://scala-lang.org/api/3.x/scala/util/control/NonLocalReturns$.html). Example:
+A better alternative to nonlocal returns and also the `scala.util.control.Breaks` API is provided by [`scala.util.boundary` and `boundary.break`](http://dotty.epfl.ch/api/scala/util/boundary$.html).
+
+Example:
 
 ```scala
-import scala.util.control.NonLocalReturns.*
-
-extension [T](xs: List[T])
-  def has(elem: T): Boolean = returning {
-    for x <- xs do
-      if x == elem then throwReturn(true)
-    false
-  }
-
-@main def test(): Unit =
-  val xs = List(1, 2, 3, 4, 5)
-  assert(xs.has(2) == xs.contains(2))
+import scala.util.boundary, boundary.break
+
+def firstIndex[T](xs: List[T], elem: T): Int =
+  boundary:
+    for (x, i) <- xs.zipWithIndex do
+      if x == elem then break(i)
+    -1
 ```
 
 Note: compiler produces deprecation error on nonlocal returns only with `-source:future` option.

docs/_spec/TODOreference/dropped-features/nonlocal-returns.md

@@ -13,14 +13,12 @@ A drop-in library replacement is provided in [`scala.util.control.NonLocalReturn
 
 ```scala
 import scala.util.control.NonLocalReturns.*
-
 extension [T](xs: List[T])
   def has(elem: T): Boolean = returning {
     for x <- xs do
       if x == elem then throwReturn(true)
     false
   }
-
 @main def test(): Unit =
   val xs = List(1, 2, 3, 4, 5)
   assert(xs.has(2) == xs.contains(2))