Teuchos - Trilinos Tools Package Version of the Day
Static Public Attributes | Related Functions
Teuchos::Describable Class Reference

Base class for all objects that can describe themselves. More...

#include <Teuchos_Describable.hpp>

Inheritance diagram for Teuchos::Describable:
Teuchos::LabeledObject Teuchos::CommRequest< int > Teuchos::Comm< Ordinal > Teuchos::CommRequest< OrdinalType > Teuchos::Condition Teuchos::ConditionXMLConverter Teuchos::ConstHandle< PointerType > Teuchos::Dependency Teuchos::DependencyXMLConverter Teuchos::FunctionObject Teuchos::FunctionObjectXMLConverter Teuchos::MpiReductionOpBase Teuchos::ParameterEntryValidator Teuchos::ParameterEntryXMLConverter Teuchos::Polynomial< CoeffT > Teuchos::ReferenceTypeReductionOp< Ordinal, T > Teuchos::UnitTestBase Teuchos::ValidatorXMLConverter Teuchos::ValueTypeReductionOp< Ordinal, T > Teuchos::ValueTypeReductionOp< Ordinal, char > Teuchos::ValueTypeReductionOp< Ordinal, Packet > Teuchos::ValueTypeReductionOp< Ordinal, std::pair< double, int > > Teuchos::ValueTypeReductionOp< Ordinal, std::pair< ScalarType, IndexType > >

List of all members.

Public Member Functions

Public virtual member functions
virtual std::string description () const
 Return a simple one-line description of this object.
virtual void describe (FancyOStream &out, const EVerbosityLevel verbLevel=verbLevel_default) const
 Print the object with some verbosity level to a FancyOStream.
void describe (std::ostream &out, const EVerbosityLevel verbLevel=verbLevel_default) const
 Version of describe() that takes an std::ostream instead of a FancyOStream.
virtual ~Describable ()
 Destructor (marked virtual for memory safety of derived classes).

Static Public Attributes

static const EVerbosityLevel verbLevel_default = VERB_DEFAULT
 Default value for the verbLevel argument of describe().

Related Functions

(Note that these are not member functions.)

DescribableStreamManipulatorState describe (const Describable &describable, const EVerbosityLevel verbLevel=Describable::verbLevel_default)
 Describable output stream manipulator.
std::ostream & operator<< (std::ostream &os, const DescribableStreamManipulatorState &d)
 Output stream operator for Describable manipulator.

Detailed Description

Base class for all objects that can describe themselves.

This base class is designed to be a minimally invasive approach for letting subclasses provide detailed debug-style information about their current state. This interface has just two virtual member functions, describe() and description(), which both have default implementations. The shorter version description() generates a brief one-line description, while the longer version describe() is designed for more detailed multiline formatted output.

Since both of these functions have reasonable default implementations, when a subclass inherits from this base class, no virtual functions need to be overridden to start with. However, when debugging time comes, one or both of these functions should be overridden to provide more useful information.

This interface derives from the LabeledObject interface. Therefore, a user may set an object-specific label on every Describable object, and the label may be incorporated into the description of the object.

Definition at line 76 of file Teuchos_Describable.hpp.


Constructor & Destructor Documentation

Teuchos::Describable::~Describable ( ) [virtual]

Destructor (marked virtual for memory safety of derived classes).

Definition at line 80 of file Teuchos_Describable.cpp.


Member Function Documentation

std::string Teuchos::Describable::description ( ) const [virtual]

Return a simple one-line description of this object.

The default implementation just returns typeName(*this), along with the object's label if defined. The function typeName(*this) guarantees that a demangled, human-readable name is returned on most platforms. Even if subclasses choose to override this function, this default implementation can still be called as Teuchos::Describable::description() in order to print the label name along with the class name.

Reimplemented in Teuchos::MpiComm< Ordinal >, and Teuchos::SerialComm< Ordinal >.

Definition at line 52 of file Teuchos_Describable.cpp.

