Provided by: libbobcat-dev_3.19.01-1ubuntu1_amd64 
NAME
FBB::IFilterStreambuf - Filtering stream buffer initialized by a std::istream object
SYNOPSIS
#include <bobcat/ifilterstreambuf>
Linking option: -lbobcat
DESCRIPTION
FBB::IFilterStreambuf objects may be used as a std::streambuf for std::istream objects,
filtering the information produced by those objects.
The class IFilterStreambuf was designed with the openSSL BIO (cf. bio(3ssl)) in mind.
Since the BIO concept was developed in the context of the C programming language, BIOs do
not support C++ streams. Nonetheless, the concept of a filtering device is an attractive
one, and is offered by the FBB::IFilterStreambuf class.
In addition to filtering, IFilterStreambuf objects use split buffers, and thus, depending
on the (configurable) size of buffer that is maintained by IFilterStreambuf objects,
usually multiple characters read from the IFilterStreambuf can be pushed back again.
The class IFilterStreambuf is an abstract base class. It is used via classes that are
derived from IFilterStreambuf, implementing its pure virtual load member (see below at
PRIVATE VIRTUAL MEMBER FUNCTIONS).
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, as IFilterStreambuf inherits from this class.
Some of the std::streambuf’s member are overridden by IFilterStreambuf, see the next
section.
Overloaded move and/or copy assignment operators are not available.
PROTECTED CONSTRUCTOR
o IFilterStreambuf(size_t bufSize = 1000):
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 bufSize 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.
PROTECTED MEMBER FUNCTION
o 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).
The member setBuffer should only once be called from the derived class’s
constructor. Once it has been called, the peek member of the std::istream that is
initialized with the IFilterStreambuf 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’s constructor, then peek returns 0 until at least one character
has been retrieved from the istream object.
PRIVATE VIRTUAL MEMBER FUNCTIONS
o 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
IFilterStreambuf 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 IFilterStreambuf object to its own
buffer, from where they are then retrieved (or to where they can be pushed back) by
the application.
The filter member allows implementations to filter and/or modify the information
that is 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 IBase64Streambuf(3bobcat) provide
additional examples of classes derived from IFilterStreambuf.
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;
o int pbackfail() final override:
The pbackfail member is final; derived classes cannot override it. Currently it
merely returns EOF. This may change in future implementations.
o std::streamsize showmanyc() final override:
The showmanyc 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 filter call.
o int underflow() final override:
The underflow member is final; derived classes cannot override it. It calls filter,
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 filter. The final
attribute was added to the above three members to give IFilterStreambuf objects
full control over their own buffers.
EXAMPLE
Here is a class, derived from IFilterStreambuf, filtering out a predefined set of
characters. It is used twice to filter digits and vowels, to illustrate chaining of
IFilterStreambuf objects.
#include <iostream>
#include <istream>
#include <string>
#include <bobcat/ifilterstreambuf>
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, "1234567890");
std::istream in1(&buf1);
CharFilterStreambuf buf2(in1, "AEIOUaeiou");
std::istream in2(&buf2);
std::cout << in2.rdbuf();
}
FILES
bobcat/ifdstreambuf - defines the class interface
SEE ALSO
bobcat(7), isymcryptstreambuf(3bobcat), ibase64streambuf(3bobcat),
ofilterstreambuf(3bobcat). std::streambuf
BUGS
None reported.
DISTRIBUTION FILES
o bobcat_3.19.01-x.dsc: detached signature;
o bobcat_3.19.01-x.tar.gz: source archive;
o bobcat_3.19.01-x_i386.changes: change log;
o libbobcat1_3.19.01-x_*.deb: debian package holding the libraries;
o libbobcat1-dev_3.19.01-x_*.deb: debian package holding the libraries, headers and
manual pages;
o http://sourceforge.net/projects/bobcat: public archive location;
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).