--- name: "multibuf" section: "3bobcat" platform: "linux" package: "libbobcat-dev" version: "6.07.01-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/multibuf/3bobcat" --- # multibuf(3bobcat) Selectively writes multiple streams ## NAME FBB::MultiBuf - Selectively writes multiple streams ## SYNOPSIS **#include \**\ 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** is given a mode-tag indicating whether the stream should always be used when information is inserted into the **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 **MultiBuf** is used to initialize a *std::ostream* 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. An **MultiBuf** object should be outlived by all active streams that are associated with it. **MultiBuf** objects refer to *std::ostreams* which are passed to it, and not to their *std::streambufs*. So it is possible to change these *std::ostream’s std::streambufs* without reinstalling the *std::ostreams* themselves. 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 In the **Mode** enumeration the following values are defined: - o **OFF**:\ A *std::ostream* having this mode will not be used when information is inserted into a **MultiBuf** - o **ON**:\ A *std::ostream* having this mode will be used when information is inserted into a **MultiBuf** - o **ONCE**:\ A *std::ostream* having this mode will be used once, until the next flushing operation, when information is inserted into an **MultiBuf** - o **RESET**:\ A *std::ostream* having this mode will not be used when information is inserted into a **MultiBuf**. At a flush operation all **ONCE** modes will be set to **RESET** - o **ALL**:\ This mode is used in combination with the member *remove* to remove all *std::ostream* elements matching a specified *std::ostream* argument. ## TYPES The following subtypes are defined in the class **FBB:MultiBuf**: - o **iterator**:\ This is a synonym of *std::vector\::iterator* - o **const\_iterator**:\ This is a synonym of *std::vector\::const\_iterator* ## NESTED CLASS The class **MultiBuf::stream** is defined as a nested class of **MultiBuf**. It offers the following constructor and public members: - o **stream(std::ostream &os, Mode mode = ON)**:\ The constructor stores a *std::ostream* object, and associates a **Mode** value with it. - o **void setMode(Mode mode)**:\ This member is used to redefine the **stream**’s **Mode** value. - o **void mode() const**:\ This member returns the **stream**’s **Mode** value. - o **operator std::ostream &()**:\ This member returns the **stream**’s *std::ostream*. ## CONSTRUCTORS - o **MultiBuf()**:\ The default constructor creates a **MultiBuf** object which contains no associated *std::ostream* objects. - o **MultiBuf(std::ostream &os, Mode mode = ON)**:\ This constructor creates a **MultiBuf** object which is immediately associated with the *std::ostream* specified as its first argument. - o **MultiBuf(std::vector\ const &osvector)**:\ This constructor creates a **MultiBuf** object which is immediately associated with all *std::ostream* objects that are stored in the **MultiBuf::stream** elements of the specified vector. Copy and move constructors (and assignment operators) are not available. ## MEMBER FUNCTIONS All members of *std::ostringstream* and *std::exception* are available, as **MultiBuf** inherits from these classes. - o **iterator begin()**:\ This member returns an iterator to the first **stream** element that is stored in a **MultiBuf** object. - o **const\_iterator begin()**:\ This member returns an iterator to the first (unmodifiable) **stream** element that is stored in a **MultiBuf** object. - o **iterator end()**:\ This member returns an iterator pointing beyond the last **stream** element that is stored in a **MultiBuf** object. - o **const\_iterator end()**:\ This member returns an iterator pointing beyond the last (unmodifiable) **stream** element that is stored in a **MultiBuf** object. - o **void insert(std::ostream &os, Mode mode = ON)**:\ This member adds the specified *std::ostream* using the specified **Mode** to the current set of **stream** objects. Note that if called multiple times for identical *std::ostreams* these objects are inserted multiple times as well. - o **void insert(std::vector\ const &os)**:\ This member adds all **stream** objects stored in the **os** vector to the current set of **stream** objects. - o **bool remove(std::ostream &os, Mode mode = ONCE)**:\ If *os* is stored in the **MultiBuf** it is removed, and *true* is returned. If mode *ALL* is specified all *os* objects that were stored in the **MultiBuf** object are removed (and *true* is returned). If the *os* object was not stored *false* is returned. To determine whether *os* has been stored in the **MultiBuf** object its address is compared to the addresses of the *std::ostream* objects that are stored inside the **MultiBuf** object: the object(s) having addresses *&os* is (are) removed. - o **void void setOnce()**:\ This member will reset all the *RESET* **Mode** values of the stored **stream** objects to *ONCE*. - o **size\_t size() const**:\ The number of streams currently serviced by the **MultiBuf** object is returned. ## EXAMPLE ``` #include #include #include 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)](/bobcat/7.md) ## 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**).