Provided by: libbobcat-dev_4.08.06-1build1_amd64 bug

NAME

       FBB::Mstream - Generic message handling stream

SYNOPSIS

       #include <bobcat/mstream>
       Linking option: -lbobcat

DESCRIPTION

       Objects  of  this class are used for handling messages in a standardized way. Messages may
       be prefixed with order (line) numbers an/or, labels. Messages generated by Mstream objects
       may  optionally  end  by throwing an FBB::Exception (which is an std::exception), allowing
       simple implementation of, e.g., fatal error messages.

       Four message streams are provided by the BOBCAT library and may be  used  after  including
       the mstream header file. They are all defined in the FBB namespace:

       o      FBB::emsg for generating standard (labeled and numbered) error messages, e.g.

              [Error 1] this is an error message

       o      FBB::fmsg  for  generating  (labeled) fatal error messages, ending in an exception,
              e.g.,

              [Fatal] this fatal message is followed by an exception

              The exception’s what member contains FBB::fmsg’s id value (see member id below).

       o      FBB::imsg for generating plain informational messages, e.g.,

              this is a plain message

       o      FBB::wmsg for generating (labeled) warning messages;

              [Warning] this is a warning

              By default all messages are inserted into the standard  output  stream,  but  other
              destinations (standard error, a named file, etc.) can easily be configured.

       Mstream objects themselves are std::ostream objects, so they can be used as objects passed
       to functions expecting ostream arguments.  Messages  inserted  into  Mstream  objects  are
       buffered  until  the  buffer  is  flushed  by  their std::ostream parts or when either the
       FBB::endl or FBB::flush is inserted into the message stream. Since these manipulators  act
       like  std::endl  and  std::flush  when  inserted into another kind of std::ostream object,
       using FBB::endl and  using  FBB::flush  might  be  worth  considering.  Also,  when  using
       namespace  std  and  using  namespace  FBB  is  specified  the  FBB::endl  and  FBB::flush
       manipulator will automatically be used with Mstream objects.

       Messages inserted into Mstream objects are considered completed at the  insertion  of  the
       FBB::endl  or FBB::flush manipulators. Message labels, line number labels and line numbers
       will only be shown for the next line after  these  manipulators  have  been  inserted  and
       exceptions are, if needed, thrown from these manipulators.

NAMESPACE

       FBB
       All elements mentioned in this man-page, are defined in the namespace FBB.

INHERITS FROM

       std::ostream

CONSTRUCTORS

       o      Mstream():
              The  default  constructor  generates  messages  using  the  std::streambuf  used by
              std::cout. There is no limit to the number of messages that  may  be  inserted.  No
              message  or  line  numbers  are  shown,  no  exceptions  are  thrown when inserting
              messages.

       o      explicit      Mstream(std::ostream       &ostr,       size_t       maxCount       =
              std::numeric_limits<size_t>::max(),  std::string  const  &tag = "", bool throwing =
              false):
              This constructor uses the std::streambuf that is also used by the ostream ostr.  By
              default  (using  the  default  argument  values) there is no limit to the number of
              messages that may be inserted. No message or line numbers are shown, no  exceptions
              are   thrown   when   inserting   messages.   Specifying   any   other  value  than
              std::numeric_limits<size_t>::max() will set the maximum number of messages that can
              be  inserted  to  that  value. The tag defines the text of the message label (e.g.,
              Error).

              When throwing is true an exception  is  thrown  after  completing  a  message.  The
              generated  exception’s what member may show the FBB::Mstream object’s id (see below
              at the member id) of the Mstream object throwing the exception.

       o      explicit      Mstream(std::streambuf      *buf,       size_t       maxCount       =
              std::numeric_limits<size_t>::max(),  std::string  const  &tag = "", bool throwing =
              false):
              This constructor uses buf to insert messages into.  The  remaining  parameters  are
              identical to those of the previous constructor.

       o      explicit     Mstream(std::string     const     &name,     size_t     maxCount     =
              std::numeric_limits<size_t>::max(), std::string const &tag = "",  bool  throwing  =
              false):
              This  constructor  creates  a  std::ofstream  from  the provided name parameter. It
              throws an exception if the stream cannot be opened for writing. If a file  by  that
              name  already  exists  it  is rewritten.  The remaining parameters are identical to
              those of the previous two constructors.  As Mstream inherits from std::ostream  the
              copy constructor is not available. Neither is the move constructor.

