Objects of this class may be used to handle messages in a standardized
way. Messages may be prefixed with order numbers and labels and/or line
numbers. Messages generated by Mstream objects may optionally end in
an 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:
FBB::emsg for generating standard (labeled and numbered) error
messages, e.g.
[Error 1] this is an error message
FBB::fmsg for generating (labeled) fatal error messages, ending in an
exception, e.g.,
[Fatal] this fatal message is followed by an exception
FBB::imsg for generating plain informational messages, e.g.,
this is a plain message
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 stdandusing 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
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
exception are thrown when inserting messages.
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 exception 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 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
Mstream object from which the exception was thrown as well as the
text FBB::Mstream.
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.
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 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.
As Mstream inherits from std::ostream the copy constructor is
not available. Neither is the move constructor.
MEMBER FUNCTIONS
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).
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.
int id() const:
returns the unique id of the Mstream object.
bool lineExcess() const:
returns true after attempting to insert an additional message
after maxCount number of messages have been inserted.
std::string const &lineTag() const:
returns the currently used line-tag (by default `Line').
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.
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.
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.
void on():
by default and after calling on messages inserted into the
Mstream object are sent to their destination stream.
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.
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.
void reset(FBB::Mstream const &mstream):
the current object is reset using the parameters of the mstream
parameter.
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.
FBB::Exception exception 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.
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 FBB::Exception exception is thrown after
completing a message.
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.
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
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 reset members.
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.
bool setActive(bool ifTrue):
If ifTrue equals true the Mstream is activated
otherwise its actions are suppressed. Returns ifTrue.
void setCount(size_t count):
assigns the value count to the object's message counter.
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).
void setLineTag(std::string const &tag):
specifies the tag prefixing line numbers. By default the line tag
equals `Line'.
void setMaxCount(size_t maxCount):
defines maxCount as the maximum number of messages that can be
inserted into the Mstream object.
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].
std::string const &tag() const:
returns the currently used message tag (by default an empty string).
bool throws():
returns true when the Mstream 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
Mstream object from which the exception was thrown as well as the
text FBB::Mstream.
void throwing(bool ifTrue):
modifies the behaviro of Mstream objects at completed
messages. After passing trueMstream objects will throw an
FBB::Exception exception at the next completed message, otherwise this
exception is not thrown. The generated exception holds the id (see earlier for
the member id) of the Mstream object from which the exception was
thrown as well as the text FBB::Mstream.
MANIPULATORS
Note that the following two manipulators are not members of the class
Mstream, but are free functions defined in the namespace FBB.
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.
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 will throw an FBB:::Exception exception which holds
the id (see earlier for the member id) of the Mstream object from
which the exception was thrown as well as the text FBB::Mstream. When
used in combination with another kind of std::ostream object it acts like
std::flush.
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 stdandusing 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>
#include <bobcat/errno>
using namespace std;
using namespace FBB;
int main(int argc, char **argv)
try
{
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" << endl;
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;
cerr << "(cerr) LineExcess: " << emsg.lineExcess() << ", count = " <<
emsg.count() << endl;
emsg << "Fourth error" << endl;
cerr << "(cerr) LineExcess: " << emsg.lineExcess() << ", count = " <<
emsg.count() << endl;
cerr << "Beyond\n";
}
catch(FBB::Errno const &e)
{
std::cerr << "Got an Errno object: " << e.why() << '\n';
}
catch(...)
{
std::cerr << "Got an exception\n";
}
FILES
bobcat/mstream - defines the class interface
SEE ALSO
bobcat(7), errno(3bobcat), mbuf(3bobcat)
BUGS
None Reported.
DISTRIBUTION FILES
bobcat_3.22.00-x.dsc: detached signature;
bobcat_3.22.00-x.tar.gz: source archive;
bobcat_3.22.00-x_i386.changes: change log;
libbobcat1_3.22.00-x_*.deb: debian package holding the
libraries;
libbobcat1-dev_3.22.00-x_*.deb: debian package holding the
libraries, headers and manual pages;
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).