Convert from one value type to another.
- Template Parameters
-
| TypeTo | The type to which to convert; the output type. |
| TypeFrom | The type from which to convert; the input type. |
User documentation
This template function lets you convert from one value type to another, possibly with checks for overflow (where appropriate) in a debug build of Teuchos. For example, to convert between int and double:
double d = 3.14;
assert (i == 3);
TypeTo as(const TypeFrom &t)
Convert from one value type to another.
In a debug build of Teuchos, this will check for overflow, since there are some double-precision floating-point values that do not fit in a 32-bit integer. In a release build, this will not check for overflow. You are responsible for knowing the difference. If you always want to check for overflow (e.g., to validate user input), use the asSafe() function. Note that conversion from a floating-point number to an integer, or from a higher-precision floating-point number to a lower-precision floating-point number, may truncate or round (as it does in the above example). We do not check for truncation or rounding.
"Debug build of Teuchos" means more than just building with debug compiler flags. It means debug checking was turned on when Trilinos was built. If you are building Trilinos yourself, you may turn on debug checking by setting the Trilinos_ENABLE_DEBUG CMake configure option to ON (rather than OFF, which is the default). Note that enabling debug checking affects other operations in Teuchos besides this conversion, and may have a significant run-time cost, especially for RCP and ArrayRCP.
The IEEE 754 standard defines the result of conversions from a larger to a smaller built-in floating-point type, including double to float, long double to float, and long doubledouble. Such conversions might overflow (result in a value too large in magnitude to fit in the target type) or underflow (result in a value too small to fit in a normalized value of the target type). We never check for overflow or underflow for these conversions. Their behavior depends on the current rounding mode and whether your hardware and compiler correctly implement denormalized values. Typically, overflow results in an Inf of the same sign as the input, and underflow results in either a denormalized value or zero. If you want to do bounds checking, you should set the appropriate trap so that overflow or underflow will raise the SIGFPE signal. Please refer to the IEEE 754 standard for details. Note that debug-mode as() conversions from e.g., std::string to built-in floating-point types still check for overflow.
- Note
- We cannot promise that converting from a type T1 to another type T2 and back again will result in the same T1 value with which we started. For example, converting from a long long to a double may result in truncation, since long long has 63 bits of significand and double has 53.
Developer documentation
This function uses the traits class ValueTypeConversionTraits to perform checking and conversion. If debug checking is turned on, this function uses the traits class' safeConvert() method to perform possibly checked conversion. Otherwise, it uses the traits class' convert() method for unchecked conversion.
If you want to specialize this function's behavior, you should specialize ValueTypeConversionTraits for your combination of input and output types (TypeFrom resp. TypeTo). Be sure to define the specialization in the Teuchos namespace. We provide specializations of ValueTypeConversionTraits in this file for a variety of types. You must define both safeConvert() and convert() in the specialization, since as() will call safeConvert() in a debug build and convert() in a release build.
- Note
- The implementations below do not consider truncation of floating-point values to be unsafe conversion. For example, converting from a long long (63 bits of significand) to a double (53 bits of significand) may result in truncation, but we do not consider this unsafe. "Unsafe" mainly refers to overflow or lack of representation.
Definition at line 2840 of file Teuchos_as.hpp.
1.13.2