Teuchos - Trilinos Tools Package Version of the Day
Classes | Modules | Defines | Functions
Teuchos Language Support Utilities

Classes

class  Teuchos::ValueTypeConversionTraits< TypeTo, TypeFrom >
 Default traits class for all conversions of value types. More...
class  Teuchos::ConstTypeTraits< T >
 Traits class that strips 'const' off of a type. 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...
struct  Teuchos::TypeTraits::is_same< T1, T2 >
 Default is_equal traits class has value equal to false, indicating that T1 and T2 are not equal,. More...
struct  Teuchos::TypeTraits::is_same< T, T >
 Partial specialization of is_equal class for equal types, where value equal to true. More...

Modules

 Template classes for testing assertions at compile time.
 Utility code for throwing exceptions and setting breakpoints.

Defines

#define TEUCHOS_SWITCH_DEFAULT_DEBUG_ASSERT()   break
 Macro to insert switch default that throws in a debug build.
#define TEUCHOS_IF_ELSE_DEBUG_ASSERT()   else {}
 Macro to insert else block that throws in a debug build.
#define TEUCHOS_STANDARD_CATCH_STATEMENTS(VERBOSE, ERR_STREAM, SUCCESS_FLAG)   TEUCHOS_STANDARD_CATCH_STATEMENTS_IMPL(VERBOSE, ERR_STREAM, true, 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.
TEUCHOS_LIB_DLL_EXPORT 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 concrete type name of a passed-in object.
template<typename T >
std::string Teuchos::concreteTypeName (const T &t)
 Template function for returning the type name of the actual concrete name of a passed-in object.

Define Documentation

#define TEUCHOS_SWITCH_DEFAULT_DEBUG_ASSERT ( )    break

Macro to insert switch default that throws in a debug build.

In a non-debug build, however, this does nothing. This is also helpful for removing code that would otherwise show as not being covered.

Definition at line 59 of file Teuchos_DebugDefaultAsserts.hpp.

#define TEUCHOS_IF_ELSE_DEBUG_ASSERT ( )    else {}

Macro to insert else block that throws in a debug build.

In a non-debug build, however, this does nothing. This is also helpful for removing code that would otherwise show as not being covered.

Definition at line 73 of file Teuchos_DebugDefaultAsserts.hpp.

#define TEUCHOS_STANDARD_CATCH_STATEMENTS (   VERBOSE,
  ERR_STREAM,
  SUCCESS_FLAG 
)    TEUCHOS_STANDARD_CATCH_STATEMENTS_IMPL(VERBOSE, ERR_STREAM, true, 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 );
 }

NOTE: This macro will print out stacktraces generated by exceptions thrown with the TEUCHOS_TEST_FOR_EXCEPTION() family of macros (see the main doc page for details).

Examples:
ArrayRCP_test.cpp, CommandLineProcessor/cxx_main.cpp, FancyOutputting_test.cpp, and test/MemoryManagement/RCP_test.cpp.

Definition at line 136 of file Teuchos_StandardCatchMacros.hpp.


Function Documentation

template<class TypeTo , class TypeFrom >
TypeTo Teuchos::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.

Examples:
ArrayRCP_test.cpp.

Definition at line 134 of file Teuchos_as.hpp.

template<class TypeTo , class TypeFrom >
TypeTo Teuchos::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.

Definition at line 174 of file Teuchos_as.hpp.

template<class T_To , class T_From >
T_To& Teuchos::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.

Examples:
FancyOutputting_test.cpp.

Definition at line 173 of file Teuchos_dyn_cast.hpp.

template<class T >
const T& Teuchos::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.

Examples:
test/MemoryManagement/RCP_test.cpp.

Definition at line 61 of file Teuchos_getConst.hpp.

template<class TypeTo , class TypeFrom >
TypeTo Teuchos::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.

Definition at line 81 of file Teuchos_implicit_cast.hpp.

template<class TypeTo , class TypeFrom >
TypeTo& Teuchos::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).

Definition at line 116 of file Teuchos_implicit_cast.hpp.

template<class TypeTo , class TypeFrom >
TypeTo* Teuchos::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).

Definition at line 150 of file Teuchos_implicit_cast.hpp.

template<typename T >
std::string Teuchos::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.

Definition at line 81 of file Teuchos_toString.hpp.

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.

Definition at line 53 of file Teuchos_TypeNameTraits.cpp.

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

Template function for returning the concrete type name of a passed-in object.

Uses the traits class TypeNameTraits so the behavior of this function can be specialized in every possible way. The default return value is typically derived from typeid(t).name().

Definition at line 104 of file Teuchos_TypeNameTraits.hpp.

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

Template function for returning the type name of the actual concrete name of a passed-in object.

Uses the traits class TypeNameTraits so the behavior of this function can be specialized in every possible way.

Definition at line 127 of file Teuchos_TypeNameTraits.hpp.

 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines