Provided by: libbobcat-dev_6.04.00-1ubuntu3_amd64 bug

NAME

       FBB::IFilterBuf - Filtering stream buffer initialized by a std::istream object

SYNOPSIS

       #include <bobcat/ifilterbuf>
       Linking option: -lbobcat

DESCRIPTION

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

       Because IFilterBuf is a streambuf  its  member  underflow  is  automatically  called  when
       reading  operations  are  requested  from  the  stream  object using the IFilterBuf as its
       streambuf. If no chars  are  currently  available  (i.e.,  srcBegin  ==  srcEnd,  see  the
       description of the filter member below), then filter is called, which may store characters
       in a (local) buffer of at most maxSize characters (see the description of  the  IFilterBuf
       constructor  below).  Once  this  buffer  has been filled filter updates the *srcBegin and
       *srcEnd pointers so that they point to,  respectively,  the  the  location  of  the  first
       character  in  the local buffer and beyond the location of the last character in the local
       buffer.

       The class IFilterBuf 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::IFilterBuf class.

       In  addition  to filtering, IFilterBuf offers flexible internal buffer management: derived
       classes can put characters back on the internal buffer until the beginning of  the  buffer
       has  been reached, but may then continue pushing characters on the buffer until the buffer
       has reached its maximum size. This maximum size is defined by  the  constructor’s  maxSize
       parameter (see below).

       The  class  IFilterBuf  is an abstract base class. It is used via classes that are derived
       from IFilterBuf, 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 IFilterBuf inherits from this class.

PROTECTED CONSTRUCTOR

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

       Copy and move constructors (and assignment operators) 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).

              Derived  classes  do  not have to call this member, but if they do they should only
              call setBuffer once from their constructors. Once setBuffer has  been  called,  the
              peek  member  of  the  std::istream  that is available to 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 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
              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 IFilterBuf 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  IBase64Buf(3bobcat)  provide
              additional examples of classes derived from  IFilterBuf.

              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(int ch) override:
              If  IFilterBuf’s  internally  used buffer has reached its maximmum size then EOF is
              returned. Otherwise, ch is inserted at the beginning of the internally used buffer,
              becoming the next character that’s retrieved from the object’s buffer;

       o      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  filter  call
              is returned;

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

EXAMPLE

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

       #include <iostream>
       #include <fstream>
       #include <istream>
       #include <string>

       #include <bobcat/ifilterbuf>

       using namespace std;
       using namespace FBB;

       class CharFilterStreambuf: public IFilterBuf
       {
           istream &d_in;         // stream to read from
           string d_rmChars;      // chars to rm
           string d_buffer;       // locally buffered chars
           size_t const d_maxSize = 100;

           public:
               CharFilterStreambuf(istream &in, string const &rmChars);

           private:
               bool filter(char const **srcBegin,
                           char const **srcEnd) override;
       };

       CharFilterStreambuf::CharFilterStreambuf(istream &in,
                                                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) != 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(int argc, char **argv)
       {
           if (argc == 1)
           {
               cout << "arg[1]: file to process, arg[2]: processed file\n";
               return 0;
           }

           ifstream in{ argv[1] };
           CharFilterStreambuf buf1(in, "1234567890");
           istream in1(&buf1);

           CharFilterStreambuf buf2(in1, "AEIOUaeiou");
           istream in2(&buf2);

           ofstream out{ argv[2] };
           out << in2.rdbuf();
       }

FILES

       bobcat/ifdbuf - defines the class interface

SEE ALSO

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

BUGS

       None reported.

BOBCAT PROJECT FILES

       o      https://fbb-git.gitlab.io/bobcat/: gitlab project page;

       o      bobcat_6.04.00-x.dsc: detached signature;

       o      bobcat_6.04.00-x.tar.gz: source archive;

       o      bobcat_6.04.00-x_i386.changes: change log;

       o      libbobcat1_6.04.00-x_*.deb: debian package containing the libraries;

       o      libbobcat1-dev_6.04.00-x_*.deb:  debian  package  containing the libraries, headers
              and manual pages;

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).