[Version 13.0] Feature support for Overload resolution priority

standard/attributes.md

@@ -514,6 +514,7 @@ A number of attributes affect the language in some way. These attributes include
 - `System.Diagnostics.CodeAnalysis.SetsRequiredMembersAttribute` ([§23.5.12.1](attributes.md#235121-the-setsrequiredmembers-attribute)) and `System.Runtime.CompilerServices.RequiredMemberAttribute` ([§23.5.12.2](attributes.md#235122-the-requiredmember-attribute)), which are used in required-member contexts ([§15.7.1](classes.md#1571-general)).
 - `System.Runtime.CompilerServices.CollectionBuilderAttribute` ([§23.5.13](attributes.md#23513-the-collectionbuilder-attribute)), which designates a collection type as having a collection-creation method.
 - `System.Runtime.CompilerServices.InlineArrayAttribute` ([§23.5.14](attributes.md#23514-the-inlinearray-attribute)), which marks a struct type as an inline array type ([§16.6](structs.md#166-inline-arrays)).
+- `System.Runtime.CompilerServices.OverloadResolutionPriorityAttribute` (§OvrldResPriAttribute), which specifies the priority of a member during overload resolution.
 
 The Nullable static analysis attributes ([§23.5.7](attributes.md#2357-code-analysis-attributes)) can improve the correctness of warnings generated for nullabilities and null states ([§8.9.5](types.md#895-nullabilities-and-null-states)).
 
@@ -1593,6 +1594,68 @@ The builder type shall be a non-generic class or struct.
 
 This attribute is used to identify a non-record struct as an inline array type. For further information and examples of its use, see [§16.6](structs.md#166-inline-arrays).
 
+### §OvrldResPriAttribute The OverloadResolutionPriority attribute
+
+The attribute `OverloadResolutionPriority` is used to specify the priority of a member during overload resolution, as an `int` argument to the constructor. The absence of this attribute is equivalent to its presence with an argument of `0`. The higher the number, the higher the priority. All overloads with a lower priority than the highest overload priority are removed from the set of applicable matches.
+
+A library author might use this attribute to ensure that a new, better overload is preferred over an existing one, to reduce memory allocation, for example. This attribute informs the compiler which overload should be preferred.
+
+> <!-- Example: {template:"standalone-console", name:"OverloadResolutionPriority1", expectedOutput:["Span"]} -->
+> *Example*: Consider the following:
+>
+> ```csharp
+> class Program
+> {
+>     static void Main()
+>     {
+>         var c = new C();
+>         int[] arr = [1, 2, 3];
+>         c.M(arr);   // Prints "Span"
+>     }
+> }
+> class C
+> {
+>     [OverloadResolutionPriority(1)]
+>     public void M(params ReadOnlySpan<int> s) => Console.WriteLine("Span");
+>     public void M(params int[] a) => Console.WriteLine("Array");
+> }
+> ```
+>
+> The second method has an implicit priority of zero, and in the absence of the explicit attribute, the second of the overloads would be invoked. However, with the attribute present, the first is invoked instead.
+>
+> <!-- Example: {template:"standalone-console", name:"OverloadResolutionPriority2"} -->
+> Certain uses of this attribute can make a member uncallable, as follows:
+>
+> ```csharp
+> class Program
+> {
+>     static void Main()
+>     {
+>         var c = new C();
+>         c.M1(1); // Calls C3.M1(long), not M1(int)
+>         c.M2(1); // Calls C3.M2(int, string), not M2(int)
+>         c.M3("abc"); // Calls C3.M3(object), not M3(string)
+>     }
+> }
+> class C
+> {
+>     public void M1(int i) { }
+>     [OverloadResolutionPriority(1)]
+>     public void M1(long l) { }
+>
+>     [Conditional("DEBUG")]
+>     public void M2(int i) { }
+>     [OverloadResolutionPriority(1), Conditional("DEBUG")]
+>     public void M2(int i, [CallerArgumentExpression(nameof(i))] string s = "") { }
+>
+>     public void M3(string s) { }
+>     [OverloadResolutionPriority(1)]
+>     public void M3(object o) { }
+> }
+> ```
+>
+> *end example*
+
 ## 23.6 Attributes for interoperation
 
 For interoperation with other languages, an indexer may be implemented using indexed properties. If the indexer is not decorated with `IndexerNameAttribute`, then the name `Item` is used by default. `IndexerNameAttribute` enables a developer to override this default and specify a different name.

standard/expressions.md

@@ -1,15 +1,15 @@
 # 12 Expressions
 
 ## 12.1 General
 
 An expression is a sequence of operators and operands. This clause defines the syntax, order of evaluation of operands and operators, and meaning of expressions.
 
 An expression *E* is said to ***directly contain*** a subexpression *E₁* if it is not subject to a user-defined conversion [§10.5](conversions.md#105-user-defined-conversions) whose parameter is not of a non-nullable value type, and one of the following conditions holds:
 
 - *E* is *E₁*.
 - If *E* is a parenthesized expression `(E₂)`, and *E₂* directly contains *E₁*.
 - If *E* is a null-forgiving operator expression `E₂!`, and *E₂* directly contains *E₁*.
 - If *E* is a cast expression `(T)E₂`, and the cast does not subject *E₂* to a non-lifted user-defined conversion whose parameter is not of a non-nullable value type, and *E₂* directly contains *E₁*.
 
 ## 12.2 Expression classifications
 
@@ -1064,9 +1064,15 @@
 
 Each of these contexts defines the set of candidate function members and the list of arguments in its own unique way. For instance, the set of candidates for a method invocation does not include methods marked override ([§12.5](expressions.md#125-member-lookup)), and methods in a base class are not candidates if any method in a derived class is applicable ([§12.8.10.2](expressions.md#128102-method-invocations)).
 
+Each method has an ***overload resolution priority*** of type `int` that is used during the process of resolving a method group. By default, that priority is zero. Its value can be set via `OverloadResolutionPriorityAttribute` (§OvrldResPriAttribute). The overload resolution priority of a member comes from the least-derived declaration of that member. Overload resolution priority is not inherited or inferred from any interface members a type member may implement, and given a member `Mx` that implements an interface member `Mi`, no warning is issued if `Mx` and `Mi` have different overload resolution priorities.
+
 Once the candidate function members and the argument list have been identified, the selection of the best function member is the same in all cases:
 
 - First, the set of candidate function members is reduced to those function members that are applicable with respect to the given argument list ([§12.6.4.2](expressions.md#12642-applicable-function-member)). If this reduced set is empty, a compile-time error occurs.
+- Then, the reduced set of candidate members is grouped by declaring type. Within each group:
+  - Candidate function members are ordered by overload resolution priority. If the member is an override, the overload resolution priority comes from the least-derived declaration of that member.
+  - All members that have a lower overload resolution priority than the highest found within its declaring type group are removed.
+- The reduced groups are then recombined into the final set of applicable candidate function members.
 - Then, the best function member from the set of applicable candidate function members is located. If the set contains only one function member, then that function member is the best function member. Otherwise, the best function member is the one function member that is better than all other function members with respect to the given argument list, provided that each function member is compared to all other function members using the rules in [§12.6.4.3](expressions.md#12643-better-function-member). If there is not exactly one function member that is better than all other function members, then the function member invocation is ambiguous and a binding-time error occurs.
 
 The following subclauses define the exact meanings of the terms *applicable function member* and *better function member*.

standard/standard-library.md

@@ -970,6 +970,14 @@ namespace System.Runtime.CompilerServices
         public ModuleInitializerAttribute() { }
     }
 
+    [System.AttributeUsage(System.AttributeTargets.Constructor
+    | System.AttributeTargets.Method | System.AttributeTargets.Property,
+      AllowMultiple=false, Inherited=false)]
+    public sealed class OverloadResolutionPriorityAttribute : Attribute
+    {
+        public OverloadResolutionPriorityAttribute(int priority) {}
+    }
+
     [System.AttributeUsage(System.AttributeTargets.Class |
       System.AttributeTargets.Field | System.AttributeTargets.Property |
       System.AttributeTargets.Struct, AllowMultiple=false, Inherited=false)]
@@ -1550,6 +1558,7 @@ The following library types are referenced in this specification. The full names
 - `global::System.Runtime.CompilerServices.InterpolatedStringHandlerAttribute`
 - `global::System.Runtime.CompilerServices.ITuple`
 - `global::System.Runtime.CompilerServices.ModuleInitializerAttribute`
+- `global::System.Runtime.CompilerServices.OverloadResolutionPriorityAttribute`
 - `global::System.Runtime.CompilerServices.RequiredMemberAttribute`
 - `global::System.Runtime.CompilerServices.TaskAwaiter`
 - `global::System.Runtime.CompilerServices.TaskAwaiter<TResult>`