.TH "FBB::Mstream" "3bobcat" "2005\-2020" "libbobcat\-dev_5\&.07\&.00" "Message handler" .PP .SH "NAME" FBB::Mstream \- Generic message handling stream .PP .SH "SYNOPSIS" \fB#include \fP .br Linking option: \fI\-lbobcat\fP .PP .SH "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 \fIMstream\fP objects may optionally end by throwing an \fIFBB::Exception\fP (which is an \fIstd::exception\fP), allowing simple implementation of, e\&.g\&., fatal error messages\&. .PP Four message streams are provided by the \fIBOBCAT\fP library and may be used after including the \fImstream\fP header file\&. They are all defined in the \fIFBB\fP namespace: .IP o \fIFBB::emsg\fP for generating standard (labeled and numbered) error messages, e\&.g\&. .nf [Error 1] this is an error message .fi .IP o \fIFBB::fmsg\fP for generating (labeled) fatal error messages, ending in an exception, e\&.g\&., .nf [Fatal] this fatal message is followed by an exception .fi The exception\(cq\&s \fIwhat\fP member contains \fIFBB::fmsg\(cq\&s id\fP value (see member \fIid\fP below)\&. .IP o \fIFBB::imsg\fP for generating plain informational messages, e\&.g\&., .nf this is a plain message .fi .IP o \fIFBB::wmsg\fP for generating (labeled) warning messages; .nf [Warning] this is a warning .fi By default all messages are inserted into the standard output stream, but other destinations (standard error, a named file, etc\&.) can easily be configured\&. .PP \fIMstream\fP objects themselves are \fIstd::ostream\fP objects, so they can be used as objects passed to functions expecting \fIostream\fP arguments\&. Messages inserted into \fIMstream\fP objects are buffered until the buffer is flushed by their \fIstd::ostream\fP parts or when either the \fIFBB::endl\fP or \fIFBB::flush\fP is inserted into the message stream\&. Since these manipulators act like \fIstd::endl\fP and \fIstd::flush\fP when inserted into another kind of \fIstd::ostream\fP object, \fIusing FBB::endl\fP and \fIusing FBB::flush\fP might be worth considering\&. Also, when \fIusing namespace std\fP \fIand\fP \fIusing namespace FBB\fP is specified the \fIFBB::endl\fP and \fIFBB::flush\fP manipulator will automatically be used with \fIMstream\fP objects\&. .PP Messages inserted into \fIMstream\fP objects are considered completed at the insertion of the \fIFBB::endl\fP or \fIFBB::flush\fP 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\&. .PP .SH "NAMESPACE" \fBFBB\fP .br All elements mentioned in this man\-page, are defined in the namespace \fBFBB\fP\&. .PP .SH "INHERITS FROM" \fBstd::ostream\fP .PP .SH "CONSTRUCTORS" .IP o \fBMstream()\fP: .br The default constructor generates messages using the \fIstd::streambuf\fP used by \fIstd::cout\fP\&. 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\&. .IP o \fBexplicit Mstream(std::ostream &ostr, size_t maxCount = std::numeric_limits::max(), std::string const &tag = \(dq\&\(dq\&, bool throwing = false)\fP: .br This constructor uses the \fIstd::streambuf\fP that is also used by the \fIostream ostr\fP\&. 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 \fIstd::numeric_limits::max()\fP will set the maximum number of messages that can be inserted to that value\&. The \fItag\fP defines the text of the message label (e\&.g\&., \fIError\fP)\&. .IP When \fIthrowing\fP is \fItrue\fP an exception is thrown after completing a message\&. The generated exception\(cq\&s \fIwhat\fP member may show the \fBFBB::Mstream\fP object\(cq\&s id (see below at the member \fIid\fP) of the \fIMstream\fP object throwing the exception\&. .IP o \fBexplicit Mstream(std::streambuf *buf, size_t maxCount = std::numeric_limits::max(), std::string const &tag = \(dq\&\(dq\&, bool throwing = false)\fP: .br This constructor uses \fIbuf\fP to insert messages into\&. The remaining parameters are identical to those of the previous constructor\&. .IP o \fBexplicit Mstream(std::string const &name, size_t maxCount = std::numeric_limits::max(), std::string const &tag = \(dq\&\(dq\&, bool throwing = false)\fP: .br This constructor creates a \fIstd::ofstream\fP from the provided \fIname\fP 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\&. .PP Copy and move constructors (and assignment operators) are not available\&. .PP .SH "MEMBER FUNCTIONS" .PP .IP o \fBsize_t count() const\fP: .br returns the number of inserted messages (if \fIsetCount\fP has been called: the value set by the last \fIsetCount\fP call plus the number of inserted messages since that call)\&. .IP .IP o \fBbool isActive() const\fP: .br returns \fItrue\fP if messages can actually be inserted into the \fBFBB::MStream\fP object, and \fIfalse\fP if inserted messages are ignored\&. When ignoring messages the message count is not updated\&. .IP .IP o \fBint id() const\fP: .br returns the unique \fIid\fP of the \fIMstream\fP object\&. .IP .IP o \fBbool lineExcess() const\fP: .br returns \fBtrue\fP after attempting to insert an additional message after \fImaxCount\fP number of messages have been inserted\&. .IP .IP o \fBstd::string const &lineTag() const\fP: .br returns the currently used line\-tag (by default `\fILine\fP\(cq\&)\&. .IP .IP o \fBsize_t maxCount() const\fP: .br returns the maximum number of messages that can be inserted\&. If the returned value equals \fIstd::numeric_limits::max()\fP then there is no limit to the number of messages that can be inserted\&. .IP .IP o \fBvoid noLineNr()\fP: .br calling this member will suppress the display of a line number if it is called after calling \fIsetLineNr\fP (see below) but before a message is being (or has been) inserted\&. .IP .IP o \fBvoid off()\fP: .br after calling \fIoff\fP messages inserted into the \fIMstream\fP object are silently ignored\&. After calling \fIoff\fP the internal message counter is not incremented when messages are inserted\&. .IP .IP o \fBvoid on()\fP: .br by default and after calling \fIon\fP messages inserted into the \fIMstream\fP object are sent to their destination stream\&. .IP .IP o \fBvoid reset(std::ostream &ostr)\fP: .br messages inserted into the \fIMstream\fP object are handled by the \fIstd::streambuf\fP also used by \fIostr\fP\&. Other parameters (e\&.g\&., \fImaxCount\fP, the message label) are kept as\-is\&. .IP .IP o \fBvoid reset(std::streambuf *buf)\fP: .br messages inserted into the \fIMstream\fP object are handled by \fIstd::streambuf buf\fP\&. Other parameters (e\&.g\&., \fImaxCount\fP, the message label) are kept as\-is\&. .IP .IP o \fBvoid reset(FBB::Mstream const &mstream)\fP: .br the current object is reset using the parameters of the \fImstream\fP parameter\&. .IP .IP o \fBvoid reset(std::string const &name, size_t maxCount, std::string const &tag, bool throwing)\fP: .br messages inserted into \fIMstream\fP objects are handled by a \fIstd::ofstream\fP created using the provided \fIname\fP 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\&., \fImaxCount\fP, the message label) are kept as\-is\&. .IP .IP o \fBvoid reset(std::ostream &ostr, size_t maxCount, std::string const &tag, bool throwing)\fP: .br messages inserted into \fIMstream\fP objects are handled by the \fIstd::streambuf\fP also used by \fIostr\fP\&. By specifying \fIstd::numeric_limits::max()\fP for \fImaxCount\fP there is no limit to the number of messages that may be handled by this \fIstd::streambuf\fP\&. The \fItag\fP defines the text of the message label (e\&.g\&., \fIError\fP or the empty string for no message label)\&. When \fIthrowing\fP is specified as \fItrue\fP an exception is thrown after completing a message\&. .IP .IP o \fBvoid reset(std::streambuf *buf, size_t maxCount, std::string const &tag, bool throwing)\fP: .br messages inserted into \fIMstream\fP objects are handled by \fIstd::streambuf buf\fP\&. The remaining parameters are identical to those of the previous \fIreset\fP member\&. .IP .IP o \fBvoid reset(std::string const &name, size_t maxCount, std::string const &tag, bool throwing)\fP: .br messages inserted into \fIMstream\fP objects are handled by a \fIstd::ofstream\fP created using the provided \fIname\fP 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 \fIreset\fP members\&. .IP .IP o \fBvoid reset(FBB::Mstream const &mstream)\fP: .br the current object is reset using the parameters of the \fImstream\fP parameter\&. Following the reset all of the current object\(cq\&s parameters can independently be modified from those used by \fImstream\fP\&. .IP .IP o \fBbool setActive(bool ifTrue)\fP: .br If \fIifTrue\fP equals \fItrue\fP the \fIMstream\fP is activated otherwise its actions are suppressed\&. Returns \fIifTrue\fP\&. .IP .IP o \fBvoid setCount(size_t count)\fP: .br assigns the value \fIcount\fP to the object\(cq\&s message counter\&. .IP .IP o \fBvoid setLineNr(size_t lineNr)\fP: .br specifies the value \fIlineNr\fP as the message\(cq\&s line number when the next line is displayed (see also \fInoLineNr\fP)\&. This value is \fInot\fP changed by the \fIMstream\fP 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)\&. .IP .IP o \fBvoid setLineTag(std::string const &tag)\fP: .br specifies the tag prefixing line numbers\&. By default the line tag equals `\fILine\fP\(cq\&\&. .IP .IP o \fBvoid setMaxCount(size_t maxCount)\fP: .br defines \fImaxCount\fP as the maximum number of messages that can be inserted into the \fIMstream\fP object\&. .IP .IP o \fBvoid setTag(std::string const &tag)\fP: .br 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 `\fIError\fP\(cq\& will prefix messages with \fI[Error]\fP\&. .IP .IP o \fBstd::string const &tag() const\fP: .br returns the currently used message tag (by default an empty string)\&. .IP .IP o \fBbool throws()\fP: .br returns \fItrue\fP when the \fIMstream\fP object will throw an exception at the next completed message\&. The generated exception\(cq\&s \fIwhat\fP member contains the id (see earlier for the member \fIid\fP) of the \fIMstream\fP object throwing the exception\&. .IP .IP o \fBvoid throwing(bool ifTrue)\fP: .br modifies the behaviro of \fIMstream\fP objects at completed messages\&. After passing \fItrue\fP \fIMstream\fP objects will throw an exception at the next completed message, otherwise this exception is not thrown\&. The generated exception\(cq\&s \fIwhat\fP member contains the id (see earlier for the member \fIid\fP) of the \fIMstream\fP object throwing the exception\&. .PP .SH "MANIPULATORS" Note that the following two manipulators are not members of the class \fBMstream\fP, but are free functions defined in the namespace \fBFBB\fP\&. .PP .IP o \fBstd::ostream &endl(std::ostream &out)\fP: .br This manipulator inserts a newline character in the \fIMstream\fP\(cq\&s stream and then calls \fIFBB::flush\fP\&. This manipulator acts like \fIstd::endl\fP and \fIstd::flush\fP when inserted into another kind of \fIstd::ostream\fP object\&. .IP .IP o \fBstd::ostream &flush(std::ostream &out)\fP: .br This manipulator completes the message that is currently being inserted into an \fIMstream\fP object\&. It flushes the object\(cq\&s destination stream and prepares the object for the next message\&. When the object\(cq\&s \fIthrows\fP member returns \fItrue\fP it throws an exception whose \fIwhat\fP member contains the id (see earlier for the member \fIid\fP) of the \fIMstream\fP object throwing the exception\&. When used in combination with another kind of \fIstd::ostream\fP object it acts like \fIstd::flush\fP\&. .IP .IP o \fBstd::ostream &noid(std::ostream &out)\fP: .br This manipulator completes the message that is currently being inserted into an \fIMstream\fP object\&. It flushes the object\(cq\&s destination stream and prepares the object for the next message\&. When the object\(cq\&s \fIthrows\fP member returns \fItrue\fP it throws an exception whose \fIwhat\fP member does not contain the \fBMstream\fP object\(cq\&s ID\&. When used in combination with another kind of \fIstd::ostream\fP object it acts like \fIstd::flush\fP\&. .IP .IP o \fBstd::ostream &noidl(std::ostream &out)\fP: .br This manipulator inserts a newline character in the \fIMstream\fP\(cq\&s stream and then calls \fIFBB::noid\fP\&. This manipulator acts like \fIstd::endl\fP and \fIstd::flush\fP when inserted into another kind of \fIstd::ostream\fP object\&. .PP As the manipulators \fIFBB::endl\fP and \fIFBB::flush\fP act like, respectively, \fIstd::endl\fP and \fIstd::flush\fP when inserted into another kind of \fIstd::ostream\fP object, using the declarations `\fIusing FBB::endl\fP\(cq\& and `\fIusing FBB::flush\fP\(cq\& might be worth considering\&. Also, when \fIusing namespace std\fP \fIand\fP \fIusing namespace FBB\fP is specified the \fIFBB::endl\fP and \fIFBB::flush\fP manipulator will automatically be called when inserting \fIendl\fP or \fIflush\fP into \fIMstream\fP objects\&. .PP .SH "EXAMPLE" .nf #include #include #include #include using namespace std; using namespace FBB; int main(int argc, char **argv) try { cout << sizeof(Mstream) << \(cq\& \(cq\& << sizeof(Mbuf) << \(cq\&\en\(cq\&; imsg << \(dq\&Informational: \(dq\& << endl; imsg\&.off(); cout << \(dq\&The i\-msg stream is now off\&. This message should appear once\(dq\& << endl; imsg << \(dq\&The i\-msg stream is now off\&. This message should appear once\(dq\& << endl; imsg << \(dq\&The i\-msg stream is now off\&. This message should appear once\(dq\& << endl; cout << \(dq\&But this message is shown\(dq\& << endl; wmsg << \(dq\&Warning message\(dq\& << endl; emsg << \(dq\&Oops, this this is an error (not really)\(dq\& << endl; emsg << \(dq\&Oops, this goes wrong, too\(dq\& << noid; imsg\&.on(); imsg << \(dq\&And another informational msg: \(dq\& << emsg\&.count() << \(dq\& error messages\en\(dq\& << flush; emsg << \(dq\&Third error\(dq\& << endl; emsg\&.setMaxCount(3); imsg << \(dq\&Msg in between\(dq\& << endl; imsg\&.setTag(\(dq\&tag\(dq\&); imsg << \(dq\&tagged message\(dq\& << endl; imsg\&.setTag(\(dq\&label\(dq\&); imsg << \(dq\&labeled message\(dq\& << endl; cerr << \(dq\&(cerr) LineExcess: \(dq\& << emsg\&.lineExcess() << \(dq\&, count = \(dq\& << emsg\&.count() << endl; emsg << \(dq\&Fourth error\en\(dq\& << noid; // no id is shown emsg << \(dq\&Fourth error\en\(dq\& << flush; // shows id (remove the previous // statement) cerr << \(dq\&(cerr) LineExcess: \(dq\& << emsg\&.lineExcess() << \(dq\&, count = \(dq\& << emsg\&.count() << endl; cerr << \(dq\&Beyond\en\(dq\&; } catch(exception const &e) { std::cerr << \(dq\&Got a std::exception: \(dq\& << e\&.what() << \(cq\&\en\(cq\&; } catch(\&.\&.\&.) { std::cerr << \(dq\&Got an exception\en\(dq\&; } .fi .PP .SH "FILES" \fIbobcat/mstream\fP \- defines the class interface .PP .SH "SEE ALSO" \fBbobcat\fP(7), \fBexception\fP(3bobcat), \fBmbuf\fP(3bobcat) .PP .SH "BUGS" None Reported\&. .PP .SH "BOBCAT PROJECT FILES" .PP .IP o \fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page; .IP o \fIbobcat_5\&.07\&.00\-x\&.dsc\fP: detached signature; .IP o \fIbobcat_5\&.07\&.00\-x\&.tar\&.gz\fP: source archive; .IP o \fIbobcat_5\&.07\&.00\-x_i386\&.changes\fP: change log; .IP o \fIlibbobcat1_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the libraries; .IP o \fIlibbobcat1\-dev_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the libraries, headers and manual pages; .PP .SH "BOBCAT" Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&. .PP .SH "COPYRIGHT" This is free software, distributed under the terms of the GNU General Public License (GPL)\&. .PP .SH "AUTHOR" Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&. .PP