User-defined conversions

User-defined conversions

C# allows the pre-defined implicit and explicit conversions to be augmented by user-defined conversions. User-defined conversions are introduced by declaring conversion operators (‎10.9.3) in class and struct types.

Permitted user-defined conversions

C# permits only certain user-defined conversions to be declared. In particular, it is not possible to redefine an already existing implicit or explicit conversion. A class or struct is permitted to declare a conversion from a source type S to a target type T only if all of the following are true:

S and T are different types.

Either S or T is the class or struct type in which the operator declaration takes place.

Neither S nor T is object or an interface-type.

T is not a base class of S, and S is not a base class of T.

The restrictions that apply to user-defined conversions are discussed further in ‎10.9.3.

Evaluation of user-defined conversions

A user-defined conversion converts a value from its type, called the source type, to another type, called the target type. Evaluation of a user-defined conversion centers on finding the most specific user-defined conversion operator for the particular source and target types. This determination is broken into several steps:

Finding the set of classes and structs from which user-defined conversion operators will be considered. This set consists of the source type and its base classes and the target type and its base classes (with the implicit assumptions that only classes and structs can declare user-defined operators, and that non-class types have no base classes).

From that set of types, determining which user-defined conversion operators are applicable. For a conversion operator to be applicable, it must be possible to perform a standard conversion (‎6.3) from the source type to the operand type of the operator, and it must be possible to perform a standard conversion from the result type of the operator to the target type.

From the set of applicable user-defined operators, determining which operator is unambiguously the most specific. In general terms, the most specific operator is the operator whose operand type is "closest" to the source type and whose result type is "closest" to the target type. The exact rules for establishing the most specific user-defined conversion operator are defined in the following sections.

Once a most specific user-defined conversion operator has been identified, the actual execution of the user-defined conversion involves up to three steps:

First, if required, performing a standard conversion from the source type to the operand type of the user-defined conversion operator.

Next, invoking the user-defined conversion operator to perform the conversion.

Finally, if required, performing a standard conversion from the result type of the user-defined conversion operator to the target type.

Evaluation of a user-defined conversion never involves more than one user-defined conversion operator. In other words, a conversion from type S to type T will never first execute a user-defined conversion from S to X and then execute a user-defined conversion from X to T.

Exact definitions of evaluation of user-defined implicit or explicit conversions are given in the following sections. The definitions make use of the following terms:

If a standard implicit conversion (‎6.3.1) exists from a type A to a type B, and if neither A nor B are interface-types, then A is said to be encompassed by B, and B is said to encompass A.

The most encompassing type in a set of types is the one type that encompasses all other types in the set. If no single type encompasses all other types, then the set has no most encompassing type. In more intuitive terms, the most encompassing type is the "largest" type in the set-the one type to which each of the other types can be implicitly converted.

The most encompassed type in a set of types is the one type that is encompassed by all other types in the set. If no single type is encompassed by all other types, then the set has no most encompassed type. In more intuitive terms, the most encompassed type is the "smallest" type in the set-the one type that can be implicitly converted to each of the other types.

User-defined implicit conversions

A user-defined implicit conversion from type S to type T is processed as follows:

Find the set of types, D, from which user-defined conversion operators will be considered. This set consists of S (if S is a class or struct), the base classes of S (if S is a class), T (if T is a class or struct), and the base classes of T (if T is a class).

Find the set of applicable user-defined conversion operators, U. This set consists of the user-defined implicit conversion operators declared by the classes or structs in D that convert from a type encompassing S to a type encompassed by T. If U is empty, the conversion is undefined and an error occurs.

Find the most specific source type, S_X, of the operators in U:

If any of the operators in U convert from S, then S_X is S.

Otherwise, S_X is the most encompassed type in the combined set of source types of the operators in U. If no most encompassed type can be found, then the conversion is ambiguous and an error occurs.

Find the most specific target type, T_X, of the operators in U:

If any of the operators in U convert to T, then T_X is T.

Otherwise, T_X is the most encompassing type in the combined set of target types of the operators in U. If no most encompassing type can be found, then the conversion is ambiguous and an error occurs.

If U contains exactly one user-defined conversion operator that converts from S_X to T_X, then this is the most specific conversion operator. If no such operator exists, or if more than one such operator exists, then the conversion is ambiguous and an error occurs. Otherwise, the user-defined conversion is applied:

If S is not S_X, then a standard implicit conversion from S to S_X is performed.

The most specific user-defined conversion operator is invoked to convert from S_X to T_X.

If T_X is not T, then a standard implicit conversion from T_X to T is performed.

User-defined explicit conversions

A user-defined explicit conversion from type S to type T is processed as follows:

Find the set of types, D, from which user-defined conversion operators will be considered. This set consists of S (if S is a class or struct), the base classes of S (if S is a class), T (if T is a class or struct), and the base classes of T (if T is a class).

Find the set of applicable user-defined conversion operators, U. This set consists of the user-defined implicit or explicit conversion operators declared by the classes or structs in D that convert from a type encompassing or encompassed by S to a type encompassing or encompassed by T. If U is empty, the conversion is undefined and an error occurs.

Find the most specific source type, S_X, of the operators in U:

If any of the operators in U convert from S, then S_X is S.

Otherwise, if any of the operators in U convert from types that encompass S, then S_X 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 an error occurs.

Otherwise, S_X is the most encompassing type in the combined set of source types of the operators in U. If no most encompassing type can be found, then the conversion is ambiguous and an error occurs.

Find the most specific target type, T_X, of the operators in U:

If any of the operators in U convert to T, then T_X is T.

Otherwise, if any of the operators in U convert to types that are encompassed by T, then T_X is the most encompassing type in the combined set of source types of those operators. If no most encompassing type can be found, then the conversion is ambiguous and an error occurs.

Otherwise, T_X is the most encompassed type in the combined set of target types of the operators in U. If no most encompassed type can be found, then the conversion is ambiguous and an error occurs.

If U contains exactly one user-defined conversion operator that converts from S_X to T_X, then this is the most specific conversion operator. If no such operator exists, or if more than one such operator exists, then the conversion is ambiguous and an error occurs. Otherwise, the user-defined conversion is applied:

If S is not S_X, then a standard explicit conversion from S to S_X is performed.

The most specific user-defined conversion operator is invoked to convert from S_X to T_X.

If T_X is not T, then a standard explicit conversion from T_X to T is performed.