.TH "FBB::IFilterBuf" "3bobcat" "2005\-2020" "libbobcat\-dev_5\&.07\&.00" "Filtering Input Stream Buffer" .PP .SH "NAME" FBB::IFilterBuf \- Filtering stream buffer initialized by a std::istream object .PP .SH "SYNOPSIS" \fB#include \fP .br Linking option: \fI\-lbobcat\fP .PP .SH "DESCRIPTION" \fBFBB::IFilterBuf\fP objects may be used as a \fBstd::streambuf\fP for \fIstd::istream\fP objects, filtering the information produced by those objects\&. .PP The class \fIIFilterBuf\fP was designed with the \fBopenSSL BIO\fP (cf\&. \fBbio\fP(3ssl)) in mind\&. Since the BIO concept was developed in the context of the \fBC\fP programming language, BIOs do not support \fBC++\fP streams\&. Nonetheless, the concept of a filtering device is an attractive one, and is offered by the \fBFBB::IFilterBuf\fP class\&. .PP In addition to filtering, \fBIFilterBuf\fP offers flexible internal buffer management: derived classes can push back characters until the beginning of the internal buffer has been reached, but may then continue pushing back characters until the internal buffer has reached its maximum size\&. This maximum size is defined by the constructor\(cq\&s \fImaxSize\fP parameter (see below)\&. .PP The class \fBIFilterBuf\fP is an abstract base class\&. It is used via classes that are derived from \fBIFilterBuf\fP, implementing its pure virtual \fIload\fP member (see below at \fBPRIVATE VIRTUAL MEMBER FUNCTIONS\fP)\&. .PP .SH "NAMESPACE" \fBFBB\fP .br All constructors, members, operators and manipulators, mentioned in this man\-page, are defined in the namespace \fBFBB\fP\&. .PP .SH "INHERITS FROM" \fBstd::streambuf\fP .PP .SH "MEMBER FUNCTIONS" All members of \fBstd::streambuf\fP are available, as \fBIFilterBuf\fP inherits from this class\&. .PP .SH "PROTECTED CONSTRUCTOR" .IP o \fBIFilterBuf(size_t maxSize = 1000)\fP: .br 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 \fImaxSize\fP characters, but the actual number of characters that is stored in the buffer is determined by the member \fIfilter\fP (see below) and by using the member \fIstreambuf::sputbackc\fP\&. .PP Copy and move constructors (and assignment operators) are not available\&. .PP .SH "PROTECTED MEMBER FUNCTION" .PP .IP o \fBvoid setBuffer()\fP: .br This member initializes the base class\(cq\&s buffer pointers (i\&.e\&., \fIeback, gptr,\fP and \fIegptr\fP) with the initial range of characters retrieved by \fIfilter\fP (see below)\&. .IP Derived classes do not have to call this member, but if they do they should only call \fIsetBuffer\fP once from their constructors\&. Once \fIsetBuffer\fP has been called, the \fIpeek\fP member of the \fIstd::istream\fP that is available to \fBIFilterBuf\fP 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\(cq\&s constructor, then \fIpeek\fP returns 0 until at least one character has been retrieved from the \fIistream\fP object\&. .PP .SH "PRIVATE VIRTUAL MEMBER FUNCTIONS" .PP .IP o \fBvirtual bool filter(char const **srcBegin, char const **srcEnd) = 0\fP: .br The \fIfilter\fP member is declared as a pure virtual member: derived classes \fImust\fP override \fIfilter\fP with their own implementation\&. .IP 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 \fIIFilterBuf\fP 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 \fBIFilterBuf\fP object to its own buffer, from where they are then retrieved (or to where they can be pushed back) by the application\&. .IP The \fIfilter\fP member allows implementations to filter and/or modify the information that is obtained by this member\&. The \fBEXAMPLE\fP section below provides an example filtering out a configurable set of characters from a provided \fIstd::istream\fP\&. Bobcat\(cq\&s classes \fBISymCryptStreambuf\fP(3bobcat) and \fBIBase64Buf\fP(3bobcat) provide additional examples of classes derived from \fBIFilterBuf\fP\&. .IP The \fIfilter\fP member should return \fIfalse\fP if no (more) information is available\&. It should return \fItrue\fP if information is available, in which case \fI*srcBegin\fP and \fI*srcEnd\fP should be pointing to, respectively, the first character and beyond the last character made available by \fIfilter\fP; .IP .IP o \fBint pbackfail(int ch) override\fP: .br If \fIIFilterBuf\(cq\&s\fP internally used buffer has reached its maximmum size then EOF is returned\&. Otherwise, \fIch\fP is inserted at the beginning of the internally used buffer, becoming the next character that\(cq\&s retrieved from the object\(cq\&s buffer; .IP .IP o \fBstd::streamsize showmanyc() override\fP: .br 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 \fIfilter\fP call is returned; .IP .IP o \fBint underflow() override\fP: .br Once the internally used buffer is empty \fIfilter\fP is called to obtain a new series of filtered characters\&. If \fIfilter\fP returns \fIfalse underflow\fP returns EOF\&. Otherwise the series of characters returned by \fIfilter\fP are transferred to the \fIIFilterBuf\(cq\&s\fP internal buffer to be processed by the \fIstd::istream\fP that\(cq\&s initialized with the \fIIFilterBuf\fP object\&. .PP .SH "EXAMPLE" .PP Here is a class, derived from \fIIFilterBuf\fP, filtering out a predefined set of characters\&. It is used twice to filter digits and vowels, illustrating chaining of \fBIFilterBuf\fP objects\&. .PP .nf #include #include #include #include class CharFilterStreambuf: public FBB::IFilterBuf { std::istream &d_in; // stream to read from std::string d_rmChars; // chars to rm std::string d_buffer; // locally buffered chars size_t const d_maxSize = 100; public: CharFilterStreambuf(std::istream &in, std::string const &rmChars); private: bool filter(char const **srcBegin, char const **srcEnd) override; }; CharFilterStreambuf::CharFilterStreambuf(std::istream &in, std::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) != std::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() { CharFilterStreambuf buf1(std::cin, \(dq\&1234567890\(dq\&); std::istream in1(&buf1); CharFilterStreambuf buf2(in1, \(dq\&AEIOUaeiou\(dq\&); std::istream in2(&buf2); std::cout << in2\&.rdbuf(); } .fi .PP .SH "FILES" \fIbobcat/ifdbuf\fP \- defines the class interface .PP .SH "SEE ALSO" \fBbobcat\fP(7), \fBisymcryptstreambuf\fP(3bobcat), \fBibase64buf\fP(3bobcat), \fBofilterbuf\fP(3bobcat)\&. \fBstd::streambuf\fP .PP .SH "BUGS" None reported\&. .PP .SH "BOBCAT PROJECT FILES" .PP .IP o \fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page; .IP o \fIbobcat_5\&.07\&.00\-x\&.dsc\fP: detached signature; .IP o \fIbobcat_5\&.07\&.00\-x\&.tar\&.gz\fP: source archive; .IP o \fIbobcat_5\&.07\&.00\-x_i386\&.changes\fP: change log; .IP o \fIlibbobcat1_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the libraries; .IP o \fIlibbobcat1\-dev_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the libraries, headers and manual pages; .PP .SH "BOBCAT" Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&. .PP .SH "COPYRIGHT" This is free software, distributed under the terms of the GNU General Public License (GPL)\&. .PP .SH "AUTHOR" Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&. .PP