Skip to content

Commit

Permalink
Create detailed article on C# tuples (#1284)
Browse files Browse the repository at this point in the history
* Create Tuples content in C# 7 content
Outline and start on first draft.

* finish tuples article and samples

Ready for a final proofread

* proofread, remove wrenches

This is now ready for review.

* respond to all feedback.

Reviews from @svick and @rpetrusha
  • Loading branch information
BillWagner authored Nov 29, 2016
1 parent 9d698d0 commit c48f486
Show file tree
Hide file tree
Showing 13 changed files with 922 additions and 38 deletions.
31 changes: 19 additions & 12 deletions docs/csharp/csharp-7.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,6 @@ Add a sample at RC that shows how if statements
scope out variables.
-->

This small language change improves your productivity in important ways:
* The code is easier to read.
- You declare the out variable where you use it, not on another line above.
* No need to assign an initial value.
Expand All @@ -78,9 +77,10 @@ that contain multiple fields to represent the data members.
The fields are not validated, and you cannot define your own methods

> [!NOTE]
> Tuples were available as an API class before C# 7, but had many limitations.
> Most importantly, the members of these tuples were named `Item1`, `Item2`
> and so on. The language features for Tuples address this limitations.
> Tuples were available before C# 7 as an API, but had many limitations.
> Most importantly, the members of these tuples were named
> `Item1`, `Item2` and so on. The language support enables semantic names
> for the fields of a Tuple.
You can create a tuple by assigning each member to a value:

Expand All @@ -94,12 +94,12 @@ names to each of the members of the tuple:
[!code-csharp[NamedTuple](../../samples/snippets/csharp/new-in-7/new-in-7/program.cs#05_NamedTuple "Named tuple")]

> [!NOTE]
> The new tuples features require the @System.ValueTuple type. For Visual Studio 15
> The new tuples features require the `System.ValueTuple` type. For Visual Studio 15
> Preview 5 and earlier preview releases, you must add the NuGet package "System.ValueTuple",
> available in the pre-release stream.
The `namedLetters` tuple contains fields referred to as `alpha` and
`beta`. In a tuple assignment, you can also specify the names of the fields
The `namedLetters` tuple contains fields referred to as `Alpha` and
`Beta`. In a tuple assignment, you can also specify the names of the fields
on the right hand side of the assignment:

[!code-csharp[ImplicitNamedTuple](../../samples/snippets/csharp/new-in-7/new-in-7/program.cs#06_ImplicitNamedTuple "Implicitly named tuple")]
Expand All @@ -110,24 +110,31 @@ left and right hand side of the assignment:
[!code-csharp[NamedTupleConflict](../../samples/snippets/csharp/new-in-7/new-in-7/program.cs#07_NamedTupleConflict "Named tuple conflict")]

The line above generates a warning, `CS8123`, telling you that the names on the right
side of the assignment, `alpha` and `beta` are ignored because they conflict
with the names on the left side, `first` and `second`.
side of the assignment, `Alpha` and `Beta` are ignored because they conflict
with the names on the left side, `First` and `Second`.

The examples above show the basic syntax to declare tuples. Tuples are
most useful as return types for `private` and `internal` methods. Tuples
provide a simple syntax for those methods to return multiple discrete values:
You save the work of authoring a `class` or a `struct` that
defines the type returned. There is no need for creating a new type.

Creating a tuple is more efficient and more productive.
It is a simpler, lightweight syntax to define a data structure that carries
more than one value. The example method below returns the minimimum and maximum
values found in a sequence of integers:

[!code-csharp[TupleReturningMethod](../../samples/snippets/csharp/new-in-7/new-in-7/program.cs#08_TupleReturningMethod "Tuple returning method")]

Using tuples in this way offers several advantages:

* You save the work of authoring a `class` or a `struct` that defines the type returned.
* You do not need to create new symbol.
* You do not need to create new type.
* The language enhancements removes the need to call the @System.Tuple.Create%60%601(%60%600) methods.

The declaration for the method provides the names for the fields of the
tuple that is returned. When you call the method, the return value is a
tuple whose fields are `max` and `min`:
tuple whose fields are `Max` and `Min`:

[!code-csharp[CallingTupleMethod](../../samples/snippets/csharp/new-in-7/new-in-7/program.cs#09_CallingTupleMethod "Calling a tuple returning method")]

Expand Down Expand Up @@ -337,7 +344,7 @@ the return value is a reference:
Now, the second `WriteLine` statement in the example above will print
out the value `24`, indicating that the storage in the matrix has been
modified. The local variable has been declared with the `ref` modifier,
and it will take a `ref` return. You must initialize a `ref` varaible when
and it will take a `ref` return. You must initialize a `ref` variable when
it is declared, you cannot split the declaration and the initialization.

The C# language has two other rules that protect you from mis-using
Expand Down
Loading

0 comments on commit c48f486

Please sign in to comment.