FBB::Mbuf - std::streambuf handling messages

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

libbobcat-dev_6.07.01                               2005-2025                                 FBB::Mbuf(3bobcat)

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

       o      https://fbb-git.gitlab.io/bobcat/: gitlab project page;

       Debian Bobcat project files:

       o      libbobcat6: debian package containing the shared library, changelog and copyright note;

       o      libbobcat-dev:  debian package containing the static library, headers, manual pages, and developer
              info;

       None Reported.

       o      Mbuf():
              The default constructor handles messages using the std::streambuf also 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
              exception are thrown when inserting messages.

       o      explicitMbuf(std::streambuf*buf,size_tmaxCount=std::numeric_limits<size_t>::max(),std::stringconst&tag="",boolthrowing=false):
              This constructor uses buf to handle messages. 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  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::Exception exception is thrown after completing a message. The generated
              exception holds the id (see below for the member id)  of  the  FBB::Mbuf  object  from  which  the
              exception was thrown as well as the text FBB::Mbuf.

       o      explicitMbuf(std::stringconst&name,size_tmaxCount=std::numeric_limits<size_t>::max(),std::stringconst&tag="",boolthrowing=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::Exception 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.

       Copy and move constructors (and assignment operators) are not available.

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

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

       By default all messages are inserted into the standard output stream, but  other  destinations  (standard
       error, a named file, etc.) can easily 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, and passing Mbuf  objects  to
       other kind of ostream objects is deprecated and results in undefined behavior.

       See the mstream(3bobcat) example.

bobcat/mbuf - defines the class interface

std::streambuf

       o      size_tcount()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      boollineExcess()const:
              returns true after attempting to insert an additional message after maxCount() number of  messages
              have been inserted.

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

       o      size_tmaxCount()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      voidnoLineNr():
              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      voidreset(std::streambuf*buf,size_tmaxCount,std::stringconst&tag,boolthrowing):
              messages inserted into FBB::Mbuf  objects  are  handled  by  std::streambufbuf.   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::Exception
              exception is thrown after completing a message.

       o      voidreset(std::stringconst&name,size_tmaxCount,std::stringconst&tag,boolthrowing):
              messages inserted into FBB::Mbuf objects are handled by a std::ofstream created using the provided
              name parameter. It throws an FBB::Exception 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 reset members.

       o      voidreset(FBB::Mbufconst&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      voidsetCount(size_tcount):
              assigns the value count to the object’s message counter.

       o      voidsetLineNr(size_tlineNr):
              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      voidsetLineTag(std::stringconst&tag):
              specifies the tag prefixing line numbers. By default the line tag equals `Line’.

       o      voidsetMaxCount(size_tmaxCount):
              defines maxCount as the maximum number of messages that can be inserted into the FBB::Mbuf object.

       o      voidsetTag(std::stringconst&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::stringconst&tag()const:
              returns the currently used message tag (by default an empty string).

       o      boolthrows():
              returns  true  when  the  FBB::Mbuf  object  will  throw  an  FBB::Exception 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      voidthrowing(boolifTrue):
              modifies  the  behavior  of  FBB::Mbuf objects at completed messages. After passing trueFBB::Mbuf
              objects will throw an FBB::Exception exception at  the  next  completed  message,  otherwise  this
              exception is not thrown.

       FBB::Mbuf - std::streambuf handling messages

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

bobcat(7), exception(3bobcat), mstream(3bobcat)

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