Moved and revised the is operator article (#23884)

* Moved and revised the is operator article

* Apply suggestions from code review

Co-authored-by: Genevieve Warren <[email protected]>

* Update docs/csharp/language-reference/operators/type-testing-and-cast.md

Co-authored-by: Bill Wagner <[email protected]>

Co-authored-by: Genevieve Warren <[email protected]>
Co-authored-by: Bill Wagner <[email protected]>

Author: 3 people

.openpublishing.redirection.json

@@ -1282,6 +1282,10 @@
             "source_path": "docs/csharp/language-reference/keywords/interpolated-strings.md",
             "redirect_url": "/dotnet/csharp/language-reference/tokens/interpolated"
         },
+        {
+            "source_path": "docs/csharp/language-reference/keywords/is.md",
+            "redirect_url": "/dotnet/csharp/language-reference/operators/is"
+        },
         {
             "source_path": "docs/csharp/language-reference/keywords/iteration-statements.md",
             "redirect_url": "/dotnet/csharp/language-reference/keywords/statement-keywords"

docs/csharp/discards.md

@@ -79,5 +79,5 @@ Without assigning the task to a discard, the following code generates a compiler
 ## See also
 
 - [Deconstructing tuples and other types](deconstruct.md)
-- [`is` keyword](language-reference/keywords/is.md)
+- [`is` operator](language-reference/operators/is.md)
 - [`switch` keyword](language-reference/keywords/switch.md)

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

@@ -28,7 +28,7 @@ Keywords are predefined, reserved identifiers that have special meanings to the
 |[finally](try-finally.md)|[fixed](fixed-statement.md)|[float](../builtin-types/floating-point-numeric-types.md)|[for](for.md)|
 |[foreach](foreach-in.md)|[goto](goto.md)|[if](if-else.md)|[implicit](../operators/user-defined-conversion-operators.md)|
 |[in](in.md)|[int](../builtin-types/integral-numeric-types.md)|[interface](interface.md)|[internal](internal.md)|
-|[is](is.md)|[lock](lock-statement.md)|[long](../builtin-types/integral-numeric-types.md)|[namespace](namespace.md)|
+|[is](../operators/is.md)|[lock](lock-statement.md)|[long](../builtin-types/integral-numeric-types.md)|[namespace](namespace.md)|
 |[new](../operators/new-operator.md)|[null](null.md)|[object](../builtin-types/reference-types.md)|[operator](../operators/operator-overloading.md)|
 |[out](out.md)|[override](override.md)|[params](params.md)|[private](private.md)|
 |[protected](protected.md)|[public](public.md)|[readonly](readonly.md)|[ref](ref.md)|

docs/csharp/language-reference/keywords/is.md

@@ -0,0 +1,55 @@
+---
+title: "is operator - C# reference"
+description: "Learn about the C# is operator that matches an expression against a pattern"
+ms.date: 04/23/2021
+f1_keywords: 
+  - "is_CSharpKeyword"
+  - "is"
+helpviewer_keywords: 
+  - "is keyword [C#]"
+ms.assetid: bc62316a-d41f-4f90-8300-c6f4f0556e43
+---
+# is operator (C# reference)
+
+In C# 6 and earlier, the `is` operator checks if the result of an expression is compatible with a given type. For information about the type-testing `is` operator, see the [is operator](type-testing-and-cast.md#is-operator) section of the [Type-testing and cast operators](type-testing-and-cast.md) article.
+
+Beginning with C# 7.0, you can also use the `is` operator to match an expression against a pattern, as the following example shows:
+
+:::code language="csharp" source="snippets/shared/IsOperator.cs" id="IntroExample":::
+
+In the preceding example, the `is` operator matches an expression against a [property pattern](patterns.md#property-pattern) with nested [constant](patterns.md#constant-pattern) and [relational](patterns.md#relational-patterns) patterns.
+
+The `is` operator can be useful in the following scenarios:
+
+- To check the run-time type of an expression, as the following example shows:
+
+  :::code language="csharp" source="snippets/shared/IsOperator.cs" id="DeclarationPattern":::
+
+  The preceding example shows the use of a [declaration pattern](patterns.md#declaration-and-type-patterns).
+
+- To check for `null`, as the following example shows:
+
+  :::code language="csharp" source="snippets/shared/IsOperator.cs" id="NullCheck":::
+
+  When you match an expression against `null`, the compiler guarantees that no user-overloaded `==` or `!=` operator is invoked.
+
+- Beginning with C# 9.0, you can use a [negation pattern](patterns.md#logical-patterns) to do a non-null check, as the following example shows:
+
+  :::code language="csharp" source="snippets/shared/IsOperator.cs" id="NonNullCheck":::
+
+For the complete list of patterns supported by the `is` operator, see [Patterns](patterns.md).
+
+## C# language specification
+
+For more information, see [The is operator](~/_csharplang/spec/expressions.md#the-is-operator) section of the [C# language specification](~/_csharplang/spec/introduction.md) and the following C# language proposals:
+
+- [Pattern matching](~/_csharplang/proposals/csharp-7.0/pattern-matching.md)
+- [Pattern matching with generics](~/_csharplang/proposals/csharp-7.1/generics-pattern-match.md)
+
+## See also
+
+- [C# reference](../index.md)
+- [C# operators and expressions](index.md)
+- [Patterns](patterns.md)
+- [Tutorial: Use pattern matching to build type-driven and data-driven algorithms](../../tutorials/pattern-matching.md)
+- [Type-testing and cast operators](../operators/type-testing-and-cast.md)

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

@@ -16,7 +16,7 @@ helpviewer_keywords:
 
 C# introduced pattern matching in C# 7.0. Since then, each major C# version extends pattern matching capabilities. The following C# expressions and statements support pattern matching:
 
-- [`is` expression](../keywords/is.md)
+- [`is` expression](is.md)
 - `switch` [statement](../keywords/switch.md)
 - `switch` [expression](switch-expression.md) (introduced in C# 8.0)
 

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

@@ -0,0 +1,49 @@
+using System;
+
+namespace operators
+{
+    public static class IsOperator
+    {
+        public static void Examples()
+        {
+            DeclarationPattern();
+        }
+
+        // <IntroExample>
+        static bool IsFirstSummerMonday(DateTime date) => date is { Month: 6, Day: <=7, DayOfWeek: DayOfWeek.Monday };
+        // </IntroExample>
+
+        private static void DeclarationPattern()
+        {
+            // <DeclarationPattern>
+            int i = 34;
+            object iBoxed = i;
+            int? jNullable = 42;
+            if (iBoxed is int a && jNullable is int b)
+            {
+                Console.WriteLine(a + b);  // output 76
+            }
+            // </DeclarationPattern>
+        }
+
+        private static void NullCheck(object input)
+        {
+            // <NullCheck>
+            if (input is null)
+            {
+                return;
+            }
+            // </NullCheck>
+        }
+
+        private static void NonNullCheck(object result)
+        {
+            // <NonNullCheck>
+            if (result is not null)
+            {
+                Console.WriteLine(result.ToString());
+            }
+            // </NonNullCheck>
+        }
+    }
+}

docs/csharp/language-reference/operators/snippets/shared/IsOperator.cs

@@ -111,6 +111,9 @@ static async Task Main(string[] args)
             SwitchExpressions.Examples();
             Console.WriteLine();
 
+            Console.WriteLine("============= is operator example ==============");
+            IsOperator.Examples();
+            Console.WriteLine();
         }
     }
 }

docs/csharp/language-reference/operators/snippets/shared/Program.cs

@@ -42,9 +42,19 @@ E is T
 
 where `E` is an expression that returns a value and `T` is the name of a type or a type parameter. `E` cannot be an anonymous method or a lambda expression.
 
-The `E is T` expression returns `true` if the result of `E` is non-null and can be converted to type `T` by a reference conversion, a boxing conversion, or an unboxing conversion; otherwise, it returns `false`. The `is` operator doesn't consider user-defined conversions.
+The `is` operator returns `true` when an expression result is non-null and any of the following conditions are true:
 
-The following example demonstrates that the `is` operator returns `true` if the runtime type of an expression result derives from a given type, that is, there exists a reference conversion between types:
+- The run-time type of an expression result is `T`.
+
+- The run-time type of an expression result derives from type `T`, implements interface `T`, or another [implicit reference conversion](~/_csharplang/spec/conversions.md#implicit-reference-conversions) exists from it to `T`.
+
+- The run-time type of an expression result is a [nullable value type](../builtin-types/nullable-value-types.md) with the underlying type `T` and the <xref:System.Nullable%601.HasValue?displayProperty=nameWithType> is `true`.
+
+- A [boxing](../../programming-guide/types/boxing-and-unboxing.md#boxing) or [unboxing](../../programming-guide/types/boxing-and-unboxing.md#unboxing) conversion exists from the run-time type of an expression result to type `T`.
+
+The `is` operator doesn't consider user-defined conversions.
+
+The following example demonstrates that the `is` operator returns `true` if the run-time type of an expression result derives from a given type, that is, there exists a reference conversion between types:
 
 [!code-csharp[is with reference conversion](snippets/shared/TypeTestingAndConversionOperators.cs#IsWithReferenceConversion)]
 

docs/csharp/language-reference/operators/type-testing-and-cast.md

@@ -1108,10 +1108,6 @@ items:
           href: language-reference/keywords/using-statement.md
       - name: extern alias
         href: language-reference/keywords/extern-alias.md
-    - name: Type-testing Keywords
-      items:
-        - name: is
-          href: language-reference/keywords/is.md
     - name: Generic Type Constraint Keywords
       items:
         - name: new constraint
@@ -1261,6 +1257,9 @@ items:
     - name: delegate operator
       href: language-reference/operators/delegate-operator.md
       displayName: anonymous
+    - name: is operator
+      href: language-reference/operators/is.md
+      displayName: pattern matching
     - name: nameof expression
       href: language-reference/operators/nameof.md
       displayName: nameof operator
@@ -1274,7 +1273,7 @@ items:
       displayName: stack allocation, span, stackalloc operator
     - name: switch expression
       href: language-reference/operators/switch-expression.md
-      displayName: "switch, pattern matching, patterns"
+      displayName: pattern matching, patterns
     - name: true and false operators
       href: language-reference/operators/true-false-operators.md
     - name: with expression

docs/csharp/toc.yml

@@ -100,7 +100,7 @@ Discards are supported in the following scenarios:
 
 - When deconstructing tuples or user-defined types.
 - When calling methods with [out](../language-reference/keywords/out-parameter-modifier.md) parameters.
-- In a pattern matching operation with the [is](../language-reference/keywords/is.md) and [switch](../language-reference/keywords/switch.md) statements.
+- In a pattern matching operation with the [is](../language-reference/operators/is.md) and [switch](../language-reference/keywords/switch.md) statements.
 - As a standalone identifier when you want to explicitly identify the value of an assignment as a discard.
 
 The following example defines a `QueryCityDataForYears` method that returns a 6-tuple that contains data for a city for two different years. The method call in the example is concerned only with the two population values returned by the method and so treats the remaining values in the tuple as discards when it deconstructs the tuple.
@@ -115,7 +115,7 @@ For more information, see [Discards](../discards.md).
 
 Pattern matching supports `is` expressions and `switch` expressions. Each enables inspecting an object and its properties to determine if that object satisfies the sought pattern. You use the `when` keyword to specify additional rules to the pattern.
 
-The `is` pattern expression extends the familiar [`is` operator](../language-reference/keywords/is.md#pattern-matching-with-is) to query an object about its type and assign the result in one instruction. The following code checks if a variable is an `int`, and if so, adds it to the current sum:
+The `is` pattern expression extends the familiar [`is` operator](../language-reference/operators/is.md) to query an object about its type and assign the result in one instruction. The following code checks if a variable is an `int`, and if so, adds it to the current sum:
 
 ```csharp
 if (input is int count)