Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions standard/basic-concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -628,9 +628,9 @@ Methods, instance constructors, indexers, and operators are characterized by the
- The signature of a method consists of the name of the method, the number of type parameters, and the type and parameter-passing mode of each of its parameters, considered in the order left to right. For these purposes, any type parameter of the method that occurs in the type of a parameter is identified not by its name, but by its ordinal position in the type parameter list of the method. The signature of a method specifically does not include the return type, parameter names, type parameter names, type parameter constraints, the `params` or `this` parameter modifiers, nor whether parameters are required or optional.
- The signature of an instance constructor consists of the type and parameter-passing mode of each of its parameters, considered in the order left to right. The signature of an instance constructor specifically does not include the `params` modifier that may be specified for the right-most parameter, nor whether parameters are required or optional.
- The signature of an indexer consists of the type of each of its parameters, considered in the order left to right. The signature of an indexer specifically does not include the element type, nor does it include the `params` modifier that may be specified for the right-most parameter, nor whether parameters are required or optional.
- The signature of an operator consists of the name of the operator and the type of each of its parameters, considered in the order left to right. The signature of an operator specifically does not include the result type.
- The signature of a conversion operator consists of the source type and the target type. The implicit or explicit classification of a conversion operator is not part of the signature.
- Two signatures of the same member kind (method, instance constructor, indexer or operator) are considered to be the *same signatures* if they have the same name, number of type parameters, number of parameters, and parameter-passing modes, and an identity conversion exists between the types of their corresponding parameters ([§10.2.2](conversions.md#1022-identity-conversion)).
- The signature of an operator consists of the name of the operator, whether the operator is checked or regular ([§15.10.1](classes.md#15101-general)), and the type of each of its parameters, considered in the order left to right. The signature of an operator specifically does not include the result type.
- The signature of a conversion operator consists of the source type, the target type, and whether the operator is checked or regular. The implicit or explicit classification of a conversion operator is not part of the signature.
- Two signatures of the same member kind (method, instance constructor, indexer or operator) are considered to be the *same signatures* if they have the same name, number of type parameters, number of parameters, and parameter-passing modes, an identity conversion exists between the types of their corresponding parameters ([§10.2.2](conversions.md#1022-identity-conversion)), and, for operators, both are checked or both are regular.

Signatures are the enabling mechanism for ***overloading*** of members in classes, structs, and interfaces:

Expand Down
48 changes: 33 additions & 15 deletions standard/classes.md
Original file line number Diff line number Diff line change
Expand Up @@ -1516,14 +1516,14 @@ The following method names are reserved. While many have corresponding operators
| `op_BitwiseAndAssignment` | (reserved) |
| `op_BitwiseOr` | `\|` |
| `op_BitwiseOrAssignment` | (reserved) |
| `op_CheckedAddition` | (reserved for future use) |
| `op_CheckedDecrement` | (reserved for future use) |
| `op_CheckedDivision` | (reserved for future use) |
| `op_CheckedExplicit` | (reserved for future use) |
| `op_CheckedIncrement` | (reserved for future use) |
| `op_CheckedMultiply` | (reserved for future use) |
| `op_CheckedSubtraction` | (reserved for future use) |
| `op_CheckedUnaryNegation` | (reserved for future use) |
| `op_CheckedAddition` | checked addition `+` |
| `op_CheckedDecrement` | checked decrement `--` |
| `op_CheckedDivision` | checked division `/` |
| `op_CheckedExplicit` | checked explicit (narrowing) coercion |
| `op_CheckedIncrement` | checked increment `++` |
| `op_CheckedMultiply` | checked multiply `*` |
| `op_CheckedSubtraction` | checked subtraction `-` |
| `op_CheckedUnaryNegation` | checked unary negation `-` |
| `op_Comma` | (reserved) |
| `op_Decrement` | `--` (prefix and postfix) |
| `op_Division` | `/` |
Expand Down Expand Up @@ -4981,7 +4981,7 @@ logical_negation_operator
;

overloadable_unary_operator
: '+' | '-' | logical_negation_operator | '~' | '++' | '--' | 'true' | 'false'
: '+' | 'checked'? '-' | logical_negation_operator | '~' | 'checked'? '++' | 'checked'? '--' | 'true' | 'false'
;

binary_operator_declarator
Expand All @@ -4990,13 +4990,13 @@ binary_operator_declarator
;

overloadable_binary_operator
: '+' | '-' | '*' | '/' | '%' | '&' | '|' | '^' | '<<'
| right_shift | '==' | '!=' | '>' | '<' | '>=' | '<='
: 'checked'? '+' | 'checked'? '-' | 'checked'? '*' | 'checked'? '/' | '%' | '&' | '|' | '^' | '<<'
| right_shift | '==' | '!=' | '>' | '<' | '>=' | '<='
;

conversion_operator_declarator
: 'implicit' 'operator' type '(' fixed_parameter ')'
| 'explicit' 'operator' type '(' fixed_parameter ')'
| 'explicit' 'operator' 'checked'? type '(' fixed_parameter ')'
;

operator_body
Expand Down Expand Up @@ -5032,6 +5032,18 @@ Additional information on unary and binary operators can be found in [§12.4](e

Additional information on conversion operators can be found in [§10.5](conversions.md#105-user-defined-conversions).

An *operator_declaration* containing `checked` declares a ***checked operator***. An *operator_declaration* without `checked` declares a ***regular operator***. For each checked operator declared in a type there shall be a corresponding declaration of a regular operator in that same type whose signature differs only by the absence of `checked`, and whose return type is the same.

> *Note*: The opposite is not required. A regular operator need not have a matching checked operator, including when the operator has no checked form. *end note*

It is suggested that a user-defined checked operator throw an exception (such as `System.OverflowException`) when the result of an operation is too large to represent in the destination type, whatever that might mean for that type.

It is suggested that a user-defined regular operator not throw an exception when the result of an operation is too large to represent in the destination type, whatever that might mean for that type. Instead, it should return an instance representing a truncated result, whatever that might mean for that type.

A checked operator does not implement a regular operator, and vice versa.

The presence of `checked` in a checked operator declaration has no effect on the checked context of that operator’s *operator_body*. That is controlled by the `checked` and `unchecked` operators or statements present in that *operator_body*, or by the default checking context provided by the runtime environment.

### 15.10.2 Unary operators

The following rules apply to unary operator declarations, where `T` denotes the instance type of the class or struct that contains the operator declaration:
Expand All @@ -5040,10 +5052,14 @@ The following rules apply to unary operator declarations, where `T` denotes the
- A unary `++` or `--` operator shall take a single parameter of type `T` or `T?` and shall return that same type or a type derived from it.
- A unary `true` or `false` operator shall take a single parameter of type `T` or `T?` and shall return type `bool`.

The signature of a unary operator consists of the operator token (`+`, `-`, `!`, `~`, `++`, `--`, `true`, or `false`) and the type of the single parameter. The return type is not part of a unary operator’s signature, nor is the name of the parameter.
The signature of a unary operator consists of the operator token (`+`, `-`, `!`, `~`, `++`, `--`, `true`, or `false`), whether the operator is checked or regular, and the type of the single parameter. The return type is not part of a unary operator’s signature, nor is the name of the parameter.

The `true` and `false` unary operators require pair-wise declaration. A compile-time error occurs if a class declares one of these operators without also declaring the other. The `true` and `false` operators are described further in [§12.27](expressions.md#1227-boolean-expressions).

> *Note*: A unary `++`, `--`, or `-` operator may have a checked form (see [§15.10.1](classes.md#15101-general)). *end note*

<!-- markdownlint-disable MD028 -->

> *Example*: The following example shows an implementation and subsequent usage of operator++ for an integer vector class:
>
> <!-- Example: {template:"standalone-console-without-using", name:"UnaryOperators", replaceEllipsis:true, customEllipsisReplacements:[null,"return 0;","return 0;",null]} -->
Expand Down Expand Up @@ -5088,14 +5104,16 @@ The following rules apply to binary operator declarations, where `T` denotes the
- A binary non-shift operator shall take two parameters, at least one of which shall have type `T` or `T?`, and can return any type.
- A binary `<<` or `>>` operator ([§12.14](expressions.md#1214-shift-operators)) shall take two parameters, the first of which shall have type `T` or `T?` and the second of which shall have type `int` or `int?`, and can return any type.

The signature of a binary operator consists of the operator token (`+`, `-`, `*`, `/`, `%`, `&`, `|`, `^`, `<<`, `>>`, `==`, `!=`, `>`, `<`, `>=`, or `<=`) and the types of the two parameters. The return type and the names of the parameters are not part of a binary operator’s signature.
The signature of a binary operator consists of the operator token (`+`, `-`, `*`, `/`, `%`, `&`, `|`, `^`, `<<`, `>>`, `==`, `!=`, `>`, `<`, `>=`, or `<=`), whether the operator is checked or regular, and the types of the two parameters. The return type and the names of the parameters are not part of a binary operator’s signature.

Certain binary operators require pair-wise declaration. For every declaration of either operator of a pair, there shall be a matching declaration of the other operator of the pair. Two operator declarations match if identity conversions exist between their return types and their corresponding parameter types. The following operators require pair-wise declaration:

- operator `==` and operator `!=`
- operator `>` and operator `<`
- operator `>=` and operator `<=`

> *Note*: A binary `+`, `-`, `*`, or `/` operator may have a checked form (see [§15.10.1](classes.md#15101-general)). *end note*

### 15.10.4 Conversion operators

A conversion operator declaration introduces a ***user-defined conversion*** ([§10.5](conversions.md#105-user-defined-conversions)), which augments the pre-defined implicit and explicit conversions.
Expand Down Expand Up @@ -5196,7 +5214,7 @@ For all types but `object`, the operators declared by the `Convertible<T>` type

User-defined conversions are not allowed to convert from or to *interface_type*s. In particular, this restriction ensures that no user-defined transformations occur when converting to an *interface_type*, and that a conversion to an *interface_type* succeeds only if the `object` being converted actually implements the specified *interface_type*.

The signature of a conversion operator consists of the source type and the target type. (This is the only form of member for which the return type participates in the signature.) The implicit or explicit classification of a conversion operator is not part of the operator’s signature. Thus, a class or struct cannot declare both an implicit and an explicit conversion operator with the same source and target types.
The signature of a conversion operator consists of the source type and the target type. (This is the only form of member for which the return type participates in the signature.) To allow a type to have both checked and regular operators with the same source- and target-type combination, the signature of a checked conversion operator also includes the fact that it is checked. The implicit or explicit classification of a conversion operator is not part of the operator’s signature. Thus, a class or struct cannot declare both an implicit and an explicit conversion operator with the same source and target types. (This restriction applies to both regular and checked explicit conversion operators.)

> *Note*: In general, user-defined implicit conversions should be designed to never throw exceptions and never lose information. If a user-defined conversion can give rise to exceptions (for example, because the source argument is out of range) or loss of information (such as discarding high-order bits), then that conversion should be defined as an explicit conversion. *end note*
<!-- markdownlint-disable MD028 -->
Expand Down
13 changes: 11 additions & 2 deletions standard/conversions.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 10 Conversions

## 10.1 General

Check warning on line 3 in standard/conversions.md

View workflow job for this annotation

GitHub Actions / word-converter

Markdown to Word Converter - MDC032

Line length 91 > maximum 83; Console.WriteLine(identity.Method.ReturnParameter.IsDefined(typeof(MarkAttribute), false));

Check warning on line 4 in standard/conversions.md

View workflow job for this annotation

GitHub Actions / word-converter

Markdown to Word Converter - MDC032

Line length 94 > maximum 83; Console.WriteLine(identity.Method.GetParameters()[0].IsDefined(typeof(MarkAttribute), false));
A ***conversion*** causes an expression to be converted to, or treated as being of, a particular type; in the former case a conversion may involve a change in representation. Conversions can be ***implicit*** or ***explicit***, and this determines whether an explicit cast is required.

Expand Down Expand Up @@ -809,8 +809,11 @@
- If `E` has a type, let `S` be that type.
- If `S` or `T` are nullable value types, let `Sᵢ` and `Tᵢ` be their underlying types, otherwise let `Sᵢ` and `Tᵢ` be `S` and `T`, respectively.
- If `Sᵢ` or `Tᵢ` are type parameters, let `S₀` and `T₀` be their effective base classes, otherwise let `S₀` and `T₀` be `Sᵢ` and `Tᵢ`, respectively.
- Find the set of types, `D`, from which user-defined conversion operators will be considered. This set consists of `S₀` (if `S₀` exists and is a class or struct), the base classes of `S₀` (if `S₀` exists and is a class), `T₀` (if `T₀` is a class or struct), and the base classes of `T₀` (if `T₀` is a class). A type is added to the set `D` only if an identity conversion to another type already included in the set does not exist.
- Find the set of applicable user-defined and lifted conversion operators, `U`. This set consists of the user-defined and lifted implicit or explicit conversion operators declared by the classes or structs in `D` that convert from a type encompassing `E` or encompassed by `S` (if it exists) to a type encompassing or encompassed by `T`. If `U` is empty, the conversion is undefined and a compile-time error occurs.
- Find the set of types, `D`, from which user-defined conversion operators will be considered. This set consists of `S₀` (if `S₀` exists and is a class or struct), the base classes of `S₀` (if `S₀` exists and is a class), `T₀` (if `T₀` is a class or struct), and the base classes of `T₀` (if `T₀` is a class). A type is added to the set `D` only if an identity conversion to another type already included in the set doesn’t exist.
- Find the set of conversion operators, `U₀` (see [§15.10.1](classes.md#15101-general), [§15.10.4](classes.md#15104-conversion-operators)). This set consists of:
- In an `unchecked` evaluation context, the user-defined implicit or regular explicit conversion operators declared by the classes or structs in `D`.
- In a `checked` evaluation context, the user-defined implicit conversion operators and the checked and regular explicit conversion operators declared by the classes or structs in `D`, except for regular explicit conversion operators that have a pair-wise matching checked operator declaration within the same declaring type.
- Find the set of applicable user-defined and lifted conversion operators, `U`. This set consists of the operators in `U₀` and their lifted forms that convert from a type encompassing `E` or encompassed by `S` (if it exists) to a type encompassing or encompassed by `T`. If `U` is empty, the conversion is undefined and a compile-time error occurs.
- Find the most-specific source type, `Sₓ`, of the operators in `U`:
- If `S` exists and any of the operators in `U` convert from `S`, then `Sₓ` is `S`.
- Otherwise, if any of the operators in `U` convert from types that encompass `E`, then `Sₓ` is the most-encompassed type in the combined set of source types of those operators. If no most-encompassed type can be found, then the conversion is ambiguous and a compile-time error occurs.
Expand Down Expand Up @@ -1101,6 +1104,12 @@
>
> *end note*

A lambda expression that contains an application of a checked user-defined division operator shall not be converted to an expression tree type; a compile-time error occurs.

Checked user-defined unary negation, addition, subtraction, multiplication, and explicit conversions are represented using the existing `System.Linq.Expressions.Expression` factory methods `NegateChecked`, `AddChecked`, `SubtractChecked`, `MultiplyChecked`, and `ConvertChecked`, respectively, with a `System.Reflection.MethodInfo` identifying the selected operator. The `Method` property of the resulting `System.Linq.Expressions.UnaryExpression` or `System.Linq.Expressions.BinaryExpression` identifies that operator.

> *Note*: The restriction on division does not exclude predefined division or regular user-defined division in a checked context. As assignment is not supported in an expression tree, there are no such factory methods for checked increment or checked decrement. *end note*

## 10.8 Method group conversions

An implicit conversion exists from a method group ([§12.2](expressions.md#122-expression-classifications)) to a compatible delegate type ([§21.4](delegates.md#214-delegate-compatibility)). If `D` is a delegate type, and `E` is an expression that is classified as a method group, then `D` is compatible with `E` if and only if `E` contains at least one method that is applicable in its normal form ([§12.6.4.2](expressions.md#12642-applicable-function-member)) to any argument list ([§12.6.2](expressions.md#1262-argument-lists)) having types and modifiers matching the parameter types and modifiers of `D`, as described in the following.
Expand Down
6 changes: 4 additions & 2 deletions standard/documentation-comments.md
Original file line number Diff line number Diff line change
Expand Up @@ -963,7 +963,7 @@ IDs:
"M:Acme.Widget.op_UnaryPlus(Acme.Widget)"
```

The complete set of unary operator function names used is as follows: `op_UnaryPlus`, `op_UnaryNegation`, `op_LogicalNot`, `op_OnesComplement`, `op_Increment`, `op_Decrement`, `op_True`, and `op_False`.
The complete set of unary operator function names used is as follows: `op_UnaryPlus`, `op_UnaryNegation`, `op_CheckedUnaryNegation`, `op_LogicalNot`, `op_OnesComplement`, `op_Increment`, `op_CheckedIncrement`, `op_Decrement`, `op_CheckedDecrement`, `op_True`, and `op_False`.

**Binary operators**

Expand All @@ -984,10 +984,12 @@ IDs:
"M:Acme.Widget.op_Addition(Acme.Widget,Acme.Widget)"
```

The complete set of binary operator function names used is as follows: `op_Addition`, `op_Subtraction`, `op_Multiply`, `op_Division`, `op_Modulus`, `op_BitwiseAnd`, `op_BitwiseOr`, `op_ExclusiveOr`, `op_LeftShift`, `op_RightShift`, `op_Equality`, `op_Inequality`, `op_LessThan`, `op_LessThanOrEqual`, `op_GreaterThan`, and `op_GreaterThanOrEqual`.
The complete set of binary operator function names used is as follows: `op_Addition`, `op_CheckedAddition`, `op_Subtraction`, `op_CheckedSubtraction`, `op_Multiply`, `op_CheckedMultiply`, `op_Division`, `op_CheckedDivision`, `op_Modulus`, `op_BitwiseAnd`, `op_BitwiseOr`, `op_ExclusiveOr`, `op_LeftShift`, `op_RightShift`, `op_Equality`, `op_Inequality`, `op_LessThan`, `op_LessThanOrEqual`, `op_GreaterThan`, and `op_GreaterThanOrEqual`.

**Conversion operators** have a trailing “`~`” followed by the return type. When either the source or destination of a conversion operator is a generic type, the “`<`” and “`">`” characters are replaced by the “`{`” and “`}`” characters, respectively.

The complete set of conversion operator function names used is as follows: `op_Explicit`, `op_CheckedExplicit`, and `op_Implicit`.

<!-- Example: {template:"standalone-lib-without-using", name:"IDStringsConversionOps", replaceEllipsis:true, customEllipsisReplacements:["return default;","return default;"], additionalFiles:["IProcess.cs"]} -->
```csharp
namespace Acme
Expand Down
Loading
Loading