FBB::Mbuf(3bobcat)                                                Message handler                                               FBB::Mbuf(3bobcat)

NAME

       FBB::Mbuf - std::streambuf handling messages

SYNOPSIS

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

DESCRIPTION

       Objects  of  this  class  implement a std::streambuf class that are used to handle messages in a standardized way. Messages may be prefixed
       with order numbers and labels and/or line numbers.

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

       FBB::Mbuf  objects themselves are std::streambuf objects, so they can be used to construct std::ostream objects. However, they are intended
       to be used by mstream(3bobcat) objects.

NAMESPACE

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

INHERITS FROM

       std::streambuf

CONSTRUCTORS

       o      Mbuf():
              The default constructor handles messages using the std::streambuf also used by std::cout. There is no limit to the  number  of  mes-
              sages that may be inserted. No message or line numbers are shown, no exception are thrown when inserting messages.

       o      explicit  Mbuf(std::streambuf *buf, size_t maxCount = std::numeric_limits<size_t>::max(), std::string const &tag = "", bool throwing
              = false):
              This constructor uses buf to handle messages. By default (using the default argument values) there is no limit to the number of mes-
              sages  that  may  be inserted. No message or line numbers are shown, no exception are thrown when inserting messages. Specifying any
              other value than std::numeric_limits<size_t>::max() sets 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 specified as true an FBB::Errno exception is thrown after com-
              pleting a message. The generated exception holds the id (see below for the member id) of the FBB::Mbuf object from which the  excep-
              tion was thrown as well as the text FBB::Mbuf.

       o      explicit  Mbuf(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 that receives the  messages  handled  by  the  constructed
              FBB:Mbuf object. It throws an FBB::Errno 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  FBB::Mbuf  inherits  from
              std::streambuf 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 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 mes-
              sage is being (or has been) inserted.

       o      void reset(std::streambuf *buf, size_t maxCount, std::string const &tag, bool throwing):
              messages inserted into FBB::Mbuf objects are handled by std::streambuf buf.  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 FBB::Errno exception  is
              thrown after completing a message.

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

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

       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  FBB::Mbuf 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 FBB::Mbuf 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., speci-
              fying 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  FBB::Mbuf object will throw an FBB::Errno exception at the next completed message. The generated exception
              holds the id (see earlier for the member id) of the FBB::Mbuf object from which the  exception  was  thrown  as  well  as  the  text
              FBB::Mbuf.

       o      void throwing(bool ifTrue):
              modifies  the  behavior  of  FBB::Mbuf  objects at completed messages. After passing true FBB::Mbuf objects will throw an FBB::Errno
              exception at the next completed message, otherwise this exception is not thrown.

EXAMPLE

       See the mstream(3bobcat) example.

FILES

       bobcat/mbuf - defines the class interface

SEE ALSO

       bobcat(7), errno(3bobcat), mstream(3bobcat)

BUGS

       None Reported.

DISTRIBUTION FILES

       o      bobcat_3.01.00-x.dsc: detached signature;

       o      bobcat_3.01.00-x.tar.gz: source archive;

       o      bobcat_3.01.00-x_i386.changes: change log;

       o      libbobcat1_3.01.00-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_3.01.00-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).

libbobcat1-dev_3.01.00-x.tar.gz                                      2005-2012                                                  FBB::Mbuf(3bobcat)