Teuchos Language Support Utilities

Modules
group	Utility functions for passing arrays into argument lists.
	The purpose of this utility is to make passing arrays into argument lists easier.
group	Template classes for testing assertions at compile time.
group	Utility code for replacing calls to exit() with macros that result in thrown exceptions.
group	Utility code for throwing exceptions and setting breakpoints.
Classes
class	Teuchos::m_bad_cast
	Exception class for bad cast. More...
Defines
#define	TEUCHOS_STANDARD_CATCH_STATEMENTS(VERBOSE, ERR_STREAM, SUCCESS_FLAG)
	Simple macro that catches and reports standard exceptions and other exceptions.
Functions
template<class T_To, class T_From>
T_To &	Teuchos::dyn_cast (T_From &from)
	Dynamic casting utility function meant to replace dynamic_cast<T&> by throwing a better documented error message.
template<class T>
const T &	Teuchos::getConst (T &t)
	Return a constant reference to an object given a non-const reference.

---

Define Documentation

#define TEUCHOS_STANDARD_CATCH_STATEMENTS (  VERBOSE, ERR_STREAM, SUCCESS_FLAG   )

Value: catch( const std::exception &excpt ) { \ if((VERBOSE)) { \ std::ostringstream oss; \ oss \ << "p="<<::Teuchos::GlobalMPISession::getRank()<<": *** Caught standard exception of type \'" \ <<typeid(excpt).name()<<"\' : " << excpt.what() << std::endl; \ (ERR_STREAM) << oss.str(); \ (SUCCESS_FLAG) = false; \ } \ } \ catch( ... ) { \ if((VERBOSE)) { \ std::ostringstream oss; \ oss << "p="<<::Teuchos::GlobalMPISession::getRank()<<": *** Caught an unknown exception\n"; \ (ERR_STREAM) << oss.str(); \ (SUCCESS_FLAG) = false; \ } \ } Simple macro that catches and reports standard exceptions and other exceptions. This macro should be used to write simple main() program functions wrapped in a try statement as: int main(...) { bool verbose = true; bool success = true; try { ... } TEUCHOS_STANDARD_CATCH_STATEMENTS(verbose,std::cerr,success); return ( success ? 0 : 1 ); } Examples: CommandLineProcessor/cxx_main.cpp, FancyOutputting_test.cpp, and test/RefCountPtr/cxx_main.cpp. Definition at line 55 of file Teuchos_StandardCatchMacros.hpp.

---

Function Documentation

template<class T_To, class T_From> T_To& dyn_cast (  T_From &  from  )  [inline]

Dynamic casting utility function meant to replace dynamic_cast<T&> by throwing a better documented error message. Existing uses of the built-in dynamic_cast<T&>() operator such as: C &c = dynamic_cast<C&>(a); are easily replaced as: C &c = dyn_cast<C>(a); and that is it. One could write a perl script to do this automatically. This utility function is designed to cast an object reference of type T_From to type T_To and if the cast fails at runtime then an exception (derived from std::bad_cast) is thrown that contains a very good error message. Consider the following class hierarchy: class A {}; class B : public A {}; class C : public A {}; Now consider the following program: int main( int argc, char* argv[] ) { B b; A &a = b; try { std::cout << "\nTrying: dynamic_cast<C&>(a);\n"; dynamic_cast<C&>(a); } catch( const std::bad_cast &e ) { std::cout << "\nCaught std::bad_cast exception e where e.what() = \"" << e.what() << "\"\n"; } try { std::cout << "\nTrying: Teuchos::dyn_cast<C>(a);\n"; Teuchos::dyn_cast<C>(a); } catch( const std::bad_cast &e ) { std::cout << "\nCaught std::bad_cast exception e where e.what() = \"" << e.what() << "\"\n"; } return 0; } The above program will print something that looks like (compiled with g++ for example): Trying: dynamic_cast<C&>(a); Caught std::bad_cast exception e where e.what() = "St8bad_cast" Trying: Teuchos::dyn_cast<C>(a); Caught std::bad_cast exception e where e.what() = "../../../../packages/teuchos/src/Teuchos_dyn_cast.cpp:46: true: dyn_cast<1C>(1A) : Error, the object with the concrete type '1B' (passed in through the interface type '1A') does not support the interface '1C' and the dynamic cast failed!" The above program shows that the standard implementation of dynamic_cast<T&>() does not return any useful debugging information at all but the templated function Teuchos::dyn_cast<T>() returns all kinds of useful information. The generated error message gives the type of the interface that the object was passed in as (i.e. A), what the actual concrete type of the object is (i.e. B) and what type is trying to be dynamically casted to (i.e. C). This type of information is extremely valuable when trying to track down these type of runtime dynamic casting errors. In some cases (such as with gdb), debuggers do not even give the type of concrete object so this function is very important on these platforms. In many cases, a debugger does not even need to be opened to diagnose what the problem is and how to fix it. Note that this function is inlined and does not incur any significant runtime performance penalty over the raw dynamic_cast<T&>() operator. Definition at line 151 of file Teuchos_dyn_cast.hpp.

template<class T> const T& getConst (  T &  t  )  [inline]

Return a constant reference to an object given a non-const reference. This function just provides a shorthand notation for const_cast<const T&>(t) as getCost(t) so that one does not have to type in the name of the class which can be quite long in some cases. Definition at line 48 of file Teuchos_getConst.hpp.

---