Revised and merged the subtraction operator articles (#12541)

* Revised and merged the subtraction operator articles

* Fix section link

Author: pkulikov

.openpublishing.redirection.json

@@ -594,6 +594,10 @@
             "source_path": "docs/csharp/language-reference/operators/right-shift-operator.md",
             "redirect_url": "/dotnet/csharp/language-reference/operators/bitwise-and-shift-operators#right-shift-operator-"
         },
+        {
+            "source_path": "docs/csharp/language-reference/operators/subtraction-assignment-operator.md",
+            "redirect_url": "/dotnet/csharp/language-reference/operators/arithmetic-operators#compound-assignment"
+        },
         {
             "source_path": "docs/csharp/language-reference/operators/xor-assignment-operator.md",
             "redirect_url": "/dotnet/csharp/language-reference/operators/boolean-logical-operators#compound-assignment"

docs/csharp/language-reference/operators/addition-operator.md

@@ -33,7 +33,7 @@ Starting with C# 6, [string interpolation](../tokens/interpolated.md) provides a
 
 ## Delegate combination
 
-For [delegate](../keywords/delegate.md) types, the `+` operator returns a new delegate instance that, when invoked, invokes the first operand and then invokes the second operand. If any of the operands is `null`, the `+` operator returns the value of another operand (which also might be `null`). The following example shows how delegates can be combined with the `+` operator:
+For operands of the same [delegate](../keywords/delegate.md) type, the `+` operator returns a new delegate instance that, when invoked, invokes the first operand and then invokes the second operand. If any of the operands is `null`, the `+` operator returns the value of another operand (which also might be `null`). The following example shows how delegates can be combined with the `+` operator:
 
 [!code-csharp-interactive[delegate combination](~/samples/snippets/csharp/language-reference/operators/AdditionExamples.cs#AddDelegates)]
 
@@ -80,3 +80,4 @@ For more information, see the [Unary plus operator](~/_csharplang/spec/expressio
 - [Events](../../programming-guide/events/index.md)
 - [Checked and unchecked](../keywords/checked-and-unchecked.md)
 - [Arithmetic operators](arithmetic-operators.md)
+- [- and -= operators](subtraction-operator.md)

docs/csharp/language-reference/operators/index.md

@@ -193,7 +193,7 @@ These operators have higher precedence than the next section and lower precedenc
 
 [x += y](arithmetic-operators.md#compound-assignment) – increment. Add the value of `y` to the value of `x`, store the result in `x`, and return the new value. If `x` designates an [event](../keywords/event.md), then `y` must be an appropriate method that C# adds as an event handler.
 
-[x -= y](subtraction-assignment-operator.md) – decrement. Subtract the value of `y` from the value of `x`, store the result in `x`, and return the new value. If `x` designates an [event](../keywords/event.md), then `y` must be an appropriate method that C# removes as an event handler.
+[x -= y](arithmetic-operators.md#compound-assignment) – decrement. Subtract the value of `y` from the value of `x`, store the result in `x`, and return the new value. If `x` designates an [event](../keywords/event.md), then `y` must be an appropriate method that C# removes as an event handler.
 
 [x *= y](arithmetic-operators.md#compound-assignment) – multiplication assignment. Multiply the value of `y` to the value of `x`, store the result in `x`, and return the new value.
 

docs/csharp/language-reference/operators/subtraction-assignment-operator.md

@@ -1,35 +1,74 @@
 ---
-title: "- operator - C# Reference"
+title: "- and -= operators - C# Reference"
 ms.custom: seodec18
-
-ms.date: 07/20/2015
+ms.date: 05/27/2019
 f1_keywords: 
   - "-_CSharpKeyword"
+  - "-=_CSharpKeyword"
 helpviewer_keywords: 
+  - "subtraction operator [C#]"
+  - "delegate removal [C#]"
   - "- operator [C#]"
-  - "subtraction operator (-) [C#]"
+  - "subtraction assignment operator [C#]"
+  - "event unsubscription [C#]"
+  - "-= operator [C#]"
 ms.assetid: 4de7a4fa-c69d-48e6-aff1-3130af970b2d
 ---
-# - operator (C# Reference)
+# - and -= operators (C# Reference)
+
+The `-` operator is supported by the built-in numeric types and [delegate](../keywords/delegate.md) types.
+
+For information about the arithmetic `-` operator, see the [Unary plus and minus operators](arithmetic-operators.md#unary-plus-and-minus-operators) and [Subtraction operator -](arithmetic-operators.md#subtraction-operator--) sections of the [Arithmetic operators](arithmetic-operators.md) article.
+
+## Delegate removal
+
+For operands of the same [delegate](../keywords/delegate.md) type, the `-` operator returns a delegate instance that is calculated as follows:
+
+- If both operands are non-null and the invocation list of the second operand is a proper contiguous sublist of the invocation list of the first operand, the result of the operation is a new invocation list that is obtained by removing the second operand's entries from the invocation list of the first operand. If the second operand's list matches multiple contiguous sublists in the first operand's list, only the right-most matching sublist is removed. If removal results in an empty list, the result is `null`.
+- If the invocation list of the second operand is not a proper contiguous sublist of the invocation list of the first operand, the result of the operation is the first operand.
+- If the first operand is `null`, the result of the operation is `null`. If the second operand is `null`, the result of the operation is the first operand.
+
+The following example shows how the `-` operation performs delegate removal:
+
+[!code-csharp-interactive[delegate removal](~/samples/csharp/language-reference/operators/SubtractionOperator.cs#DelegateRemoval)]
+
+## Subtraction assignment operator -=
+
+An expression using the `-=` operator, such as
+
+```csharp
+x -= y
+```
+
+is equivalent to
 
-The `-` operator can function as either a unary or a binary operator.
+```csharp
+x = x - y
+```
 
-## Remarks
+except that `x` is only evaluated once.
+  
+The following example demonstrates the usage of the `-=` operator:
 
-Unary `-` operators are predefined for all numeric types. The result of a unary `-` operation on a numeric type is the numeric negation of the operand.
+[!code-csharp-interactive[-= examples](~/samples/csharp/language-reference/operators/SubtractionOperator.cs#SubtractAndAssign)]
 
-Binary `-` operators are predefined for all numeric and enumeration types to subtract the second operand from the first.
+You also use the `-=` operator to specify an event handler method to remove when you unsubscribe from an [event](../keywords/event.md). For more information, see [How to: subscribe to and unsubscribe from events](../../programming-guide/events/how-to-subscribe-to-and-unsubscribe-from-events.md).
 
-Delegate types also provide a binary `-` operator, which performs delegate removal.
+## Operator overloadability
 
-User-defined types can overload the unary `-` and binary `-` operators. For more information, see [operator keyword](../keywords/operator.md).
+A user-defined type can [overload](../keywords/operator.md) the `-` operator. When a binary `-` operator is overloaded, the `-=` operator is also implicitly overloaded. A user-defined type cannot explicitly overload the `-=` operator.
 
-## Example
+## C# language specification
 
-[!code-csharp[csRefOperators#40](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csrefOperators/CS/csrefOperators.cs#40)]
+For more information, see the [Unary minus operator](~/_csharplang/spec/expressions.md#unary-minus-operator) and [Subtraction operator](~/_csharplang/spec/expressions.md#subtraction-operator) sections of the [C# language specification](../language-specification/index.md).
 
 ## See also
 
 - [C# Reference](../index.md)
 - [C# Programming Guide](../../programming-guide/index.md)
-- [C# operators](index.md)
+- [C# Operators](index.md)
+- [Delegates](../../programming-guide/delegates/index.md)
+- [Events](../../programming-guide/events/index.md)
+- [Checked and unchecked](../keywords/checked-and-unchecked.md)
+- [Arithmetic operators](arithmetic-operators.md)
+- [+ and += operators](addition-operator.md)

docs/csharp/language-reference/operators/subtraction-operator.md

@@ -29,14 +29,13 @@
   - name: + and += operators
     href: addition-operator.md
     displayName: string concatenation, delegate combination, event subscription
-  - name: "- operator"
+  - name: "- and -= operators"
     href: subtraction-operator.md
+    displayName: delegate removal, event unsubscription
   - name: = operator
     href: assignment-operator.md
   - name: "?: operator"
     href: conditional-operator.md
-  - name: -= operator
-    href: subtraction-assignment-operator.md
   - name: "?? operator"
     href: null-coalescing-operator.md
   - name: => operator

docs/csharp/language-reference/operators/toc.yml

@@ -98,5 +98,5 @@ You subscribe to an event that is published by another class when you want to wr
 - [Events](../../../csharp/programming-guide/events/index.md)
 - [event](../../../csharp/language-reference/keywords/event.md)
 - [How to: Publish Events that Conform to .NET Framework Guidelines](../../../csharp/programming-guide/events/how-to-publish-events-that-conform-to-net-framework-guidelines.md)
-- [-= Operator (C# Reference)](../../language-reference/operators/subtraction-assignment-operator.md)
+- [- and -= operators](../../language-reference/operators/subtraction-operator.md)
 - [+ and += operators](../../language-reference/operators/addition-operator.md)

docs/csharp/programming-guide/events/how-to-subscribe-to-and-unsubscribe-from-events.md

@@ -60,7 +60,7 @@ Common tasks in application development are adding controls to and removing cont
 
 ### To remove controls from a collection programmatically  
 
-1. Remove the event handler from the event. In Visual Basic, use the [RemoveHandler Statement](~/docs/visual-basic/language-reference/statements/removehandler-statement.md) keyword; in Visual C#, use the [-= Operator (C# Reference)](~/docs/csharp/language-reference/operators/subtraction-assignment-operator.md).  
+1. Remove the event handler from the event. In Visual Basic, use the [RemoveHandler Statement](~/docs/visual-basic/language-reference/statements/removehandler-statement.md) keyword; in C#, use the [-= operator](~/docs/csharp/language-reference/operators/subtraction-operator.md).  
 
 2. Use the `Remove` method to delete the desired control from the panel's `Controls` collection.