.TH "FBB::OFilterBuf" "3bobcat" "2005\-2023" "libbobcat\-dev_6\&.04\&.00" "ostream filtering"

.PP 
.SH "NAME"
FBB::OFilterBuf \- Base class for std::ostream filtering
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/ofilterbuf>\fP
.br 
Linking option: \fI\-lbobcat\fP
.PP 
.SH "DESCRIPTION"

.PP 
The \fBFBB::OFilterBuf\fP class is a specialization of the
\fIstd::streambuf\fP class and can be used as a base class for classes
implementing \fIostream\fP\-filtering\&.
.PP 
Ostream filtering is defined here as the process by which inserted characters
are subject to processing before they are passed on to another (filtered)
\fIostream\fP object (or they may be rejected)\&. The filtering may also result in
inserting additional information into the filtered \fIostream\fP\&.
.PP 
\fIChaining\fP of filters is also possible: the filtered \fIostream\fP may itself
use an \fIOFilterBuf\fP to filter its received information before passing
it on to yet another \fIostream\fP\&.
.PP 
As \fIOFilterBuf\fP inherits from \fIstd::streambuf\fP an
\fIOFilterBuf\fP object can be used to provide an \fIostream\fP object
with a \fIstd::streambuf\fP\&. Information inserted into such a stream travels the
following route:
.IP o 
The information is converted to characters using the standard
conversion facilities implemented by \fIstd::ostream\fP objects\&. E\&.g\&., when
inserting the value \fI123\fP this value is converted to
the characters \fI\(cq\&1\(cq\&, \(cq\&2\(cq\&\fP and \fI\(cq\&3\(cq\&\fP, respectively\&.
.IP o 
Each of the characters is then offered (in turn) to the
\fIstd::streambuf\fP that is associated with the \fIostream\fP object\&. In
particular, the \fIstd::streambuf\fP\(cq\&s \fIoverflow()\fP member is called\&.
.IP o 
\fIOFstreamBuf\fP\(cq\&s default \fIoverflow()\fP function ignores characters,
but specializations can override \fIoverflow()\fP to process the received
characters \fIad lib\fP\&.
.IP o 
A overriding \fIoverflow()\fP function has access to the member
\fIOFstreambuf::out()\fP which is a reference to the \fIstd::ostream\fP receiving
the filtered information\&.
To implement a simple copy\-filter (i\&.e\&., all characters are accepted
as\-is) a class must be derived from \fIOFilterBuf\fP providing an
overriding implementation of \fIoverflow()\fP, e\&.g\&., as follows:
.nf 

    int DerivedClass::overflow(int ch)
    {
        out()\&.put(ch);
    }
        
.fi 
Next this \fIstd::streambuf\fP specialization can be associated with an
\fIostream\fP into which information to be `copy filtered\(cq\& can be inserted
(cf\&. the EXAMPLE section below)\&.
.PP 
.SH "NAMESPACE"
\fBFBB\fP
.br 
All constructors, members, operators and manipulators, mentioned in this
man\-page, are defined in the namespace \fBFBB\fP\&.
.PP 
.SH "INHERITS FROM"
std::streambuf
.PP 
.SH "CONSTRUCTORS"
As \fIOFilterBuf\fP should be used as a base class all its
constructors are protected\&.
.PP 
.IP o 
\fBOFilterBuf()\fP:
.br 
This constructor creates a \fIOFilterBuf\fP object without
associating it with a destination (filtered) \fIostream\fP\&.
.IP 
.IP o 
\fBOFilterBuf(std::string const &fname,
openmode mode = std::ios::out)\fP:
.br 
This constructor creates a \fIOFilterBuf\fP object and opens a
private \fIstd::ofstream\fP object whose filename is provided and that should
receive the filtered information\&.
.IP 
.IP o 
\fBOFilterBuf(std::ostream &out)\fP:
.br 
This constructor creates a \fIOFilterBuf\fP object and will insert
any filtered information into the provided  \fIostream\fP object\&.

.PP 
Copy and move constructors (and assignment operators) are not available\&.
.PP 
.SH "PROTECTED MEMBER FUNCTIONS"

.PP 
Except for the public members inherited from \fBstd::ostreambuf\fP all of
\fIOFilterBuf\(cq\&s\fP members are protected\&.
.PP 
Derived classes should provide their own implementation of \fIint
underflow(int ch)\fP to implement filtering\&.
.PP 
.IP o 
\fBvoid reset(std::string const &fname, openmode mode = std::ios::out)\fP:
.br 
This member flushes the current destination (filtered)
\fIstd::ostream\fP and associates the \fIOFilterBuf\fP object with an
\fIstd::ofstream\fP object whose filename is provided and that should receive
subsequently filtered information\&.
.IP 
.IP o 
\fBvoid reset(std::ostream &out)\fP:
.br 
This member flushes the current destination (filtered)
\fIstd::ostream\fP object and associates the \fIOFilterBuf\fP object with
the provided \fIostream\fP object\&.
.IP 
.IP o 
\fBstd::ostream &out() const\fP:
.br 
This member is available to derived classes to insert information into
the destination (filtered) stream\&.

.PP 
.SH "EXAMPLE"
.nf 

    #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
    }
        
.fi 

.PP 
.SH "FILES"
\fIbobcat/ofilterbuf\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBifilterbuf\fP(3bobcat)
.PP 
.SH "BUGS"
None Reported\&.
.PP 
.SH "BOBCAT PROJECT FILES"

.PP 
.IP o 
\fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page;
.IP o 
\fIbobcat_6\&.04\&.00\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_6\&.04\&.00\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_6\&.04\&.00\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_6\&.04\&.00\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_6\&.04\&.00\-x_*\&.deb\fP: debian package containing the
libraries, headers and manual pages;

.PP 
.SH "BOBCAT"
Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&.
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&.
.PP