FBB::IFilterBuf(3bobcat)

📦
version 6.15.01 · 7 versions
, in ubuntu stonking

✨ FBB::IFilterBuf 💅

okay bestie, buckle up, because we're diving into FBB::IFilterBuf — a filtering input stream buffer, and it lives in the bobcat manual (section 3, if you're keeping score 🎀).

🌸 NAME 🌸

FBB::IFilterBuf — a filtering stream buffer that gets initialized by a std::istream object. it's giving "middleware for your streams," no cap ✨

🦋 SYNOPSIS 🦋

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

💖 DESCRIPTION 💖

so here's the vibe: FBB::IFilterBuf objects can be used as a std::streambuf for std::istream objects, and what they do is filter the information that those objects produce. literally the bouncer at the club door of your stream 😭

because IFilterBuf is a streambuf, its member underflow gets automatically called whenever reading operations are requested from the stream object that's using IFilterBuf as its streambuf. and if there are no chars currently available — like, srcBegin == srcEnd, check the description of the filter member below for the deets — then filter gets called, and it may store characters in a (local) buffer of at most maxSize characters (that's the IFilterBuf constructor, described below, iykyk). once this buffer has been filled, filter updates the *srcBegin and *srcEnd pointers so they point to, respectively, the location of the first character in the local buffer and beyond the location of the last character in the local buffer. slay 💅

fun fact: the class IFilterBuf was designed with the openSSL BIO in mind (cf. bio(3ssl)). and the way that the BIO concept was developed in the context of the C programming language means BIOs do not support C++ streams. BUT — and this is the iconic part — the concept of a filtering device is an attractive one, and it's offered by the FBB::IFilterBuf class. periodt ✨

on top of filtering, IFilterBuf offers flexible internal buffer management: derived classes can put characters back on the internal buffer until the beginning of the buffer has been reached, but they may then continue pushing characters onto the buffer until the buffer has reached its maximum size. this maximum size is defined by the constructor's maxSize parameter (see below).

and listen — IFilterBuf is an abstract base class. it's used via classes derived from IFilterBuf that implement its pure virtual load member (see below at PRIVATE VIRTUAL MEMBER FUNCTIONS). not me making you read the whole page 🙈 it's worth it tho.

🌈 NAMESPACE 🌈

FBB

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

👑 INHERITS FROM 👑

std::streambuf

⭐ MEMBER FUNCTIONS ⭐

all members of std::streambuf are available, because IFilterBuf inherits from this class. the whole inheritance tree ate and left no crumbs 💜

🎀 PROTECTED CONSTRUCTOR 🎀

  • IFilterBuf(size_t maxSize = 1000) — this constructor initializes the streambuf. while the streambuf is being used, its internally used buffer is gradually filled. it may be filled with up to maxSize characters, but the actual number of characters stored in the buffer is determined by the member filter (see below) and by using the member streambuf::sputbackc.
copy and move constructors (and assignment operators) are not available. they said nope, not today 🚫

🧚 PROTECTED MEMBER FUNCTION 🧚

  • void setBuffer() — this member initializes the base class's buffer pointers (i.e., eback, gptr, and egptr) with the initial range of characters retrieved by filter (see below).

derived classes do not have to call this member, but if they do, they should only call setBuffer once, from their constructors. once setBuffer has been called, the peek member of the std::istream that's available to IFilterBuf objects can be called to inspect the next available character, even if no other stream operation has as yet been performed. if it is not called by the derived class's constructor, then peek returns 0 until at least one character has been retrieved from the istream object.

💅 PRIVATE VIRTUAL MEMBER FUNCTIONS 💅

  • virtual bool filter(char const **srcBegin, char const **srcEnd) = 0 — the filter member is declared as a pure virtual member: derived classes must override filter with their own implementation.

derived class objects are responsible for obtaining information (in any amount) from the device with which they interact. this information is then passed on to the IFilterBuf via two pointers, pointing, respectively, to the first available character and beyond the last available character. the characters indicated by this range are subsequently transferred by the IFilterBuf object to its own buffer, from where they're then retrieved (or to where they can be pushed back) by the application. it's giving relay race 🏃♀️✨

