Casting and conversions (F#)
This article describes support for type conversions in F#.
F# provides conversion operators for arithmetic conversions between various primitive types, such as between integer and floating point types. The integral and char conversion operators have checked and unchecked forms; the floating point operators and the
enum conversion operator do not. The unchecked forms are defined in
FSharp.Core.Operators and the checked forms are defined in
FSharp.Core.Operators.Checked. The checked forms check for overflow and generate a runtime exception if the resulting value exceeds the limits of the target type.
Each of these operators has the same name as the name of the destination type. For example, in the following code, in which the types are explicitly annotated,
byte appears with two different meanings. The first occurrence is the type and the second is the conversion operator.
let x : int = 5 let b : byte = byte x
The following table shows conversion operators defined in F#.
||Convert to byte, an 8-bit unsigned type.|
||Convert to signed byte.|
||Convert to a 16-bit signed integer.|
||Convert to a 16-bit unsigned integer.|
||Convert to a 32-bit signed integer.|
||Convert to a 32-bit unsigned integer.|
||Convert to a 64-bit signed integer.|
||Convert to a 64-bit unsigned integer.|
||Convert to a native integer.|
||Convert to an unsigned native integer.|
||Convert to a 64-bit double-precision IEEE floating point number.|
||Convert to a 32-bit single-precision IEEE floating point number.|
||Convert to an enumerated type.|
In addition to built-in primitive types, you can use these operators with types that implement
op_Implicit methods with appropriate signatures. For example, the
int conversion operator works with any type that provides a static method
op_Explicit that takes the type as a parameter and returns
int. As a special exception to the general rule that methods cannot be overloaded by return type, you can do this for
enum operator is a generic operator that takes one type parameter that represents the type of the
enum to convert to. When it converts to an enumerated type, type inference attempts to determine the type of the
enum that you want to convert to. In the following example, the variable
col1 is not explicitly annotated, but its type is inferred from the later equality test. Therefore, the compiler can deduce that you are converting to a
Color enumeration. Alternatively, you can supply a type annotation, as with
col2 in the following example.
type Color = | Red = 1 | Green = 2 | Blue = 3 // The target type of the conversion cannot be determined by type inference, so the type parameter must be explicit. let col1 = enum<Color> 1 // The target type is supplied by a type annotation. let col2 : Color = enum 2
You can also specify the target enumeration type explicitly as a type parameter, as in the following code:
let col3 = enum<Color> 3
Note that the enumeration casts work only if the underlying type of the enumeration is compatible with the type being converted. In the following code, the conversion fails to compile because of the mismatch between
// Error: types are incompatible let col4 : Color = enum 2u
For more information, see Enumerations.
Casting Object Types
Conversion between types in an object hierarchy is fundamental to object-oriented programming. There are two basic types of conversions: casting up (upcasting) and casting down (downcasting). Casting up a hierarchy means casting from a derived object reference to a base object reference. Such a cast is guaranteed to work as long as the base class is in the inheritance hierarchy of the derived class. Casting down a hierarchy, from a base object reference to a derived object reference, succeeds only if the object actually is an instance of the correct destination (derived) type or a type derived from the destination type.
F# provides operators for these types of conversions. The
:> operator casts up the hierarchy, and the
:?> operator casts down the hierarchy.
In many object-oriented languages, upcasting is implicit; in F#, the rules are slightly different. Upcasting is applied automatically when you pass arguments to methods on an object type. However, for let-bound functions in a module, upcasting is not automatic, unless the parameter type is declared as a flexible type. For more information, see Flexible Types.
:> operator performs a static cast, which means that the success of the cast is determined at compile time. If a cast that uses
:> compiles successfully, it is a valid cast and has no chance of failure at run time.
You can also use the
upcast operator to perform such a conversion. The following expression specifies a conversion up the hierarchy:
When you use the upcast operator, the compiler attempts to infer the type you are converting to from the context. If the compiler is unable to determine the target type, the compiler reports an error. A type annotation may be required.
:?> operator performs a dynamic cast, which means that the success of the cast is determined at run time. A cast that uses the
:?> operator is not checked at compile time; but at run time, an attempt is made to cast to the specified type. If the object is compatible with the target type, the cast succeeds. If the object is not compatible with the target type, the runtime raises an
You can also use the
downcast operator to perform a dynamic type conversion. The following expression specifies a conversion down the hierarchy to a type that is inferred from program context:
As for the
upcast operator, if the compiler cannot infer a specific target type from the context, it reports an error. A type annotation may be required.
The following code illustrates the use of the
:?> operators. The code illustrates that the
:?> operator is best used when you know that conversion will succeed, because it throws
InvalidCastException if the conversion fails. If you do not know that a conversion will succeed, a type test that uses a
match expression is better because it avoids the overhead of generating an exception.
type Base1() = abstract member F : unit -> unit default u.F() = printfn "F Base1" type Derived1() = inherit Base1() override u.F() = printfn "F Derived1" let d1 : Derived1 = Derived1() // Upcast to Base1. let base1 = d1 :> Base1 // This might throw an exception, unless // you are sure that base1 is really a Derived1 object, as // is the case here. let derived1 = base1 :?> Derived1 // If you cannot be sure that b1 is a Derived1 object, // use a type test, as follows: let downcastBase1 (b1 : Base1) = match b1 with | :? Derived1 as derived1 -> derived1.F() | _ -> () downcastBase1 base1
Because the generic operators
upcast rely on type inference to determine the argument and return type, you can replace
let base1 = d1 :> Base1 in the previous code example with
let base1: Base1 = upcast d1.
A type annotation is required, because
upcast by itself could not determine the base class.
Implicit upcast conversions
Implicit upcasts are inserted in the following situations:
When providing a parameter to a function or method with a known named type. This includes when a construct such as computation expressions or slicing becomes a method call.
When assigning to or mutating a record field or property that has a known named type.
When a branch of an
matchexpression has a known target type arising from another branch or overall known type.
When an element of a list, array, or sequence expression has a known target type.
For example, consider the following code:
open System open System.IO let findInputSource () : TextReader = if DateTime.Now.DayOfWeek = DayOfWeek.Monday then // On Monday a TextReader Console.In else // On other days a StreamReader File.OpenText("path.txt")
Here the branches of the conditional compute a
StreamReader respectively. On the second branch, the known target type is
TextReader from the type annotation on the method, and from the first branch. This means no upcast is needed on the second branch.
To show a warning at every point an additional implicit upcast is used, you can enable warning 3388 (
/warnon:3388 or property
Implicit numeric conversions
F# uses explicit widening of numeric types in most cases via conversion operators. For example, explicit widening is needed for most numeric types, such as
int16, or from
float64, or when either source or destination type is unknown.
However, implicit widening is allowed for 32-bit integers widened to 64-bit integers, in the same situations as implicit upcasts. For example, consider a typical API shape:
type Tensor(…) = static member Create(sizes: seq<int64>) = Tensor(…)
Integer literals for int64 may be used:
Tensor.Create([100L; 10L; 10L])
Or integer literals for int32:
Tensor.Create([int64 100; int64 10; int64 10])
Widening happens automatically for
double, when both source and destination type are known during type inference. So in cases such as the previous examples,
int32 literals can be used:
Tensor.Create([100; 10; 10])
You can also optionally enable the warning 3389 (
/warnon:3389 or property
<WarnOn>3389</WarnOn>) to show a warning at every point implicit numeric widening is used.
.NET-style implicit conversions
.NET APIs allow the definition of
op_Implicit static methods to provide implicit conversions between types. These are applied automatically in F# code when passing arguments to methods. For example, consider the following code making explicit calls to
open System.Xml.Linq let purchaseOrder = XElement.Load("PurchaseOrder.xml") let partNos = purchaseOrder.Descendants(XName.op_Implicit "Item")
op_Implicit conversions are applied automatically for argument expressions when types are available for source expression and target type:
open System.Xml.Linq let purchaseOrder = XElement.Load("PurchaseOrder.xml") let partNos = purchaseOrder.Descendants("Item")
You can also optionally enable the warning 3395 (
/warnon:3395 or property
<WarnOn>3395</WarnOn>) to show a warning at every point a .NET-style implicit conversion is used.
op_Implicit conversions are also applied automatically for non-method-argument expressions in the same situations as implicit upcasts. However, when used widely or inappropriately, implicit conversions can interact poorly with type inference and lead to code that's harder to understand. For this reason, these always generate warnings when used in non-argument positions.
To show a warning at every point that a .NET-style implicit conversion is used for a non-method argument, you can enable warning 3391 (
/warnon:3391 or property
Summary of warnings related to conversions
The following optional warnings are provided for uses of implicit conversions:
/warnon:3388(additional implicit upcast)
/warnon:3389(implicit numeric widening)
op_Implicitat non-method arguments, on by default)
op_Implicitat method arguments)