FBB::Mstream(3bobcat)

📦

version 6.15.01 · 7 versions

6.15.01 · ubuntu stonking (latest)
5.11.01 · nixos 26.05, nixpkgs unstable
5.09.01 · ubuntu jammy
6.04.00 · ubuntu noble
6.02.02 · debian bookworm
6.11.00 · ubuntu resolute
6.07.01 · debian trixie, ubuntu questing

💖 FBB::Mstream — Message handler 💖

okay so bestie, pull up a chair, because we're talking about FBB::Mstream(3bobcat) — the generic message handling stream. it's giving organized, it's giving labeled, and ngl it's about to make your error messages look so much better than a raw std::cerr << "oops". 🎀

✨ NAME ✨

FBB::Mstream — Generic message handling stream 🦋

✨ SYNOPSIS ✨

#include <bobcat/mstream>

Linking option: -lbobcat

✨ DESCRIPTION ✨

so, objects of this class handle your messages in a standardized way. like, unbothered, consistent, iconic. Messages may be prefixed with order (line) numbers and/or labels, so your output actually tells you what happened and when. And as a lil extra flair, messages generated by Mstream objects may optionally end by throwing an FBB::Exception (which is an std::exception, so it plays nicely with the rest of the world) — which makes implementing stuff like fatal error messages genuinely simple. no cap. 🔥

The BOBCAT library provides four message streams, and you can use them as soon as you've included the mstream header file. They're all defined in the FBB namespace:

FBB::emsg — for generating standard (labeled and numbered) error messages, e.g.

[Error 1] this is an error message

FBB::fmsg — for generating (labeled) fatal error messages, ending in an exception, e.g.

[Fatal] this fatal message is followed by an exception

The exception's what member contains FBB::fmsg's id value (see the member id below).

FBB::imsg — for generating plain informational messages, e.g.

this is a plain message

FBB::wmsg — for generating (labeled) warning messages, e.g.

[Warning] this is a warning

By default all messages are inserted into the standard output stream, but other destinations (standard error, a named file, etc.) can easily be configured. so you're not stuck, bestie. 💅

Mstream objects themselves are std::ostream objects, which means they can totally be passed to functions expecting ostream arguments. main character energy fr fr. 👑

Messages inserted into Mstream objects are buffered until the buffer is flushed by their std::ostream parts, or when either the FBB::endl or FBB::flush manipulator is inserted into the message stream. And here's the cute part: since these manipulators act like std::endl and std::flush when inserted into another kind of std::ostream object, using FBB::endl and using FBB::flush might be worth considering. also — when using namespace std and using namespace FBB are specified, the FBB::endl and FBB::flush manipulator will automatically be used with Mstream objects. so convenient, we're obsessed. 😭💖

Messages inserted into Mstream objects are considered completed at the insertion of the FBB::endl or FBB::flush manipulators. Message labels, line number labels and line numbers will only be shown for the next line after these manipulators have been inserted, and exceptions are, if needed, thrown from these manipulators. so yeah — the manipulators are doing a lot of heavy lifting here. respect. 🫶

✨ NAMESPACE ✨

FBB

All elements mentioned in this man-page, are defined in the namespace FBB. 🌸

✨ INHERITS FROM ✨

std::ostream

✨ CONSTRUCTORS ✨

Mstream() — the default constructor generates messages using the std::streambuf used by std::cout. There is no limit to the number of messages that may be inserted. No message or line numbers are shown, and no exceptions are thrown when inserting messages. chill vibes only. 🌈
explicit Mstream(std::ostream &ostr, size_t maxCount = std::numeric_limits<size_t>::max(), std::string const &tag = "", bool throwing = false) — this constructor uses the std::streambuf that is also used by the ostream ostr. By default (i.e. using the default argument values) there is no limit to the number of messages that may be inserted, no message or line numbers are shown, and no exceptions are thrown when inserting messages. ✨ Specifying any other value than std::numeric_limits<size_t>::max() will set the maximum number of messages that can be inserted to that value. The tag defines the text of the message label (e.g., Error).

