.TH "FBB::IFilterStreambuf" "3bobcat" "2005\-2018" "libbobcat\-dev_4\&.08\&.06\-x\&.tar\&.gz" "Filtering Input Stream Buffer" .PP .SH "NAME" FBB::IFilterStreambuf \- 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::IFilterStreambuf\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 \fIIFilterStreambuf\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::IFilterStreambuf\fP class\&. .PP In addition to filtering, \fBIFilterStreambuf\fP objects use split buffers, and thus, depending on the (configurable) size of buffer that is maintained by \fBIFilterStreambuf\fP objects, usually multiple characters read from the \fBIFilterStreambuf\fP can be pushed back again\&. .PP The class \fBIFilterStreambuf\fP is an abstract base class\&. It is used via classes that are derived from \fBIFilterStreambuf\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 \fBIFilterStreambuf\fP inherits from this class\&. Some of the \fBstd::streambuf\fP\(cq\&s member are overridden by \fBIFilterStreambuf\fP, see the next section\&. .PP Overloaded move and/or copy assignment operators are not available\&. .PP .SH "PROTECTED CONSTRUCTOR" .IP o \fBIFilterStreambuf(size_t bufSize = 1000)\fP: .br This constructor initializes the streambuf, using a buffer of the indicated size\&. While the streambuf is being used, its buffer is gradually filled\&. Eventually, when it is full the oldest characters are removed from the buffer, making room for more recent characters\&. At most half the \fIbufSize\fP number of characters will be removed during a single refill\&. The constructor ensures that the size of the buffer will always be at least 100\&. Copy\- and move constructors 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 The member \fIsetBuffer\fP should only once be called from the derived class\(cq\&s constructor\&. Once it has been called, the \fIpeek\fP member of the \fIstd::istream\fP that is initialized with the \fBIFilterStreambuf\fP will return 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 \fIIFilterStreambuf\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 \fBIFilterStreambuf\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 \fBIBase64Streambuf\fP(3bobcat) provide additional examples of classes derived from \fBIFilterStreambuf\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 o \fBint pbackfail() final override\fP: .br The \fIpbackfail\fP member is final; derived classes cannot override it\&. Currently it merely returns \fIEOF\fP\&. This may change in future implementations\&. .IP o \fBstd::streamsize showmanyc() final override\fP: .br The \fIshowmanyc\fP member is final; derived classes cannot override it\&. It returns the current number of characters that are (still) waiting to be processed in the range of characters returned by the latest \fIfilter\fP call\&. .IP o \fBint underflow() final override\fP: .br The \fIunderflow\fP member is final; derived classes cannot override it\&. It calls \fIfilter\fP, and refreshes at most half the size of its internal buffer with characters from the range of characters that was returned by the most recent call of \fIfilter\fP\&. The \fIfinal\fP attribute was added to the above three members to give \fIIFilterStreambuf\fP objects full control over their own buffers\&. .PP .SH "EXAMPLE" .PP Here is a class, derived from \fIIFilterStreambuf\fP, filtering out a predefined set of characters\&. It is used twice to filter digits and vowels, to illustrate chaining of \fBIFilterStreambuf\fP objects\&. .PP .nf #include #include #include #include class CharFilterStreambuf: public FBB::IFilterStreambuf { 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/ifdstreambuf\fP \- defines the class interface .PP .SH "SEE ALSO" \fBbobcat\fP(7), \fBisymcryptstreambuf\fP(3bobcat), \fBibase64streambuf\fP(3bobcat), \fBofilterstreambuf\fP(3bobcat)\&. \fBstd::streambuf\fP .PP .SH "BUGS" None reported\&. .PP .SH "DISTRIBUTION FILES" .IP o \fIbobcat_4\&.08\&.06\-x\&.dsc\fP: detached signature; .IP o \fIbobcat_4\&.08\&.06\-x\&.tar\&.gz\fP: source archive; .IP o \fIbobcat_4\&.08\&.06\-x_i386\&.changes\fP: change log; .IP o \fIlibbobcat1_4\&.08\&.06\-x_*\&.deb\fP: debian package holding the libraries; .IP o \fIlibbobcat1\-dev_4\&.08\&.06\-x_*\&.deb\fP: debian package holding the libraries, headers and manual pages; .IP o \fIhttp://sourceforge\&.net/projects/bobcat\fP: public archive location; .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