Provided by: libbobcat-dev_4.08.02-2build1_amd64 
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.02-x.dsc: detached signature;
o bobcat_4.08.02-x.tar.gz: source archive;
o bobcat_4.08.02-x_i386.changes: change log;
o libbobcat1_4.08.02-x_*.deb: debian package holding the libraries;
o libbobcat1-dev_4.08.02-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).