C# deconstruct and discards topics (dotnet#2737)

* First commit for deconstruction/discards

* Wrote more

* Interim commit

* Finished writing discards topic

* Updated TOC

* Updated what's new topic

* Incorporated feedback

* Corrected bad code link

* Fixed broekn link

Author: Ron Petrusha

docs/csharp/deconstruct.md

@@ -0,0 +1,104 @@
+---
+title: Deconstructing tuples and other types | Microsoft Docs
+description: Learn how to deconstruct tuples and other types
+keywords: .NET, .NET Core, C#0
+author: rpetrusha
+ms-author: ronpet
+ms.date: 07/18/2016
+ms.topic: article
+ms.prod: .net
+ms.technology: devlang-csharp
+ms.devlang: csharp
+ms.assetid: 0b0c4b0f-4a47-4f66-9b8e-f5c63b195960
+---
+
+# Deconstructing tuples and other types #
+
+A tuple provides a light-weight way to retrieve multiple values from a method call. But once you retrieve the tuple, you have to handle its individual elements. Doing this on an element-by-element basis is cumbersome, as the following example shows. The `QueryCityData` method returns a 3-tuple, and each of its elements is assigned to a variable in a separate operation.
+
+[!code-csharp[WithoutDeconstruction](../../samples/snippets/csharp/programming-guide/deconstructing-tuples/deconstruct-tuple1.cs)]
+
+Retrieving multiple field and property values from an object can be equally cumbersome: you have to assign a field or property value to a variable on a member-by-member basis. 
+
+Starting with C# 7, you can retrieve multiple elements from a tuple or retrieve multiple field, property, and computed values from an object in a single *deconstruct* operation. When you deconstruct a tuple, you assign its elements to individual variables. When you deconstruct an object, you assign selected values to individual variables. 
+
+## Deconstructing a tuple
+
+C# features built-in support for deconstructing tuples, which lets you unpackage all the items in a tuple in a single operation. The general syntax for deconstructing a tuple is similar to the syntax for defining one: you enclose the variables to which each element is to be assigned in parentheses in the left side of an assignment statement. For example, the following statement assigns the elements of a 4-tuple to four separate variables:
+
+```csharp
+var (name, address, city, zip) = contact.GetAddressInfo();
+```
+
+There are two ways to deconstruct a tuple:
+
+- You can explicitly declare the type of each field inside parentheses. The following example uses this approach to deconstruct the 3-tuple returned by the `QueryCityData` method.
+
+    [!code-csharp[Deconstruction-Explicit](../../samples/snippets/csharp/programming-guide/deconstructing-tuples/deconstruct-tuple2.cs#1)]
+
+- You can use the `var` keyword so that C# infers the type of each variable. You place the `var` keyword outside of the parentheses. The following example uses type inference when deconstructing the 3-tuple returned by the `QueryCityData` method.
+ 
+      [!code-csharp[Deconstruction-Infer](../../samples/snippets/csharp/programming-guide/deconstructing-tuples/deconstruct-tuple3.cs#1)]
+
+    You can also use the `var` keyword individually with any or all of the variable declarations inside the parentheses. 
+
+      [!code-csharp[Deconstruction-Infer-Some](../../samples/snippets/csharp/programming-guide/deconstructing-tuples/deconstruct-tuple4.cs#1)]
+
+    This is cumbersome and is not recommended.
+
+Note that you cannot specify a specific type outside the parentheses even if every field in the tuple has the
+same type. This generates compiler error CS8136, "`var (...)` form disallows a specific type for `var`.
+
+Note that you must also assign each element of the tuple to a variable. If you omit any elements, the compiler generates error CS8132, "Cannot deconstruct a tuple of 'x' elements into 'y' variables."
+
+## Deconstructing tuple elements with discards
+
+Often when deconstructing a tuple, you're interested in the values of only some elements. Starting with C# 7, you can take advantage of C#'s support for *discards*, which are write-only variables whose values you've chosen to ignore. A discard is designated by an underscore character ("_") in an assignment. You can discard as many values as you like; all are represented by the single discard, `_`.
+
+The following example illustrates the use of tuples with discards. The `QueryCityDataForYears` method returns a 6-tuple with the name of a city, its area, a year, the city's population for that year, a second year, and the city's population for that second year. The example shows the change in population between those two years. Of the data available from the tuple, we're unconcerned with the city area, and we know the city name and the two dates at design-time. As a result, we're only interested in the two population values stored in the tuple, and can handle its remaining values as discards.  
+
+[!code-csharp[Tuple-discard](../../samples/snippets/csharp/programming-guide/deconstructing-tuples/discard-tuple1.cs)]
+
+### Deconstructing user-defined types
+
+Non-tuple types do not offer built-in support for discards. However, as the author of a class, a struct, or an interface, you can allow instances of the type to be deconstructed by implementing one or more `Deconstruct` methods. The method returns void, and each value to be deconstructed is indicated by an [out](language-reference/keywords/out-parameter-modifier.md) parameter in the method signature. For example, the following `Deconstruct` method of a `Person` class returns the first, middle, and last name:
+
+[!code-csharp[Class-deconstruct](../../samples/snippets/csharp/programming-guide/deconstructing-tuples/deconstruct-class1.cs#1)]
+
+You can then deconstruct an instance of the `Person` class named `p` with an assignment like the following:
+
+[!code-csharp[Class-deconstruct](../../samples/snippets/csharp/programming-guide/deconstructing-tuples/deconstruct-class1.cs#2)]
+
+The following example overloads the `Deconstruct` method to return various combinations of properties of a `Person` object. Individual overloads return:
+
+- A first and last name.
+- A first, last, and middle name.
+- A first name, a last name, a city name, and a state name.
+
+[!code-csharp[Class-deconstruct](../../samples/snippets/csharp/programming-guide/deconstructing-tuples/deconstruct-class2.cs)]
+
+Because you can overload the `Deconstruct` method to reflect groups of data that are commonly extracted from an object, you should be careful to define `Deconstruct` methods with signatures that are distinctive and unambiguous. Multiple `Deconstruct` methods that have the same number of `out` parameters or the same number and type of `out` parameters in a different order can cause confusion. 
+
+The overloaded `Deconstruct` method in the following example illustrates one possible source of confusion. The first overload returns the first name, middle name, last name, and age of a `Person` object, in that order. The second overload returns name information only along with annual income, but the first, middle, and last name are in a different order. This makes it easy to confuse the order of arguments when deconstructing a `Person` instance.
+
+[!code-csharp[Deconstruct-ambiguity](../../samples/snippets/csharp/programming-guide/deconstructing-tuples/deconstruct-ambiguous.cs)]
+
+## Deconstructing a user-defined type with discards
+
+Just as you do with [tuples](#deconstructing-tuple-elements-with-discards), you can use discards to ignore selected items returned by a `Deconstruct` method. Each discard is defined by a variable named "_", and a single deconstruction operation can include multiple discards.
+
+The following example deconstructs a `Person` object into four strings (the first and last names, the city, and the state) but discards the last name and the state.
+
+[!code-csharp[Class-discard](../../samples/snippets/csharp/programming-guide/deconstructing-tuples/class-discard1.cs#1)]
+
+## Deconstructing a user-defined type with an extension method
+
+If you didn't author a class, struct, or interface, you can still deconstruct objects of that type by implementing one or more `Deconstruct` [extension methods](programming-guide/classes-and-structs/extension-methods.md) to return the values in which you're interested. 
+
+The following example defines two `Deconstruct` extension methods for the <xref:System.Reflection.PropertyInfo?displayProperty=fullName> class. The first returns a set of values that indicate the characteristics of the property, including its type, whether it's static or instance, whether it's read-only, and whether it's indexed. The second indicates the property's accessibility. Because the accessibility of get and set accessors can differ, Boolean values indicate whether the property has separate get and set accessors and, if it does, whether they have the same accessibility. If there is only one accessor or both the get and the set accessor have the same accessibility, the `access` variable indicates the accessibility of the property as a whole. Otherwise, the accessibility of the get and set accessors are indicated by the accessaccessibility is indicated by the `getAccess` and `setAccess` variables.
+
+[!code-csharp[Extension-deconstruct](../../samples/snippets/csharp/programming-guide/deconstructing-tuples/deconstruct-extension1.cs)]
+ 
+## See also
+[Discards](discards.md)   
+[Tuples](tuples.md)  

docs/csharp/discards.md

@@ -0,0 +1,85 @@
+---
+title: Discards - C# Guide| Microsoft Docs
+description: Describes C#'s support for discards, which are unassigned, discardable variables, and the ways in which discards can be used.
+keywords: .NET,.NET Core
+author: rpetrusha
+ms.author: ronpet
+ms.date: 07/21/2017
+ms.topic: article
+ms.prod: .net
+ms.technology: devlang-csharp
+ms.devlang: csharp
+---
+# Discards - C# Guide
+
+Starting with C# 7, C# supports discards, which are temporary, dummy variables that are intentionally unused in application code. Discards are equivalent to unassigned variables; they do not have a value. Because there is only a single discard variable, and that variable may not even be allocated storage, discards can reduce memory allocations. Because they make the intent of your code clear, they enhance its readability and maintainability.
+
+You indicate that a variable is a discard by assigning it the underscore (`_`) as its name. For example, the following method call returns a 3-tuple in which the first and second values are discards:
+
+```csharp
+(var _, _, area) = city.GetCityInformation(cityName);
+```
+
+In C# 7, discards are supported in assignments in the following contexts:
+
+- Tuple and object [deconstruction](deconstruct.md).
+- Pattern matching with [is](language-reference/keywords/is.md) and [switch](language-reference/keywords/switch.md).
+- Calls to methods with `out` parameters.
+- A standalone `_` when no `_` is in scope.
+
+When `_` is a valid discard, attempting to retrieve its value or use it in an assignment operation generates compiler error CS0301, "The name '_' does not exist in the current context". This is because `_` is not assigned a value, and may not even be assigned a storage location. If it were an actual variable, you could not discard more than one value, as the previous example did.
+
+## Tuple and object deconstruction
+
+Discards are particularly useful in working with tuples when your application code uses some tuple elements but ignores others. For example, the following `QueryCityDataForYears` method returns a 6-tuple with the name of a city, its area, a year, the city's population for that year, a second year, and the city's population for that second year. The example shows the change in population between those two years. Of the data available from the tuple, we're unconcerned with the city area, and we know the city name and the two dates at design-time. As a result, we're only interested in the two population values stored in the tuple, and can handle its remaining values as discards.  
+
+[!code-csharp[Tuple-discard](../../samples/snippets/csharp/programming-guide/deconstructing-tuples/discard-tuple1.cs)]
+
+For more information on deconstructing tuples with discards, see [Deconstructing tuples and other types](deconstruct.md#deconstructing-tuple-elements-with-discards).
+
+The `Deconstruct` method of a class, structure, or interface also allows you to retrieve and deconstruct a specific set of data from an object. You can use discards when you are interested in working with only a subset of the deconstructed values. Ihe following example deconstructs a `Person` object into four strings (the first and last names, the city, and the state), but discards the last name and the state.
+
+[!code-csharp[Class-discard](../../samples/snippets/csharp/programming-guide/deconstructing-tuples/class-discard1.cs)]
+
+For more information on deconstructing user-defined types with discards, see [Deconstructing tuples and other types](deconstruct.md#deconstructing-a-user-defined type-with-discards).
+
+## Pattern matching with `switch` and `is`
+
+The *discard pattern* can be used in pattern matching with the [is](language-reference/keywords/is.md) and [switch](language-reference/keywords/switch.md) keywords. Every expression always matches the discard pattern.
+
+The following example defines a `ProvidesFormatInfo` method that uses [is](language-reference/keywords/is.md) statements to determine whether an object provides an <xref:System.IFormatProvider> implementation and tests whether the object is `null`. It also uses the discard pattern to handle non-null objects of any other type.
+
+[!code-csharp[discard-pattern](../../samples/snippets/csharp/programming-guide/discards/discard-pattern2.cs)]
+
+## Calls to methods with out parameters
+
+When calling the `Deconstruct` method to deconstruct a user-defined type (an instance of a class, structure, or interface), you can discard the values of individual `out` arguments. But you can also discard the value of `out` arguments when calling any method with an out parameter. 
+
+The following example calls the [DateTime.TryParse(String, out DateTime)](<xref:System.DateTime.TryParse(System.String,System.DateTime@)>) method to determine whether the string representation of a date is valid in the current culture. Because the example is concerned only with validating the date string and not with parsing it to extract the date, the `out` argument to the method is a discard.
+
+[!code-csharp[discard-with-out](../../samples/snippets/csharp/programming-guide/discards/discard-out1.cs)]
+
+## A standalone discard
+
+You can use a standalone discard to indicate any variable that you choose to ignore. The following example uses a standalone discard to ignore the <xref:System.Threading.Tasks.Task> object returned by an asynchronous operation. This has the effect of suppressing the exception that the operation throws as it is about to complete.
+
+[!code-csharp[standalone-discard](../../samples/snippets/csharp/programming-guide/discards/standalone-discard1.cs)]
+
+Note that `_` is also a valid identifier. When used outside of a supported context, `_` is treated not as a discard but as a valid variable. If an identifier named `_` is already in scope, the use of `_` as a standalone discard can result in:
+
+- Accidental modification of the value of the in-scope `_` variable by assigning it the value of the intended discard. For example:
+
+   [!code-csharp[standalone-discard](../../samples/snippets/csharp/programming-guide/discards/standalone-discard2.cs#1)]
+ 
+- A compiler error for violating type safety. For example:
+
+   [!code-csharp[standalone-discard](../../samples/snippets/csharp/programming-guide/discards/standalone-discard2.cs#2)]
+ 
+- Compiler error CS0136, "A local or parameter named '_' cannot be declared in this scope because that name is used in an enclosing local scope to define a local or parameter." For example:
+
+   [!code-csharp[standalone-discard](../../samples/snippets/csharp/programming-guide/discards/standalone-discard2.cs#3)]
+
+## See also
+[Deconstructing tuples and other types](deconstruct.md)   
+[`is` keyword](language-reference/keywords/is.md)   
+[`switch` keyword](language-reference/keywords/switch.md)   

docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md

@@ -875,6 +875,8 @@ f1_keywords:
   - "CS0589"
   - "CS0656"
   - "CS8038"
+  - "CS8132"
+  - "CS8136"
   - "CS8137"
   - "CS8139"
   - "CS8156"

docs/csharp/whats-new/csharp-7.md

@@ -19,6 +19,8 @@ C# 7 adds a number of new features to the C# language:
     - You can declare `out` values inline as arguments to the method where they are used.
 * [Tuples](#tuples)
     - You can create lightweight, unnamed types that contain multiple public fields. Compilers and IDE tools understand the semantics of these types.
+* [Discards](#discards)
+    Discards are temporary, write-only variables used in assignments when you don't care about the value assigned. They are particularly useful when deconstructing tuples and user-defined types, as well as when calling methods with `out` parameters.
 * [Pattern Matching](#pattern-matching)
     - You can create branching logic based on arbitrary types and values of the members of those types.
 * [`ref` locals and returns](#ref-locals-and-returns)
@@ -198,6 +200,26 @@ can rename the extract variables as part of the assignment:
 You can learn more in depth about tuples in the
 [tuples topic](../tuples.md).
 
+## Discards
+
+Often when deconstructing a tuple or calling a method with `out` parameters, you're forced to define a variable whose value you don't care about and don't intend to use. C# adds support for *discards* to handle this scenario. A discard is a write-only variable whose name is `_` (the underscore character); you can assign all of the values that you intend to discard to the single variable. A discard is like an unassigned variable; apart from the assignment statement, the discard can't be used in code.
+
+Discards are supported in the following scenarios:
+
+* When deconstructing tuples or user-defined types.
+
+* When calling methods with [out](..\language-reference\keywords\out.md) parameters.
+
+* In a pattern matching operation with the [is](..\language-reference\keywords\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 a 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.
+
+[!code-csharp[Tuple-discard](../../../samples/snippets/csharp/programming-guide/deconstructing-tuples/discard-tuple1.cs)]
+
+For more information, see [Discards](../discards.md).
+ 
 ## Pattern matching
 
 *Pattern matching* is a feature that allows you to implement method dispatch on
@@ -535,7 +557,7 @@ feature:
 
 > [!NOTE]
 > You need to add the NuGet package [`System.Threading.Tasks.Extensions`](https://www.nuget.org/packages/System.Threading.Tasks.Extensions/)
-> in order to use the <xref:System.Threading.Tasks.Task.ValueTask%601> type.
+> in order to use the <xref:System.Threading.Tasks.ValueTask%601> type.
 
 A simple optimization would be to use `ValueTask` in places where
 `Task` would be used before. However, if you want to perform extra

docs/toc.md

@@ -191,12 +191,14 @@
 ### [Classes](csharp/classes.md)
 ### [Structs](csharp/structs.md)
 ### [Tuples](csharp/tuples.md)
+### [Deconstructing tuples and other types](deconstruct.md)
 ### [Interfaces](csharp/programming-guide/interfaces/index.md)
 <!--### [🔧 Methods and Lambda Expressions](csharp/methods-lambda-expressions.md)-->
-#### [Methods](csharp/methods.md)
+### [Methods](csharp/methods.md)
 #### [Lambda Expressions](csharp/lambda-expressions.md)
 ### [Properties](csharp/properties.md)
 ### [Indexers](csharp/indexers.md)
+### [Discards](discards.md)
 ### [Generics](csharp/programming-guide/generics/index.md)
 ### [Iterators](csharp/iterators.md)
 ### [Delegates & events](csharp/delegates-events.md)