Repository navigation
Update for new tiebreaker rules #4677
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
5647b21
3005ef0
e83b496
c48017b
0e679f3
00d2946
d97ac0b
f2046f7
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -18,10 +18,10 @@ The `in` keyword causes arguments to be passed by reference. It is like the [ref | |
|
|
||
| [!code-csharp-interactive[cs-in-keyword](../../../../samples/snippets/csharp/language-reference/keywords/in-ref-out-modifier/InParameterModifier.cs#1)] | ||
|
|
||
| The preceding example demonstrates that the `in` modifier is unnecessary at the call site. It is only required in the method declaration. | ||
| The preceding example demonstrates the `in` modifier is usually unnecessary at the call site. It is only required in the method declaration. | ||
|
|
||
| > [!NOTE] | ||
| > The `in` keyword can also be used with a generic type parameter to specify that the type parameter is contravariant, as part of a `foreach` statement, or as part of a `join` clause in a LINQ query. For more information on the use of the `in` keyword in these contexts, see [in](in.md) which provides links to all those uses. | ||
| > The `in` keyword can also be used with a generic type parameter to specify that the type parameter is contravariant, as part of a `foreach` statement, or as part of a `join` clause in a LINQ query. For more information on the use of the `in` keyword in these contexts, see [in](in.md), which provides links to all those uses. | ||
|
|
||
| Variables passed as `in` arguments must be initialized before being passed in a method call. However, the called method may not assign a value or modify the argument. | ||
|
|
||
|
|
@@ -37,36 +37,91 @@ class CS0663_Example | |
| } | ||
| ``` | ||
|
|
||
| Overloading based on the presence of `in` is allowed, but generates a compiler warning: | ||
| Overloading based on the presence of `in` is allowed: | ||
|
|
||
| ```csharp | ||
| class InOverloads | ||
| { | ||
| // Discouraged. Calling SampleMethod(value) is ambiguous. | ||
| public void SampleMethod(in int i) { } | ||
| public void SampleMethod(int i) { } | ||
| } | ||
| ``` | ||
|
|
||
| Properties or constants may be passed as `in` parameters, because the calling method may not modify their values. | ||
|
|
||
| You can't use the `in`, `ref`, and `out` keywords for the following kinds of methods: | ||
|
|
||
| - Async methods, which you define by using the [async](../../../csharp/language-reference/keywords/async.md) modifier. | ||
|
|
||
| - Iterator methods, which include a [yield return](../../../csharp/language-reference/keywords/yield.md) or `yield break` statement. | ||
| ## Overload resolution rules | ||
|
|
||
| You can understand the overload resolution rules for methods with by value vs. `in` arguments through understanding the motivation for `in` arguments. Defining methods using `in` parameters is a potential performance optimization. Some `struct` type arguments may be large in size, and when methods are called in tight loops or critical code paths, the cost of copying those structures is critical. Methods declare `in` parameters to specify that arguments may be passed by reference safely because the called method does not modify the state of that argument. Passing those arguments by reference avoids the (potentially) expensive copy. | ||
|
|
||
| Specifying `in` on arguments at the call site is typically optional. There is no semantic difference between passing arguments by value and passing them by reference using the `in` modifier. The `in` modifier at the call site is optional because you don't need to indicate that the argument's value might be changed. You explicitly add the `in` modifier at the call site to ensure the argument is passed by reference, not by value. Explicitly using `in` has two effects: | ||
|
|
||
| First, specifying `in` at the call site forces the compiler to select a method defined with a matching `in` parameter. Otherwise, when two methods differ only in the presence of `in`, the by value overload is a better match. | ||
|
|
||
| Second, specifying `in` declares your intent to pass an argument by reference. The argument used with `in` must represent a location that can be directly referred to. The same general rules for `out` and `ref` arguments apply: You cannot use constants, ordinary properties, or other expressions that produce values. Otherwise, omitting `in` at the call site informs the compiler that you will allow it to create a temporary variable to pass by read-only reference to the method. The compiler creates a temporary variable to overcome several restrictions with `in` arguments: | ||
|
|
||
| You typically declare `in` arguments to avoid the copy operations necessary for passing arguments by value. This is most useful when arguments are value types such as structures where copy operations are more expensive than passing by reference. | ||
| - A temporary variable allows compile-time constants as `in` parameters. | ||
| - A temporary variable allows properties, or other expressions for `in` parameters. | ||
| - A temporary variable allows arguments where there is an implicit conversion from the argument type to the parameter type. | ||
|
|
||
| In all the preceding instances, the compiler creates a temporary variable that stores the value of the constant, property, or other expression. | ||
|
|
||
| The following code illustrates these rules: | ||
|
|
||
| ```csharp | ||
| static void Method(in int argument) | ||
| { | ||
| // implementation removed | ||
| } | ||
|
|
||
| Method(5); // OK, temporary variable created. | ||
| Method(5L); // CS1503: no implicit conversion from long to int | ||
| short s = 0; | ||
| Method(s); // OK, temporary int created with the value 0 | ||
| Method(in s); // CS1503: cannot convert from in short to in int | ||
| int i = 42; | ||
| Method(i); // passed by readonly reference | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. readonly --> read-only (this recurs in numerous places, starting with the next line)
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Replaced everyone it is not referencing the keyword |
||
| Method(in i); // passed by readonly reference, explicitly using `in` | ||
| ``` | ||
|
|
||
| > [!WARNING] | ||
| > `in` parameters can be even more expensive if misused. The compiler may not know if member methods modify the state of the struct. Whenever the compiler cannot ensure that the object is not modified, it defensively creates a copy and calls member references using that copy. Any possible modifications are to that defensive copy. The two ways to avoid these copies are to pass `in` parameters as `in` arguments or to define structures as `readonly struct`. | ||
| Now, suppose another method using by value arguments was available. The results change as shown in the following code: | ||
|
|
||
| ```csharp | ||
| static void Method(int argument) | ||
| { | ||
| // implementation removed | ||
| } | ||
|
|
||
| static void Method(in int argument) | ||
| { | ||
| // implementation removed | ||
| } | ||
|
|
||
| Method(5); // Calls overload passed by value | ||
| Method(5L); // CS1503: no implicit conversion from long to int | ||
| short s = 0; | ||
| Method(s); // Calls overload passed by value. | ||
| Method(in s); // CS1503: cannot convert from in short to in int | ||
| int i = 42; | ||
| Method(i); // Calls overload passed by value | ||
| Method(in i); // passed by readonly reference, explicitly using `in` | ||
| ``` | ||
|
|
||
| The only method call where the argument is passed by reference is the final one. | ||
|
|
||
| > [!NOTE] | ||
| > The preceding code uses `int` as the argument type for simplicity. Because `int` is no larger than a reference in most modern machines, there is no benefit to passing a single `int` as a readonly reference. | ||
|
|
||
| ## Limitations on `in` parameters | ||
|
|
||
| You can't use the `in`, `ref`, and `out` keywords for the following kinds of methods: | ||
|
|
||
| - Async methods, which you define by using the [async](async.md) modifier. | ||
| - Iterator methods, which include a [yield return](yield.md) or `yield break` statement. | ||
|
|
||
| ## C# Language Specification | ||
| [!INCLUDE[CSharplangspec](~/includes/csharplangspec-md.md)] | ||
|
|
||
| ## See Also | ||
| [C# Reference](../../../csharp/language-reference/index.md) | ||
| [C# Programming Guide](../../../csharp/programming-guide/index.md) | ||
| [C# Keywords](../../../csharp/language-reference/keywords/index.md) | ||
| [Method Parameters](../../../csharp/language-reference/keywords/method-parameters.md) | ||
| [Reference Semantics with Value Types](../../../csharp/reference-semantics-with-value-types.md) | ||
| [C# Reference](../index.md) | ||
| [C# Programming Guide](../../programming-guide/index.md) | ||
| [C# Keywords](index.md) | ||
| [Method Parameters](method-parameters.md) | ||
| [Reference Semantics with Value Types](../../reference-semantics-with-value-types.md) | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is unrelated to your PR, but the in disambiguation topic is in the Query Keywords section in the TOC, which seems like the wrong place.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm going to create a new issue for this: #4757
That way, this PR stays focused on this single topic.