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

    A tt(std::ostream) initialized with the address of a bf(MultiBuf) then
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.

All active streams passed to a bf(MultiBuf) object should outlive the
tt(MultiBuf) object. It is the responsibility of the tt(MultiBuf) user that
this requirement is met.

bf(MultiBuf) objects insert information to their configured tt(std::ostream)
objects (not directly to those streams' tt(std::streambuf) objects). 

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)
    The bf(MultiBuf::Mode) enumeration defines the following values:
    itemization(
    itb(OFF)
       No information is inserted into tt(std::ostreams) associated with the
        mode tt(OFF);
    itb(ON)
       Information inserted into the tt(std::ostream) using a tt(MultiBuf)
        streambuf is inserted in all tt(std::ostream) objects associated with
        the mode tt(ON);
    itb(ONCE)
       Information inserted into the tt(std::ostream) using a tt(MultiBuf)
        streambuf is inserted in all tt(std::ostream) objects associated with
        the mode tt(ONCE) up through the next tt(std::flush). Following the
        tt(std::flush) insertion the tt(std::ostream's) mode is set to
        tt(RESET);
    itb(RESET)
       No information is inserted into tt(std::ostreams) associated with the
        mode tt(RESET). See also the members tt(reset) and tt(setOnce) below.
    )

manpagesection(NESTED CLASS)
    The class bf(MultiBuf::Stream) is a nested class of
bf(MultiBuf). It offers the following public members:
    itemization(
    itb(std::ostream &ostream() const)
        This member returns a reference to the bf(Stream)'s
        tt(std::ostream). The returned tt(ostream) can be processed
        independently from the other tt(ostream) objects provided to  the
        tt(MultiBuf) object. See also the members tt(begin) and tt(streamVect)
        below;
    itb(Mode mode() const)
        This member returns the  bf(Stream)'s  bf(Mode).
    )


manpagesection(TYPES)
    The following types are defined by the class bf(FBB:MultiBuf):
    itemization(
    itb(StreamVect)
        A synonym of tt(std::vector<MultiBuf::Stream>);
    itb(const_iterator)
        A synonym of tt(StreamVect::const_iterator).
    )

manpagesection(CONSTRUCTORS)
    itemization(
    itb(MultiBuf())
       A bf(MultiBuf) object is initialized without associated
        tt(std::ostream) objects;
    itb(MultiBuf(std::ostream, ...))
       This constructor creates a bf(MultiBuf) object 
        associated with one or more tt(std::ostream) objects specified as the
        constructor's arguments, using tt(Mode ON) for all the specified
        tt(ostream) objects;
    itb(MultiBuf(std::ostream, Mode mode, ...))
       This constructor creates a bf(MultiBuf) object receiving pairs of
        arguments. The first element of each pair is a tt(std::ostream), the
        second element is the tt(std::ostream's Mode).
    )

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

manpagesection(MEMBER FUNCTIONS)
   All members of tt(std::ostringstream) and tt(std::exception) are
    available, as bf(MultiBuf) inherits from these classes. However, the
    tt(std::streambuf's) default tt(seek_off) and tt(seek_pos) (both returning
    -1) are used as the streams handled by a bf(MultiBuf) object may not all
    support seek operations.

    itemization(
    itb(const_iterator begin() const)
       A const-iterator to the first tt(Stream) object stored in the
        bf(MultiBuf) object is returned;

    itb(void clear())
       The tt(MultiBuf's StreamVect) is cleared;

    itb(const_iterator end() const)
       A const-iterator referring just beyond the last tt(Stream)
        object stored in the tt(MultiBuf) object is returned;

    itb(void insert(std::ostream &os, Mode mode = ON))
       A tt(Stream) object referring to the arguments' tt(std::ostream) object
        using the specified bf(Mode) is added to the current set of bf(Stream)
        objects. Note that tt(insert) may be called repeatedly with the same
        tt(std::ostream) arguments;

    itb(void insert(std::vector<stream> const &os))
       This member adds all bf(stream) objects stored in the bf(os) vector to

    itb(Mode mode() const)
       The tt(Mode) associated with a tt(Stream) object referring to 
        tt(os) is returned. If no such tt(Stream) object is available tt(Mode
        OFF) is returned;

    itb(bool remove(std::ostream &os))
        The (first) tt(Stream) object referring to tt(os) is removed from
        bf(MultiBuf's StreamVect), and tt(true) is returned. If no tt(Stream)
        object refers to tt(os) then tt(false) is returned;

    itb(bool remove(size_t idx)) 
       If tt(idx) is at least equal to the tt(StreamVect's) size tt(false) is
        returned. Otherwise element tt(idx) of the bf(MultiBuf's StreamVect)
        is removed, and tt(true) is returned;

    itb(void reset(Mode mode))
       The tt(Mode) values of all tt(Stream) objects maintained by the
        tt(MultiBuf) object are set to tt(mode);

    itb(bool reset(ostream &os, Mode mode))
       The tt(Mode) of the first tt(Stream) object referring to 
        tt(os) is set to tt(mode) and tt(true) is
        returned. If no such tt(Stream) object is available tt(false) is
        returned; 

    itb(void void setOnce())
       The tt(Mode RESET) values of all tt(Stream) objects are changed to
        tt(Mode ONCE);

    itb(void void setOnce(std::ostream &os))
       The tt(Mode) value of the first tt(Stream) object referring to tt(os)
        is set to tt(Mode ONCE);

    itb(bool void setOnce(size_t idx)) If tt(idx) is at least equal to the
        tt(StreamVect's) size tt(false) is returned. Otherwise the tt(Mode)
        value of element tt(idx) of the tt(StreamVect) is set to tt(ONCE) and
        tt(true) is returned.

    itb(size_t size() const)
        Returns the tt(StreamVect's) size;

    itb(MultiBuf::StreamVect const &streamVect() const)
        Returns a const-reference to the tt(MultiBuf's StreamVect).
    )

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)
