Rename stripNull

Author: noti0na1

compiler/src/dotty/tools/dotc/core/Definitions.scala

@@ -613,8 +613,7 @@ class Definitions {
   @tu lazy val StringModule: Symbol = StringClass.linkedClass
     @tu lazy val String_+ : TermSymbol = enterMethod(StringClass, nme.raw.PLUS, methOfAny(StringType), Final)
     @tu lazy val String_valueOf_Object: Symbol = StringModule.info.member(nme.valueOf).suchThat(_.info.firstParamTypes match {
-      case List(pt) =>
-        pt.isAny || pt.stripNull.isAnyRef
+      case List(pt) => pt.isAny || pt.stripNullWhenExplicit.isAnyRef
       case _ => false
     }).symbol
 
@@ -626,13 +625,13 @@ class Definitions {
   @tu lazy val ClassCastExceptionClass: ClassSymbol   = requiredClass("java.lang.ClassCastException")
     @tu lazy val ClassCastExceptionClass_stringConstructor: TermSymbol  = ClassCastExceptionClass.info.member(nme.CONSTRUCTOR).suchThat(_.info.firstParamTypes match {
       case List(pt) =>
-        pt.stripNull.isRef(StringClass)
+        pt.stripNullWhenExplicit.isRef(StringClass)
       case _ => false
     }).symbol.asTerm
   @tu lazy val ArithmeticExceptionClass: ClassSymbol  = requiredClass("java.lang.ArithmeticException")
     @tu lazy val ArithmeticExceptionClass_stringConstructor: TermSymbol  = ArithmeticExceptionClass.info.member(nme.CONSTRUCTOR).suchThat(_.info.firstParamTypes match {
       case List(pt) =>
-        pt.stripNull.isRef(StringClass)
+        pt.stripNullWhenExplicit.isRef(StringClass)
       case _ => false
     }).symbol.asTerm
 

compiler/src/dotty/tools/dotc/core/NullOpsDecorator.scala

@@ -17,7 +17,7 @@ object NullOpsDecorator {
      *  If this type isn't (syntactically) nullable, then returns the type unchanged.
      *  The type will not be changed if explicit-nulls is not enabled.
      */
-    def stripNull(using Context): Type = {
+    def stripNullWhenExplicit(using Context): Type = {
       def strip(tp: Type): Type =
         val tpWiden = tp.widenDealias
         val tpStriped = tpWiden match {
@@ -47,7 +47,7 @@ object NullOpsDecorator {
 
     /** Is self (after widening and dealiasing) a type of the form `T | Null`? */
     def isNullableUnion(using Context): Boolean = {
-      val stripped = self.stripNull
+      val stripped = self.stripNullWhenExplicit
       stripped ne self
     }
 

compiler/src/dotty/tools/dotc/core/Types.scala

@@ -833,7 +833,7 @@ object Types {
         case OrNull(tp1) if Feature.unsafeNullsEnabled =>
           // Selecting `name` from a type `T | Null` is like selecting `name` from `T`, if
           // unsafeNulls is enabled. This can throw at runtime, but we trade soundness for usability.
-          tp1.findMember(name, pre.stripNull, required, excluded)
+          tp1.findMember(name, pre.stripNullWhenExplicit, required, excluded)
         case _ =>
           // we need to keep the invariant that `pre <: tp`. Branch `union-types-narrow-prefix`
           // achieved that by narrowing `pre` to each alternative, but it led to merge errors in
@@ -3191,7 +3191,7 @@ object Types {
     def apply(tp: Type)(using Context) =
       if tp.isNullType then tp else OrType(tp, defn.NullType, soft = false)
     def unapply(tp: Type)(using Context): Option[Type] =
-      val tp1 = tp.stripNull
+      val tp1 = tp.stripNullWhenExplicit
       if tp1 ne tp then Some(tp1) else None
   }
 

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

@@ -54,7 +54,7 @@ class ExpandSAMs extends MiniPhase:
           checkRefinements(tpe, fn)
           tree
         case tpe =>
-          val tpe1 = checkRefinements(tpe.stripNull, fn)
+          val tpe1 = checkRefinements(tpe.stripNullWhenExplicit, fn)
           val Seq(samDenot) = tpe1.possibleSamMethods
           cpy.Block(tree)(stats,
               AnonClass(tpe1 :: Nil, fn.symbol.asTerm :: Nil, samDenot.symbol.asTerm.name :: Nil))

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

@@ -211,7 +211,7 @@ class SyntheticMembers(thisPhase: DenotTransformer) {
       def filterStringConstructor(s: Symbol): Boolean = s.info match {
         case m: MethodType if s.isConstructor && m.paramInfos.size == 1 =>
           val head = m.paramInfos.head
-          val pinfo = head.stripNull
+          val pinfo = head.stripNullWhenExplicit
           pinfo == defn.StringType
         case _ => false
       }

compiler/src/dotty/tools/dotc/typer/Typer.scala

@@ -1317,7 +1317,7 @@ class Typer extends Namer
       if (tree.tpt.isEmpty)
         meth1.tpe.widen match {
           case mt: MethodType =>
-            val pt1 = pt.stripNull
+            val pt1 = pt.stripNullWhenExplicit
             pt1 match {
               case SAMType(sam)
               if !defn.isFunctionType(pt1)
@@ -1676,7 +1676,7 @@ class Typer extends Namer
   }
 
   def typedSeqLiteral(tree: untpd.SeqLiteral, pt: Type)(using Context): SeqLiteral = {
-    val elemProto = pt.stripNull.elemType match {
+    val elemProto = pt.stripNullWhenExplicit.elemType match {
       case NoType => WildcardType
       case bounds: TypeBounds => WildcardType(bounds)
       case elemtp => elemtp

docs/docs/internals/explicit-nulls.md

@@ -5,7 +5,7 @@ title: "Explicit Nulls"
 
 The explicit nulls feature (enabled via a flag) changes the Scala type hierarchy
 so that reference types (e.g. `String`) are non-nullable. We can still express nullability
-with union types: e.g. `val x: String|Null = null`.
+with union types: e.g. `val x: String | Null = null`.
 
 The implementation of the feature in dotty can be conceptually divided in several parts:
   1. changes to the type hierarchy so that `Null` is only a subtype of `Any`
@@ -27,15 +27,13 @@ We change the type hierarchy so that `Null` is only a subtype of `Any` by:
 
 ## Working with Nullable Unions
 
-There are some utility functions for nullable types in `NullOpsDecorator.scala` . They are extension methods for `Type`; hence we can use them in this way: `tp.f(...)`.
+There are some utility functions for nullable types in `NullOpsDecorator.scala`.
+They are extension methods for `Type`; hence we can use them in this way: `tp.f(...)`.
 
-- `stripNull` syntactically strips all `Null` types in the union:
+- `stripNullWhenExplicit` syntactically strips all `Null` types in the union:
   e.g. `String|Null => String`.
-- `stripAllNullS` collapses all `Null` unions within this type, and not just the outermost
-  ones (as `stripNull` does).
 - `isNullableUnion` determines whether `this` is a nullable union.
 - `isNullableAfterErasure` determines whether `this` type can have `null` value after erasure.
-- `isUnsafelyConvertible` determines whether we can convert `this` type to `pt` unsafely if we ignore `Null` type.
 
 Within `Types.scala`, we also defined an extractor `OrNull` to extract the non-nullable part of a nullable unions .
 

docs/docs/reference/other-new-features/explicit-nulls.md

@@ -56,6 +56,12 @@ So far, we have found the following useful:
 
     Don't use `.nn` on mutable variables directly, because it may introduce an unknown type into the type of the variable.
 
+  - An `unsafeNulls` language feature
+
+    When imported, `T | Null` can be used as `T`, similar to regular Scala (without explicit nulls).
+
+    See UnsafeNulls section for more details.
+
 ## Unsoundness
 
 The new type system is unsound with respect to `null`. This means there are still instances where an expression has a non-nullable type like `String`, but its value is actually `null`.
@@ -424,17 +430,38 @@ We don't support:
 
 ### UnsafeNulls
 
-It is difficult to work with nullable values, we introduce a language feature `unsafeNulls`. Inside this "unsafe" scope, all `T | Null` values can be used as `T`, and `Null` type keeps being a subtype of `Any`.
+It is difficult to work with many nullable values, we introduce a language feature `unsafeNulls`.
+Inside this "unsafe" scope, all `T | Null` values can be used as `T`.
 
-Users can import `scala.language.unsafeNulls` to create such scopes, or use `-language:unsafeNulls` to enable this feature globally. The following unsafe null operations will apply to all nullable types:
-1. select member of `T` on `T | Null` object
-2. call extension methods of `T` on `T | Null`
-3. convert `T1` to `T2` if `T1.stripAllNulls <:< T2.stripAllNulls` or `T1` is `Null` and `T2` has null value after erasure
-4. allow equality check between `T` and `T | Null`
+Users can import `scala.language.unsafeNulls` to create such scopes, or use `-language:unsafeNulls` to enable this feature globally (for migration purpose only).
+
+Assume `T` is a reference type (a subtype of `AnyRef`), the following unsafe operation rules are
+applied in this unsafe-nulls scope:
+1. the members of `T` can be found on `T | Null`
+2. a value with type `T` can be compared with `T | Null` and `Null`
+3. suppose `T1` is not a subtype of `T2` using explicit-nulls subtyping (where `Null` is a direct
+subtype of Any), extension methods and implicit conversions designed for `T2` can be used for
+`T1` if `T1` is a subtype of `T2` using regular subtyping rules (where `Null` is a subtype of every
+reference type)
+4. suppose `T1` is not a subtype of `T2` using explicit-nulls subtyping, a value with type `T1`
+can be used as `T2` if `T1` is a subtype of `T2` using regular subtyping rules
 
 Addtionally, `null` can be used as `AnyRef` (`Object`), which means you can select `.eq` or `.toString` on it.
 
-The intention of this `unsafeNulls` is to give users a better migration path for explicit nulls. Projects for Scala 2 or regular dotty can try this by adding `-Yexplicit-nulls -language:unsafeNulls` to the compile options. A small number of manual modifications are expected (for example, some code relies on the fact of `Null <:< AnyRef`). To migrate to full explicit nulls in the future, `-language:unsafeNulls` can be dropped and add `import scala.language.unsafeNulls` only when needed.
+The program in `unsafeNulls` will have a **similar** semantic as regular Scala, but not **equivalent**.
+
+For example, the following code cannot be compiled even using unsafe nulls. Because of the
+Java interoperation, the type of the get method becomes `T | Null`.
+
+```Scala
+def head[T](xs: java.util.List[T]): T = xs.get(0) // error
+```
+
+Since the compiler doesn’t know whether `T` is a reference type, it is unable to cast `T | Null`
+to `T`. A `.nn` need to be inserted after `xs.get(0)` by user manually to fix the error, which
+strips the `Nul`l from its type.
+
+The intention of this `unsafeNulls` is to give users a better migration path for explicit nulls. Projects for Scala 2 or regular dotty can try this by adding `-Yexplicit-nulls -language:unsafeNulls` to the compile options. A small number of manual modifications are expected. To migrate to full explicit nulls in the future, `-language:unsafeNulls` can be dropped and add `import scala.language.unsafeNulls` only when needed.
 
 ```scala
 def f(x: String): String = ???

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

@@ -101,6 +101,10 @@ object language:
     */
   object `3.1`
 
-  /** Unsafe Nulls fot Explicit Nulls */
+  /** Unsafe Nulls fot Explicit Nulls
+    * Inside the "unsafe" scope, `Null` is considered as a subtype of all reference types.
+    *
+    * @see [[http://dotty.epfl.ch/docs/reference/other-new-features/explicit-nulls.html]]
+    */
   object unsafeNulls
 end language