Install Now
FBB::Mstream - Generic message handling stream
Contents
Bobcat
Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.
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;
Bugs
None Reported.
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 explicitMstream(std::ostream&ostr,size_tmaxCount=std::numeric_limits<size_t>::max(),std::stringconst&tag="",boolthrowing=false):
This constructor uses the std::streambuf that is also used by the ostreamostr. 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 explicitMstream(std::streambuf*buf,size_tmaxCount=std::numeric_limits<size_t>::max(),std::stringconst&tag="",boolthrowing=false):
This constructor uses buf to insert messages into. The remaining parameters are identical to those
of the previous constructor.
o explicitMstream(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. 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.
Copy and move constructors (and assignment operators) are not available.
Copyright
This is free software, distributed under the terms of the GNU General Public License (GPL).
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’sid 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, usingFBB::endl and usingFBB::flush might be worth considering. Also, when
usingnamespacestdandusingnamespaceFBB 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.
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
Inherits From
std::ostream
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 `usingFBB::endl’ and `usingFBB::flush’ might be worth considering. Also, when usingnamespacestdandusingnamespaceFBB is
specified the FBB::endl and FBB::flush manipulator will automatically be called when inserting endl or
flush into Mstream objects.
Member Functions
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 boolisActive()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 intid()const:
returns the unique id of the Mstream object.
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 voidoff():
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 voidon():
by default and after calling on messages inserted into the Mstream object are sent to their
destination stream.
o voidreset(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 voidreset(std::streambuf*buf):
messages inserted into the Mstream object are handled by std::streambufbuf. Other parameters
(e.g., maxCount, the message label) are kept as-is.
o voidreset(FBB::Mstreamconst&mstream):
the current object is reset using the parameters of the mstream parameter.
o voidreset(std::stringconst&name):
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 voidreset(std::ostream&ostr,size_tmaxCount,std::stringconst&tag,boolthrowing):
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 voidreset(std::streambuf*buf,size_tmaxCount,std::stringconst&tag,boolthrowing):
messages inserted into Mstream objects are handled by std::streambufbuf. The remaining parameters
are identical to those of the previous reset member.
o voidreset(std::stringconst&name,size_tmaxCount,std::stringconst&tag,boolthrowing):
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 voidreset(FBB::Mstreamconst&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 boolsetActive(boolifTrue):
If ifTrue equals true the Mstream is activated otherwise its actions are suppressed. Returns
ifTrue.
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 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 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 Mstream 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 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 voidthrowing(boolifTrue):
modifies the behaviro of Mstream objects at completed messages. After passing trueMstream 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.
Name
FBB::Mstream - Generic message handling stream
Namespace
FBB
All elements mentioned in this man-page, are defined in the namespace FBB.
See Also
bobcat(7), exception(3bobcat), mbuf(3bobcat)
Synopsis
#include<bobcat/mstream>
Linking option: -lbobcat
PNG Icons
