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.23.01-x.dsc: detached signature;
- o
- bobcat_3.23.01-x.tar.gz: source archive;
- o
- bobcat_3.23.01-x_i386.changes: change log;
- o
- libbobcat1_3.23.01-x_*.deb: debian package holding the
libraries;
- o
- libbobcat1-dev_3.23.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).