6. Conversions
A conversion enables an expression to be treated as being of a particular type. A conversion may cause an expression of a given type to be treated as having a different type, or it may cause an expression without a type to get a type. Conversions can be implicit or explicit, a classification that determines whether an explicit cast is required. For instance, the conversion from type int to type long is implicit, so expressions of type int can implicitly be treated as type long. The opposite conversion, from type long to type int, is explicit, so an explicit cast is required.
int a = 123;
long b = a; // Implicit conversion from int to long
int c = (int) b; // Explicit conversion from long to int
Some conversions are defined by the language. Programs may also define their own conversions (§6.4).
The classification of conversions into “explicit” and “implicit” is handy when the developer needs to know whether a given conversion might fail at runtime. None of the implicit conversions ever fail, but explicit conversions might.
Another way of partitioning conversions that this specification does not consider in depth would be into representation-preserving and representation-changing conversions. For example, an explicit conversion from a base class (Animal) to a derived class (Giraffe) might fail at runtime if the expression converted is not an instance of Giraffe. If it does succeed, at least we know that the conversion will result in exactly the same object. An implicit conversion from int to double, however, always succeeds but always changes the representation; a brand-new double value is created, which has a completely different representation than the integer.
This partitioning of conversions will become important when we get to covariant array conversions.
6.1 Implicit Conversions
The following conversions are classified as implicit conversions:
• Identity conversions
• Implicit numeric conversions
• Implicit enumeration conversions
• Implicit nullable conversions
• Null literal conversions
• Implicit reference conversions
• Boxing conversions
• Implicit constant expression conversions
• User-defined implicit conversions
• Anonymous function conversions
• Method group conversions
Implicit conversions can occur in a variety of situations, including function member invocations (§7.4.4), cast expressions (§7.6.6), and assignments (§7.16).
The predefined implicit conversions always succeed and never cause exceptions to be thrown. Properly designed user-defined implicit conversions should exhibit these characteristics as well.
6.1.1 Identity Conversion
An identity conversion converts from any type to the same type. This conversion exists only such that an entity that already has a required type can be said to be convertible to that type.
6.1.2 Implicit Numeric Conversions
The implicit numeric conversions are listed here:
• From sbyte to short, int, long, float, double, or decimal
• From byte to short, ushort, int, uint, long, ulong, float, double, or decimal
• From short to int, long, float, double, or decimal
• From ushort to int, uint, long, ulong, float, double, or decimal
• From int to long, float, double, or decimal
• From uint to long, ulong, float, double, or decimal
• From long to float, double, or decimal
• From ulong to float, double, or decimal
• From char to ushort, int, uint, long, ulong, float, double, or decimal
• From float to double
Conversions from int, uint, long, or ulong to float and from long or ulong to double may cause a loss of precision, but will never cause a loss of magnitude. The other implicit numeric conversions never lose any information.
There are no implicit conversions to the char type, so values of the other integral types do not automatically convert to the char type.
6.1.3 Implicit Enumeration Conversions
An implicit enumeration conversion permits the decimal-integer-literal 0 to be converted to any enum-type and to any nullable-type whose underlying type is an enum-type. In the latter case, the conversion is evaluated by converting to the underlying enum-type and wrapping the result (§4.1.10).
This issue is particularly important for enums that represent a set of flags. To be compliant with CLR guidelines, it is a good idea for enum types intended to be used as flags to be marked with the [Flags] attribute and to have a “None” value set to zero. But for those that do no meet these criteria, it is nice to be able to assign zero without having to cast.
Lots more dos and don’ts exist regarding proper use of enumerated types. See section 4.8 of “Framework Design Guidelines” for details.
The Microsoft implementation of C# 3.0 allows any constant zero to go to any enum, not just literal constant zeros. This minor specification violation exists for historical reasons.
The default value for an enum type is 0, so assigning the literal 0 provides a consistent means of resetting an enum variable to its default value. For combinable flags-based enums, 0 means “no flags.”
6.1.4 Implicit Nullable Conversions
Predefined implicit conversions that operate on non-nullable value types can also be used with nullable forms of those types. For each of the predefined implicit identity and numeric conversions that convert from a non-nullable value type S to a non-nullable value type T, the following implicit nullable conversions exist:
• An implicit conversion from S? to T?
• An implicit conversion from S to T?
Evaluation of an implicit nullable conversion based on an underlying conversion from S to T proceeds as follows:
• If the nullable conversion is from S? to T?:
- If the source value is null (HasValue property is false), the result is the null value of type T?.
- Otherwise, the conversion is evaluated as an unwrapping from S? to S, followed by the underlying conversion from S to T, followed by a wrapping (§4.1.10) from T to T?.
• If the nullable conversion is from S to T?, the conversion is evaluated as the underlying conversion from S to T followed by a wrapping from T to T?.
6.1.5 Null Literal Conversions
An implicit conversion exists from the null literal to any nullable type. This conversion produces the null value (§4.1.10) of the given nullable type.
6.1.6 Implicit Reference Conversions
The implicit reference conversions are as follows:
• From any reference-type to object.
• From any class-type S to any class-type T, provided S is derived from T.
• From any class-type S to any interface-type T, provided S implements T.
• From any interface-type S to any interface-type T, provided S is derived from T.
• From an array-type S with an element type SE to an array-type T with an element type TE, provided all of the following are true:
- S and T differ only in element type. In other words, S and T have the same number of dimensions.
- Both SE and TE are reference-types.
- An implicit reference conversion exists from SE to TE.
The fact that both SE and TE are reference-types means that array conversion is illegal for arrays of numeric types.
Covariant array conversions were a controversial addition to the CLI and C#. This kind of conversion breaks type safety on arrays. You might assume that you can put a Turtle into an array of Animals, but it is legal to implicitly convert an array of Giraffes to an expression typed as being an array of Animals. When you attempt to add the Turtle to that thing, the runtime environment will disallow the conversion from Turtle to Giraffe. Thus it is sometimes not legal to put a Turtle into an array of Animals, and you will not know that fact until runtime. The compiler is unable to catch this type of error.
This is a place where it would be useful to characterize conversions as representation-preserving or representation-changing, rather than implicit or explicit.
The CLI rules for covariant array conversions require that the conversion from the source to the destination type preserve representation at runtime. For example, converting an array of ten integers into an array of ten doubles would end up allocating memory for each double, so it could not be done cheaply “in place.” By contrast, converting an array of Giraffes into an array of Animals preserves the representation of every element in the array at runtime, thereby preserving the representation of the array itself.
Because reference conversions always preserve the representation, the C# language restricts explicit and implicit covariant array conversions to those where the conversion between the element types is a reference conversion.
• From any array-type to System.Array and the interfaces it implements.
• From a single-dimensional array type S[] to System.Collections.Generic.IList<T> and its base interfaces, provided that there is an implicit identity or reference conversion from S to T.
• From any delegate-type to System.Delegate and the interfaces it implements.
• From the null literal to any reference-type.
• Implicit conversions involving type parameters that are known to be reference types. See §6.1.9 for more details on implicit conversions involving type parameters.
The implicit reference conversions are those conversions between reference-types that can be proven to always succeed; for this reason, the conversions do not require checks at runtime.
Reference conversions—whether implicit or explicit—never change the referential identity of the object being converted. In other words, while a reference conversion may change the type of the reference, it never changes the type or value of the object being referred to.
Unlike array types, constructed reference types do not exhibit “covariant” conversions. As a consequence, a type List<B> has no conversion (either implicit or explicit) to List<A> even if B is derived from A. Likewise, no conversion exists from List<B> to List<object>.
This constraint is intended to prevent the same sorts of problems that presently plague covariant arrays.
6.1.7 Boxing Conversions
A boxing conversion permits a value-type to be implicitly converted to a reference type. Such a conversion exists from any non-nullable-value-type to object, to System.ValueType and to any interface-type implemented by the non-nullable-value-type. Furthermore, an enum-type can be converted to the type System.Enum.
A boxing conversion exists from a nullable-type to a reference type if and only if a boxing conversion exists from the underlying non-nullable-value-type to the reference type.
Boxing a value of a non-nullable-value-type consists of allocating an object instance and copying the value-type value into that instance. A struct can be boxed to the type System.ValueType, as that is a base class for all structs (§11.3.2).
Boxing a value of a nullable-type proceeds as follows:
• If the source value is null (HasValue property is false), the result is a null reference of the target type.
• Otherwise, the result is a reference to a boxed T produced by unwrapping and boxing the source value.
Boxing conversions are described further in §4.3.1.
6.1.8 Implicit Constant Expression Conversions
An implicit constant expression conversion permits the following conversions:
• A constant-expression (§7.18) of type int can be converted to type sbyte, byte, short, ushort, uint, or ulong, provided the value of the constant-expression is within the range of the destination type.
• A constant-expression of type long can be converted to type ulong, provided the value of the constant-expression is not negative.
6.1.9 Implicit Conversions Involving Type Parameters
The following implicit conversions exist for a given type parameter T:
• From T to its effective base class C, from T to any base class of C, and from T to any interface implemented by C. At runtime, if T is a value type, the conversion is executed as a boxing conversion. Otherwise, the conversion is executed as an implicit reference conversion or identity conversion.
• From T to an interface type I in T’s effective interface set and from T to any base interface of I. At runtime, if T is a value type, the conversion is executed as a boxing conversion. Otherwise, the conversion is executed as an implicit reference conversion or identity conversion.
• From T to a type parameter U, provided T depends on U (§10.1.5). At runtime, if U is a value type, then T and U are necessarily the same type and no conversion is performed. Otherwise, if T is a value type, the conversion is executed as a boxing conversion. Otherwise, the conversion is executed as an implicit reference conversion or identity conversion.
• From the null literal to T, provided T is known to be a reference type.
If T is known to be a reference type (§10.1.5), the previously mentioned conversions are all classified as implicit reference conversions (§6.1.6). If T is not known to be a reference type, these conversions are classified as boxing conversions (§6.1.7).
6.1.10 User-Defined Implicit Conversions
A user-defined implicit conversion consists of an optional standard implicit conversion, followed by execution of a user-defined implicit conversion operator, followed by another optional standard implicit conversion. The exact rules for evaluating user-defined implicit conversions are described in §6.4.4.
6.1.11 Anonymous Function Conversions and Method Group Conversions
Anonymous functions and method groups do not have types in and of themselves, but may be implicitly converted to delegate types or expression tree types. Anonymous function conversions are described in more detail in §6.5 and method group conversions in §6.6.
6.2 Explicit Conversions
The following conversions are classified as explicit conversions:
• All implicit conversions
• Explicit numeric conversions
• Explicit enumeration conversions
• Explicit nullable conversions
• Explicit reference conversions
• Explicit interface conversions
• Unboxing conversions
• User-defined explicit conversions
Explicit conversions can occur in cast expressions (§7.6.6).
The set of explicit conversions includes all implicit conversions. This means that redundant cast expressions are allowed.
The explicit conversions that are not implicit conversions are conversions that cannot be proven to always succeed, conversions that are known to possibly lose information, and conversions across domains of types sufficiently different to merit explicit notation.
Explicit conversions might or might not succeed at runtime. Any conversion that the compiler can prove will never succeed is typically an error. Consider, for example, casting (IFoo)x, where x is a variable of a sealed class type that does not implement interface IFoo. There is no possible way that this cast will succeed at runtime, so it is a compile-time error to even try to make the cast.
6.2.1 Explicit Numeric Conversions
The explicit numeric conversions are the conversions from a numeric-type to another numeric-type for which an implicit numeric conversion (§6.1.2) does not already exist:
• From sbyte to byte, ushort, uint, ulong, or char
• From byte to sbyte and char
• From short to sbyte, byte, ushort, uint, ulong, or char
• From ushort to sbyte, byte, short, or char
• From int to sbyte, byte, short, ushort, uint, ulong, or char
• From uint to sbyte, byte, short, ushort, int, or char
• From long to sbyte, byte, short, ushort, int, uint, ulong, or char
• From ulong to sbyte, byte, short, ushort, int, uint, long, or char
• From char to sbyte, byte, or short
• From float to sbyte, byte, short, ushort, int, uint, long, ulong, char, or decimal
• From double to sbyte, byte, short, ushort, int, uint, long, ulong, char, float, or decimal
• From decimal to sbyte, byte, short, ushort, int, uint, long, ulong, char, float, or double
Because the explicit conversions include all implicit and explicit numeric conversions, it is always possible to convert from any numeric-type to any other numeric-type using a cast expression (§7.6.6).
The explicit numeric conversions might possibly lose information or possibly cause exceptions to be thrown. An explicit numeric conversion is processed as follows:
• For a conversion from an integral type to another integral type, the processing depends on the overflow checking context (§7.5.12) in which the conversion takes place:
- In a checked context, the conversion succeeds if the value of the source operand is within the range of the destination type, but throws a System.OverflowException if the value of the source operand is outside the range of the destination type.
- In an unchecked context, the conversion always succeeds, and proceeds as follows:
• If the source type is larger than the destination type, then the source value is truncated by discarding its “extra” most significant bits. The result is then treated as a value of the destination type.
• If the source type is smaller than the destination type, then the source value is either sign-extended or zero-extended so that it is the same size as the destination type. Sign-extension is used if the source type is signed; zero-extension is used if the source type is unsigned. The result is then treated as a value of the destination type.
• If the source type is the same size as the destination type, then the source value is treated as a value of the destination type.
• For a conversion from decimal to an integral type, the source value is rounded toward zero to the nearest integral value, and this integral value becomes the result of the conversion. If the resulting integral value is outside the range of the destination type, a System.OverflowException is thrown.
• For a conversion from float or double to an integral type, the processing depends on the overflow checking context (§7.5.12) in which the conversion takes place:
- In a checked context, the conversion proceeds as follows:
• If the value of the operand is NaN or infinite, a System.OverflowException is thrown.
• Otherwise, the source operand is rounded toward zero to the nearest integral value. If this integral value is within the range of the destination type, then this value is the result of the conversion.
• Otherwise, a System.OverflowException is thrown.
- In an unchecked context, the conversion always succeeds, and proceeds as follows:
• If the value of the operand is NaN or infinite, the result of the conversion is an unspecified value of the destination type.
• Otherwise, the source operand is rounded toward zero to the nearest integral value. If this integral value is within the range of the destination type then this value is the result of the conversion.
• Otherwise, the result of the conversion is an unspecified value of the destination type.
• For a conversion from double to float, the double value is rounded to the nearest float value. If the double value is too small to represent as a float, the result becomes positive zero or negative zero. If the double value is too large to represent as a float, the result becomes positive infinity or negative infinity. If the double value is NaN, the result is also NaN.
• For a conversion from float or double to decimal, the source value is converted to decimal representation and rounded to the nearest number after the 28th decimal place if required (§4.1.7). If the source value is too small to represent as a decimal, the result becomes zero. If the source value is NaN, infinity, or too large to represent as a decimal, a System.OverflowException is thrown.
• For a conversion from decimal to float or double, the decimal value is rounded to the nearest double or float value. While this conversion may lose precision, it never causes an exception to be thrown.
The round-to-zero behavior in the real-to-integral conversions is efficient but not always the most useful approach. For instance, (int) 3.9 evaluates to 3, rather than 4. C# provides no built-in mechanism for converting to the nearest integer; this capability is left to external libraries. In Microsoft’s .NET Framework, the static Convert class provides this functionality via methods such as ToInt32.
6.2.2 Explicit Enumeration Conversions
The explicit enumeration conversions are listed here:
• From sbyte, byte, short, ushort, int, uint, long, ulong, char, float, double, or decimal to any enum-type
• From any enum-type to sbyte, byte, short, ushort, int, uint, long, ulong, char, float, double, or decimal
• From any enum-type to any other enum-type
An explicit enumeration conversion between two types is processed by treating any participating enum-type as the underlying type of that enum-type, and then performing an implicit or explicit numeric conversion between the resulting types. For example, given an enum-type E with an underlying type of int, a conversion from E to byte is processed as an explicit numeric conversion (§6.2.1) from int to byte, and a conversion from byte to E is processed as an implicit numeric conversion (§6.1.2) from byte to int.
6.2.3 Explicit Nullable Conversions
Explicit nullable conversions permit predefined explicit conversions that operate on non-nullable value types to be used with nullable forms of those types. For each of the predefined explicit conversions that convert from a non-nullable value type S to a non-nullable value type T (§6.1.1, §6.1.2, §6.1.3, §6.2.1, and §6.2.2), the following nullable conversions exist:
• An explicit conversion from S? to T?
• An explicit conversion from S to T?
• An explicit conversion from S? to T
Evaluation of a nullable conversion based on an underlying conversion from S to T proceeds as follows:
• If the nullable conversion is from S? to T?:
- If the source value is null (HasValue property is false), the result is the null value of type T?.
- Otherwise, the conversion is evaluated as an unwrapping from S? to S, followed by the underlying conversion from S to T, followed by a wrapping from T to T?.
• If the nullable conversion is from S to T?, the conversion is evaluated as the underlying conversion from S to T followed by a wrapping from T to T?.
• If the nullable conversion is from S? to T, the conversion is evaluated as an unwrapping from S? to S followed by the underlying conversion from S to T.
Note that an attempt to unwrap a nullable value will throw an exception if the value is null.
6.2.4 Explicit Reference Conversions
The explicit reference conversions are listed here:
• From object to any other reference-type.
• From any class-type S to any class-type T, provided S is a base class of T.
• From any class-type S to any interface-type T, provided S is not sealed and provided S does not implement T.
• From any interface-type S to any class-type T, provided T is not sealed or provided T implements S.
• From any interface-type S to any interface-type T, provided S is not derived from T.
• From an array-type S with an element type SE to an array-type T with an element type TE, provided all of the following are true:
- S and T differ only in element type. In other words, S and T have the same number of dimensions.
- Both SE and TE are reference-types.
- An explicit reference conversion exists from SE to TE.
• From System.Array and the interfaces it implements to any array-type.
• From a single-dimensional array type S[ ] to System.Collections.Generic.IList<T> and its base interfaces, provided that there is an explicit reference conversion from S to T.
• From System.Collections.Generic.IList<S> and its base interfaces to a single-dimensional array type T[ ], provided that there is an explicit identity or reference conversion from S to T.
• From System.Delegate and the interfaces it implements to any delegate-type.
• Explicit conversions involving type parameters that are known to be reference types. For more details on explicit conversions involving type parameters, see §6.2.6.
The explicit reference conversions are those conversions between reference types that require runtime checks to ensure they are correct.
For an explicit reference conversion to succeed at runtime, either the value of the source operand must be null or the actual type of the object referenced by the source operand must be a type that can be converted to the destination type by an implicit reference conversion (§6.1.6). If an explicit reference conversion fails, a System.InvalidCastException is thrown.
Reference conversions—whether implicit or explicit—never change the referential identity of the object being converted. In other words, although a reference conversion may change the type of the reference, it never changes the type or value of the object being referred to.
6.2.5 Unboxing Conversions
An unboxing conversion permits a reference type to be explicitly converted to a value-type. An unboxing conversion exists from the types object and System.ValueType to any non-nullable-value-type, and from any interface-type to any non-nullable-value-type that implements the interface-type. Furthermore, type System.Enum can be unboxed to any enum-type.
An unboxing conversion exists from a reference type to a nullable-type if an unboxing conversion exists from the reference type to the underlying non-nullable-value-type of the nullable-type.
An unboxing operation consists of first checking that the object instance is a boxed value of the given value-type, and then copying the value out of the instance. Unboxing a null reference to a nullable-type produces the null value of the nullable-type. A struct can be unboxed from the type System.ValueType, as that is a base class for all structs (§11.3.2).
Unboxing conversions are described further in §4.3.2.
6.2.6 Explicit Conversions Involving Type Parameters
The following explicit conversions exist for a given type parameter T:
• From the effective base class C of T to T and from any base class of C to T. At runtime, if T is a value type, the conversion is executed as an unboxing conversion. Otherwise, the conversion is executed as an explicit reference conversion or identity conversion.
• From any interface type to T. At runtime, if T is a value type, the conversion is executed as an unboxing conversion. Otherwise, the conversion is executed as an explicit reference conversion or identity conversion.
• From T to any interface-type I, provided there is not already an implicit conversion from T to I. At run-time, if T is a value type, the conversion is executed as a boxing conversion followed by an explicit reference conversion. Otherwise, the conversion is executed as an explicit reference conversion or identity conversion.
• From a type parameter U to T, provided T depends on U (§10.1.5). At runtime, if U is a value type, then T and U are necessarily the same type and no conversion is performed. Otherwise, if T is a value type, the conversion is executed as an unboxing conversion. Otherwise, the conversion is executed as an explicit reference conversion or identity conversion.
If T is known to be a reference type, the previously mentioned conversions are all classified as explicit reference conversions (§6.2.4). If T is not known to be a reference type, these conversions are classified as unboxing conversions (§6.2.5).
The rules given in this section do not permit a direct explicit conversion from an unconstrained type parameter to a non-interface type, which might be surprising. This rule is intended to prevent confusion and to make the semantics of such conversions clear. For example, consider the following declaration:
class X<T>
{
public static long F(T t) {
return (long)t; // Error
}
}
If the direct explicit conversion of t to int were permitted, one might expect that X<int>.F(7) would return 7L. However, that result would not occur, because the standard numeric conversions are considered only when the types are known to be numeric at compile time. To make the semantics clear, the preceding example must be rewritten as follows:
class X<T>
{
public static long F(T t) {
return (long)(object)t; // Okay, but will only work when T is long
}
}
This code will compile but executing X<int>.F(7) will now throw an exception at runtime, because a boxed int cannot be converted directly to a long.
The behavior of conversions involving type parameters can be further illustrated with the following method:
static T Cast<T>(object value) { return (T)value; }
This method can perform a reference conversion or an unboxing, but never a numeric or user-defined conversion:
string s = Cast<string>("s"); // Okay - reference conversion
int i = Cast<int>(3); // Okay - unboxing
long l = Cast<long>(3); // InvalidCastException: attempts an unboxing
// instead of an int->long numeric conversion
An identical situation arises in the method System.Linq.Enumerable.Cast, a standard query operator in Microsoft’s LINQ implementation.
6.2.7 User-Defined Explicit Conversions
A user-defined explicit conversion consists of an optional standard explicit conversion, followed by execution of a user-defined implicit or explicit conversion operator, followed by another optional standard explicit conversion. The exact rules for evaluating user-defined explicit conversions are described in §6.4.5.
The conversions that “sandwich” the user-defined conversion are explicit conversions and, therefore, might fail themselves. Thus a user-defined explicit conversion has three potential points of failure at runtime, not just one.
Even so, at least the sandwiching conversions are never user-defined conversions themselves. For example, if there is an user-defined explicit conversion from X to Y, and a user-defined explicit conversion from Y to Z, then an attempt to cast X to Z will not succeed.
That said, the chain of explicit conversions can get quite long in contrived scenarios. For example, consider a struct Foo with a user-defined explicit conversion from Foo? to decimal. A cast on an expression of type Footo type int? will convert Foo to Foo?, then Foo? to decimal, then decimal to int, and then int to int?.
6.3 Standard Conversions
The standard conversions are those predefined conversions that can occur as part of a user-defined conversion.
6.3.1 Standard Implicit Conversions
The following implicit conversions are classified as standard implicit conversions:
• Identity conversions (§6.1.1)
• Implicit numeric conversions (§6.1.2)
• Implicit nullable conversions (§6.1.4)
• Implicit reference conversions (§6.1.6)
• Boxing conversions (§6.1.7)
• Implicit constant expression conversions (§6.1.8)
• Implicit conversions involving type parameters (§6.1.9)
The standard implicit conversions specifically exclude user-defined implicit conversions.
6.3.2 Standard Explicit Conversions
The standard explicit conversions are all standard implicit conversions plus the subset of the explicit conversions for which an opposite standard implicit conversion exists. In other words, if a standard implicit conversion exists from a type A to a type B, then a standard explicit conversion exists from type A to type B and from type B to type A.
6.4 User-Defined Conversions
C# allows the predefined implicit and explicit conversions to be augmented by user-defined conversions. User-defined conversions are introduced by declaring conversion operators (§10.10.3) in class and struct types.
Conversions, in general, imply that multiple types are somehow interchangeable. That notion, in turn, implies that one of more of the types may not be necessary. As you write more conversion methods, consider whether you might have created multiple types that serve the same purpose.
When you write conversions for reference types, be sure to preserve the property that the result of a reference conversion always refers to the same object as the source.
6.4.1 Permitted User-Defined Conversions
C# permits only certain user-defined conversions to be declared. In particular, it is not possible to redefine an existing implicit or explicit conversion.
For a given source type S and target type T, if S or T are nullable types, let S0 and T0 refer to their underlying types; otherwise, S0 and T0 are equal to S and T, respectively. 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:
• S0 and T0 are different types.
• Either S0 or T0 is the class or struct type in which the operator declaration takes place.
• Neither S0 nor T0 is an interface-type.
• Excluding user-defined conversions, a conversion does not exist from S to T or from T to S.
The restrictions that apply to user-defined conversions are discussed further in §10.10.3.
6.4.2 Lifted Conversion Operators
Given a user-defined conversion operator that converts from a non-nullable value type S to a non-nullable value type T, a lifted conversion operator exists that converts from S? to T?. This lifted conversion operator performs an unwrapping from S? to S, followed by the user-defined conversion from S to T, followed by a wrapping from T to T?, except that a null-valued S? converts directly to a null-valued T?.
A lifted conversion operator has the same implicit or explicit classification as its underlying user-defined conversion operator. The term “user-defined conversion” applies to the use of both user-defined and lifted conversion operators.
6.4.3 Evaluation of User-Defined Conversions
A user-defined conversion converts a value from its type, called thesource type, to another type, called the target type. Evaluation of a user-defined conversion centers on finding themost 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 nonclass types have no base classes). For the purposes of this step, if either the source type or the target type is a nullable-type, their underlying type is used instead.
• From that set of types, determining which user-defined and lifted 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. User-defined conversion operators are preferred over lifted conversion operators. 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:
1. If required, perform a standard conversion from the source type to the operand type of the user-defined or lifted conversion operator.
2. Invoke the user-defined or lifted conversion operator to perform the conversion.
3. If required, perform a standard conversion from the result type of the user-defined or lifted conversion operator to the target type.
Evaluation of a user-defined conversion never involves more than one user-defined or lifted 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 is an interface-type, 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.
The more conversion operators you write, the more likely it becomes that you will introduce ambiguities among conversions. Those ambiguities will make your class more difficult to use.
6.4.4 User-Defined Implicit Conversions
A user-defined implicit conversion from type S to type T is processed as follows:
• Determine the types S0 and T0. If S or T is a nullable type, S0 and T0 are their underlying types; otherwise, S0 and T0 are equal to S and T, respectively.
• Find the set of types, D, from which user-defined conversion operators will be considered. This set consists of S0 (if S0 is a class or struct), the base classes of S0 (if S0 is a class), and T0 (if T0 is a class or struct).
• Find the set of applicable user-defined and lifted conversion operators, U. This set consists of the user-defined and lifted 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 a compile-time error occurs.
• Find the most specific source type, SX, of the operators in U:
- If any of the operators in U convert from S, then SX is S.
- Otherwise, SX is the most encompassed type in the combined set of source types of the operators in U. If exactly one most encompassed type cannot be found, then the conversion is ambiguous and a compile-time error occurs.
• Find the most specific target type, TX, of the operators in U:
- If any of the operators in U convert to T, then TX is T.
- Otherwise, TX is the most encompassing type in the combined set of target types of the operators in U. If exactly one most encompassing type cannot be found, then the conversion is ambiguous and a compile-time error occurs.
• Find the most specific conversion operator:
- If U contains exactly one user-defined conversion operator that converts from SX to TX, then it is the most specific conversion operator.
- Otherwise, if U contains exactly one lifted conversion operator that converts from SX to TX, then it is the most specific conversion operator.
- Otherwise, the conversion is ambiguous and a compile-time error occurs.
- If S is not SX, then a standard implicit conversion from S to SX is performed.
- The most specific conversion operator is invoked to convert from SX to TX.
- If TX is not T, then a standard implicit conversion from TX to T is performed.
Be careful with user-defined implicit conversions. They are great for building things like math libraries, but for complex type conversions, a more readable and maintainable strategy is to build explicit methods into your classes to convert from one type to another [for example, Item.ToUpdateItem()]. I had a lengthy discussion about this issue with Craig Andera once, and his recommendation was a simple one: “If you find yourself typing public static operator, you’re doing something wrong.” This position may be a bit extreme, but you should definitely think twice.
6.4.5 User-Defined Explicit Conversions
A user-defined explicit conversion from type S to type T is processed as follows:
• Determine the types S0 and T0. If S or T is a nullable type, S0 and T0 are their underlying types; otherwise, S0 and T0 are equal to S and T, respectively.
• Find the set of types, D, from which user-defined conversion operators will be considered. This set consists of S0 (if S0 is a class or struct), the base classes of S0 (if S0 is a class), T0 (if T0 is a class or struct), and the base classes of T0 (if T0 is a class).
• 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 or encompassed by S 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, SX, of the operators in U:
- If any of the operators in U convert from S, then SX is S.
- Otherwise, if any of the operators in U convert from types that encompass S, then SX 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.
- Otherwise, SX is the most encompassing type in the combined set of source types of the operators in U. If exactly one most encompassing type cannot be found, then the conversion is ambiguous and a compile-time error occurs.
• Find the most specific target type, TX, of the operators in U:
- If any of the operators in U convert to T, then TX is T.
- Otherwise, if any of the operators in U convert to types that are encompassed by T, then TX is the most encompassing type in the combined set of target types of those operators. If exactly one most encompassing type cannot be found, then the conversion is ambiguous and a compile-time error occurs.
- Otherwise, TX 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 a compile-time error occurs.
• Find the most specific conversion operator:
- If U contains exactly one user-defined conversion operator that converts from SX to TX, then it is the most specific conversion operator.
- Otherwise, if U contains exactly one lifted conversion operator that converts from SX to TX, then it is the most specific conversion operator.
- Otherwise, the conversion is ambiguous and a compile-time error occurs.
• Apply the conversion:
- If S is not SX, then a standard explicit conversion from S to SX is performed.
- The most specific user-defined conversion operator is invoked to convert from SX to TX.
- If TX is not T, then a standard explicit conversion from TX to T is performed.
6.5 Anonymous Function Conversions
An anonymous-method-expression or lambda-expression is classified as an anonymous function (§7.14). The expression does not have a type but can be implicitly converted to a compatible delegate type or expression tree type. Specifically, a delegate type D is compatible with an anonymous function F provided that the following criteria are met:
• If F contains an anonymous-function-signature, then D and F have the same number of parameters.
• If F does not contain an anonymous-function-signature, then D may have zero or more parameters of any type, as long as no parameter of D has the out parameter modifier.
• If F has an explicitly typed parameter list, each parameter in D has the same type and modifiers as the corresponding parameter in F.
• If F has an implicitly typed parameter list, D has no ref or out parameters.
• If D has a void return type and the body of F is an expression, when each parameter of F is given the type of the corresponding parameter in D, the body of F is a valid expression (§7) that would be permitted as a statement-expression (§8.6).
• If D has a void return type and the body of F is a statement block, when each parameter of F is given the type of the corresponding parameter in D, the body of F is a valid statement block (§8.2) in which no return statement specifies an expression.
• If D has a non-void return type and the body of F is an expression, when each parameter of F is given the type of the corresponding parameter in D, the body of F is a valid expression (§7) that is implicitly convertible to the return type of D.
• If D has a non-void return type and the body of F is a statement block, when each parameter of F is given the type of the corresponding parameter in D, the body of F is a valid statement block (§8.2) with a nonreachable end point in which each return statement specifies an expression that is implicitly convertible to the return type of D.
An expression tree type Expression<D> is compatible with an anonymous function F if the delegate type D is compatible with F.
The examples that follow use a generic delegate type Func<A, R>, which represents a function that takes an argument of type A and returns a value of type R:
delegate R Func<A, R>(A arg);
In the assignments
Func<int, int> f1 = x => x + 1; // Okay
Func<int, double> f2 = x => x + 1; // Okay
Func<double, int> f3 = x => x + 1; // Error
the parameter and return types of each anonymous function are determined from the type of the variable to which the anonymous function is assigned.
The first assignment successfully converts the anonymous function to the delegate type Func<int, int> because, when x is given type int, x + 1 is a valid expression that is implicitly convertible to type int.
Likewise, the second assignment successfully converts the anonymous function to the delegate type Func<int, double> because the result of x + 1 (of type int) is implicitly convertible to type double.
The third assignment produces a compile-time error because, when x is given type double, the result of x + 1 (of type double) is not implicitly convertible to type int.
Anonymous functions may influence overload resolution and participate in type inference. See §7.4 for further details.
6.5.1 Evaluation of Anonymous Function Conversions to Delegate Types
Conversion of an anonymous function to a delegate type produces a delegate instance that references the anonymous function and the (possibly empty) set of captured outer variables that are active at the time of the evaluation. When the delegate is invoked, the body of the anonymous function is executed. The code in the body is executed using the set of captured outer variables referenced by the delegate.
The invocation list of a delegate produced from an anonymous function contains a single entry. The exact target object and the target method of the delegate are unspecified. In particular, it is unspecified whether the target object of the delegate is null, the this value of the enclosing function member, or some other object.
Conversions of semantically identical anonymous functions with the same (possibly empty) set of captured outer variable instances to the same delegate types are permitted (but not required) to return the same delegate instance. The term “semantically identical” is used here to mean that execution of the anonymous functions will, in all cases, produce the same effects given the same arguments. This rule permits code such as the following to be optimized.
delegate double Function(double x);
class Test
{
static double[ ] Apply(double[ ] a, Function f) {
double[ ] result = new double[a.Length];
for (int i = 0; i < a.Length; i++) result[i] = f(a[i]);
return result;
}
static void F(double[ ] a, double[ ] b) {
a = Apply(a, (double x) => Math.Sin(x));
b = Apply(b, (double y) => Math.Sin(y));
…
}
}
Because the two anonymous function delegates have the same (empty) set of captured outer variables, and because the anonymous functions are semantically identical, the compiler is permitted to have the delegates refer to the same target method. Indeed, the compiler is permitted to return the very same delegate instance from both anonymous function expressions.
The Microsoft C# compiler does not actually implement this optimization, although it does cache and reuse delegate instances when possible.
6.5.2 Evaluation of Anonymous Function Conversions to Expression Tree Types
Conversion of an anonymous function to an expression tree type produces an expression tree (§4.6). More precisely, evaluation of the anonymous function conversion leads to the construction of an object structure that represents the structure of the anonymous function itself.
Like a delegate, an expression tree can have a set of captured outer variables.
6.5.3 Implementation Example
This section describes a possible implementation of anonymous function conversions in terms of other C# constructs. The implementation described here is based on the same principles used by the Microsoft C# compiler. It is by no means a mandated implementation, however, nor is it the only implementation possible. This implementation mentions conversions to expression trees only briefly, as their exact semantics are outside the scope of this specification.
The remainder of this section gives several examples of anonymous functions with different characteristics. For each example, a corresponding translation to code that uses only other C# constructs is provided. In the examples, the identifier D is assumed to represent the following delegate type:
public delegate void D();
The simplest form of an anonymous function is one that captures no outer variables:
class Test
{
static void F() {
D d = () => {
Console.WriteLine("test"); };
}
}
This function can be translated to a delegate instantiation that references a compiler-generated static method in which the code of the anonymous function is placed:
class Test
{
static void F() {
D d = new D(__Method1);
}
static void __Method1() {
Console.WriteLine("test");
}
}
In the following example, the anonymous function references instance members of this:
class Test
{
int x;
void F() {
D d = () => { Console.WriteLine(x); };
}
}
This function can be translated to a compiler-generated instance method containing the code of the anonymous function:
class Test
{
int x;
void F() {
D d = new D(__Method1);
}
void __Method1() {
Console.WriteLine(x);
}
}
In this example, the anonymous function captures a local variable:
class Test
{
void F() {
int y = 123;
D d = () => { Console.WriteLine(y); };
}
}
The lifetime of the local variable must now be extended to at least the lifetime of the anonymous function delegate. This result can be achieved by “hoisting” the local variable into a field of a compiler-generated class. Instantiation of the local variable (§7.14.4.2) then corresponds to creating an instance of the compiler-generated class, and accessing the local variable corresponds to accessing a field in the instance of the compiler-generated class. Furthermore, the anonymous function becomes an instance method of the compiler-generated class:
class Test
{
void F() {
__Locals1 __locals1 = new __Locals1();
__locals1.y = 123;
D d = new D(__locals1.__Method1);
}
class__Locals1
{
public int y;
public void __Method1() {
Console.WriteLine(y);
}
}
}
Finally, the following anonymous function captures this as well as two local variables with different lifetimes:
class Test
{
int x;
void F() {
int y = 123;
for (int i = 0; i < 10; i++) {
int z = i * 2;
D d = () => { Console.WriteLine(x + y + z); };
}
}
}
In this case, a compiler-generated class is created for each statement block in which locals are captured such that the locals in the different blocks can have independent lifetimes. An instance of __Locals2, the compiler-generated class for the inner statement block, contains the local variable z and a field that references an instance of __Locals1. An instance of __Locals1, the compiler-generated class for the outer statement block, contains the local variable y and a field that references this of the enclosing function member. With these data structures, it becomes possible to reach all captured outer variables through an instance of __Local2, and the code of the anonymous function can, therefore, be implemented as an instance method of that class.
If F() returned an instance of D, the lives of all the variables this function captures would be extended.
class Test
{
void F() {
__Locals1 __locals1 = new __Locals1();
__locals1.__this = this;
__locals1.y = 123;
for (int i = 0; i < 10; i++) {
__Locals2 __locals2 = new __Locals2();
__locals2.__locals1 = __locals1;
__locals2.z = i * 2;
D d = new D(__locals2.__Method1);
}
}
class __Locals1
{
public Test __this;
public int y;
}
class __Locals2
{
public __Locals1 __locals1;
public int z;
public void __Method1() {
Console.WriteLine(__locals1.__this.x + __locals1.y + z);
}
}
}
The same technique applied here to capture local variables can also be used when converting anonymous functions to expression trees: References to the compiler-generated objects can be stored in the expression tree, and access to the local variables can be represented as field accesses on these objects. The advantage of this approach is that it allows the “lifted” local variables to be shared between delegates and expression trees.
A downside of this implementation technique (and a disadvantage shared by many implementations of many languages that have similar closure semantics) is that two different anonymous functions in the same method that are closed over two different local variables cause the lifetimes of both variables to be extended to the lifetime of the longest-lived delegate.
Supppose you have two local variables, expensive and cheap, and two delegates, one closed over each:
D longlived = ()=>cheap;
D shortlived = ()=>expensive;
Then the lifetime of expensive is at least as long as the lifetime of the object referred to by longlived, even though expensive is not actually used by longlived. A more sophisticated implementation would partition closed-over variables into separate compiler-generated classes and avoid this problem.
6.6 Method Group Conversions
An implicit conversion (§6.1) exists from a method group (§7.1) to a compatible delegate type. Given a delegate type D and an expression E that is classified as a method group, an implicit conversion exists from E to D if E contains at least one method that is applicable in its normal form (§7.4.3.1) to an argument list constructed by use of the parameter types and modifiers of D, as described in the following discussion.
The compile-time application of a conversion from a method group E to a delegate type D is described in this section. Note that the existence of an implicit conversion from E to D does not guarantee that the compile-time application of the conversion will succeed without error.
In particular, overload resolution can pick the best function member containing a delegate type in its signature. By contrast, an implicit conversion from a method group, provided as an argument, to that delegate type will result in a compile-time error. This result may occur, for instance, because overload resolution cannot find the single best method in that group, or the best method is found, but constraints on its type parameters are not satisfied or it is not compatible with the delegate type.
• A single method M is selected corresponding to a method invocation (§7.5.5.1) of the form E(A), with the following modifications:
- The argument list A is a list of expressions, each classified as a variable and with the type and modifier (ref or out) of the corresponding parameter in the formal-parameter-list of D.
- The candidate methods considered are only those methods that are applicable in their normal form (§7.4.3.1), not those applicable only in their expanded form.
• If the algorithm of §7.5.5.1 produces an error, then a compile-time error occurs. Otherwise, the algorithm produces a single best method M having the same number of parameters as D and the conversion is considered to exist.
• The selected method M must be compatible (§15.2) with the delegate type D; otherwise, a compile-time error occurs.
• If the selected method M is an instance method, then the instance expression associated with E determines the target object of the delegate.
• If the selected method M is an extension method that is denoted by means of a member access on an instance expression, then that instance expression determines the target object of the delegate.
• The result of the conversion is a value of type D—namely, a newly created delegate that refers to the selected method and target object.
Note that this process can lead to the creation of a delegate to an extension method, if the algorithm of §7.5.5.1 fails to find an instance method but succeeds in processing the invocation of E(A) as an extension method invocation (§7.5.5.2). A delegate created in this way captures the extension method as well as its first argument.
The following example demonstrates method group conversions:
delegate string D1(object o);
delegate object D2(string s);
delegate object D3();
delegate string D4(object o, params object[ ] a);
delegate string D5(int i);
class Test
{
static string F(object o) {…}
static void G() {
D1 d1 = F; // Okay
D2 d2 = F; // Okay
D3 d3 = F; // Error – not applicable
D4 d4 = F; // Error – not applicable in normal form
D5 d5 = F; // Error – applicable but not compatible
}
}
The assignment to d1 implicitly converts the method group F to a value of type D1.
The assignment to d2 shows how it is possible to create a delegate to a method that has less derived (contravariant) parameter types and a more derived (covariant) return type.
The assignment to d3 shows how no conversion exists if the method is not applicable.
The assignment to d4 shows how the method must be applicable in its normal form.
The assignment to d5 shows how parameter and return types of the delegate and method are allowed to differ only for reference types.
As with all other implicit and explicit conversions, the cast operator can be used to explicitly perform a method group conversion. Thus the example
object obj = new EventHandler(myDialog.OkClick);
could instead be written
object obj = (EventHandler)myDialog.OkClick;
Method groups may influence overload resolution and participate in type inference. See §7.4 for further details.
The runtime evaluation of a method group conversion proceeds as follows:
• If the method selected at compile time is an instance method, or if it is an extension method that is accessed as an instance method, then the target object of the delegate is determined from the instance expression associated with E:
- The instance expression is evaluated. If this evaluation causes an exception, no further steps are executed.
- If the instance expression is of a reference-type, the value computed by the instance expression becomes the target object. If the target object is null, a System.Null-Reference-Exception is thrown and no further steps are executed.
- If the instance expression is of a value-type, a boxing operation (§4.3.1) is performed to convert the value to an object, and this object becomes the target object.
• Otherwise, the selected method is part of a static method call, and the target object of the delegate is null.
• A new instance of the delegate type D is allocated. If not enough memory is available to allocate the new instance, a System.OutOfMemoryException is thrown and no further steps are executed.
• The new delegate instance is initialized with a reference to the method that was determined at compile time and a reference to the target object computed earlier.