When throwing is true an exception is thrown after completing a message. The generated exception's what member may show the FBB::Mstream object's id (see below at the member id) of the Mstream object throwing the exception.

explicit Mstream(std::streambuf *buf, size_t maxCount = std::numeric_limits<size_t>::max(), std::string const &tag = "", bool throwing = false) — this constructor uses buf to insert messages into. The remaining parameters are identical to those of the previous constructor. same energy, different destination. 💫
explicit Mstream(std::string const &name, size_t maxCount = std::numeric_limits<size_t>::max(), std::string const &tag = "", bool throwing = false) — this constructor creates a std::ofstream from the provided name parameter. It throws an exception if the stream cannot be opened for writing. If a file by that name already exists it is rewritten — so heads up on that one, bestie. ⚠️ The remaining parameters are identical to those of the previous two constructors.

lowkey important: copy and move constructors (and assignment operators) are not available. no duplicating this stream, periodt. 💀

💖 MEMBER FUNCTIONS 💖

okay bestie, here's the whole toolbox, every single one, no skips 🔥

size_t count() const — hands you back the number of messages that got inserted. and if you called setCount at some point, it's the value from that last setCount call plus however many messages have been inserted since then. math but make it messages 💅
bool isActive() const — true if messages can actually make it into the FBB::MStream object, false if inserted messages are just getting ignored. heads up: while it's ignoring stuff, the message count does not get updated. ghosted messages don't count fr fr.
int id() const — the unique id of the Mstream object. it's giving government name 🪪
bool lineExcess() const — true once you've tried to insert one more message after maxCount messages already went in. you overstayed, bestie 😭
std::string const &lineTag() const — the line-tag currently in use. default is Line. ✨
size_t maxCount() const — the maximum number of messages that can be inserted. if what comes back equals std::numeric_limits<size_t>::max(), then congrats, there's literally no limit, the limit is a myth 👑
void noLineNr() — calling this suppresses the display of a line number, but only if you call it after setLineNr (scroll down 👇) and before a message is being inserted (or has already been inserted). timing is everything 💅
void off() — after this, any message you insert into the Mstream object gets silently ignored. and nope, the internal message counter does not get incremented when messages are inserted. silence, but make it on purpose 🤫
void on() — this is the default state, and after calling it, messages inserted into the Mstream object get sent to their destination stream. we're back, baby 🌈
void reset(std::ostream &ostr) — messages inserted into the Mstream object now get handled by the std::streambuf that ostr also uses. everything else (like maxCount, the message label) stays exactly as it was. only the vibe of where changed.
void reset(std::streambuf *buf) — messages inserted into the Mstream object now get handled by the std::streambuf buf. other parameters (e.g., maxCount, the message label) are kept as-is. same energy, different buffer.
void reset(FBB::Mstream const &mstream) — the current object gets reset using the parameters of the mstream parameter. copy-paste but for settings 🎀
void reset(std::string const &name) — messages inserted into Mstream objects get handled by a std::ofstream created using the name you passed. if the stream can't be opened for writing, an exception is thrown. and yes, if a file by that name already exists, it gets rewritten (so, gone, bestie 💀). other parameters (e.g., maxCount, the message label) are kept as-is.
void reset(std::ostream &ostr, size_t maxCount, std::string const &tag, bool throwing) — messages inserted into Mstream objects get handled by the std::streambuf that ostr also uses. if you specify std::numeric_limits<size_t>::max() for maxCount, there is no limit to the number of messages that this std::streambuf may handle. tag defines the text of the message label (e.g., Error, or the empty string for no message label at all). when throwing is specified as true, an exception is thrown after completing a message. dramatic much? correct answer: yes ✨
void reset(std::streambuf *buf, size_t maxCount, std::string const &tag, bool throwing) — messages inserted into Mstream objects get handled by std::streambuf buf. the remaining parameters are identical to those of the previous reset member. same deal, new home 📦
void reset(std::string const &name, size_t maxCount, std::string const &tag, bool throwing) — messages inserted into Mstream objects get handled by a std::ofstream created using the name you passed. it throws an exception if the stream can't be opened for writing. if a file by that name already exists it is rewritten (rip to whatever was in there 🙈). the remaining parameters are identical to those of the previous two reset members.
void reset(FBB::Mstream const &mstream) — the current object is reset using the parameters of the mstream parameter. and here's the glow-up: following the reset, all of the current object's parameters can be modified independently from those used by mstream. it's giving main character energy, you're your own person now 💅
bool setActive(bool ifTrue) — if ifTrue equals true the Mstream gets activated, otherwise its actions are suppressed. and it returns ifTrue. polite and functional 🫶
void setCount(size_t count) — assigns the value count to the object's message counter. reset the tally, bestie 🔢
void setLineNr(size_t lineNr) — sets the value lineNr as the message's line number for when the next line is displayed (peep noLineNr too 👀). lowkey important: this value is not changed by the Mstream object itself. to display another line number you'll have to call this member again — meaning the line number does not just automatically show up again at every new line. you have to keep asking. needy, but iconic.
void setLineTag(std::string const &tag) — sets the tag that prefixes line numbers. by default the line tag equals Line. 🎀
void setMaxCount(size_t maxCount) — defines maxCount as the maximum number of messages that can be inserted into the Mstream object. the ceiling. the cap. the limit 🌸
void setTag(std::string const &tag) — specifies the tag that prefixes messages. by default the tag is empty. if it's not empty, the tag is enclosed by square brackets. e.g., specifying the tag Error will prefix messages with [Error]. so cute, so labeled 💖
std::string const &tag() const — returns the message tag currently in use. by default that's an empty string. nothing there. a void. a moment of silence 🤫
bool throws() — returns true when the Mstream object will throw an exception at the next completed message. the generated exception's what member contains the id (see earlier for the member id) of the Mstream object throwing the exception. snitch behavior, honestly 💀
void throwing(bool ifTrue) — modifies the behavior of Mstream objects at completed messages. after passing true, Mstream objects will throw an exception at the next completed message, otherwise this exception is not thrown. the generated exception's what member contains the id (see earlier for the member id) of the Mstream object throwing the exception. same id-in-the-error situation as above bestie 🔥

