Teuchos Package Browser (Single Doxygen Collection)  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Static Public Attributes | Related Functions | List of all members
Teuchos::Describable Class Reference

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

#include <Teuchos_Describable.hpp>

Inheritance diagram for Teuchos::Describable:
Inheritance graph
[legend]

Static Public Attributes

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

Related Functions

(Note that these are not member functions.)

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

Public virtual member functions

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

Additional Inherited Members

- Public Member Functions inherited from Teuchos::LabeledObject
 LabeledObject ()
 Construct with an empty label. More...
 
virtual ~LabeledObject ()
 
virtual void setObjectLabel (const std::string &objectLabel)
 Set the object label (see LabeledObject). More...
 
virtual std::string getObjectLabel () const
 Get the object label (see LabeledObject). More...
 

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 44 of file Teuchos_Describable.hpp.

Constructor & Destructor Documentation

Teuchos::Describable::~Describable ( )
virtual

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

Definition at line 48 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::SerialComm< Ordinal >.

Definition at line 20 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::rcpFromRef;
// 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 32 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 41 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 "
...
}

Definition at line 177 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 "
...
}

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 213 of file Teuchos_Describable.hpp.

Member Data Documentation

const EVerbosityLevel Teuchos::Describable::verbLevel_default = VERB_DEFAULT
static

Default value for the verbLevel argument of describe().

Definition at line 47 of file Teuchos_Describable.hpp.


The documentation for this class was generated from the following files: