.TH "FBB::MultiBuf" "3bobcat" "2005\-2020" "libbobcat\-dev_5\&.07\&.00" "Writing multiple streams"

.PP 
.SH "NAME"
FBB::MultiBuf \- Selectively writes multiple streams
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/multibuf>\fP
.br 
Linking option: \fI\-lbobcat\fP 
.PP 
.SH "DESCRIPTION"
The \fBFBB::MultiBuf\fP class is a specialization of
\fIstd::streambuf\fP\&. It can be used to write selectively to multiple
\fIstd::ostreams\fP\&. Each \fIstd::ostream\fP that is associated with a
\fBMultiBuf\fP is given a mode\-tag indicating whether the stream
should always be used when information is inserted into the
\fBMultiBuf\fP, just once, or not at all\&. Each of the stream\(cq\&s 
mode\-tags may be set to any of the defined tag\-values\&. 
.PP 
When the address of a \fBMultiBuf\fP is used to initialize a
\fIstd::ostream\fP the constructed \fIstd::ostream\fP becomes an
output\-multiplexer: by inserting information into the \fIstd::ostream\fP object,
all \fIstd::ostream\fP objects added to its \fBMultiBuf\fP buffer which
have an active mode receive that information\&.
.PP 
An \fBMultiBuf\fP object should be outlived by all active streams
that are associated with it\&.
.PP 
\fBMultiBuf\fP objects refer to \fIstd::ostreams\fP which are passed to it,
and not to their \fIstd::streambufs\fP\&. So it is possible to change these
\fIstd::ostream\(cq\&s std::streambufs\fP without reinstalling the \fIstd::ostreams\fP
themselves\&. 
.PP 
No assumptions should be made about the order in which the \fIstd::ostream\fP
objects that are associated with the \fBMultiBuf\fP objects are
visited when information is inserted\&.
.PP 
.SH "NAMESPACE"
\fBFBB\fP
.br 
All constructors, members, operators and manipulators, mentioned in this
man\-page, are defined in the namespace \fBFBB\fP\&.
.PP 
.SH "INHERITS FROM"
\fIstd::streambuf\fP
.PP 
.SH "ENUMERATION"
In the \fBMode\fP enumeration the following values are defined:
.IP o 
\fBOFF\fP:
.br 
A \fIstd::ostream\fP having this mode will not be used when information
is inserted into a \fBMultiBuf\fP
.IP o 
\fBON\fP:
.br 
A \fIstd::ostream\fP having this mode will be used when information
is inserted into a \fBMultiBuf\fP
.IP o 
\fBONCE\fP:
.br 
A \fIstd::ostream\fP having this mode will be used once, until the next
flushing operation, when information is inserted into an
\fBMultiBuf\fP
.IP o 
\fBRESET\fP:
.br 
A \fIstd::ostream\fP having this mode will not be used when information
is inserted into a \fBMultiBuf\fP\&. At a flush operation all \fBONCE\fP
modes will be set to \fBRESET\fP
.IP o 
\fBALL\fP:
.br 
This mode is used in combination with the member \fIremove\fP to remove 
all \fIstd::ostream\fP elements matching a specified \fIstd::ostream\fP argument\&.

.PP 
.SH "TYPES"
The following subtypes are defined in the class \fBFBB:MultiBuf\fP:
.IP o 
\fBiterator\fP:
.br 
This is a synonym of \fIstd::vector<stream>::iterator\fP
.IP o 
\fBconst_iterator\fP:
.br 
This is a synonym of \fIstd::vector<stream>::const_iterator\fP

.PP 
.SH "NESTED CLASS"
The class \fBMultiBuf::stream\fP is defined as a nested class of
\fBMultiBuf\fP\&. It offers the following constructor and public
members: 
.IP o 
\fBstream(std::ostream &os, Mode mode = ON)\fP:
.br 
The constructor stores a \fIstd::ostream\fP object, and associates a
\fBMode\fP value with it\&.
.IP o 
\fBvoid setMode(Mode mode)\fP:
.br 
This member is used to redefine the \fBstream\fP\(cq\&s  \fBMode\fP value\&.
.IP o 
\fBvoid mode() const\fP:
.br 
This member returns the  \fBstream\fP\(cq\&s  \fBMode\fP value\&.
.IP o 
\fBoperator std::ostream &()\fP:
.br 
This member returns the  \fBstream\fP\(cq\&s  \fIstd::ostream\fP\&.

.PP 
.SH "CONSTRUCTORS"
.IP o 
\fBMultiBuf()\fP:
.br 
The default constructor creates a \fBMultiBuf\fP object which
contains no associated \fIstd::ostream\fP objects\&.
.IP o 
\fBMultiBuf(std::ostream &os, Mode mode = ON)\fP:
.br 
This constructor creates a \fBMultiBuf\fP object which
is immediately associated with the \fIstd::ostream\fP specified as its first
argument\&. 
.IP o 
\fBMultiBuf(std::vector<MultiBuf::stream> const &osvector)\fP:
.br 
This constructor creates a \fBMultiBuf\fP object which is
immediately associated with all \fIstd::ostream\fP objects that are stored in
the \fBMultiBuf::stream\fP elements of the specified vector\&.

.PP 
Copy and move constructors (and assignment operators) are not available\&.
.PP 
.SH "MEMBER FUNCTIONS"
All members of \fIstd::ostringstream\fP and \fIstd::exception\fP are
available, as \fBMultiBuf\fP inherits from these classes\&.
.IP o 
\fBiterator begin()\fP:
.br 
This member returns an iterator to the first \fBstream\fP element that
is stored in a \fBMultiBuf\fP object\&.
.IP o 
\fBconst_iterator begin()\fP:
.br 
This member returns an iterator to the first (unmodifiable) \fBstream\fP
element that is stored in a \fBMultiBuf\fP object\&.
.IP o 
\fBiterator end()\fP:
.br 
This member returns an iterator pointing beyond the last \fBstream\fP
element that is stored in a \fBMultiBuf\fP object\&.
.IP o 
\fBconst_iterator end()\fP:
.br 
This member returns an iterator pointing beyond the last
(unmodifiable) \fBstream\fP element that is stored in a \fBMultiBuf\fP
object\&.
.IP o 
\fBvoid insert(std::ostream &os, Mode mode = ON)\fP:
.br 
This member adds the specified \fIstd::ostream\fP using the specified
\fBMode\fP to the current set of \fBstream\fP objects\&. Note that if called
multiple times for identical \fIstd::ostreams\fP these objects are inserted
multiple times as well\&.
.IP o 
\fBvoid insert(std::vector<stream> const &os)\fP:
.br 
This member adds all \fBstream\fP objects stored in the \fBos\fP vector to
the current set of \fBstream\fP objects\&.
.IP o 
\fBbool remove(std::ostream &os, Mode mode = ONCE)\fP:
.br 
If \fIos\fP is stored in the \fBMultiBuf\fP it is removed, and
\fItrue\fP is returned\&. If mode \fIALL\fP is specified all \fIos\fP objects that
were stored in the \fBMultiBuf\fP object are removed (and \fItrue\fP is
returned)\&. If the \fIos\fP object was not stored \fIfalse\fP is returned\&. To
determine whether \fIos\fP has been stored in the \fBMultiBuf\fP object its
address is compared to the addresses of the \fIstd::ostream\fP objects that are
stored inside the \fBMultiBuf\fP object: the object(s) having addresses
\fI&os\fP is (are) removed\&.
.IP o 
\fBvoid void setOnce()\fP:
.br 
This member will reset all the \fIRESET\fP \fBMode\fP values of the stored
\fBstream\fP objects to \fIONCE\fP\&.
.IP o 
\fBsize_t size() const\fP:
.br 
The number of streams currently serviced by the
\fBMultiBuf\fP object is returned\&.

.PP 
.SH "EXAMPLE"
.nf 

#include <iostream>
#include <fstream>
#include <bobcat/multibuf>

using namespace std;
using namespace FBB;

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

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

    os << \(dq\&This is on cout and out\en\(dq\&
          \(dq\&This is on cout only\en\(dq\&;

    msb\&.setOnce();
    os << \(dq\&This is on cout and out\en\(dq\&
          \(dq\&This is on cout only\en\(dq\&;
}
    
.fi 

.PP 
.SH "FILES"
\fIbobcat/multibuf\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7)
.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