Merge pull request #9229 from dotnet/madst-extensions

Describe scoping rules for extension declaration type parameters and receiver parameter; describe rules for extension operators.

Author: MadsTorgersen

meetings/working-groups/extensions/disambiguation-syntax-examples.md

@@ -48,7 +48,7 @@ var repetition = new IEnumerable<int>(first, 10);
 // Static extension members
 var range = IEnumerable<int>.(MyExtensions.Range)(0, 10);
 var empty = IEnumerable<int>.(MyExtensions.Empty);
-range (MyExtensions.+=) 5;
+range (MyExtensions.+=) 5; /* or */ (MyExtensions.+)(range, 5);
 ReadOnlySpan<int> span = (MyExtensions.implicit)(range);
 
 // Instance extension members
@@ -200,3 +200,133 @@ var isEmpty = (query using MyExtensions).IsEmpty;
 var first = (query using MyExtensions)[0];
 var repetition = new (IEnumerable<int> using MyExtensions)(first, 10);
 ```
+
+## Speakable lowering
+
+``` c#
+// Static extension members
+var range = MyExtensions.Range(0, 10);
+var empty = MyExtensions.Empty;
+range = MyExtensions.op_addition(range, 5);
+ReadOnlySpan<int> span = MyExtensions.op_implicit(range); // Need target typing?
+
+// Instance extension members
+var query = MyExtensions.Where(range, i => i < 10);
+var isEmpty = MyExtensions.get_IsEmpty(query);
+var first = MyExtensions.get_Item(query, 0);
+var repetition = MyExtensions.__ctor_IEnumerable<int>(first, 10);
+```
+
+## Using clauses as statements
+
+``` c#
+using static MyExtensions 
+{
+    // Static extension members
+    var range = IEnumerable<int>.Range(0, 10);
+    var empty = IEnumerable<int>.Empty;
+    range += 5;
+    ReadOnlySpan<int> span = range;
+
+    // Instance extension members
+    var query = range.Where(i => i < 10);
+    var isEmpty = query.IsEmpty;
+    var first = query[0];
+    var repetition = new IEnumerable<int>(first, 10);
+}
+```
+
+- Doesn't address bypassing instance member
+
+
+``` c#
+// Static extension members
+var range = MyExtensions.(IEnumerable<int>).Range(0, 10);
+var empty = MyExtensions.(IEnumerable<int>).Empty;
+MyExtensions.(range) += 5;
+ReadOnlySpan<int> span = MyExtensions.(range);
+
+// Instance extension members
+var query = MyExtensions.(range).Where(i => i < 10);
+var isEmpty = MyExtensions.(query).IsEmpty;
+var first = MyExtensions.(query)[0];
+var repetition = new MyExtensions.(IEnumerable<int>)(first, 10);
+```
+
+
+``` c#
+// Static extension members
+var range = IEnumerable<int>.(MyExtensions).Range(0, 10);
+var empty = IEnumerable<int>.(MyExtensions).Empty;
+range.(MyExtensions) += 5;
+ReadOnlySpan<int> span = range.(MyExtensions);
+
+// Instance extension members
+var query = range.(MyExtensions).Where(i => i < 10);
+var isEmpty = query.(MyExtensions).IsEmpty;
+var first = query.(MyExtensions)[0];
+var repetition = new IEnumerable<int>.(MyExtensions)(first, 10);
+```
+
+
+``` c#
+// Static extension members
+var range = IEnumerable<int>.as(MyExtensions).Range(0, 10);
+var empty = IEnumerable<int>.as(MyExtensions).Empty;
+range.as(MyExtensions) += 5;
+ReadOnlySpan<int> span = range.as(MyExtensions);
+
+// Instance extension members
+var query = range.as(MyExtensions).Where(i => i < 10);
+var isEmpty = query.as(MyExtensions).IsEmpty;
+var first = query.as(MyExtensions)[0];
+var repetition = new IEnumerable<int>.as(MyExtensions)(first, 10);
+```
+
+
+``` c#
+// Static extension members
+var range = IEnumerable<int>.MyExtensions.Range(0, 10);
+var empty = IEnumerable<int>.MyExtensions.Empty;
+range.MyExtensions += 5;
+ReadOnlySpan<int> span = range.MyExtensions;
+
+// Instance extension members
+var query = range.MyExtensions.Where(i => i < 10);
+var isEmpty = query.MyExtensions.IsEmpty;
+var first = query.MyExtensions[0];
+var repetition = new IEnumerable<int>.MyExtensions(first, 10);
+```
+- Doesn't allow giving the full name of `MyExtensions`
+
+
+``` c#
+// Static extension members
+var range = IEnumerable<int>.in(MyExtensions).Range(0, 10);
+var empty = IEnumerable<int>.in(MyExtensions).Empty;
+range.in(MyExtensions) += 5;
+ReadOnlySpan<int> span = range.in(MyExtensions);
+
+// Instance extension members
+var query = range.in(MyExtensions).Where(i => i < 10);
+var isEmpty = query.in(MyExtensions).IsEmpty;
+var first = query.in(MyExtensions)[0];
+var repetition = new IEnumerable<int>.in(MyExtensions)(first, 10);
+```
+
+
+
+``` c#
+// Static extension members
+var range = IEnumerable<int>.at(MyExtensions).Range(0, 10);
+var empty = IEnumerable<int>.at(MyExtensions).Empty;
+range.at(MyExtensions) += 5;
+ReadOnlySpan<int> span = range.at(MyExtensions);
+
+// Instance extension members
+var query = range.at(MyExtensions).Where(i => i < 10);
+var isEmpty = query.at(MyExtensions).IsEmpty;
+var first = query.at(MyExtensions)[0];
+var repetition = new IEnumerable<int>.at(MyExtensions)(first, 10);
+```
+

meetings/working-groups/extensions/extension-operators.md

@@ -0,0 +1,73 @@
+# Extension operators
+
+***Note:*** *Does not cover user-defined implicit and explicit conversion operators, which are not yet designed or planned.*
+
+## Declaration
+Like all extension members, extension operators are declared within an extension block:
+
+``` c#
+public static class Operators
+{
+    extension<TElement>(TElement[] source) where TElement : INumber<TElement>
+    {
+        public static TElement[] operator *(TElement[] vector, TElement scalar) { ... }
+        public static TElement[] operator *(TElement scalar, TElement[] vector) { ... }
+        public void operator *=(TElement scalar) { ... }
+    }
+}
+```
+
+Extension operator declarations generally follow the rules for non-extension [user-defined operators in the Standard](https://github.com/dotnet/csharpstandard/blob/standard-v7/standard/classes.md#1510-operators) as well as the soon-to-be-added [user-defined compound assignment operators](https://github.com/dotnet/csharplang/blob/main/proposals/user-defined-compound-assignment.md). 
+
+Generally speaking, the rules pertaining to the *containing type* of the declaration instead apply to the *extended type*. 
+
+A static extension operator for the extended type `T` must take at least one parameter of type `S` or `S?`, where `S` and `T` are identity convertible.
+
+For operators that require pair-wise declaration, the two declarations are allowed to occur in separate extension blocks for extended types `S` and `T` respectively, as long as `S` and `T` are identity convertible and the extension blocks occur in the same static class.
+
+Like other extension members, extension operators cannot use the `abstract`, `virtual`, `override` or `sealed` modifiers.
+
+An extension operator may not have the same signature as a predefined operator.
+
+``` c#
+public static class Operators
+{
+    extension(int[])
+    {
+        public static int[] operator +(int[] vector, int scalar) { ... }    // OK; parameter and extended type agree
+        public static int operator +(int scalar1, int scalar2) { ... }      // ERROR: extended type not used as parameter type
+                                                                            // and ERROR: same signature as predefined +(int, int)
+        public static bool operator ==(int[] vector1, int[] vector2){ ... } // ERROR: '!=' declaration missing
+        public static bool operator <(int[] vector1, int[] vector2){ ... }  // OK: `>` is declared below
+    }
+    extension(int[])
+    {
+        public static bool operator >(int[] vector1, int[] vector2){ ... }  // OK: `<` is declared above
+    }
+}
+```
+
+**Open question:** Should we disallow user-defined extension operators where the types of all parameters and receivers are type parameters? Otherwise specific instantiations could have the same signature as a predefined operator.
+
+## Overload resolution
+
+Like other extension members, extension operators are only considered if no applicable predefined or non-extension user-defined operators were found. The search then proceeds outwards scope by scope, starting with the innermost namespace within which the operator application occurs, until at least one applicable extension operator declaration is found. For compound assignment operators, this involves looking for first user-defined compound assignment operators and then, if none found, non-assignment operators, before moving on to the next scope.
+
+At each scope, overload resolution works the same as other extension members:
+- The set of operator declarations for the given name (i.e. operator) is determined
+- Type inference is attempted for each, based on operand expressions
+- Declarations that fail type inference are removed
+- Declarations that are not applicable to the operands are removed
+- If there are no remaining candidates, proceed to the enclosing scope (or, if looking for compound-assignment operators, the corresponding simple operator)
+- Applying overload resolution between the candidate, select the unique best candidate, if it exists
+- If no unique best candidate can be found, overload resolution fails with an ambiguity error.
+
+Using `*` and `*=` declarations above:
+
+``` c#
+int[] numbers = { 1, 2, 3 };
+
+var i = 2 * 3;       // predefined operator *(int, int)
+var v = numbers * 4; // extension operator *(int[], int)
+v *= 5;              // extension operator *=(int)
+```

proposals/extensions.md

@@ -52,6 +52,38 @@ receiver_parameter // add
 Extension declarations shall only be declared in non-generic, non-nested static classes.  
 It is an error for a type to be named `extension`.  
 
+### Scoping rules
+
+The type parameters and receiver parameter of an extension declaration are in scope within the body of the extension declaration. It is an error to refer to the receiver parameter from within a static member, except within a `nameof` expression. It is an error for members to declare type parameters or parameters (as well as local variables and local functions directly within the member body) with the same name as a type parameter or receiver parameter of the extension declaration.
+
+``` c#
+public static class E
+{
+    extension<T>(T[] ts)
+    {
+        public bool M1(T t) => ts.Contains(t);        // `T` and `ts` are in scope
+        public static bool M2(T t) => ts.Contains(t); // Error: Cannot refer to `ts` from static context
+        public void M3(int T, string ts) { }          // Error: Cannot reuse names `T` and `ts`
+        public void M4<T, ts>(string s) { }           // Error: Cannot reuse names `T` and `ts`
+    }
+}
+```
+
+It is not an error for the members themselves to have the same name as the type parameters or receiver parameter of the enclosing extension declaration. Member names are not directly found in a simple name lookup from within the extension declaration; lookup will thus find the type parameter or receiver parameter of that name, rather than the member. 
+
+Members do give rise to static methods being declared directly on the enclosing static class, and those can be found via simple name lookup; however, an extension declaration type parameter or receiver parameter of the same name will be found first.
+
+``` c#
+public static class E
+{
+    extension<T>(T[] ts)
+    {
+        public void T() { M(ts); } // Generated static method M<T>(T[]) is found
+        public void M() { T(ts); } // Error: T is a type parameter
+    }
+}
+```
+
 ### Static classes as extension containers
 
 Extensions are declared inside top-level non-generic static classes, just like extension methods today,