From 5dbe9cf255fb011c10a6a830b1bc60c04c445ef2 Mon Sep 17 00:00:00 2001 From: Rex Jaeschke Date: Sun, 1 Nov 2026 17:59:12 +0000 Subject: [PATCH 1/7] add support for User-Defined Compound Assignment Operators Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 361b9a77-2b4c-45e6-969f-e6785c47f27e --- standard/expressions.md | 108 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 106 insertions(+), 2 deletions(-) diff --git a/standard/expressions.md b/standard/expressions.md index c6a504763..66fa45c6d 100644 --- a/standard/expressions.md +++ b/standard/expressions.md @@ -195,17 +195,19 @@ The ***overloadable unary operator***s are: > `+ - !` (logical negation only) `~ ++ -- true false` +A newer, alternate approach to explicit overloading of `++` and `--` is discussed in §increment-operators. + Only the operators listed above can be overloaded. In particular, it is not possible to overload the null-forgiving operator (postfix `!`, [§12.8.9](expressions.md#1289-null-forgiving-expressions)) or the unary index from-end operator (prefix `^`, ([§12.9.6](expressions.md#1296-index-from-end-operator))). > *Note*: Although `true` and `false` are not used explicitly in expressions (and therefore are not included in the precedence table in [§12.4.2](expressions.md#1242-operator-precedence-and-associativity)), they are considered operators because they are invoked in several expression contexts: Boolean expressions ([§12.27](expressions.md#1227-boolean-expressions)) and expressions involving the conditional ([§12.21](expressions.md#1221-conditional-operator)) and conditional logical operators ([§12.17](expressions.md#1217-conditional-logical-operators)). *end note* The ***overloadable binary operator***s are: -> `+ - * / % & | ^ << >> >>> == != > < <= >=` +> `+ - * / % & | ^ << >> >>> == != > < <= >= «op»=` Only the operators listed above can be overloaded. In particular, it is not possible to overload member access, method invocation, or the `..`, `=`, `&&`, `||`, `??`, `?:`, `=>`, `checked`, `unchecked`, `new`, `typeof`, `default`, `as`, and `is` operators. -When a binary operator is overloaded, the corresponding compound assignment operator, if any, is also implicitly overloaded. +When a binary operator is overloaded, the corresponding compound assignment operator, if any, is also implicitly overloaded. Explicit overloading of a compound assignment operator is discussed in §compound-assignment-operators. > *Example*: An overload of operator `*` is also an overload of operator `*=`. This is described further in [§12.24](expressions.md#1224-assignment-operators). *end example* @@ -243,12 +245,31 @@ The descriptions of individual operators in [§12.9](expressions.md#129-unary-op ### 12.4.4 Unary operator overload resolution +#### §UnaryOpOverResGen General + +[Instance increment operator overload resolution is discussed in §InsIncOpOverRes.] + An operation of the form `«op» x` or `x «op»`, where «op» is an overloadable unary operator, and `x` is an expression of type `X`, is processed as follows: - The set of candidate user-defined operators provided by `X` for the operation `operator «op»(x)` is determined using the rules of [§12.4.6](expressions.md#1246-candidate-user-defined-operators). - If the set of candidate user-defined operators is not empty, then this becomes the set of candidate operators for the operation. Otherwise, the predefined unary `operator «op»` implementations, including their lifted forms, become the set of candidate operators for the operation. The predefined implementations of a given operator are specified in the description of the operator. The predefined operators provided by an enum or delegate type are only included in this set when the binding-time type—or the underlying type if it is a nullable type—of either operand is the enum or delegate type. - The overload resolution rules of [§12.6.4](expressions.md#1264-overload-resolution) are applied to the set of candidate operators to select the best operator with respect to the argument list `(x)`, and this operator becomes the result of the overload resolution process. If overload resolution fails to select a single best operator, a binding-time error occurs. +#### §InsIncOpOverRes Instance increment operator overload resolution + +An operation of the form `«op» x` or `x «op»`, where «op» is an overloadable instance increment operator, and `x` is an expression of type `X`, is processed as follows: + +- The set of candidate user-defined operators provided by `X` for the operation `operator «op»(x)` is determined using the rules of candidate instance increment operators (§CandInsIncOp). +- If the set of candidate user-defined operators is not empty, then this becomes the set of candidate operators for the operation. Otherwise, the overload resolution yields no result. +- The overload resolution rules ([§12.6.4](expressions.md#1264-overload-resolution)) are applied to the set of candidate operators to select the best operator, and this operator becomes the result of the overload resolution process. If overload resolution fails to select a single best operator, a binding-time error occurs. + +#### §CandInsIncOp Candidate instance increment operators + +Given a type `T` and an operation `«op»`, where `«op»` is an overloadable instance increment operator, the set of candidate user-defined operators provided by `T` is determined as follows: + +- In an `unchecked` evaluation context, it is a group of operators that would be produced by the member lookup process ([§12.5.1](expressions.md#1251-general)) when only instance `operator «op»()` operators were considered matching the target name `N`. +- In a `checked` evaluation context, it is a group of operators that would be produced by the member lookup process when only instance `operator «op»()` and instance `operator checked «op»()` operators were considered matching the target name `N`. The `operator «op»()` operators that have pair-wise matching `operator checked «op»()` declarations are excluded from the group. + ### 12.4.5 Binary operator overload resolution An operation of the form `x «op» y`, where «op» is an overloadable binary operator, `x` is an expression of type `X`, and `y` is an expression of type `Y`, is processed as follows: @@ -3019,6 +3040,8 @@ post_decrement_expression ; ``` +The following applies when *primary_expression* has a non-user-defined type: + The operand of a postfix increment or decrement operation shall be an expression classified as a variable, a property access, or an indexer access. The result of the operation is a value of the same type as the operand. If the *primary_expression* has the compile-time type `dynamic` then the operator is dynamically bound ([§12.3.3](expressions.md#1233-dynamic-binding)), the *post_increment_expression* or *post_decrement_expression* has the compile-time type `dynamic` and the following rules are applied at run-time using the run-time type of the *primary_expression*. @@ -3048,6 +3071,25 @@ The `++` and `--` operators also support prefix notation ([§12.9.7](expressions An operator `++` or operator `--` implementation can be invoked using either postfix or prefix notation. It is not possible to have separate operator implementations for the two notations. +The following applies when *primary_expression* has a user-defined type: + +A user-defined type may provide a static form, an instance form, or both forms, of *operator_declaration* for this operator (§increment-operators). + +If the result of the operation is used or `x` in `x «op»` is not classified as a variable, the operation is processed by applying unary operator overload resolution as +specified as specified earlier in this subclause for non-user-defined types. + +> *Note*: Consider a user-defined type, `U`, that declares an instance `operator++` but not a static one. Given an instance of `U` called `x`, `x++` produces an error as the result is used but no unary operator overload resolution is possible. *end note* + +Otherwise, priority is given to the instance increment operator, if one exists, as follows: + +First, an attempt is made to process the operation by applying +instance increment operator overload resolution§InsIncOpOverRes). If the process produces no result and no error, then the operation is processed by applying unary operator overload resolution as specified earlier in this subclause for non-user-defined types. + +Otherwise, `x«op»` is evaluated as follows: + +- If the type of `x` is known to be a reference type, the operator method is invoked on `x`. If `x` is `null`, the operator method invocation shall throw a `NullReferenceException`. +- If the type of `x` is not known to be a reference type, the operator method is invoked on `x`. + ### 12.8.17 The new operator #### 12.8.17.1 General @@ -4356,6 +4398,8 @@ pre_decrement_expression ; ``` +The following applies when *unary_expression* has a non-user-defined type: + The operand of a prefix increment or decrement operation shall be an expression classified as a variable, a property access, or an indexer access. The result of the operation is a value of the same type as the operand. If the operand of a prefix increment or decrement operation is a property or indexer access, the property or indexer shall have both a get and a set or init accessor. If this is not the case, a binding-time error occurs. @@ -4383,6 +4427,25 @@ An operator `++` or operator `--` implementation can be invoked using either p Lifted ([§12.4.8](expressions.md#1248-lifted-operators)) forms of the unlifted predefined prefix increment and decrement operators defined above are also predefined. +The following applies when *unary_expression* has a user-defined type: + +A user-defined type may provide a static form, an instance form, or both forms, of *operator_declaration* for this operator (§increment-operators). + +If `x` in `«op» x` is classified as a variable, priority is given to the instance increment version, if one exists, as follows: + +First, an attempt is made to process the operation by applying instance increment operator overload resolution (InsIncOpOverRes). If the process produces no result and no error, then the operation is processed by applying unary operator overload resolution as specified earlier in this subclause for non-user-defined types. + +Otherwise, `«op»x` is evaluated as follows: + +- If the type of `x` is known to be a reference type, `x` is evaluated to get an instance `x₀`, the operator method is invoked on that instance, and `x₀` is returned as the result of the operation. If `x₀` is `null`, the operator method invocation shall throw a `NullReferenceException`. + +- If the type of `x` is not known to be a reference type: + + - If the result of increment is used, `x` is evaluated to get an instance `x₀`, the operator method is invoked on that instance, `x₀` is assigned to `x`, and `x₀` is returned as the result of the assignment. + - Otherwise, the operator method is invoked on `x`. + +Side effects in `x` are evaluated only once in the process. + ### 12.9.8 Cast expressions A *cast_expression* is used to convert explicitly an expression to a given type. @@ -8058,6 +8121,10 @@ The ref assignment operator shall not read the storage location referenced by th ### 12.24.5 Compound assignment +#### §CompAssignGen General + +[Explicit compound assignment operator overload handling is discussed later in this subsection.] + ```ANTLR compound_assignment : unary_expression compound_assignment_operator expression @@ -8121,6 +8188,43 @@ The intuitive effect of the rule for predefined operators is simply that `x «op > *Note*: This also means that compound assignment operations support lifted operators. Since a compound assignment `x «op»= y` is evaluated as either `x = x «op» y` or `x = (T)(x «op» y)`, the rules of evaluation implicitly cover lifted operators. *end note* +The following discusses the case when an explicit compound assignment operator is declared: + +If `x` in `x «op»= y` is classified as a variable, priority is given to compound assignment operators (§compound-assignment-operators), as follows. + +First, an attempt is made to process an operation of the form `x «op»= y` by applying +compound assignment operator overload resolution (§CompAssignOpOver). If the process produces no result and no error, then the operation is processed by applying binary operator overload resolution as the earlier part of this subclause specifies. + +Otherwise, the operation is evaluated as follows: + +- If the type of `x` is known to be a reference type, `x` is evaluated to get an instance `x₀`, the operator method is invoked on that instance with `y` as the argument, and `x₀` is returned as result of the compound assignment. +- If `x₀` is `null`, the operator method invocation shall throw a `NullReferenceException`. + +If the type of `x` is not known to be a reference type: + +- If the result of compound assignment is used, the `x` is evaluated to get an instance `x₀`, the operator method is invoked on that instance with `y` as the argument, `x₀` is assigned to `x` and `x₀` is returned as the result of the compound assignment. +- Otherwise, the operator method is invoked on `x` with `y` as the argument. + +Side effects in `x` are evaluated only once in the process. + +#### §CompAssignOpOver Compound assignment operator overload resolution + +An operation of the form `x «op»= y`, where `«op»=` is an overloadable compound assignment operator, `x` is an expression of type `X` is processed as follows: + +- The set of candidate user-defined operators provided by `X` for the operation `operator «op»=(y)` is determined using the rules of candidate compound assignment operators (§CandCompAssignOp). +- If at least one candidate user-defined operator in the set is applicable to the argument list `(y)`, then this becomes the set of candidate operators for the operation. Otherwise, the overload resolution yields no result. +- The overload resolution rules([§12.6.4](expressions.md#1264-overload-resolution)) are applied to the set of candidate operators to select the best operator with respect to the argument list `(y)`, and this operator becomes the result of the overload resolution process. If overload resolution fails to select a single best operator, a binding-time error occurs. + +#### §CandCompAssignOp Candidate compound assignment operators + +Given a type `T` and an operation `«op»=`, where `«op»=` is an overloadable compound assignment operator, the set of candidate user-defined operators provided by `T` is determined as follows: + +- In an unchecked evaluation context, it is a group of operators that would be produced + by the member lookup process ([§12.5.1](expressions.md#1251-general)) process when only instance `operator «op»=(Y)` operators were considered matching the target name `N`. +- In a checked evaluation context, it is a group of operators that would be produced + by the member lookup] process when only instance `operator «op»=(Y)` and instance `operator checked «op»=(Y)` operators were considered matching the target name `N`. The `operator «op»=(Y)` operators that have pair-wise matching `operator checked «op»=(Y)` + declarations are excluded from the group. + ### 12.24.6 Event assignment An event assignment is a subset of *compound_assignment* where the left operand of a `+=` or `-=` operator is classified as an event access. An event assignment is evaluated as follows: From 6f7587b705da489ee1c6322eae6c594befbd6457 Mon Sep 17 00:00:00 2001 From: Rex Jaeschke Date: Sun, 1 Nov 2026 13:16:36 -0500 Subject: [PATCH 2/7] add support for User-Defined Compound Assignment Operators Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 361b9a77-2b4c-45e6-969f-e6785c47f27e --- standard/classes.md | 198 +++++++++++++++++++++++++++++++++----------- 1 file changed, 149 insertions(+), 49 deletions(-) diff --git a/standard/classes.md b/standard/classes.md index f7abe690a..91af99e04 100644 --- a/standard/classes.md +++ b/standard/classes.md @@ -1595,37 +1595,44 @@ The following method names are reserved. While many have corresponding operators | **Method Name** | **C# Operator** | |--------------|----------------------| | `op_Addition` | `+` (binary) | -| `op_AdditionAssignment` | (reserved) | +| `op_AdditionAssignment` | `+=` | | `op_AddressOf` | (reserved) | | `op_Assign` | (reserved) | | `op_BitwiseAnd` | `&` (binary) | -| `op_BitwiseAndAssignment` | (reserved) | +| `op_BitwiseAndAssignment` | `&=` | | `op_BitwiseOr` | `\|` | -| `op_BitwiseOrAssignment` | (reserved) | +| `op_BitwiseOrAssignment` | `|=` | | `op_CheckedAddition` | checked addition `+` | -| `op_CheckedDecrement` | checked decrement `--` | +| `op_CheckedAdditionAssignment` | checked `+=` | +| `op_CheckedDecrement` | static checked decrement `--` | +| `op_CheckedDecrementAssignment` | instance checked decrement `--` | | `op_CheckedDivision` | checked division `/` | | `op_CheckedExplicit` | checked explicit (narrowing) coercion | -| `op_CheckedIncrement` | checked increment `++` | +| `op_CheckedIncrement` | static checked increment `++` | +| `op_CheckedIncrementAssignment` | instance checked decrement `--` | | `op_CheckedMultiply` | checked multiply `*` | | `op_CheckedSubtraction` | checked subtraction `-` | +| `op_CheckedSubtractionAssignment` | checked `-=` | | `op_CheckedUnaryNegation` | checked unary negation `-` | | `op_Comma` | (reserved) | -| `op_Decrement` | `--` (prefix and postfix) | +| `op_Decrement` | static `--` | +| `op_DecrementAssignment` | instance `++` | | `op_Division` | `/` | -| `op_DivisionAssignment` | (reserved) | +| `op_DivisionAssignment` | `/=` | +| `op_CheckedDivisionAssignment` | checked `/=` | | `op_Equality` | `==` | | `op_ExclusiveOr` | `^` | -| `op_ExclusiveOrAssignment` | (reserved) | +| `op_ExclusiveOrAssignment` | `^=` | | `op_Explicit` | explicit (narrowing) coercion | | `op_False` | `false` | | `op_GreaterThan` | `>` | | `op_GreaterThanOrEqual` | `>=` | | `op_Implicit` | implicit (widening) coercion | -| `op_Increment` | `++` (prefix and postfix) | +| `op_Increment` | static `++` | +| `op_IncrementAssignment` | instance `++` | | `op_Inequality` | `!=` | | `op_LeftShift` | `<<` | -| `op_LeftShiftAssignment` | (reserved) | +| `op_LeftShiftAssignment` | `<<=` | | `op_LessThan` | `<` | | `op_LessThanOrEqual` | `<=` | | `op_LogicalAnd` | (reserved) | @@ -1633,22 +1640,23 @@ The following method names are reserved. While many have corresponding operators | `op_LogicalOr` | (reserved) | | `op_MemberSelection` | (reserved) | | `op_Modulus` | `%` | -| `op_ModulusAssignment` | (reserved) | -| `op_MultiplicationAssignment` | (reserved) | +| `op_ModulusAssignment` | `%=` | +| `op_MultiplicationAssignment` | `*=` | +| `op_CheckedMultiplicationAssignment` | checked `*=` | | `op_Multiply` | `*` (binary) | | `op_OnesComplement` | `~` | | `op_PointerDereference` | (reserved) | | `op_PointerToMemberSelection` | (reserved) | | `op_RightShift` | `>>` | -| `op_RightShiftAssignment` | (reserved) | +| `op_RightShiftAssignment` | `>>=` | | `op_SignedRightShift` | (reserved) | | `op_Subtraction` | `-` (binary) | -| `op_SubtractionAssignment` | (reserved) | +| `op_SubtractionAssignment` | `-=` | | `op_True` | `true` | | `op_UnaryNegation` | `-` (unary) | | `op_UnaryPlus` | `+` (unary) | | `op_UnsignedRightShift` | `>>>` | -| `op_UnsignedRightShiftAssignment` | (reserved) | +| `op_UnsignedRightShiftAssignment` | `>>>=` | ## 15.4 Constants @@ -5283,6 +5291,9 @@ operator_modifier | 'abstract' | 'virtual' | 'sealed' + | 'override' + | 'new' + | 'readonly' | unsafe_modifier // unsafe code support ; @@ -5290,6 +5301,8 @@ operator_declarator : unary_operator_declarator | binary_operator_declarator | conversion_operator_declarator + | increment_operator_declarator + | compound_assignment_operator_declarator ; unary_operator_declarator @@ -5301,7 +5314,7 @@ logical_negation_operator ; overloadable_unary_operator - : '+' | 'checked'? '-' | logical_negation_operator | '~' | 'checked'? '++' | 'checked'? '--' | 'true' | 'false' + : '+' | 'checked'? '-' | logical_negation_operator | '~' | 'true' | 'false' ; binary_operator_declarator @@ -5319,6 +5332,28 @@ conversion_operator_declarator | 'explicit' 'operator' 'checked'? type '(' fixed_parameter ')' ; +increment_operator_declarator + : type 'operator' overloadable_increment_operator '(' fixed_parameter ')' + | 'void' 'operator' overloadable_increment_operator '(' ')' + ; + +overloadable_increment_operator + : 'checked'? '++' + | 'checked'? '--' + ; + +compound_assignment_operator_declarator + : 'void' 'operator' overloadable_compound_assignment_operator + '(' fixed_parameter ')' + ; + +overloadable_compound_assignment_operator + : 'checked'? '+=' | 'checked'? '-=' | 'checked'? '*=' | 'checked'? '/=' | + '%=' | '&=' | '|=' | '^=' | '<<=' + | right_shift_assignment + | unsigned_right_shift_assignment + ; + operator_body : block | '=>' expression ';' @@ -5330,7 +5365,7 @@ operator_body *Note*: The prefix logical negation ([§12.9.4](expressions.md#1294-logical-negation-operator)) and postfix null-forgiving operators ([§12.8.9](expressions.md#1289-null-forgiving-expressions)), while represented by the same lexical token (`!`), are distinct. The latter is not an overloadable operator. *end note* -There are three categories of overloadable operators: Unary operators ([§15.10.2](classes.md#15102-unary-operators)), binary operators ([§15.10.3](classes.md#15103-binary-operators)), and conversion operators ([§15.10.4](classes.md#15104-conversion-operators)). +The following categories of overloadable operators exist: unary operators ([§15.10.2](classes.md#15102-unary-operators)), binary operators ([§15.10.3](classes.md#15103-binary-operators)), conversion operators ([§15.10.4](classes.md#15104-conversion-operators)), increment operators [§increment-operators), and compound assignment operators [§compound-assignment-operators). The *operator_body* is either a semicolon, a block body ([§15.6.1](classes.md#1561-general)) or an expression body ([§15.6.1](classes.md#1561-general)). A block body consists of a *block*, which specifies the statements to execute when the operator is invoked. The *block* shall conform to the rules for value-returning methods described in [§15.6.11](classes.md#15611-method-body). An expression body consists of `=>` followed by an expression and a semicolon, and denotes a single expression to perform when the operator is invoked. @@ -5338,7 +5373,7 @@ For `extern` operators, the *operator_body* consists simply of a semicolon. For The following rules apply to all operator declarations: -- An operator declaration shall include both a `public` and a `static` modifier. +- An operator declaration shall include a `public` modifier. - The parameters of an operator shall have no modifiers other than `in`. - The signature of an operator ([§15.10.2](classes.md#15102-unary-operators), [§15.10.3](classes.md#15103-binary-operators), [§15.10.4](classes.md#15104-conversion-operators)) shall differ from the signatures of all other operators declared in the same class. - All types referenced in an operator declaration shall be at least as accessible as the operator itself ([§7.4.5](basic-concepts.md#745-accessibility-constraints)). @@ -5346,7 +5381,7 @@ The following rules apply to all operator declarations: Each operator category imposes additional restrictions, as described in the following subclauses. -Like other members, operators declared in a base class are inherited by derived classes. Because operator declarations always require the class or struct in which the operator is declared to participate in the signature of the operator, it is not possible for an operator declared in a derived class to hide an operator declared in a base class. Thus, the `new` modifier is never required, and therefore never permitted, in an operator declaration. +Like other members, operators declared in a base class are inherited by derived classes. Additional information on unary and binary operators can be found in [§12.4](expressions.md#124-operators). @@ -5368,59 +5403,40 @@ The presence of `checked` in a checked operator declaration has no effect on the The following rules apply to unary operator declarations, where `T` denotes the instance type of the class or struct that contains the operator declaration: +- *operator_declaration* shall include a `static` modifier and shall not include an `override` modifier. - A unary `+`, `-`, `!` (logical negation only), or `~` operator shall take a single parameter of type `T` or `T?` and can return any type. -- A unary `++` or `--` operator shall take a single parameter of type `T` or `T?` and shall return that same type or a type derived from it. - A unary `true` or `false` operator shall take a single parameter of type `T` or `T?` and shall return type `bool`. -The signature of a unary operator consists of the operator token (`+`, `-`, `!`, `~`, `++`, `--`, `true`, or `false`) and the type of the single parameter. The return type is not part of a unary operator’s signature, nor is the name of the parameter. +The signature of a unary operator consists of the operator token (`+`, `-`, `!`, `~`, `true`, or `false`) and the type of the single parameter. The return type is not part of a unary operator’s signature, nor is the name of the parameter. The `true` and `false` unary operators require pair-wise declaration. A compile-time error occurs if a class declares one of these operators without also declaring the other. The `true` and `false` operators are described further in [§12.27](expressions.md#1227-boolean-expressions). -> *Note*: A unary `++`, `--`, or `-` operator may have a checked form (see [§15.10.1](classes.md#15101-general)). *end note* +> *Note*: A unary `-` operator may have a checked form (see [§15.10.1](classes.md#15101-general)). *end note* -> *Example*: The following example shows an implementation and subsequent usage of operator++ for an integer vector class: +> *Example*: The following example shows an implementation of operator- for an integer scalar class: > -> +> > ```csharp -> public class IntVector -> { -> public IntVector(int length) {...} -> public int Length { get { ... } } // Read-only property -> public int this[int index] { get { ... } set { ... } } // Read-write indexer -> -> public static IntVector operator++(IntVector iv) -> { -> IntVector temp = new IntVector(iv.Length); -> for (int i = 0; i < iv.Length; i++) -> { -> temp[i] = iv[i] + 1; -> } -> return temp; -> } -> } -> -> class Test +> public class MyNumber > { -> static void Main() +> private int val; +> public MyNumber(int val = 0) > { -> IntVector iv1 = new IntVector(4); // Vector of 4 x 0 -> IntVector iv2; -> iv2 = iv1++; // iv2 contains 4 x 0, iv1 contains 4 x 1 -> iv2 = ++iv1; // iv2 contains 4 x 2, iv1 contains 4 x 2 +> this.val = val; > } +> public static MyNumber operator-(MyNumber x) => new MyNumber(-x.val); > } > ``` > -> Note how the operator method returns the value produced by adding 1 to the operand, just like the postfix increment and decrement operators ([§12.8.16](expressions.md#12816-postfix-increment-and-decrement-operators)), and the prefix increment and decrement operators ([§12.9.7](expressions.md#1297-prefix-increment-and-decrement-operators)). Unlike in C++, this method should not modify the value of its operand directly as this would violate the standard semantics of the postfix increment operator ([§12.8.16](expressions.md#12816-postfix-increment-and-decrement-operators)). -> > *end example* ### 15.10.3 Binary operators The following rules apply to binary operator declarations, where `T` denotes the instance type of the class or struct that contains the operator declaration: +- *operator_declaration* shall include a `static` modifier and shall not include an `override` modifier. - A binary non-shift operator shall take two parameters, at least one of which shall have type `T` or `T?`, and can return any type. - A binary `<<`, `>>`, or `>>>` operator ([§12.14](expressions.md#1214-shift-operators)) shall take two parameters, the first of which shall have type `T` or `T?`, and can return any type. @@ -5436,6 +5452,8 @@ Certain binary operators require pair-wise declaration. For every declaration of ### 15.10.4 Conversion operators +*operator_declaration* shall include a `static` modifier and shall not include an `override` modifier. + A conversion operator declaration introduces a ***user-defined conversion*** ([§10.5](conversions.md#105-user-defined-conversions)), which augments the pre-defined implicit and explicit conversions. A conversion operator declaration that includes the `implicit` keyword introduces a user-defined implicit conversion. Implicit conversions can occur in a variety of situations, including function member invocations, cast expressions, and assignments. This is described further in [§10.2](conversions.md#102-implicit-conversions). @@ -5566,6 +5584,88 @@ The signature of a conversion operator consists of the source type and the targe > > *end example* +### §increment-operators Increment operators + +The following rules apply to static increment operator declarations, where `T` denotes the instance type of the class or struct that contains the operator declaration: + +- *operator_declaration* shall include a `static` modifier and shall not include an `override` modifier. +- An operator shall take a single parameter of type `T` or `T?` and shall return that same type or a type derived from it. + +The signature of a static increment operator consists of the operator tokens ('checked'? `++`, 'checked'? `--`) and the type of the single parameter. The return type is not part of a static increment operator’s signature, nor is the name of the parameter. + +The following rules apply to instance increment operator declarations: + +- *operator_declaration* shall not include a `static` modifier. +- An operator shall take no parameters. +- An operator shall have `void` return type. + +Effectively, an instance increment operator is a void-returning instance method that has no parameters. + +The signature of an instance increment operator consists of the operator tokens ('checked'? '++' | 'checked'? '--'). + +A checked operator declaration requires a pair-wise declaration of an unchecked operator. A compile-time error occurs otherwise. + +The purpose of the method is to adjust the value of the instance to the result of the requested increment operation, whatever that means in context of the declaring type. + +> *Example*: The following example shows an implementation of operator++ for an integer scalar class: +> +> +> ```csharp +> public class MyNumber +> { +> private int val; +> public MyNumber(int val = 0) +> { +> this.val = val; +> } +> public void operator++() +> { +> ++val; +> } +> } +> ``` +> +> *end example* + +An instance increment operator can override an operator with the same signature declared in a base class. + +### §compound-assignment-operators Compound assignment operators + +The following rules apply to compound assignment operator declarations: + +- An operator declaration shall not include a `static` modifier. +- An operator shall take one parameter. +- An operator shall have `void` return type. + +Effectively, a compound assignment operator is a `void`-returning instance method that takes one parameter. + +The signature of a compound assignment operator consists of the operator tokens +(`'checked'? '+='`, `'checked'? '-='`, `'checked'? '*='`, `'checked'? '/='`, `'%='`, `'&='`, `'|='`, `'^='`, `'<<='`, *right_shift_assignment*, *unsigned_right_shift_assignment*) and the type of the single parameter. The name of the parameter is not part of the signature. + +A checked-operator declaration requires a pair-wise declaration of a regular operator. A compile-time error occurs otherwise. + +> *Example*: The following example shows an implementation of operator+= for an integer scalar class: +> +> +> ```csharp +> public class MyNumber +> { +> private int val; +> public MyNumber(int val = 0) +> { +> this.val = val; +> } +> public void operator+=(int x) +> { +> val += x; +> } +> } +> ``` +> +> *end example* + +A compound assignment operator can override an operator with the same signature declared in a base class. + ## 15.11 Instance constructors ### 15.11.1 General From 32132533cef8c6980490e47ff3d0fa37b5bbd624 Mon Sep 17 00:00:00 2001 From: Rex Jaeschke Date: Sun, 1 Nov 2026 13:23:02 -0500 Subject: [PATCH 3/7] add support for User-Defined Compound Assignment Operators Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 361b9a77-2b4c-45e6-969f-e6785c47f27e --- standard/documentation-comments.md | 59 +++++++++++++++++++++++++++++- 1 file changed, 57 insertions(+), 2 deletions(-) diff --git a/standard/documentation-comments.md b/standard/documentation-comments.md index 11239f2f6..053675190 100644 --- a/standard/documentation-comments.md +++ b/standard/documentation-comments.md @@ -963,7 +963,7 @@ IDs: "M:Acme.Widget.op_UnaryPlus(Acme.Widget)" ``` -The complete set of unary operator function names used is as follows: `op_UnaryPlus`, `op_UnaryNegation`, `op_CheckedUnaryNegation`, `op_LogicalNot`, `op_OnesComplement`, `op_Increment`, `op_CheckedIncrement`, `op_Decrement`, `op_CheckedDecrement`, `op_True`, and `op_False`. +The complete set of unary operator function names used is as follows: `op_UnaryPlus`, `op_UnaryNegation`, `op_CheckedUnaryNegation`, `op_LogicalNot`, `op_OnesComplement`, `op_True`, and `op_False`. **Binary operators** @@ -986,7 +986,9 @@ IDs: The complete set of binary operator function names used is as follows: `op_Addition`, `op_CheckedAddition`, `op_Subtraction`, `op_CheckedSubtraction`, `op_Multiply`, `op_CheckedMultiply`, `op_Division`, `op_CheckedDivision`, `op_Modulus`, `op_BitwiseAnd`, `op_BitwiseOr`, `op_ExclusiveOr`, `op_LeftShift`, `op_RightShift`, `op_UnsignedRightShift`, `op_Equality`, `op_Inequality`, `op_LessThan`, `op_LessThanOrEqual`, `op_GreaterThan`, and `op_GreaterThanOrEqual`. -**Conversion operators** have a trailing “`~`” followed by the return type. When either the source or destination of a conversion operator is a generic type, the “`<`” and “`">`” characters are replaced by the “`{`” and “`}`” characters, respectively. +**Conversion operators** + +These have a trailing “`~`” followed by the return type. When either the source or destination of a conversion operator is a generic type, the “`<`” and “`">`” characters are replaced by the “`{`” and “`}`” characters, respectively. The complete set of conversion operator function names used is as follows: `op_Explicit`, `op_CheckedExplicit`, and `op_Implicit`. @@ -1009,6 +1011,59 @@ IDs: "M:Acme.Widget.op_Implicit(Acme.Widget)~System.Int64" ``` +**Increment operators** + + +```csharp +namespace Acme +{ + class Widget + { + public void operator ++() + { + ... + } + public static Widget operator ++(Widget n) + { + ... + } + } +} +``` + +IDs: + +```console +"M:Acme.Widget.op_IncrementAssignment" +"M:Acme.Widget.op_Increment(Acme.Widget)" +``` + +The complete set of increment operator function names used is as follows: `op_CheckedDecrement`, `op_CheckedDecrementAssignment`, `op_CheckedIncrement`, `op_CheckedIncrementAssignment`, `op_Decrement`, `op_DecrementAssignment`, `op_Increment`, and `op_IncrementAssignment`. + +**Compound assignment operators** + + +```csharp +namespace Acme +{ + class Widget + { + public void operator +=(int x) + { + ... + } + } +} +``` + +IDs: + +```console +"M:Acme.Widget.op_AdditionAssignment(System.Int32)" +``` + +The complete set of increment operator function names used is as follows: `op_AdditionAssignment`, `op_BitwiseAndAssignment`, `op_BitwiseOrAssignment`, `op_CheckedAdditionAssignment`, `op_CheckedDivisionAssignment`, `op_CheckedMultiplicationAssignment`, `op_CheckedSubtractionAssignment`, `op_DivisionAssignment`, `op_ExclusiveOrAssignment`, `op_LeftShiftAssignment`, `op_ModulusAssignment`, `op_MultiplicationAssignment`, `op_RightShiftAssignment`, `op_SubtractionAssignment`, and `op_UnsignedRightShiftAssignment`. + ## D.5 An example ### D.5.1 C\# source code From 2ff192dd8ad244f247ae3e205ad6198ccd90e359 Mon Sep 17 00:00:00 2001 From: Rex Jaeschke Date: Sun, 1 Nov 2026 13:39:59 -0500 Subject: [PATCH 4/7] fix formatting Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 361b9a77-2b4c-45e6-969f-e6785c47f27e --- standard/classes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/standard/classes.md b/standard/classes.md index 91af99e04..5663e669d 100644 --- a/standard/classes.md +++ b/standard/classes.md @@ -1601,7 +1601,7 @@ The following method names are reserved. While many have corresponding operators | `op_BitwiseAnd` | `&` (binary) | | `op_BitwiseAndAssignment` | `&=` | | `op_BitwiseOr` | `\|` | -| `op_BitwiseOrAssignment` | `|=` | +| `op_BitwiseOrAssignment` | `\|=` | | `op_CheckedAddition` | checked addition `+` | | `op_CheckedAdditionAssignment` | checked `+=` | | `op_CheckedDecrement` | static checked decrement `--` | @@ -5365,7 +5365,7 @@ operator_body *Note*: The prefix logical negation ([§12.9.4](expressions.md#1294-logical-negation-operator)) and postfix null-forgiving operators ([§12.8.9](expressions.md#1289-null-forgiving-expressions)), while represented by the same lexical token (`!`), are distinct. The latter is not an overloadable operator. *end note* -The following categories of overloadable operators exist: unary operators ([§15.10.2](classes.md#15102-unary-operators)), binary operators ([§15.10.3](classes.md#15103-binary-operators)), conversion operators ([§15.10.4](classes.md#15104-conversion-operators)), increment operators [§increment-operators), and compound assignment operators [§compound-assignment-operators). +The following categories of overloadable operators exist: unary operators ([§15.10.2](classes.md#15102-unary-operators)), binary operators ([§15.10.3](classes.md#15103-binary-operators)), conversion operators ([§15.10.4](classes.md#15104-conversion-operators)), increment operators (§increment-operators), and compound assignment operators (§compound-assignment-operators). The *operator_body* is either a semicolon, a block body ([§15.6.1](classes.md#1561-general)) or an expression body ([§15.6.1](classes.md#1561-general)). A block body consists of a *block*, which specifies the statements to execute when the operator is invoked. The *block* shall conform to the rules for value-returning methods described in [§15.6.11](classes.md#15611-method-body). An expression body consists of `=>` followed by an expression and a semicolon, and denotes a single expression to perform when the operator is invoked. @@ -5603,7 +5603,7 @@ Effectively, an instance increment operator is a void-returning instance method The signature of an instance increment operator consists of the operator tokens ('checked'? '++' | 'checked'? '--'). -A checked operator declaration requires a pair-wise declaration of an unchecked operator. A compile-time error occurs otherwise. +A checked operator declaration requires a pair-wise declaration of an unchecked operator. A compile-time error occurs otherwise. The purpose of the method is to adjust the value of the instance to the result of the requested increment operation, whatever that means in context of the declaring type. From 0c38b6908d1ed44ef79f2cc593358ce8f41fb298 Mon Sep 17 00:00:00 2001 From: Rex Jaeschke Date: Sun, 1 Nov 2026 13:46:39 -0500 Subject: [PATCH 5/7] fix example Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 361b9a77-2b4c-45e6-969f-e6785c47f27e --- standard/classes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standard/classes.md b/standard/classes.md index 5663e669d..355cd6116 100644 --- a/standard/classes.md +++ b/standard/classes.md @@ -5417,7 +5417,7 @@ The `true` and `false` unary operators require pair-wise declaration. A compile- > *Example*: The following example shows an implementation of operator- for an integer scalar class: > -> +> > ```csharp > public class MyNumber > { From 0e65ac943664ac5ea1cbaf8e7abe503c028c69e9 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 13 Nov 2026 11:50:29 -0500 Subject: [PATCH 6/7] Remove compound-assignment source trailing whitespace Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 361b9a77-2b4c-45e6-969f-e6785c47f27e --- standard/classes.md | 6 +++--- standard/expressions.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/standard/classes.md b/standard/classes.md index 355cd6116..259371b76 100644 --- a/standard/classes.md +++ b/standard/classes.md @@ -5424,7 +5424,7 @@ The `true` and `false` unary operators require pair-wise declaration. A compile- > private int val; > public MyNumber(int val = 0) > { -> this.val = val; +> this.val = val; > } > public static MyNumber operator-(MyNumber x) => new MyNumber(-x.val); > } @@ -5616,7 +5616,7 @@ The purpose of the method is to adjust the value of the instance to the result o > private int val; > public MyNumber(int val = 0) > { -> this.val = val; +> this.val = val; > } > public void operator++() > { @@ -5653,7 +5653,7 @@ A checked-operator declaration requires a pair-wise declaration of a regular ope > private int val; > public MyNumber(int val = 0) > { -> this.val = val; +> this.val = val; > } > public void operator+=(int x) > { diff --git a/standard/expressions.md b/standard/expressions.md index 66fa45c6d..f30637e70 100644 --- a/standard/expressions.md +++ b/standard/expressions.md @@ -4443,7 +4443,7 @@ Otherwise, `«op»x` is evaluated as follows: - If the result of increment is used, `x` is evaluated to get an instance `x₀`, the operator method is invoked on that instance, `x₀` is assigned to `x`, and `x₀` is returned as the result of the assignment. - Otherwise, the operator method is invoked on `x`. - + Side effects in `x` are evaluated only once in the process. ### 12.9.8 Cast expressions @@ -8204,7 +8204,7 @@ If the type of `x` is not known to be a reference type: - If the result of compound assignment is used, the `x` is evaluated to get an instance `x₀`, the operator method is invoked on that instance with `y` as the argument, `x₀` is assigned to `x` and `x₀` is returned as the result of the compound assignment. - Otherwise, the operator method is invoked on `x` with `y` as the argument. - + Side effects in `x` are evaluated only once in the process. #### §CompAssignOpOver Compound assignment operator overload resolution From 71bc65f2bcaf7c13be1791ba17244def8ea14e3e Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 20 Nov 2026 11:39:50 -0500 Subject: [PATCH 7/7] Apply approved D4/D5 standard corrections (#1851) Exact wording approved by Bill Wagner; local-only follow-on to frozen PR head. No PR approval or merge implied. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 3d3d2f48-d9e2-4c14-bdba-64027dda65b2 --- standard/classes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/standard/classes.md b/standard/classes.md index 259371b76..4aba78407 100644 --- a/standard/classes.md +++ b/standard/classes.md @@ -1609,14 +1609,14 @@ The following method names are reserved. While many have corresponding operators | `op_CheckedDivision` | checked division `/` | | `op_CheckedExplicit` | checked explicit (narrowing) coercion | | `op_CheckedIncrement` | static checked increment `++` | -| `op_CheckedIncrementAssignment` | instance checked decrement `--` | +| `op_CheckedIncrementAssignment` | instance checked increment `++` | | `op_CheckedMultiply` | checked multiply `*` | | `op_CheckedSubtraction` | checked subtraction `-` | | `op_CheckedSubtractionAssignment` | checked `-=` | | `op_CheckedUnaryNegation` | checked unary negation `-` | | `op_Comma` | (reserved) | | `op_Decrement` | static `--` | -| `op_DecrementAssignment` | instance `++` | +| `op_DecrementAssignment` | instance `--` | | `op_Division` | `/` | | `op_DivisionAssignment` | `/=` | | `op_CheckedDivisionAssignment` | checked `/=` | @@ -5367,7 +5367,7 @@ operator_body The following categories of overloadable operators exist: unary operators ([§15.10.2](classes.md#15102-unary-operators)), binary operators ([§15.10.3](classes.md#15103-binary-operators)), conversion operators ([§15.10.4](classes.md#15104-conversion-operators)), increment operators (§increment-operators), and compound assignment operators (§compound-assignment-operators). -The *operator_body* is either a semicolon, a block body ([§15.6.1](classes.md#1561-general)) or an expression body ([§15.6.1](classes.md#1561-general)). A block body consists of a *block*, which specifies the statements to execute when the operator is invoked. The *block* shall conform to the rules for value-returning methods described in [§15.6.11](classes.md#15611-method-body). An expression body consists of `=>` followed by an expression and a semicolon, and denotes a single expression to perform when the operator is invoked. +The *operator_body* is either a semicolon, a block body ([§15.6.1](classes.md#1561-general)) or an expression body ([§15.6.1](classes.md#1561-general)). A block body consists of a *block*, which specifies the statements to execute when the operator is invoked. The *block* shall conform to the rules for `void` methods when the operator’s return type is `void`, and to the rules for value-returning methods otherwise, as described in [§15.6.11](classes.md#15611-method-body). An expression body consists of `=>` followed by an expression and a semicolon, and denotes a single expression to perform when the operator is invoked. For `extern` operators, the *operator_body* consists simply of a semicolon. For an abstract operator declaration in an interface ([§19.4.7](interfaces.md#1947-interface-operators)), the *operator_body* is a semicolon. For all other operators, the *operator_body* is either a block body or an expression body.