the filter member allows implementations to filter and/or modify the information obtained by this member. the EXAMPLE section below provides an example filtering out a configurable set of characters from a provided std::istream. bobcat's classes ISymCryptStreambuf(3bobcat) and IBase64Buf(3bobcat) provide additional examples of classes derived from IFilterBuf.

the filter member should return false if no (more) information is available. it should return true if information is available, in which case *srcBegin and *srcEnd should be pointing to, respectively, the first character and beyond the last character made available by filter;

  • int pbackfail(int ch) override — if IFilterBuf's internally used buffer has reached its maximmum size then EOF is returned. otherwise, ch is inserted at the beginning of the internally used buffer, becoming the next character that's retrieved from the object's buffer;
  • std::streamsize showmanyc() override — the sum of the number of not yet processed characters in the internally used buffer and the number of not yet processed characters returned by the latest filter call is returned;
  • int underflow() override — once the internally used buffer is empty, filter is called to obtain a new series of filtered characters. if filter returns false, underflow returns EOF. otherwise the series of characters returned by filter are transferred to the IFilterBuf's internal buffer to be processed by the std::istream that's initialized with the IFilterBuf object.

🔥 EXAMPLE 🔥

here's a class, derived from IFilterBuf, filtering out a predefined set of characters. it's used twice to filter digits and vowels, illustrating chaining of IFilterBuf objects. chaining?? we love to see it 💖

#include <iostream>
#include <fstream>
#include <istream>
#include <string>

#include <bobcat/ifilterbuf>

using namespace std;
using namespace FBB;

class CharFilterStreambuf: public IFilterBuf
{
    istream &d_in;         // stream to read from
    string d_rmChars;      // chars to rm
    string d_buffer;       // locally buffered chars
    size_t const d_maxSize = 100;

    public:
        CharFilterStreambuf(istream &in, string const &rmChars);

    private:
        bool filter(char const **srcBegin,
                    char const **srcEnd) override;
};

CharFilterStreambuf::CharFilterStreambuf(istream &in,
                                         string const &rmChars)
:
    d_in(in),
    d_rmChars(rmChars)
{
    setBuffer();        // required if peek() must return the 1st
}                       // available character right from the start

bool CharFilterStreambuf::filter(char const **srcBegin,
                                 char const **srcEnd)
{
    d_buffer.clear();

    while (d_buffer.size() != d_maxSize)
    {
        char ch;
        if (not d_in.get(ch))
            break;
        if (d_rmChars.find(ch) != string::npos) // found char to rm
            continue;
        d_buffer.push_back(ch);
    }

    if (d_buffer.empty())
        return false;

    *srcBegin = d_buffer.data();
    *srcEnd = d_buffer.data() + d_buffer.size();

    return true;
}

int main(int argc, char **argv)
{
    if (argc == 1)
    {
        cout << "arg[1]: file to process, arg[2]: processed file\n";
        return 0;
    }

    ifstream in{ argv[1] };
    CharFilterStreambuf buf1(in, "1234567890");
    istream in1(&buf1);

    CharFilterStreambuf buf2(in1, "AEIOUaeiou");
    istream in2(&buf2);

    ofstream out{ argv[2] };
    out << in2.rdbuf();
}

🍓 FILES 🍓

bobcat/ifdbuf — defines the class interface

💀 SEE ALSO 💀

bobcat(7), isymcryptstreambuf(3bobcat), ibase64buf(3bobcat), ofilterbuf(3bobcat). std::streambuf

🙈 BUGS 🙈

None reported. (a clean page?? we love a bug-free era 🫶)

🌟 BOBCAT PROJECT FILES 🌟

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’. iconic naming tbh 👑

This is free software, distributed under the terms of the GNU General Public License (GPL).

✨ AUTHOR ✨

Frank B. Brokken (f.b.brokken@rug.nl).

okay that's the whole page bestie, you're officially a IFilterBuf girlie now 💅✨

this was libbobcat-dev_6.15.01, dated 2005-2026, and yes it's still FBB::IFilterBuf(3bobcat) — go filter something, ily 🫶💖

📦 where this page comes from