includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::OFilterBuf)(3bobcat)(_CurYrs_)
    (libbobcat-dev__CurVers_)(ostream filtering)

manpagename(FBB::OFilterBuf)(Base class for std::ostream filtering)

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

manpagedescription()

The bf(FBB::OFilterBuf) class is a specialization of the
tt(std::streambuf) class and can be used as a base class for classes
implementing em(ostream)-filtering. 

Ostream filtering is defined here as the process by which inserted characters
are subject to processing before they are passed on to another (filtered)
tt(ostream) object (or they may be rejected). The filtering may also result in
inserting additional information into the filtered tt(ostream).

em(Chaining) of filters is also possible: the filtered tt(ostream) may itself
use an tt(OFilterBuf) to filter its received information before passing
it on to yet another tt(ostream). 

As tt(OFilterBuf) inherits from tt(std::streambuf) an
tt(OFilterBuf) object can be used to provide an tt(ostream) object
with a tt(std::streambuf). Information inserted into such a stream travels the
following route:
    itemization(
    it() The information is converted to characters using the standard
conversion facilities implemented by tt(std::ostream) objects. E.g., when
inserting the value tt(123) this value is converted to 
the characters tt('1', '2') and tt('3'), respectively.
    it() Each of the characters is then offered (in turn) to the
tt(std::streambuf) that is associated with the tt(ostream) object. In
particular, the tt(std::streambuf)'s tt(overflow()) member is called. 
    it() tt(OFstreamBuf)'s default tt(overflow()) function ignores characters,
but specializations can override tt(overflow()) to process the received
characters em(ad lib). 
    it() A overriding tt(overflow()) function has access to the member
tt(OFstreambuf::out()) which is a reference to the tt(std::ostream) receiving
the filtered information.
    )
    To implement a simple copy-filter (i.e., all characters are accepted
as-is) a class must be derived from tt(OFilterBuf) providing an
overriding implementation of tt(overflow()), e.g., as follows:
        verb(
    int DerivedClass::overflow(int ch)
    {
        out().put(ch);
    }
        )
    Next this tt(std::streambuf) specialization can be associated with an
tt(ostream) into which information to be `copy filtered' can be inserted
(cf. the EXAMPLE section below).

includefile(include/namespace)

manpagesection(INHERITS FROM)
    std::streambuf

manpagesection(CONSTRUCTORS)
    As tt(OFilterBuf) should be used as a base class all its
constructors are protected.

    itemization(
    itb(OFilterBuf())
        This constructor creates a tt(OFilterBuf) object without
associating it with a destination (filtered) tt(ostream).

    itb(OFilterBuf(std::string const &fname, 
                                            openmode mode = std::ios::out))
        This constructor creates a tt(OFilterBuf) object and opens a
private tt(std::ofstream) object whose filename is provided and that should 
receive the filtered information.
        
    itb(OFilterBuf(std::ostream &out))
        This constructor creates a tt(OFilterBuf) object and will insert
any filtered information into the provided  tt(ostream) object.
    )

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

manpagesection(PROTECTED MEMBER FUNCTIONS)

     Except for the public members inherited from bf(std::ostreambuf) all of
tt(OFilterBuf's) members are protected.

Derived classes should provide their own implementation of tt(int
underflow(int ch)) to implement filtering.

    itemization(
    itb(void reset(std::string const &fname, openmode mode = std::ios::out))
        This member flushes the current destination (filtered)
tt(std::ostream) and associates the tt(OFilterBuf) object with an
tt(std::ofstream) object whose filename is provided and that should receive
subsequently filtered information.
        
    itb(void reset(std::ostream &out))
        This member flushes the current destination (filtered)
tt(std::ostream) object and associates the tt(OFilterBuf) object with
the provided tt(ostream) object.

    itb(std::ostream &out() const)
        This member is available to derived classes to insert information into
the destination (filtered) stream. 
    )

manpagesection(EXAMPLE)
        verb(
    #include <iostream>
    #include <cctype>
    #include <bobcat/ofilterbuf>
    
    struct NoDigits: public FBB::OFilterBuf
    {
        NoDigits(std::ostream &out)
        :
            OFilterBuf(out)
        {}

        private:
            int overflow(int ch) override
            {
                if (not isdigit(ch))
                    out().put(ch);
                return ch;
            }
    };
    
    using namespace FBB;
    using namespace std;
    
    int main()
    {
        NoDigits nod(cout);     // no digits to cout
        ostream out(&nod);
    
        out << cin.rdbuf();      // rm digits from cin
    }
        )

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

manpageseealso()
    bf(bobcat)(7), bf(ifilterbuf)(3bobcat)

manpagebugs()
    None Reported.

includefile(include/trailer)
