Teuchos Package Browser (Single Doxygen Collection) Version of the Day
Static Public Attributes | Related Functions
Teuchos::Describable Class Reference

Base class for all objects that can describe themselves and their current state. More...

#include <Teuchos_Describable.hpp>

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

List of all members.

Static Public Attributes

static const EVerbosityLevel verbLevel_default = VERB_DEFAULT
 Default value for verLevel in description()

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.

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 an FancyOStream object.

Detailed Description

Base class for all objects that can describe themselves and their current state.

This base class is designed to be a minimally invasive approach for allowing subclasses to optionally provide detailed debug-style information about their current state. This interface has just two virtual member functions, describe(void) and description(), which both have default implementations. The shorter version description() (which takes no arguments and returns an std::string object) is meant for very short one-line descriptions while the longer version describe() takes and returns a FancyOStream object and is designed for more detailed multi-line formated 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 and therefore a user can set an object-specific label on every Describable object that will be incorporated in the the description of the object.

ToDo: Include an example/testing function for a few different use cases to demonstrate how to use this interface properly.

Definition at line 68 of file Teuchos_Describable.hpp.


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 39 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 an FancyOStream object.

Parameters:
out[in] The FancyOStream object that output is sent to.
verbLevel[in] Determines the level of verbosity for which the the object will be printed. If verbLevel==VERB_DEFAULT (which is the default value), then the verbosity level will be determined by the *this object (i.e. perhaps through the ObjectWithVerbosity interface). It is up to *this how to interpret the level represented by verbLevel. The default value is VERB_DEFAULT.

In order for this function to work effectively for independently developed classes, a general consensus needs be reached as to what the various verbosity levels represented in verbLevel mean in relation to the amount of output produced.

It is expected that the subclass implementation will tab the output one increment using the OSTab class. This convention results in orderly output from independently written subclasses.

A default implementation of this function is provided that simply performs:

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

A subclass should override this function to provide more interesting and more useful information about the object.

Definition at line 51 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 170 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 206 of file Teuchos_Describable.hpp.


Member Data Documentation

Default value for verLevel in description()

Definition at line 72 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