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

#include <Teuchos_Describable.hpp>

Inheritance diagram for Teuchos::Describable:

Public Member Functions
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...

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...

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...

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::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`
	)

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
	)

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

const EVerbosityLevel Teuchos::Describable::verbLevel_default = VERB_DEFAULT

static

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:

Public Member Functions

Static Public Attributes

Related Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation