Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Examples | Search for 

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::ValueTypeConversionTraits< TypeTo, TypeFrom >
 Default traits class for all conversions of value types. More...
class  Teuchos::ConstTypeTraits< T >
 Traits class that strips of 'const'. More...
class  Teuchos::m_bad_cast
 Exception class for bad cast. More...
class  Teuchos::ToStringTraits< T >
 Default traits class for converting objects into strings. More...
class  Teuchos::TypeNameTraits< T >
 Default traits class that just returns typeid(T).name(). 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 TypeTo, class TypeFrom>
TypeTo Teuchos::as (const TypeFrom &t)
 Perform an debug-enabled checked conversion from one value type object to another.
template<class TypeTo, class TypeFrom>
TypeTo Teuchos::asSafe (const TypeFrom &t)
 Perform an always checked conversion from one value type object to another.
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.
template<class TypeTo, class TypeFrom>
TypeTo Teuchos::implicit_cast (const TypeFrom &t)
 Perform an implicit cast of concrete types with the casted object returned by value.
template<class TypeTo, class TypeFrom>
TypeTo & Teuchos::implicit_ref_cast (TypeFrom &t)
 Perform an implicit cast of reference types with a reference being returned.
template<class TypeTo, class TypeFrom>
TypeTo * Teuchos::implicit_ptr_cast (TypeFrom *t)
 Perform an implicit cast of pointer types with a pointer being returned.
template<typename T>
std::string Teuchos::toString (const T &t)
 Utility function for returning a pretty string representation of a object of type T.
std::string Teuchos::demangleName (const std::string &mangledName)
 Demangle a C++ name if valid.
template<typename T>
std::string Teuchos::typeName (const T &t)
 Template function for returning the demangled name of an object.

Define Documentation

#define TEUCHOS_STANDARD_CATCH_STATEMENTS (  VERBOSE,
ERR_STREAM,
SUCCESS_FLAG   ) 
 

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, and FancyOutputting_test.cpp.

Function Documentation

template<class TypeTo, class TypeFrom>
TypeTo as (  const TypeFrom &  t  )  [inline]
 

Perform an debug-enabled checked conversion from one value type object to another.

This function is used as:

    TypeTo myConversion( const TypeFrom& a )
    {
      return Teuchos::as<TypeTo>(a);
    }

This is just an interface function what calls the traits class ValueTypeConversionTraits to perform the actual conversion. All specializations of behavior is done through specializations of the ValueTypeConversionTraits class (which should be done in the Teuchos namespace).

When debug checking is turned on (e.g. when the TEUCHOS_DEBUG macro is defined by the --enable-teuchos-debug configure option), then the checked conversion function ValueTypeConversionTraits<TypeTo,TypeFrom>::safeConvert(t) is called. When debug checking is not turned on, the unchecked ValueTypeConversionTraits<TypeTo,TypeFrom>::convert(t) function is called.

For cases where the checking should always be done (i.e. to validate user data), use the asSafe() version of this function.

template<class TypeTo, class TypeFrom>
TypeTo asSafe (  const TypeFrom &  t  )  [inline]
 

Perform an always checked conversion from one value type object to another.

This function is used as:

    TypeTo mySafeConversion( const TypeFrom& a )
    {
      return Teuchos::asSafe<TypeTo>(a);
    }

This is just an interface function what calls the traits class ValueTypeConversionTraits to perform the actual conversion. All specializations of behavior is done through specializations of the ValueTypeConversionTraits class (which should be done in the Teuchos namespace).

This function always calls ValueTypeConversionTraits<TypeTo,TypeFrom>::safeConvert(t) independent of whether TEUCHOS_DEBUG is defined or not, which ensures that the conversions are always runtime checked and therefore well defined.

For cases where the checking should only be done in a debug build, use the the as() version of this function.

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 std::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 std::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 std::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 std::exception e where e.what() = "St8bad_cast"

  Trying: Teuchos::dyn_cast<C>(a);

  Caught std::bad_cast std::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.

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.

