Mark legacy overloads of &+ and &- unavailable. (#38723)

These were defined for both FixedWidthInteger and FixedWidthInteger & SignedInteger for source compatibility with Swift 3; the latter set probably should have been removed when we stabilized the ABI, but were not. We can't easily remove them entirely (because we need them for ABI stability now), but we can mark them unavailable so that the typechecker doesn't have to consider them..

Author: stephentyrone

stdlib/public/core/Integers.swift

@@ -3502,8 +3502,19 @@ extension UnsignedInteger where Self: FixedWidthInteger {
 
 /// An integer type that can represent both positive and negative values.
 public protocol SignedInteger: BinaryInteger, SignedNumeric {
-  // These requirements are for the source code compatibility with Swift 3
+  // These requirements are needed for binary compatibility; the following:
+  //
+  // func foo<T>(_ a: T) -> T
+  // where T: SignedInteger & FixedWidthInteger {
+  //   a &+ 1
+  // }
+  //
+  // generated a call to `static Swift.SignedInteger._maskingAdd(A, A) -> A`
+  // when compiled with Swift 5.5 and earlier.
+  @available(*, deprecated, message: "Use &+ instead.")
   static func _maskingAdd(_ lhs: Self, _ rhs: Self) -> Self
+  
+  @available(*, deprecated, message: "Use &- instead.")
   static func _maskingSubtract(_ lhs: Self, _ rhs: Self) -> Self
 }
 
@@ -3629,49 +3640,48 @@ public func numericCast<T: BinaryInteger, U: BinaryInteger>(_ x: T) -> U {
   return U(x)
 }
 
-// FIXME(integers): Absence of &+ causes ambiguity in the code like the
-// following:
-//    func f<T: SignedInteger>(_ x: T, _ y: T) {
-//      var _  = (x &+ (y - 1)) < x
-//    }
-//  Compiler output:
-//  error: ambiguous reference to member '-'
-//    var _  = (x &+ (y - 1)) < x
-//                      ^
+// Needed to support user-defined types conformance to SignedInteger.
+// We need these defaults to exist, but they are not called.
 extension SignedInteger {
-  @_transparent
+  @available(*, deprecated, message: "Use &+ instead.")
   public static func _maskingAdd(_ lhs: Self, _ rhs: Self) -> Self {
     fatalError("Should be overridden in a more specific type")
   }
-
-  @_transparent
+  
+  @available(*, deprecated, message: "Use &- instead.")
   public static func _maskingSubtract(_ lhs: Self, _ rhs: Self) -> Self {
     fatalError("Should be overridden in a more specific type")
   }
 }
 
+// These symbols have to exist for ABI compatibility, but should not be used
+// any longer; we want to find the FixedWidthInteger definitions instead.
 extension SignedInteger where Self: FixedWidthInteger {
-  // This overload is supposed to break the ambiguity between the
-  // implementations on SignedInteger and FixedWidthInteger
-  @_transparent
-  public static func &+ (lhs: Self, rhs: Self) -> Self {
-    return _maskingAdd(lhs, rhs)
+  @available(*, unavailable)
+  public static func &+(lhs: Self, rhs: Self) -> Self {
+    lhs.addingReportingOverflow(rhs).partialValue
   }
-
-  @_transparent
+  
+  // This may be called in rare situations by binaries compiled with
+  // Swift 5.5 and earlier, so we need to keep it around for compatibility.
+  // We can't mark it unavailable, because then the concrete signed integer
+  // types in the standard library would not satisfy the protocol requirements.
+  @available(*, deprecated, message: "Use &+ instead.")
   public static func _maskingAdd(_ lhs: Self, _ rhs: Self) -> Self {
-    return lhs.addingReportingOverflow(rhs).partialValue
+    lhs.addingReportingOverflow(rhs).partialValue
   }
 
-  // This overload is supposed to break the ambiguity between the
-  // implementations on SignedInteger and FixedWidthInteger
-  @_transparent
-  public static func &- (lhs: Self, rhs: Self) -> Self {
-    return _maskingSubtract(lhs, rhs)
+  @available(*, unavailable)
+  public static func &-(lhs: Self, rhs: Self) -> Self {
+    lhs.subtractingReportingOverflow(rhs).partialValue
   }
-
-  @_transparent
+  
+  // This may be called in rare situations by binaries compiled with
+  // Swift 5.5 and earlier, so we need to keep it around for compatibility.
+  // We can't mark it unavailable, because then the concrete signed integer
+  // types in the standard library would not satisfy the protocol requirements.
+  @available(*, deprecated, message: "Use &- instead.")
   public static func _maskingSubtract(_ lhs: Self, _ rhs: Self) -> Self {
-    return lhs.subtractingReportingOverflow(rhs).partialValue
+    lhs.subtractingReportingOverflow(rhs).partialValue
   }
 }

test/api-digester/Outputs/stability-stdlib-source-x86_64.swift.expected

@@ -5,3 +5,8 @@ Protocol CodingKey has generic signature change from <Self : Swift.CustomDebugSt
 Protocol Error has added inherited protocol Sendable
 Protocol Error has generic signature change from to <Self : Swift.Sendable>
 Subscript MutableCollection.subscript(_:) has generic signature change from <Self where Self : Swift.MutableCollection> to <Self where Self : Swift.MutableCollection, Self.SubSequence == Swift.Slice<Self>>
+
+// Not actually a source break; the typechecker will find these operations on
+// FixedWidthInteger instead.
+Func SignedInteger.&+(_:_:) has been removed
+Func SignedInteger.&-(_:_:) has been removed

test/api-digester/stability-stdlib-abi-without-asserts.test

@@ -72,4 +72,11 @@ Protocol Error has added inherited protocol Sendable
 Protocol Error has generic signature change from to <Self : Swift.Sendable>
 Enum Never has added a conformance to an existing protocol Identifiable
 
+// These haven't actually been removed; they are simply marked unavailable.
+// This seems to be a false positive in the ABI checker. This is not an ABI
+// break because the symbols are still present, and is not a source break
+// because FixedWidthInteger still has these operations.
+Func SignedInteger.&+(_:_:) has been removed
+Func SignedInteger.&-(_:_:) has been removed
+
 // *** DO NOT DISABLE OR XFAIL THIS TEST. *** (See comment above.)