--- name: "mbuf" section: "3bobcat" platform: "linux" package: "libbobcat-dev" version: "6.07.01-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/mbuf" --- # mbuf(3bobcat) std::streambuf handling messages ## NAME FBB::Mbuf - std::streambuf handling messages ## SYNOPSIS **#include \**\ Linking option: *-lbobcat* ## DESCRIPTION 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)](/mstream/3bobcat.md) objects, and passing *Mbuf* objects to other kind of *ostream* objects is deprecated and results in undefined behavior. ## 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 messages 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\::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 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\::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 **explicit Mbuf(std::string const &name, size\_t maxCount =** **std::numeric\_limits\::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::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. ## 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\::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 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\::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 **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::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 **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., 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 **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 **void throwing(bool ifTrue)**:\ modifies the behavior of **FBB::Mbuf** objects at completed messages. After passing *true* **FBB::Mbuf** objects will throw an *FBB::Exception* exception at the next completed message, otherwise this exception is not thrown. ## EXAMPLE See the [**mstream**(3bobcat)](/mstream/3bobcat.md) example. ## FILES *bobcat/mbuf* - defines the class interface ## SEE ALSO [**bobcat**(7)](/bobcat/7.md), [**exception**(3bobcat)](/exception/3bobcat.md), [**mstream**(3bobcat)](/mstream/3bobcat.md) ## BUGS None Reported. ## BOBCAT PROJECT FILES - 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; ## 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**).