# FBB::MultiBuf(3bobcat)

## Writing multiple streams
(libbobcat-dev_6.14.00)

## 2005-2026

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

- OFF:
  No information is inserted into std::ostreams associated with the mode OFF;
- ON:
  Information inserted into the std::ostream using a MultiBuf streambuf is inserted in all std::ostream objects associated with the mode ON;
- 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;
- 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:

- 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;
- Mode mode() const:
  This member returns the Stream's Mode.

## TYPES

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

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

## CONSTRUCTORS

- MultiBuf():
  A MultiBuf object is initialized without associated std::ostream objects;
- 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;
- 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.

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

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

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

- 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;

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

- 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;

- 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;

- 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;

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

- 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;

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

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

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

- size_t size() const:
  Returns the StreamVect's size;

- 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

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

Debian Bobcat project files:

- libbobcat6: debian package containing the shared library, changelog and copyright note;
- 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).