includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::MultiBuf)(3bobcat)(_CurYrs_)
                    (libbobcat-dev__CurVers_)
                    (Writing multiple streams)

manpagename(FBB::MultiBuf)(Selectively writes multiple streams)

manpagesynopsis()
    bf(#include <bobcat/multibuf>)nl()
    Linking option: tt(-lbobcat)

manpagedescription()
    The bf(FBB::MultiBuf) class is a specialization of
tt(std::streambuf). It can be used to write selectively to multiple
tt(std::ostreams). Each tt(std::ostream) that is associated with a
bf(MultiBuf) is given a mode-tag indicating whether the stream
should always be used when information is inserted into the
bf(MultiBuf), just once, or not at all. Each of the stream's
mode-tags may be set to any of the defined tag-values.

    When the address of a bf(MultiBuf) is used to initialize a
tt(std::ostream) the constructed tt(std::ostream) becomes an
output-multiplexer: by inserting information into the tt(std::ostream) object,
all tt(std::ostream) objects added to its bf(MultiBuf) buffer which
have an active mode receive that information.

An bf(MultiBuf) object should be outlived by all active streams
that are associated with it.

bf(MultiBuf) objects refer to tt(std::ostreams) which are passed to it,
and not to their tt(std::streambufs). So it is possible to change these
tt(std::ostream's std::streambufs) without reinstalling the tt(std::ostreams)
themselves.

No assumptions should be made about the order in which the tt(std::ostream)
objects that are associated with the bf(MultiBuf) objects are
visited when information is inserted.

includefile(include/namespace)

manpagesection(INHERITS FROM)
        tt(std::streambuf)

manpagesection(ENUMERATION)
    In the bf(Mode) enumeration the following values are defined:
    itemization(
    itb(OFF)
        A tt(std::ostream) having this mode will not be used when information
is inserted into a bf(MultiBuf)
    itb(ON)
        A tt(std::ostream) having this mode will be used when information
is inserted into a bf(MultiBuf)
    itb(ONCE)
        A tt(std::ostream) having this mode will be used once, until the next
flushing operation, when information is inserted into an
bf(MultiBuf)
    itb(RESET)
        A tt(std::ostream) having this mode will not be used when information
is inserted into a bf(MultiBuf). At a flush operation all bf(ONCE)
modes will be set to bf(RESET)
    itb(ALL)
        This mode is used in combination with the member tt(remove) to remove
all tt(std::ostream) elements matching a specified tt(std::ostream) argument.
    )

manpagesection(TYPES)
    The following subtypes are defined in the class bf(FBB:MultiBuf):
    itemization(
    itb(iterator)
        This is a synonym of tt(std::vector<stream>::iterator)
    itb(const_iterator)
        This is a synonym of tt(std::vector<stream>::const_iterator)
    )

manpagesection(NESTED CLASS)
    The class bf(MultiBuf::stream) is defined as a nested class of
bf(MultiBuf). It offers the following constructor and public
members:
    itemization(
    itb(stream(std::ostream &os, Mode mode = ON))
        The constructor stores a tt(std::ostream) object, and associates a
bf(Mode) value with it.
    itb(void setMode(Mode mode))
        This member is used to redefine the bf(stream)'s  bf(Mode) value.
    itb(void mode() const)
        This member returns the  bf(stream)'s  bf(Mode) value.
    itb(operator std::ostream &())
        This member returns the  bf(stream)'s  tt(std::ostream).
    )

manpagesection(CONSTRUCTORS)
    itemization(
    itb(MultiBuf())
        The default constructor creates a bf(MultiBuf) object which
contains no associated tt(std::ostream) objects.
    itb(MultiBuf(std::ostream &os, Mode mode = ON))
        This constructor creates a bf(MultiBuf) object which
is immediately associated with the tt(std::ostream) specified as its first
argument.
    itb(MultiBuf(std::vector<MultiBuf::stream> const &osvector))
        This constructor creates a bf(MultiBuf) object which is
immediately associated with all tt(std::ostream) objects that are stored in
the bf(MultiBuf::stream) elements of the specified vector.
    )

    Copy and move constructors (and assignment operators) are not available.

manpagesection(MEMBER FUNCTIONS)
     All members of tt(std::ostringstream) and tt(std::exception) are
available, as bf(MultiBuf) inherits from these classes.
    itemization(
    itb(iterator begin())
        This member returns an iterator to the first bf(stream) element that
is stored in a bf(MultiBuf) object.
    itb(const_iterator begin())
        This member returns an iterator to the first (unmodifiable) bf(stream)
element that is stored in a bf(MultiBuf) object.
    itb(iterator end())
        This member returns an iterator pointing beyond the last bf(stream)
element that is stored in a bf(MultiBuf) object.
    itb(const_iterator end())
        This member returns an iterator pointing beyond the last
(unmodifiable) bf(stream) element that is stored in a bf(MultiBuf)
object.
    itb(void insert(std::ostream &os, Mode mode = ON))
        This member adds the specified tt(std::ostream) using the specified
bf(Mode) to the current set of bf(stream) objects. Note that if called
multiple times for identical tt(std::ostreams) these objects are inserted
multiple times as well.
    itb(void insert(std::vector<stream> const &os))
        This member adds all bf(stream) objects stored in the bf(os) vector to
the current set of bf(stream) objects.
    itb(bool remove(std::ostream &os, Mode mode = ONCE))
        If tt(os) is stored in the bf(MultiBuf) it is removed, and
tt(true) is returned. If mode tt(ALL) is specified all tt(os) objects that
were stored in the bf(MultiBuf) object are removed (and tt(true) is
returned). If the tt(os) object was not stored tt(false) is returned. To
determine whether tt(os) has been stored in the bf(MultiBuf) object its
address is compared to the addresses of the tt(std::ostream) objects that are
stored inside the bf(MultiBuf) object: the object(s) having addresses
tt(&os) is (are) removed.
    itb(void void setOnce())
        This member will reset all the tt(RESET) bf(Mode) values of the stored
bf(stream) objects to tt(ONCE).
    itb(size_t size() const)
        The number of streams currently serviced by the
bf(MultiBuf) object is returned.
    )

manpagesection(EXAMPLE)
    verb(
#include <iostream>
#include <fstream>
#include <bobcat/multibuf>

using namespace std;
using namespace FBB;

int main()
{
    MultiBuf  msb(cout);
    ostream         os(&msb);
    ofstream        out("out");

    msb.insert(out, MultiBuf::ONCE);

    os << "This is on cout and out\n"
          "This is on cout only\n";

    msb.setOnce();
    os << "This is on cout and out\n"
          "This is on cout only\n";
}
    )

manpagefiles()
    em(bobcat/multibuf) - defines the class interface

manpageseealso()
    bf(bobcat)(7)

manpagebugs()
    None Reported.

includefile(include/trailer)
