Add @_disfavoredOverload attribute to affect overload resolution.

Introduce an attribute @_disfavoredOverload that can be used to state
that a particular declaration should be avoided if there is a
successful type-check for a non-@_disfavoredOverload. It's a way to
nudge overload resolution away from particular solutions.

Author: DougGregor

include/swift/AST/Attr.def

@@ -402,6 +402,9 @@ DECL_ATTR(_custom, Custom,
 SIMPLE_DECL_ATTR(_propertyDelegate, PropertyDelegate,
   OnStruct | OnClass | OnEnum,
   86)
+SIMPLE_DECL_ATTR(_disfavoredOverload, DisfavoredOverload,
+  OnAbstractFunction | OnVar | OnSubscript | UserInaccessible,
+  87)
 
 #undef TYPE_ATTR
 #undef DECL_ATTR_ALIAS

lib/Sema/CSGen.cpp

@@ -641,6 +641,7 @@ namespace {
         continue;
 
       if (!decl->getAttrs().isUnavailable(CS.getASTContext()) &&
+          !decl->getAttrs().hasAttribute<DisfavoredOverloadAttr>() &&
           isFavored(decl, overloadType)) {
         // If we might need to roll back the favored constraints, keep
         // track of those we are favoring.

lib/Sema/CSRanking.cpp

@@ -48,6 +48,10 @@ void ConstraintSystem::increaseScore(ScoreKind kind, unsigned value) {
       log << "attempting to fix the source";
       break;
 
+    case SK_DisfavoredOverload:
+      log << "disfavored overload";
+      break;
+
     case SK_ForceUnchecked:
       log << "force of an implicitly unwrapped optional";
       break;

lib/Sema/CSSolver.cpp

@@ -2002,6 +2002,9 @@ static Constraint *tryOptimizeGenericDisjunction(
     if (!AFD || !AFD->isGeneric())
       return false;
 
+    if (AFD->getAttrs().hasAttribute<DisfavoredOverloadAttr>())
+      return false;
+
     auto funcType = AFD->getInterfaceType();
     auto hasAnyOrOptional = funcType.findIf([](Type type) -> bool {
       if (type->getOptionalObjectType())

lib/Sema/ConstraintSystem.cpp

@@ -2169,6 +2169,12 @@ void ConstraintSystem::resolveOverload(ConstraintLocator *locator,
       << boundType->getString() << " := "
       << refType->getString() << ")\n";
   }
+
+  // If this overload is disfavored, note that.
+  if (choice.isDecl() &&
+      choice.getDecl()->getAttrs().hasAttribute<DisfavoredOverloadAttr>()) {
+    increaseScore(SK_DisfavoredOverload);
+  }
 }
 
 template <typename Fn>

lib/Sema/ConstraintSystem.h

@@ -470,6 +470,8 @@ enum ScoreKind {
   SK_Fix,
   /// A reference to an @unavailable declaration.
   SK_Unavailable,
+  /// A use of a disfavored overload.
+  SK_DisfavoredOverload,
   /// An implicit force of an implicitly unwrapped optional value.
   SK_ForceUnchecked,
   /// A user-defined conversion.

lib/Sema/TypeCheckAttr.cpp

@@ -130,6 +130,7 @@ class AttributeEarlyChecker : public AttributeVisitor<AttributeEarlyChecker> {
   IGNORED_ATTR(PrivateImport)
   IGNORED_ATTR(Custom)
   IGNORED_ATTR(PropertyDelegate)
+  IGNORED_ATTR(DisfavoredOverload)
 #undef IGNORED_ATTR
 
   void visitAlignmentAttr(AlignmentAttr *attr) {
@@ -812,6 +813,7 @@ class AttributeChecker : public AttributeVisitor<AttributeChecker> {
     IGNORED_ATTR(Transparent)
     IGNORED_ATTR(WarnUnqualifiedAccess)
     IGNORED_ATTR(WeakLinked)
+    IGNORED_ATTR(DisfavoredOverload)
 #undef IGNORED_ATTR
 
   void visitAvailableAttr(AvailableAttr *attr);

lib/Sema/TypeCheckDeclOverride.cpp

@@ -1326,6 +1326,8 @@ namespace  {
     UNINTERESTING_ATTR(ImplementationOnly)
     UNINTERESTING_ATTR(Custom)
     UNINTERESTING_ATTR(PropertyDelegate)
+    UNINTERESTING_ATTR(DisfavoredOverload)
+
 #undef UNINTERESTING_ATTR
 
     void visitAvailableAttr(AvailableAttr *attr) {

test/Constraints/disfavored.swift

@@ -0,0 +1,37 @@
+// RUN: %target-typecheck-verify-swift
+
+struct A { }
+struct B { }
+
+@_disfavoredOverload
+func f0<T>(_: T) -> A { return A() }
+
+func f0(_: Int32) -> B { return B() }
+
+
+func f1(_: StaticString) -> B { return B() }
+
+@_disfavoredOverload
+func f1<T>(_: T) -> A { return A() }
+
+func f2(_: Substring) -> B { return B() }
+
+@_disfavoredOverload
+func f2<T>(_: T) -> A { return A() }
+
+func test(s: String, answer: Int) {
+  let r0a = f0(17)
+  let _: B = r0a
+  let r0b = f0(answer)
+  let _: A = r0b
+
+  let r1 = f1("hello")
+  let _: B = r1
+  
+  let r2a = f2("hello")
+  let _: B = r2a
+  let r2b = f2("the answer is \(answer)")
+  let _: B = r2b
+  let r2c = f2(s)
+  let _: A = r2c
+}