🧚 MANIPULATORS 🧚

quick note before we dive in: the following two manipulators are not members of the class Mstream. they're free functions defined in the namespace FBB. plot twist 🦋

std::ostream &endl(std::ostream &out) — this manipulator inserts a newline character into the Mstream's stream and then calls FBB::flush. and when you insert it into some other kind of std::ostream object, it acts just like std::endl and std::flush. dual citizenship ✨
std::ostream &flush(std::ostream &out) — this manipulator completes the message that's currently being inserted into an Mstream object. it flushes the object's destination stream and gets the object ready for the next message. when the object's throws member returns true, it throws an exception whose what member contains the id (see earlier for the member id) of the Mstream object throwing the exception. when used with another kind of std::ostream object, it acts like std::flush. versatile queen 👑
std::ostream &noid(std::ostream &out) — this manipulator completes the message currently being inserted into an Mstream object. it flushes the object's destination stream and prepares the object for the next message. when the object's throws member returns true, it throws an exception whose what member does not contain the Mstream object's ID. (see how it's noid? no id. the name ate 💅) when used with another kind of std::ostream object, it acts like std::flush.
std::ostream &noidl(std::ostream &out) — this manipulator inserts a newline character into the Mstream's stream and then calls FBB::noid. this manipulator acts like std::endl and std::flush when inserted into another kind of std::ostream object. it's noid but with a line break, hence the l. iykyk 🌈

