Rename capability -> ability

Author: odersky

compiler/src/dotty/tools/dotc/transform/TypeUtils.scala

@@ -24,11 +24,11 @@ object TypeUtils {
     def isErasedClass(using Context): Boolean =
       self.underlyingClassRef(refinementOK = true).typeSymbol.is(Flags.Erased)
 
-    /** Is this type a checked exception? This is the case of the type
+    /** Is this type a checked exception? This is the case if the type
      *  derives from Exception but not from RuntimeException. According to
      *  that definition Throwable is unchecked. That makes sense since you should
      *  neither throw nor catch `Throwable` anyway, so we should not define
-     *  a capability to do so.
+     *  an ability to do so.
      */
     def isCheckedException(using Context): Boolean =
       self.derivesFrom(defn.ExceptionClass)

docs/docs/reference/experimental/canthrow.md

@@ -2,18 +2,18 @@ package scala
 import language.experimental.erasedTerms
 import annotation.implicitNotFound
 
-/** A capability class that allows to throw exception `E`. When used with the
- *  experimental.saferThrows feature, a `throw Ex` expression will require
+/** A ability class that allows to throw exception `E`. When used with the
+ *  experimental.saferExceptions feature, a `throw Ex()` expression will require
  *  a given of class `CanThrow[Ex]` to be available.
  */
-@implicitNotFound("The capability to throw exception ${E} is missing.\nThe capability can be provided by one of the following:\n - A using clause `(using CanThrow[${E}])`\n - A `canThrow` clause in a result type such as `X canThrow ${E}`\n - an enclosing `try` that catches ${E}")
+@implicitNotFound("The ability to throw exception ${E} is missing.\nThe ability can be provided by one of the following:\n - A using clause `(using CanThrow[${E}])`\n - A `canThrow` clause in a result type such as `X canThrow ${E}`\n - an enclosing `try` that catches ${E}")
 erased class CanThrow[-E <: Exception]
 
 /** A helper type to allow syntax like
  *
- *    def f(): T throws Ex
+ *    def f(): T canThrow Ex
  */
 infix type canThrow[R, +E <: Exception] = CanThrow[E] ?=> R
 
 object unsafeExceptions:
-  given canThrowAny[E <: Exception]: CanThrow[E] = ???
+  given canThrowAny: CanThrow[Exception] = ???

docs/docs/reference/metaprogramming/canthrow.md

@@ -43,7 +43,10 @@ object language:
      */
     object erasedTerms
 
-    /** Experimental support for typechecked exception capabilities */
+    /** Experimental support for typechecked exception capabilities
+     *
+     *  @see [[https://dotty.epfl.ch/docs/reference/experimental/canthrow]]
+     */
     object saferExceptions
 
   end experimental

library/src-bootstrapped/scala/CanThrow.scala

@@ -1,8 +1,8 @@
--- Error: tests/neg/saferExceptions.scala:12:16 ------------------------------------------------------------------------
-12 |      case 4 => throw Exception()             // error
+-- Error: tests/neg/saferExceptions.scala:14:16 ------------------------------------------------------------------------
+14 |      case 4 => throw Exception()             // error
    |                ^^^^^^^^^^^^^^^^^
-   |                The capability to throw exception Exception is missing.
-   |                The capability can be provided by one of the following:
+   |                The ability to throw exception Exception is missing.
+   |                The ability can be provided by one of the following:
    |                 - A using clause `(using CanThrow[Exception])`
    |                 - A `canThrow` clause in a result type such as `X canThrow Exception`
    |                 - an enclosing `try` that catches Exception
@@ -11,11 +11,11 @@
    |
    |                  import unsafeExceptions.canThrowAny
    |
--- Error: tests/neg/saferExceptions.scala:17:48 ------------------------------------------------------------------------
-17 |  def baz(x: Int): Int canThrow Failure = bar(x)  // error
+-- Error: tests/neg/saferExceptions.scala:19:48 ------------------------------------------------------------------------
+19 |  def baz(x: Int): Int canThrow Failure = bar(x)  // error
    |                                                ^
-   |                                The capability to throw exception java.io.IOException is missing.
-   |                                The capability can be provided by one of the following:
+   |                                The ability to throw exception java.io.IOException is missing.
+   |                                The ability can be provided by one of the following:
    |                                 - A using clause `(using CanThrow[java.io.IOException])`
    |                                 - A `canThrow` clause in a result type such as `X canThrow java.io.IOException`
    |                                 - an enclosing `try` that catches java.io.IOException

library/src/scala/runtime/stdLibPatches/language.scala

@@ -4,7 +4,9 @@ object test:
 
   class Failure extends Exception
 
-  def bar(x: Int): Int canThrow Failure canThrow IOException =
+  def bar(x: Int): Int
+      `canThrow` Failure
+      `canThrow` IOException =
     x match
       case 1 => throw AssertionError()
       case 2 => throw Failure()               // ok

tests/neg/saferExceptions.check

@@ -0,0 +1,15 @@
+import language.experimental.saferExceptions
+
+
+class LimitExceeded extends Exception
+
+val limit = 10e9
+
+def f(x: Double): Double canThrow LimitExceeded =
+  if x < limit then x * x else throw LimitExceeded()
+
+@main def test(xs: Double*) =
+  try println(xs.map(f).sum)
+  catch case ex: LimitExceeded => println("too large")
+
+