safe_cast (C++ Component Extensions)
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The safe_cast operation returns the specified expression as the specified type, if successful; otherwise, throws InvalidCastException.
(There are no remarks for this language feature that apply to all runtimes.)
Syntax
[default]:: safe_cast<
type-id
>(
expression
)
Parameters
Remarks
safe_cast allows you to change the type of a specified expression. In situations where you fully expect a variable or parameter to be convertible to a certain type, you can use safe_cast without a try-catch block to detect programming errors during development. For more information, see Casting (C++/CX).
Syntax
[default]:: safe_cast<
type-id
>(
expression
)
Parameters
type-id
The type to convert expression to. A handle to a reference or value type, a value type, or a tracking reference to a reference or value type.
expression
An expression that evaluates to a handle to a reference or value type, a value type, or a tracking reference to a reference or value type.
Remarks
safe_cast throws InvalidCastException if it cannot convert expression to the type specified by type-id. To catch InvalidCastException, specify the /EH (Exception Handling Model) compiler option, and use a try/catch statement.
Requirements
Compiler option: /ZW
Examples
Example
The following code example demonstrates how to use safe_cast with the Windows Runtime.
// safe_cast_ZW.cpp // compile with: /ZW /EHsc using namespace default; using namespace Platform; interface class I1 {}; interface class I2 {}; interface class I3 {}; ref class X : public I1, public I2 {}; int main(Array<String^>^ args) { I1^ i1 = ref new X; I2^ i2 = safe_cast<I2^>(i1); // OK, I1 and I2 have common type: X // I2^ i3 = static_cast<I2^>(i1); C2440 use safe_cast instead try { I3^ i4 = safe_cast<I3^>(i1); // Fails because i1 is not derived from I3. } catch(InvalidCastException^ ic) { wprintf(L"Caught expected exception: %s\n", ic->Message); } }
Output
Caught expected exception: InvalidCastException
safe_cast allows you to change the type of an expression and generate verifiable MSIL code.
Syntax
[cli]:: safe_cast< type-id >( expression )
Parameters
type-id
A handle to a reference or value type, a value type, or a tracking reference to a reference or value type.
expression
An expression that evaluates to a handle to a reference or value type, a value type, or a tracking reference to a reference or value type.
Remarks
The expression safe_cast<type-id>(expression) converts the operand expression to an object of type type-id.
The compiler will accept a static_cast in most places that it will accept a safe_cast. However, safe_cast is guaranteed to produce verifiable MSIL, where as a static_cast could produce unverifiable MSIL. See Pure and Verifiable Code (C++/CLI) and Peverify.exe (PEVerify Tool) for more information on verifiable code.
Like static_cast, safe_cast invokes user-defined conversions.
For more information about casts, see Casting Operators.
safe_cast does not apply a const_cast (cast away const).
safe_cast is in the cli namespace. See Platform, default, and cli Namespaces for more information.
For more information on safe_cast, see:
Requirements
Compiler option: /clr
Examples
Example
One example of where the compiler will not accept a static_cast but will accept a safe_cast is for casts between unrelated interface types. With safe_cast, the compiler will not issue a conversion error and will perform a check at runtime to see if the cast is possible
// safe_cast.cpp // compile with: /clr using namespace System; interface class I1 {}; interface class I2 {}; interface class I3 {}; ref class X : public I1, public I2 {}; int main() { I1^ i1 = gcnew X; I2^ i2 = safe_cast<I2^>(i1); // OK, I1 and I2 have common type: X // I2^ i3 = static_cast<I2^>(i1); C2440 use safe_cast instead try { I3^ i4 = safe_cast<I3^>(i1); // fail at runtime, no common type } catch(InvalidCastException^) { Console::WriteLine("Caught expected exception"); } }
Output
Caught expected exception