diff --git a/standard/basic-concepts.md b/standard/basic-concepts.md index 845a86529..c5c98aa18 100644 --- a/standard/basic-concepts.md +++ b/standard/basic-concepts.md @@ -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: diff --git a/standard/classes.md b/standard/classes.md index 7f702e22f..17cf9a13e 100644 --- a/standard/classes.md +++ b/standard/classes.md @@ -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` | `/` | @@ -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 @@ -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 @@ -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: @@ -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* + + + > *Example*: The following example shows an implementation and subsequent usage of operator++ for an integer vector class: > > @@ -5088,7 +5104,7 @@ 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: @@ -5096,6 +5112,8 @@ Certain binary operators require pair-wise declaration. For every declaration of - 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. @@ -5196,7 +5214,7 @@ For all types but `object`, the operators declared by the `Convertible` 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* diff --git a/standard/conversions.md b/standard/conversions.md index a329b449c..fdd04cb33 100644 --- a/standard/conversions.md +++ b/standard/conversions.md @@ -809,8 +809,11 @@ A user-defined explicit conversion from an expression `E` to a type `T` is pro - 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. @@ -1101,6 +1104,12 @@ Not every lambda expression can be converted to expression tree types. The conve > > *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. diff --git a/standard/documentation-comments.md b/standard/documentation-comments.md index a6dbfbde9..f08b75313 100644 --- a/standard/documentation-comments.md +++ b/standard/documentation-comments.md @@ -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** @@ -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`. + ```csharp namespace Acme diff --git a/standard/expressions.md b/standard/expressions.md index 142e87ff6..135e3a23d 100644 --- a/standard/expressions.md +++ b/standard/expressions.md @@ -264,7 +264,10 @@ An operation of the form `x «op» y`, where «op» is an overloadable binary Given a type `T` and an operation `operator «op»(A)`, where «op» is an overloadable operator and `A` is an argument list, the set of candidate user-defined operators provided by `T` for operator `«op»(A)` is determined as follows: - Determine the type `T₀`. If `T` is a nullable value type, `T₀` is its underlying type; otherwise, `T₀` is equal to `T`. -- For all `operator «op»` declarations in `T₀` and all lifted forms of such operators, if at least one operator is applicable ([§12.6.4.2](expressions.md#12642-applicable-function-member)) with respect to the argument list `A`, then the set of candidate operators consists of all such applicable operators in `T₀`. +- Find the set of user-defined operators, `U`. This set consists of: + - In an `unchecked` evaluation context, all regular `operator «op»` declarations in `T₀`. + - In a `checked` evaluation context, all checked and regular `operator «op»` declarations in `T₀` (see [§15.10.1](classes.md#15101-general)) except regular declarations that have a pair-wise matching checked operator declaration. +- For all operators in `U` and all lifted forms of such operators, if at least one operator is applicable ([§12.6.4.2](expressions.md#12642-applicable-function-member)) with respect to the argument list `A`, then the set of candidate operators consists of all such applicable operators. - Otherwise, if `T₀` is `object`, the set of candidate operators is empty. - Otherwise, the set of candidate operators provided by `T₀` is the set of candidate operators provided by the direct base class of `T₀`, or the effective base class of `T₀` if `T₀` is a type parameter. @@ -3427,7 +3430,7 @@ For all other operand types, the `sizeof` operator is specified in [§24.6.9](un ### 12.8.20 The checked and unchecked operators -The `checked` and `unchecked` operators are used to control the overflow-checking context for integral-type arithmetic operations and conversions. +The `checked` and `unchecked` operators are used to control the overflow-checking context for integral-type arithmetic operations and conversions. They may also be used to control the overflow-checking context for various operations and conversions involving user-defined types ([§15.10.1](classes.md#15101-general)). ```ANTLR checked_expression @@ -3449,12 +3452,16 @@ The following operations are affected by the overflow checking context establish - The predefined `-` unary operator ([§12.9.3](expressions.md#1293-unary-minus-operator)), when the operand is of an integral type. - The predefined `+`, `-`, `*`, and `/` binary operators ([§12.13](expressions.md#1213-arithmetic-operators)), when both operands are of integral or enum types. - Explicit numeric conversions ([§10.3.2](conversions.md#1032-explicit-numeric-conversions)) from one integral or enum type to another integral or enum type, or from `float` or `double` to an integral or enum type. +- User-defined `++`, `--`, unary `-`, and binary `+`, `-`, `*`, and `/` operators ([§15.10.1](classes.md#15101-general)), when a checked form of the operator is declared on the operand type. +- User-defined explicit conversion operators ([§15.10.4](classes.md#15104-conversion-operators)), when a checked form of the conversion operator is declared. -When one of the above operations produces a result that is too large to represent in the destination type, the context in which the operation is performed controls the resulting behavior: +When one of the predefined operators or explicit numeric conversions listed above produces a result that is too large to represent in the destination type, the context in which the operation is performed controls the resulting behavior: - In a `checked` context, if the operation is a constant expression ([§12.26](expressions.md#1226-constant-expressions)), a compile-time error occurs. Otherwise, when the operation is performed at run-time, a `System.OverflowException` is thrown. - In an `unchecked` context, the result is truncated by discarding any high-order bits that do not fit in the destination type. +For user-defined operators and conversions, the overflow checking context affects the selection of the operator ([§12.4.6](expressions.md#1246-candidate-user-defined-operators), [§10.5.5](conversions.md#1055-user-defined-explicit-conversions)). It does not impose overflow behavior on the selected operator or change the overflow checking context of its body ([§15.10.1](classes.md#15101-general)). + For non-constant expressions ([§12.26](expressions.md#1226-constant-expressions)) (expressions that are evaluated at run-time) that are not enclosed by any `checked` or `unchecked` operators or statements, the default overflow checking context is unchecked, unless external factors (such as compiler switches and execution environment configuration) call for checked evaluation. For constant expressions ([§12.26](expressions.md#1226-constant-expressions)) (expressions that can be fully evaluated at compile-time), the default overflow checking context is always checked. Unless a constant expression is explicitly placed in an `unchecked` context, overflows that occur during the compile-time evaluation of the expression always cause compile-time errors. diff --git a/standard/standard-library.md b/standard/standard-library.md index 5e491c7a2..09df4d919 100644 --- a/standard/standard-library.md +++ b/standard/standard-library.md @@ -372,6 +372,16 @@ namespace System.Reflection { protected MemberInfo(); } + + public abstract class MethodBase : MemberInfo + { + protected MethodBase(); + } + + public abstract class MethodInfo : MethodBase + { + protected MethodInfo(); + } } namespace System.Runtime.CompilerServices @@ -781,10 +791,37 @@ namespace System.Diagnostics.CodeAnalysis namespace System.Linq.Expressions { - public sealed class Expression + public class BinaryExpression : Expression + { + public System.Reflection.MethodInfo? Method { get; } + } + + public abstract class Expression + { + protected Expression(); + public static UnaryExpression NegateChecked(Expression expression, + System.Reflection.MethodInfo? method); + public static BinaryExpression AddChecked(Expression left, + Expression right, System.Reflection.MethodInfo? method); + public static BinaryExpression SubtractChecked(Expression left, + Expression right, System.Reflection.MethodInfo? method); + public static BinaryExpression MultiplyChecked(Expression left, + Expression right, System.Reflection.MethodInfo? method); + public static UnaryExpression ConvertChecked(Expression expression, + System.Type type, System.Reflection.MethodInfo? method); + } + + public sealed class Expression : LambdaExpression { public TDelegate Compile(); } + + public abstract class LambdaExpression : Expression { } + + public sealed class UnaryExpression : Expression + { + public System.Reflection.MethodInfo? Method { get; } + } } namespace System.Runtime.CompilerServices diff --git a/standard/statements.md b/standard/statements.md index 7eff86545..8f027f16b 100644 --- a/standard/statements.md +++ b/standard/statements.md @@ -1937,7 +1937,7 @@ The end point of a `try` statement is reachable if both of the following are tru ## 13.12 The checked and unchecked statements -The `checked` and `unchecked` statements are used to control the ***overflow-checking context*** for integral-type arithmetic operations and conversions. +The `checked` and `unchecked` statements are used to control the ***overflow-checking context*** for integral-type arithmetic operations and conversions. They may also be used to control the overflow-checking context for various operations and conversions involving user-defined types ([§15.10.1](classes.md#15101-general)). ```ANTLR checked_statement