includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::IFilterBuf)(3bobcat)(_CurYrs_)
        (libbobcat-dev__CurVers_)(Filtering Input Stream Buffer)

manpagename(FBB::IFilterBuf)
            (Filtering stream buffer initialized by a std::istream object)

manpagesynopsis()
    bf(#include <bobcat/ifilterbuf>)nl()
    Linking option: tt(-lbobcat) 

manpagedescription()
    bf(FBB::IFilterBuf) objects may be used as a bf(std::streambuf) for
tt(std::istream) objects, filtering the information produced by those objects.

    The class tt(IFilterBuf) was designed with the bf(openSSL BIO)
(cf. bf(bio)(3ssl)) in mind. Since the BIO concept was developed in the
context of the bf(C) programming language, BIOs do not support bf(C++)
streams. Nonetheless, the concept of a filtering device is an attractive one,
and is offered by the bf(FBB::IFilterBuf) class.

    In addition to filtering, bf(IFilterBuf) 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's tt(maxSize) parameter
(see below).

    The class bf(IFilterBuf) is an abstract base class. It is used via
classes that are derived from bf(IFilterBuf), implementing its pure
virtual tt(load) member (see below at bf(PRIVATE VIRTUAL MEMBER FUNCTIONS)).

includefile(include/namespace)

manpagesection(INHERITS FROM)
    bf(std::streambuf)

manpagesection(MEMBER FUNCTIONS)
     All members of bf(std::streambuf) are available, as bf(IFilterBuf)
inherits from this class.


manpagesection(PROTECTED CONSTRUCTOR)
    itemization(
    itb(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 tt(maxSize) characters, but the actual number of characters that is
stored in the buffer is determined by the member tt(filter) (see below) and by
using the member tt(streambuf::sputbackc). 
    )

    Copy and move constructors (and assignment operators) are not available.

manpagesection(PROTECTED MEMBER FUNCTION)

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

    Derived classes do not have to call this member, but if they do they
should only call tt(setBuffer) once from their constructors. Once
tt(setBuffer) has been called, the tt(peek) member of the tt(std::istream)
that is available to bf(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
tt(peek) returns 0 until at least one character has been retrieved from the
tt(istream) object.
    )

manpagesection(PRIVATE VIRTUAL MEMBER FUNCTIONS)

    itemization(
    itb(virtual bool filter(char const **srcBegin, char const **srcEnd) = 0)
        The tt(filter) member is declared as a pure virtual member: derived
classes em(must) override tt(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 tt(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 bf(IFilterBuf) object to its own buffer, from where they are then
retrieved (or to where they can be pushed back) by the application. 

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

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

    itb(int pbackfail(int ch) override)
       If tt(IFilterBuf's) internally used buffer has reached its
        maximmum size then EOF is returned. Otherwise, tt(ch) is inserted at
        the beginning of the internally used buffer, becoming the next
        character that's retrieved from the object's buffer;

    itb(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 tt(filter) call is returned;

    itb(int underflow() override)
       Once the internally used buffer is empty tt(filter) is called to obtain
        a new series of filtered characters. If tt(filter) returns tt(false
        underflow) returns EOF. Otherwise the series of characters returned by
        tt(filter) are transferred to the tt(IFilterBuf's) internal
        buffer to be processed by the tt(std::istream) that's initialized with
        the tt(IFilterBuf) object.
    )

manpagesection(EXAMPLE)

    Here is a class, derived from tt(IFilterBuf), filtering out a
predefined set of characters. It is used twice to filter digits and
vowels, illustrating chaining of bf(IFilterBuf) objects.

    verbinclude(../../ifilterbuf/driver/driver.cc)

manpagefiles()
    em(bobcat/ifdbuf) - defines the class interface

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

manpagebugs()
    None reported.

includefile(include/trailer)