MEMBER FUNCTIONS

       o      size_t count() const:
              returns the number of inserted messages (if setCount has been called: the value set
              by the last setCount call plus the number of inserted messages since that call).

       o      bool  isActive() const:
              returns true if messages can  actually be inserted into  the  FBB::MStream  object,
              and  false  if  inserted  messages  are ignored. When ignoring messages the message
              count is not updated.

       o      int id() const:
              returns the unique id of the Mstream object.

       o      bool lineExcess() const:
              returns true after attempting to insert an additional message after maxCount number
              of messages have been inserted.

       o      std::string const &lineTag() const:
              returns the currently used line-tag (by default `Line’).

       o      size_t maxCount() const:
              returns  the maximum number of messages that can be inserted. If the returned value
              equals std::numeric_limits<size_t>::max() then there is no limit to the  number  of
              messages that can be inserted.

       o      void noLineNr():
              calling  this  member  will  suppress  the display of a line number if it is called
              after calling setLineNr (see below) but before a message is  being  (or  has  been)
              inserted.

       o      void off():
              after  calling  off messages inserted into the Mstream object are silently ignored.
              After calling off the internal message counter is not incremented when messages are
              inserted.

       o      void on():
              by  default and after calling on messages inserted into the Mstream object are sent
              to their destination stream.

       o      void reset(std::ostream &ostr):
              messages inserted into the Mstream object are handled by  the  std::streambuf  also
              used by ostr. Other parameters (e.g., maxCount, the message label) are kept as-is.

       o      void reset(std::streambuf *buf):
              messages  inserted into the Mstream object are handled by std::streambuf buf. Other
              parameters (e.g., maxCount, the message label) are kept as-is.

       o      void reset(FBB::Mstream const &mstream):
              the current object is reset using the parameters of the mstream parameter.

       o      void reset(std::string const &name, size_t maxCount, std::string const  &tag,  bool
              throwing):
              messages inserted into Mstream objects are handled by a std::ofstream created using
              the provided name parameter.  An exception is thrown if the stream cannot be opened
              for  writing.  If  a  file  by  that  name  already  exists  it is rewritten. Other
              parameters (e.g., maxCount, the message label) are kept as-is.

       o      void reset(std::ostream  &ostr,  size_t  maxCount,  std::string  const  &tag,  bool
              throwing):
              messages  inserted into Mstream objects are handled by the std::streambuf also used
              by ostr.  By specifying std::numeric_limits<size_t>::max() for maxCount there is no
              limit to the number of messages that may be handled by this std::streambuf. The tag
              defines the text of the message label (e.g., Error  or  the  empty  string  for  no
              message  label).  When  throwing  is specified as true an exception is thrown after
              completing a message.

       o      void reset(std::streambuf *buf,  size_t  maxCount,  std::string  const  &tag,  bool
              throwing):
              messages  inserted  into  Mstream  objects  are  handled by std::streambuf buf. The
              remaining parameters are identical to those of the previous reset member.

       o      void reset(std::string const &name, size_t maxCount, std::string const  &tag,  bool
              throwing):
              messages inserted into Mstream objects are handled by a std::ofstream created using
              the provided name parameter. It throws an exception if the stream cannot be  opened
              for  writing. If a file by that name already exists it is rewritten.  The remaining
              parameters are identical to those of the previous two reset members.

       o      void reset(FBB::Mstream const &mstream):
              the current object  is  reset  using  the  parameters  of  the  mstream  parameter.
              Following  the  reset  all  of the current object’s parameters can independently be
              modified from those used by mstream.

       o      bool setActive(bool ifTrue):
              If  ifTrue  equals  true  the  Mstream  is  activated  otherwise  its  actions  are
              suppressed. Returns ifTrue.

       o      void setCount(size_t count):
              assigns the value count to the object’s message counter.

       o      void setLineNr(size_t lineNr):
              specifies  the  value  lineNr  as  the  message’s line number when the next line is
              displayed (see also noLineNr). This value is not changed by the Mstream object.  To
              display another line number the member will have to be called again (i.e., the line
              number is not displayed automatically again at every new line).

       o      void setLineTag(std::string const &tag):
              specifies the tag prefixing line numbers. By default the line tag equals `Line’.

       o      void setMaxCount(size_t maxCount):
              defines maxCount as the maximum number of messages that can be  inserted  into  the
              Mstream object.

       o      void setTag(std::string const &tag):
              specifies the tag prefixing messages. By default the tag is empty. If not empty the
              tag is enclosed by square brackets. E.g., specifying the tag  `Error’  will  prefix
              messages with [Error].

       o      std::string const &tag() const:
              returns the currently used message tag (by default an empty string).

       o      bool throws():
              returns  true when the Mstream object will throw an exception at the next completed
              message. The generated exception’s what member contains the id (see earlier for the
              member id) of the Mstream object throwing the exception.

       o      void throwing(bool ifTrue):
              modifies  the behaviro of Mstream objects at completed messages. After passing true
              Mstream objects will throw an exception at the next  completed  message,  otherwise
              this exception is not thrown. The generated exception’s what member contains the id
              (see earlier for the member id) of the Mstream object throwing the exception.

MANIPULATORS

       Note that the following two manipulators are not members of the  class  Mstream,  but  are
       free functions defined in the namespace FBB.

       o      std::ostream &endl(std::ostream &out):
              This manipulator inserts a newline character in the Mstream’s stream and then calls
              FBB::flush. This manipulator acts like std::endl and std::flush when inserted  into
              another kind of std::ostream object.

       o      std::ostream &flush(std::ostream &out):
              This  manipulator  completes  the  message that is currently being inserted into an
              Mstream object. It flushes the object’s destination stream and prepares the  object
              for  the  next  message.  When the object’s throws member returns true it throws an
              exception whose what member contains the id (see earlier for the member id) of  the
              Mstream  object  throwing the exception. When used in combination with another kind
              of std::ostream object it acts like std::flush.

       o      std::ostream &noid(std::ostream &out):
              This manipulator completes the message that is currently  being  inserted  into  an
              Mstream  object. It flushes the object’s destination stream and prepares the object
              for the next message.  When the object’s throws member returns true  it  throws  an
              exception  whose what member does not contain the Mstream object’s ID. When used in
              combination with another kind of std::ostream object it acts like std::flush.

       o      std::ostream &noidl(std::ostream &out):
              This manipulator inserts a newline character in the Mstream’s stream and then calls
              FBB::noid.  This  manipulator acts like std::endl and std::flush when inserted into
              another kind of std::ostream object.

       As the manipulators  FBB::endl  and  FBB::flush  act  like,  respectively,  std::endl  and
       std::flush  when inserted into another kind of std::ostream object, using the declarations
       `using FBB::endl’ and `using FBB::flush’ might be  worth  considering.  Also,  when  using
       namespace  std  and  using  namespace  FBB  is  specified  the  FBB::endl  and  FBB::flush
       manipulator will automatically be  called  when  inserting  endl  or  flush  into  Mstream
       objects.

EXAMPLE

       #include <iostream>
       #include <algorithm>
       #include <iterator>

       #include <bobcat/mstream>

       using namespace std;
       using namespace FBB;

       int main(int argc, char **argv)
       try
       {
           cout << sizeof(Mstream) << ’ ’ << sizeof(Mbuf) << ’\n’;

           imsg << "Informational: " << endl;
           imsg.off();
           cout << "The i-msg stream is now off. This message should appear once" <<
                                                                               endl;
           imsg << "The i-msg stream is now off. This message should appear once" <<
                                                                               endl;
           imsg << "The i-msg stream is now off. This message should appear once" <<
                                                                               endl;
           cout << "But this message is shown" << endl;

           wmsg << "Warning message" << endl;
           emsg << "Oops, this this is an error (not really)" << endl;
           emsg << "Oops, this goes wrong, too" << noid;

           imsg.on();
           imsg << "And another informational msg: " << emsg.count() <<
                   " error messages\n" << flush;

           emsg << "Third error" << endl;
           emsg.setMaxCount(3);

           imsg << "Msg in between" << endl;

           imsg.setTag("tag");
           imsg << "tagged message" << endl;

           imsg.setTag("label");
           imsg << "labeled message" << endl;

           cerr << "(cerr) LineExcess: " << emsg.lineExcess() << ", count = " <<
                   emsg.count() << endl;

           emsg << "Fourth error\n" << noid;       // no id is shown
           emsg << "Fourth error\n" << flush;      // shows id (remove the previous
                                                   // statement)

           cerr << "(cerr) LineExcess: " << emsg.lineExcess() << ", count = " <<
                   emsg.count() << endl;

           cerr << "Beyond\n";
       }
       catch(exception const &e)
       {
           std::cerr << "Got a std::exception: " << e.what() << ’\n’;
       }
       catch(...)
       {
           std::cerr << "Got an exception\n";
       }

FILES

       bobcat/mstream - defines the class interface

SEE ALSO

       bobcat(7), exception(3bobcat), mbuf(3bobcat)

BUGS

       None Reported.

DISTRIBUTION FILES

       o      bobcat_4.08.06-x.dsc: detached signature;

       o      bobcat_4.08.06-x.tar.gz: source archive;

       o      bobcat_4.08.06-x_i386.changes: change log;

       o      libbobcat1_4.08.06-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_4.08.06-x_*.deb:  debian  package holding the libraries, headers and
              manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;

BOBCAT

       Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.

COPYRIGHT

       This is free software, distributed under the terms  of  the  GNU  General  Public  License
       (GPL).

AUTHOR

       Frank B. Brokken (f.b.brokken@rug.nl).