[Everday C#] Add Expressions: operators article

[BillWagner]

Create docs/csharp/fundamentals/expressions/operators.md covering arithmetic, unary, increment/decrement, relational, equality survey, conditional-logical, conditional (?:), simple and compound assignment.

• Add operators snippets project (net10.0, nullable, implicit usings) with 9 region-marked examples; 0 warnings, 0 errors
• Add operators.md TOC node under Expressions and statements
• Add reciprocal link in expressions/index.md
• Add reciprocal link in expressions/equality.md
• Link excluded operators (shift/bitwise, checked/unchecked) to existing Language Reference pages

Fixes #55334

---

Internal previews

Toggle expand/collapse

File	Preview link
.openpublishing.redirection.csharp.json	Preview published page
docs/csharp/fundamentals/expressions/equality.md	Preview published page
docs/csharp/fundamentals/expressions/index.md	Preview published page
docs/csharp/fundamentals/expressions/operators.md	Preview published page
docs/csharp/fundamentals/expressions/snippets/equality/Program.cs	Preview published page
docs/csharp/fundamentals/expressions/snippets/operators/Program.cs	Preview published page
docs/csharp/fundamentals/object-oriented/objects.md	Preview published page
docs/csharp/how-to/index.md	Preview published page
docs/csharp/language-reference/compiler-messages/overloaded-operator-errors.md	Preview published page
docs/csharp/language-reference/compiler-messages/record-declaration-errors.md	Preview published page
docs/csharp/language-reference/operators/equality-operators.md	Preview published page
docs/csharp/language-reference/operators/snippets/EqualityHierarchies/Program.cs	Preview published page
docs/csharp/toc.yml	Preview published page

[Copilot]

Pull request overview

Adds a new C# Fundamentals article that explains everyday operators (arithmetic, unary, increment/decrement, relational, equality, conditional-logical, conditional ?:, and assignment), along with runnable snippets and navigation updates so the content is discoverable from the Expressions section.

Changes:

• Adds operators.md under Fundamentals → Expressions and links it from related Expressions articles.
• Introduces a new snippets project (snippets/operators) with region-tagged examples used by the article.
• Updates the C# TOC to include the new Operators article.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/csharp/toc.yml	Adds the Operators node under Fundamentals → Expressions.
docs/csharp/fundamentals/expressions/operators.md	New operators concept article with :::code inclusions and links to reference pages for excluded operator sets.
docs/csharp/fundamentals/expressions/snippets/operators/operators.csproj	New .NET snippet project configuration for the operators examples.
docs/csharp/fundamentals/expressions/snippets/operators/Program.cs	New runnable sample code containing the operator examples referenced by the article.
docs/csharp/fundamentals/expressions/index.md	Adds a cross-link to the new operators article.
docs/csharp/fundamentals/expressions/equality.md	Adds a cross-link to the new operators article.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[BillWagner]

Note for reviewers: Other than the fundamentals articles, most of the changes were updating links, and moving existing content from the Programming Guide that didn't fit in fundamentals. The large blocks of changes in the language reference area have content that already existed, was in Programming guide articles that are now redundant, and was moved. Minimal style edits are the primary changes.

[Copilot]

Pull request overview

Copilot reviewed 28 out of 28 changed files in this pull request and generated no new comments.

Suppressed comments (17)

.openpublishing.redirection.csharp.json:5798

• This redirect targets a fragment that no longer exists in fundamentals/expressions/equality.md, so requests to the deleted how-to page land at the top of the replacement article instead of the manual equality guidance. Point it to the section that now contains that content.

      "redirect_url": "/dotnet/csharp/fundamentals/expressions/equality#implement-equality-yourself-when-a-type-cant-be-a-record"

.openpublishing.redirection.csharp.json:5790

• The PR description presents this as an operators-article addition with reciprocal links, but these redirects accompany deletion of three published equality pages and their snippet projects. Document the equality-content consolidation and removals in the PR description so reviewers can assess that substantial additional scope.

    {
      "source_path_from_root": "/docs/csharp/programming-guide/statements-expressions-operators/equality-comparisons.md",
      "redirect_url": "/dotnet/csharp/fundamentals/expressions/equality"

docs/csharp/fundamentals/expressions/equality.md:108

• The first option is incomplete because custom record equality must use a matching GetHashCode; otherwise hash-based collections can treat equal records inconsistently. The second option incorrectly presents IEqualityComparer<T> as a collection type, and merely creating a comparer doesn't change synthesized record equality.

- **Implement `IEquatable<T>`** on the record and override `Equals` to use <xref:System.Linq.Enumerable.SequenceEqual*?displayProperty=nameWithType> for the collection members.
- **Use a collection type with value equality** — for example, a custom `IEqualityComparer<T>` or a type whose own `Equals` compares elements.

docs/csharp/language-reference/operators/equality-operators.md:4

• This substantial AI-assisted Markdown addition lacks the required front-matter disclosure. Add the repository's ai-usage key.

ms.date: 08/19/2026

docs/csharp/language-reference/operators/snippets/EqualityHierarchies/Program.cs:63

• The article later says this pattern is safe and complete for a sealed class, but the sample leaves Color inheritable while its typed Equals is nonvirtual. A derived type can then introduce asymmetric equality. Seal the sample so it matches the documented contract.

class Color : IEquatable<Color>

docs/csharp/language-reference/operators/equality-operators.md:99

• Compiler-generated record equality doesn't compare every declared property. It compares participating instance fields, including backing fields for auto-properties; a computed property without a backing field doesn't affect equality. The current wording teaches an incorrect contract.

Records handle inheritance correctly without manual work. The compiler-generated equality checks both runtime type and all declared properties, so it automatically satisfies the symmetry and transitivity requirements. Prefer `record` over a manual unsealed hierarchy when value equality is the goal.

docs/csharp/language-reference/operators/equality-operators.md:110

• Color is a reference-type class, not a C# value type, and IEquatable<Color> can't avoid boxing because reference types aren't boxed. Also, the typed Equals member is optional, so calling all three members required contradicts the final sentence.

Here is a minimal manual implementation for a value type that can't be a record:

:::code language="csharp" source="snippets/EqualityHierarchies/Program.cs" id="ColorDefinition":::

The implementation provides three required members: `Equals(T?)` as the core comparison, `override Equals(object?)` for object-level calls, and `override GetHashCode()` so hash-based collections work correctly. `HashCode.Combine` is a library helper that builds one hash from the same values used by `Equals`. Implementing <xref:System.IEquatable`1> (the `Equals(T?)` overload) is optional but avoids boxing when callers already have the concrete type.

docs/csharp/language-reference/operators/equality-operators.md:124

• The repository's Markdown guideline requires every ordered-list item to use 1. so Markdown performs the numbering. Replace the explicit sequence here.

1. **Reflexive**: `x.Equals(x)` returns `true`.
2. **Symmetric**: `x.Equals(y)` returns the same value as `y.Equals(x)`.
3. **Transitive**: if `x.Equals(y)` and `y.Equals(z)` are both `true`, then `x.Equals(z)` must be `true`.
4. **Consistent**: successive calls to `x.Equals(y)` return the same value as long as neither object changes.
5. **Null behavior**: `x.Equals(null)` returns `false`; `x.Equals(y)` must not throw when called on a non-null `x`.

docs/csharp/language-reference/operators/equality-operators.md:126

• IEquatable<T> doesn't make dispatch follow the declared type. Overload resolution uses the declared type, but a selected virtual method still dispatches to the runtime override, which is exactly what the proposed pattern relies on. Distinguish these two mechanisms to avoid contradicting the next paragraph.

Value equality in an unsealed class hierarchy requires more care than in a sealed class to satisfy the symmetric and transitive rules. The hazard is that `IEquatable<T>.Equals(T? other)` dispatch follows the *declared type* (the type written in the variable declaration) of the variable, not its runtime type. If `Shape` declares a non-`virtual` `Equals(Shape? other)`, a variable typed as `Shape` that holds a `Circle` at runtime invokes `Shape.Equals`—silently ignoring `Circle`-specific fields. Two `Circle` objects with different radii can compare as equal when accessed through a `Shape` variable.

docs/csharp/language-reference/operators/equality-operators.md:138

• Omitting GetType() from a hash code can't make Dictionary or HashSet incorrect. The hash contract only requires equal objects to have equal hashes; unequal runtime types can legally collide. Including the type can reduce collisions, but it isn't required for correctness.

- **`GetHashCode` includes `GetType()`**: because two objects are equal only when their runtime types match, `GetHashCode` must hash the runtime type as well as the data fields. Omitting `GetType()` here causes incorrect behavior in `Dictionary<TKey,TValue>` and `HashSet<T>`.

docs/csharp/fundamentals/expressions/operators.md:14

• This cross-language claim is inaccurate for JavaScript: == performs coercion, ! accepts truthy and falsy operands, + can concatenate after coercion, and / doesn't perform integer division. Describe the familiar syntax without implying equivalent semantics.

> **Coming from another language?** Most operators in this article (`+`, `-`, `*`, `/`, `%`, `&&`, `||`, `!`, `==`, `!=`, `<`, `>`, comparison operators, and `=`) work the same as in Java, C++, and JavaScript. The main surprises for newcomers are integer division behavior, the prefix/postfix distinction for `++`/`--`, and the way compound assignment converts back to the left-hand-side type.

docs/csharp/fundamentals/expressions/operators.md:88

• “Use == for value comparison” is unsafe as general C# guidance because == still tests identity for many reference types. Limit this advice to numeric types and strings, and tell readers that other types control their own equality semantics.

> If you're coming from JavaScript, use `==` for value comparison (C# `==` already compares by value for primitive types and strings). A common related bug is accidentally writing `=` (assignment) where you meant `==` (equality check). The compiler catches the most common forms, but double-check any `if` condition that contains `=`.

docs/csharp/fundamentals/object-oriented/objects.md:28

• Local struct values aren't guaranteed to live on the thread stack; the JIT can keep them in registers, and structs used as fields or boxed values live elsewhere. Avoid teaching stack allocation as the reason assignment copies structs.

The thread stack allocates memory for both `p1` and `p2`. The program reclaims that memory along with the type or method in which you declare it. This memory management is one reason why structs are copied on assignment. By contrast, the common language runtime automatically reclaims (garbage collects) the memory it allocates for a class instance when all references to the object go out of scope. You can't deterministically destroy a class object like you can in C++. For more information about garbage collection in .NET, see [Garbage Collection](../../../standard/garbage-collection/index.md).

docs/csharp/fundamentals/expressions/operators.md:70

• A C# char stores one UTF-16 code unit, not necessarily a Unicode code point. Surrogate code units don't represent code points by themselves, so describe the comparison in terms of the UTF-16 code-unit value.

Relational operators work on all numeric types and `char`. For `char`, comparison uses the character's numeric Unicode code point value, not any alphabetical or domain-specific ordering. In the grade example above, `'B'` is greater than or equal to `'A'` because `'B'` has Unicode value 66 and `'A'` has Unicode value 65 — the *numbers* determine the comparison, not the meaning of the letter grades.

docs/csharp/fundamentals/expressions/snippets/operators/Program.cs:19

• decimal operands also preserve the fractional result, so the comment incorrectly limits the choices to double and float. Include all three built-in fractional numeric types.

// To get a decimal result, at least one operand must be a double or float

docs/csharp/fundamentals/expressions/snippets/operators/Program.cs:73

• A C# char is a UTF-16 code unit and can contain a surrogate value that isn't a Unicode code point. Use the precise term in the published sample comments too.

// char comparison uses the character's numeric Unicode code point, not alphabetical position
// 'B' (U+0042, value 66) is less than 'A' (U+0041, value 65)? No — 'A' (65) < 'B' (66)

docs/csharp/fundamentals/object-oriented/objects.md:42

• “Records are reference types” excludes record struct, which is a value type. Distinguish record classes from record structs so the equality guidance doesn't contradict the type system.

  The default <xref:System.ValueType?displayProperty=nameWithType> implementation of `Equals` uses boxing and reflection in some cases. For information about how to provide an efficient equality algorithm that's specific to your type, see [Implement equality yourself when a type can't be a record](../../language-reference/operators/equality-operators.md#implement-equality-yourself-when-a-type-cant-be-a-record). Records are reference types that use value semantics for equality.