template<class TypeTo, class TypeFrom>
TypeTo implicit_cast (  const TypeFrom &  t  )  [inline]
 

Perform an implicit cast of concrete types with the casted object returned by value.

This function is used as:

    TypeTo myCast( const TypeFrom& a )
    {
      return Teuchos::implicit_cast<TypeTo>(a);
    }

This function will only compile for types where an implicit conversion from objects of type TypeFrom to type TypeTo exists. Note that this is a weaker operation than a static_cast<TypeTo>(t) in that the static cast will actually compile in cases where the implicit conversion would not compile and may result in incorrect code. This function can not result in incorrect code, assuming that the implicit conversions themselves do no result in incorrect code (which is another matter all together).

This function is especially helpful when one needs to be careful of what specific type is passed in as a formal argument to a function and in comparing values. In particular, using this function is far safer than using TypeTo(t) in cases where TypeTo is a built in type since TypeTo(t) in these cases is equivalent to (TypeTo)t which is an unchecked sledge-hammer cast of the worst kind.

template<class TypeTo, class TypeFrom>
TypeTo& implicit_ref_cast (  TypeFrom &  t  )  [inline]
 

Perform an implicit cast of reference types with a reference being returned.

This function is used as:

    TypeTo& myPtrCast( TypeFrom &ref1 )
    {
      return Teuchos::implicit_ref_cast<TypeTo>(ref1);
    }

This function will only compile for types where an implicit conversion from references of type TypeFrom& to references of TypeTo& exists. It is allowed for the type TypeFrom and TypeTo to actually be const types. For example, we can have TypeFrom = const std::iostream and TypeTo = const std::ostream and Teuchos::implicit_ref_cast<const std::ostream>(Teuchos::getConst(std::cout)) would compile just fine.

Note that this is a weaker operation than a static_cast<TypeTo&>(t) in that the static cast will actually compile in cases where the implicit conversion would not compile and may result in incorrect code. For example, a static cast from a base to a derived class will compile (and may be wrong) while this implicit cast function will not compile for casts from base to derived classes. This function can not result in incorrect code, assuming that the implicit conversions themselves do no result in incorrect code (which is another matter all together).

template<class TypeTo, class TypeFrom>
TypeTo* implicit_ptr_cast (  TypeFrom *  t  )  [inline]
 

Perform an implicit cast of pointer types with a pointer being returned.

This function is used as:

    TypeTo* myPtrCast( TypeFrom *ptr1 )
    {
      return Teuchos::implicit_ptr_cast<TypeTo>(ptr1);
    }

This function will only compile for types where an implicit conversion from pointers of type TypeFrom* to pointers of type TypeTo* exists. It is allowed for the type TypeFrom and TypeTo to actually be const types. For example, we can have TypeFrom = const std::iostream and TypeTo = const std::ostream and Teuchos::implicit_ptr_cast<const std::ostream>(&Teuchos::getConst(std::cout)) would compile just fine.

Note that this is a weaker operation than a static_cast<TypeTo*>(t) in that the static cast will actually compile in cases where the implicit conversion would not compile and may result in incorrect code. For example, a static cast up from a base class to a derived class will compile (and may be wrong) while this implicit cast function will not compile for such casts. This function can not result in incorrect code, assuming that the implicit conversions themselves do no result in incorrect code (which is another matter all together).

template<typename T>
std::string toString (  const T &  t  )  [inline]
 

Utility function for returning a pretty string representation of a object of type T.

NOTE: This helper function simply returns ToStringTraits<T>::toString(t) and the right way to speicalize the behavior is to specialize ToStringTraits.

Examples:
FancyOutputting_test.cpp.

std::string Teuchos::demangleName (  const std::string &  mangledName  ) 
 

Demangle a C++ name if valid.

The name must have come from typeid(...).name() in order to be valid name to pass to this function.

template<typename T>
std::string typeName (  const T &  t  ) 
 

Template function for returning the demangled name of an object.

Generated on Sun Nov 23 12:11:31 2008 for Teuchos - Trilinos Tools Package by  doxygen 1.3.9.1