void Teuchos::Describable::describe ( FancyOStream out,
const EVerbosityLevel  verbLevel = verbLevel_default 
) const [virtual]

Print the object with some verbosity level to a FancyOStream.

Parameters:
out[in/out] The output stream to which to write.
verbLevel[in] Verbosity level for printing the object. If verbLevel==VERB_DEFAULT (which is the default value), then the verbosity level will be determined by the object itself (e.g., through the ObjectWithVerbosity interface). It is up to each subclass instance how to interpret the input verbosity level.

You may wrap an std::ostream in a Teuchos::FancyOStream by including "Teuchos_FancyOStream.hpp" and calling Teuchos::getFancyOStream(). For example:

 using Teuchos::RCP;
 using Teuchos::rcpFromRef;
 using Teuchos::FancyOStream;

 // Wrap std::cout in a FancyOStream.
 RCP<FancyOStream> wrappedCout = getFancyOStream (rcpFromRef (std::cout));

 // Wrap an output file in a FancyOStream.
 // Use an RCP rather than a reference, to ensure that the file
 // isn't closed until the method is completely done with it.
 RCP<std::ofstream> outFile (new std::ofstream ("myFile.txt"));
 RCP<FancyOStream> wrappedFile = getFancyOStream (outFile);

A subclass' implementation of this method should begin by tabbing one increment using the OSTab class. That way, users need not include tabs themselves.

This class does not mandate what the different verbosity levels mean. It would be a good idea for Trilinos developers to reach a consensus on this. For example, if the subclass implements a large data structure like a sparse matrix, VERB_NONE should print nothing at all, VERB_LOW should print $O(1)$ data relative to the dimensions and number of entries of the matrix, and VERB_EXTREME may print all the entries of the matrix. The subclass must decide how to interpret verbosity levels in between these extremes.

This class provides a default implementation of this method that simply performs:

 OSTab tab (out);
 return out << this->description () << std::endl;

Subclasses should override this method to provide more useful information about the object.

Definition at line 64 of file Teuchos_Describable.cpp.

void Teuchos::Describable::describe ( std::ostream &  out,
const EVerbosityLevel  verbLevel = verbLevel_default 
) const

Version of describe() that takes an std::ostream instead of a FancyOStream.

This method just wraps out in a FancyOStream and calls the other describe() method. We provide this as a convenience to users who can't remember or don't want to make a FancyOStream out of their std::ostream.

Subclasses may not override this method. Instead, they must override the version of describe() that takes a FancyOStream.

Definition at line 73 of file Teuchos_Describable.cpp.


Friends And Related Function Documentation

DescribableStreamManipulatorState describe ( const Describable describable,
const EVerbosityLevel  verbLevel = Describable::verbLevel_default 
) [related]

Describable output stream manipulator.

This simple function allows you to insert output from Describable::describe() right in the middle of a chain of insertion operations. For example, you can write:

  void someFunc( const Teuchos::Describable &obj )
  {
    ...
    std::cout
      << "The object is described as "
      << describe(obj,Teuchos::VERB_MEDIUM);
    ...
  }

Definition at line 209 of file Teuchos_Describable.hpp.

std::ostream & operator<< ( std::ostream &  os,
const DescribableStreamManipulatorState &  d 
) [related]

Output stream operator for Describable manipulator.

To call this function use something like:

  void someFunc( const Teuchos::Describable &obj )
  {
    ...
    std::cout
      << "The object is described as "
      << describe(obj,Teuchos::VERB_MEDIUM);
    ...
  }

Note: The input std::ostream is casted to a FancyOStream object before calling Describable::describe() on the underlying Describable object. There is no way around this since this function must be written in terms of std::ostream rather than FancyOStream if one is to write compound output statements involving primitive data types.

Definition at line 245 of file Teuchos_Describable.hpp.


Member Data Documentation

Default value for the verbLevel argument of describe().

Definition at line 79 of file Teuchos_Describable.hpp.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines