FBB::Mstream

libbobcat1-dev_2.10.03-x.tar.gz

2005-2010


FBB::Mstream(3bobcat)

FBB::Mstream(3bobcat)

libbobcat1-dev_2.10.03-x.tar.gz Message handler

2005-2010

NAME

FBB::Mstream - Generic message handling stream

SYNOPSIS

#include <bobcat/mstream>
Linking option: -lbobcat

DESCRIPTION

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 FBB::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:

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::Mstream objects themselves are std::ostream objects, so they can be used as objects passed to functions expecting ostream arguments. Messages inserted into FBB::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 FBB::Mstream objects.

Messages inserted into FBB::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

As FBB::Mstream inherits from std::ostream the copy constructor is not available. Neither is the move constructor.

MEMBER FUNCTIONS

messages inserted into FBB::Mstream objects 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 FBB::Mstream objects are handled by a std::ofstream created using the provided name parameter. FBB::Errno 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 FBB::Mstream objects are handled by the std::streambuf also used by ostr. By specifying UINT_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::Errno exception is thrown after completing a message.

  • void reset(std::streambuf *buf, size_t maxCount, std::string const &tag, bool throwing):
    messages inserted into FBB::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 FBB::Mstream objects are handled by a std::ofstream created using the provided name parameter. It throws an FBB::Errno 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 FBB::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 FBB::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 FBB::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 FBB::Mstream object will throw an FBB::Errno exception at the next completed message. The generated exception holds the id (see earlier for the member id) of the FBB::Mstream object from which the exception was thrown as well as the text FBB::Mstream.

  • void throwing(bool ifTrue):
    modifies the behaviro of FBB::Mstream objects at completed messages. After passing true FBB::Mstream objects will throw an FBB::Errno 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 FBB::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.

    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 FBB::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

    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).