NAME

FBB::MultiBuf - Selectively writes multiple streams

SYNOPSIS

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

DESCRIPTION

The FBB::MultiBuf class is a specialization of std::streambuf. It can be used to write selectively to multiple std::ostreams. Each std::ostream that is associated with a MultiBuf has a mode-tag indicating whether the stream should always be used when information is inserted into the MultiBuf, just once, or not at all.

A std::ostream initialized with the address of a MultiBuf then the constructed std::ostream becomes an output-multiplexer: by inserting information into the std::ostream object all std::ostream objects added to its MultiBuf buffer which have an active mode receive that information.

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

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

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

NAMESPACE

FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace FBB.

INHERITS FROM

std::streambuf

ENUMERATION

The MultiBuf::Mode enumeration defines the following values:

o

OFF:
No information is inserted into std::ostreams associated with the mode OFF;

o

ON:
Information inserted into the std::ostream using a MultiBuf streambuf is inserted in all std::ostream objects associated with the mode ON;

o

ONCE:
Information inserted into the std::ostream using a MultiBuf streambuf is inserted in all std::ostream objects associated with the mode ONCE up through the next std::flush. Following the std::flush insertion the std::ostream’s mode is set to RESET;

o

RESET:
No information is inserted into std::ostreams associated with the mode RESET. See also the members reset and setOnce below.

NESTED CLASS

The class MultiBuf::Stream is a nested class of MultiBuf. It offers the following public members:

o

std::ostream &ostream() const:
This member returns a reference to the Stream’s std::ostream. The returned ostream can be processed independently from the other ostream objects provided to the MultiBuf object. See also the members begin and streamVect below;

o

Mode mode() const:
This member returns the Stream’s Mode.

TYPES

The following types are defined by the class FBB:MultiBuf:

o

StreamVect:
A synonym of std::vector<MultiBuf::Stream>;

o

const_iterator:
A synonym of StreamVect::const_iterator.

CONSTRUCTORS

o

MultiBuf():
A MultiBuf object is initialized without associated std::ostream objects;

o

MultiBuf(std::ostream, ...):
This constructor creates a MultiBuf object associated with one or more std::ostream objects specified as the constructor’s arguments, using Mode ON for all the specified ostream objects;

o

MultiBuf(std::ostream, Mode mode, ...):
This constructor creates a MultiBuf object receiving pairs of arguments. The first element of each pair is a std::ostream, the second element is the std::ostream’s Mode.

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

MEMBER FUNCTIONS

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

o

const_iterator begin() const:
A const-iterator to the first Stream object stored in the MultiBuf object is returned;

o

void clear():
The MultiBuf’s StreamVect is cleared;

o

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

o

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

o

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

o

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

o

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

o

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

o

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

o

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

o

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

o

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

o

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

o

size_t size() const:
Returns the StreamVect’s size;

o

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

EXAMPLE

#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";
}


    

FILES

bobcat/multibuf - defines the class interface

SEE ALSO

bobcat(7)

BUGS

None Reported.

BOBCAT PROJECT FILES

o

https://fbb-git.gitlab.io/bobcat/: gitlab project page;

Debian Bobcat project files:

o

libbobcat6: debian package containing the shared library, changelog and copyright note;

o

libbobcat-dev: debian package containing the static library, headers, manual pages, and developer info;

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