since the manipulators FBB::endl and FBB::flush act like, respectively, std::endl and std::flush when inserted into another kind of std::ostream object, maybe consider the declarations using FBB::endl and using FBB::flush. worth thinking about, bestie 🫶 also, when using namespace std and using namespace FBB is specified, the FBB::endl and FBB::flush manipulators will automatically be called when inserting endl or flush into Mstream objects. auto-pilot, slay ⭐

🌸 EXAMPLE 🌸

#include <iostream>
#include <algorithm>
#include <iterator>

#include <bobcat/mstream>

using namespace std;
using namespace FBB;

int main(int argc, char **argv)
try
{
    cout << sizeof(Mstream) << ’ ’ << sizeof(Mbuf) << ’\n’;

    imsg << "Informational: " << endl;
    imsg.off();
    cout << "The i-msg stream is now off. This message should appear once" <<
                                                                          endl;
    imsg << "The i-msg stream is now off. This message should appear once" <<
                                                                          endl;
    imsg << "The i-msg stream is now off. This message should appear once" <<
                                                                          endl;
    cout << "But this message is shown" << endl;

    wmsg << "Warning message" << endl;
    emsg << "Oops, this this is an error (not really)" << endl;
    emsg << "Oops, this goes wrong, too" << noid;

    imsg.on();
    imsg << "And another informational msg: " << emsg.count() <<
            " error messages\n" << flush;

    emsg << "Third error" << endl;
    emsg.setMaxCount(3);

    imsg << "Msg in between" << endl;

    imsg.setTag("tag");
    imsg << "tagged message" << endl;

    imsg.setTag("label");
    imsg << "labeled message" << endl;

    cerr << "(cerr) LineExcess: " << emsg.lineExcess() << ", count = " <<
            emsg.count() << endl;

    emsg << "Fourth error\n" << noid;       // no id is shown
    emsg << "Fourth error\n" << flush;      // shows id (remove the previous
                                            // statement)

    cerr << "(cerr) LineExcess: " << emsg.lineExcess() << ", count = " <<
            emsg.count() << endl;

    cerr << "Beyond\n";
}
catch(exception const &e)
{
    std::cerr << "Got a std::exception: " << e.what() << ’\n’;
}
catch(...)
{
    std::cerr << "Got an exception\n";
}

🎀 FILES 🎀

bobcat/mstream — defines the class interface

💀 BUGS 💀

None Reported. flawless behavior, no notes, periodt 💅

🦋 BOBCAT PROJECT FILES 🦋

okay bestie, here's where to actually find everything, the receipts, the links, the whole fit 💅

https://fbb-git.gitlab.io/bobcat/ — the gitlab project page, that's the main character right there 👑

Debian Bobcat project files, aka the packages you install, no cap:

libbobcat6 — the debian package holding the shared library, the changelog and the copyright note 💖
libbobcat-dev — the debian package holding the static library, the headers, the manual pages, and the developer info ✨

🌈 BOBCAT 🌈

okay so, plot twist, the name is an acronym fr fr — Bobcat stands for Brokken’s Own Base Classes And Templates. iconic name behavior honestly 🎀

🫶 COPYRIGHT 🫶

This is free software, distributed under the terms of the GNU General Public License (GPL). free software is the moment, we love to see it 💜

👑 AUTHOR 👑

Frank B. Brokken (f.b.brokken@rug.nl). not me being obsessed with the person who literally wrote all of this 😭💖

that's the whole page bestie, you made it to the end 🌸 this whole thing is libbobcat-dev_6.15.01, dated 2005-2026, and the page itself is FBB::Mstream(3bobcat) — go read the source, go write something cute, and remember: read the docs, slay the bugs ✨💅🦋

📦 where this page comes from

ubuntu stonking: libbobcat-dev 6.15.01-1 · GPL-3.0-or-later WITH OpenSSL exception
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms