.TH "FBB::OFilterStreambuf" "3bobcat" "2005\-2018" "libbobcat\-dev_4\&.08\&.06\-x\&.tar\&.gz" "ostream filtering"

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

.PP 
The \fBFBB::OFilterStreambuf\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 \fIOFilterStreambuf\fP to filter its received information before passing
it on to yet another \fIostream\fP\&. 
.PP 
As \fIOFilterStreambuf\fP inherits from \fIstd::streambuf\fP an
\fIOFilterStreambuf\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 \fIOFilterStreambuf\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"
.IP o 
\fBOFilterStreambuf()\fP:
.br 
This constructor creates a \fIOFilterStreambuf\fP object without
associating it with a destination (filtered) \fIostream\fP\&.
.IP 
.IP o 
\fBOFilterStreambuf(std::string const &fname, 
openmode mode = std::ios::out)\fP:
.br 
This constructor creates a \fIOFilterStreambuf\fP object and opens a
private \fIstd::ofstream\fP object whose filename is provided and that should 
receive the filtered information\&.
.IP 
.IP o 
\fBOFilterStreambuf(char const *fname, openmode mode = std::ios::out)\fP:
.br 
Same as the previous constructor, expecting a \fIchar const *\fP
defining the name of the private \fIstd::ofstream\fP object\&.
.IP 
.IP o 
\fBOFilterStreambuf(std::ostream &out)\fP:
.br 
This constructor creates a \fIOFilterStreambuf\fP object and will insert
any filtered information into the provided  \fIostream\fP object\&.
The class\(cq\&s destructor closes the destination (filtered) stream (cf\&. the
description of \fIclose()\fP below)\&.
.PP 
.SH "MEMBER FUNCTIONS"
All members of \fBstd::ostreambuf\fP are available, as
\fBFBB::OFilterStreambuf\fP inherits from that class\&. In particular, derived
classes should provide their own implementation of \fIint underflow(int ch)\fP
to implement any non\-trivial filtering\&.
.IP o 
\fBvoid close()\fP:
.br 
This member calls the \fIstreambuf::sync()\fP member to flush any
pending information to the destination (filtered) stream and then closes the
destination stream\&. Note that the default \fIsync()\fP member performs no
special actions but it can be overridden by derived classes to flush the
destination stream just prior to its closing\&.
.IP 
.IP o 
\fBvoid open(std::string const &fname, openmode mode = std::ios::out)\fP:
.br 
This member closes the current destination (filtered) \fIstd::ostream\fP
object and associates the \fIOFilterStreambuf\fP object with a private
\fIstd::ofstream\fP object whose filename is provided and that should receive
subsequently filtered information\&.
.IP 
.IP o 
\fBvoid open(char const *fname, openmode mode = std::ios::out)\fP:
.br 
Same as the previous member, but using a \fIchar const *\fP to specify
the name of the private \fIstd::ofstream\fP object to receive the filtered
information\&.
.IP 
.IP o 
\fBvoid open(std::ostream &out)\fP:
.br 
This member closes the current destination (filtered) \fIstd::ostream\fP
object and associates the \fIOFilterStreambuf\fP object with the provided
\fIostream\fP object\&.

.PP 
.SH "PROTECTED MEMBER FUNCTION"
.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/ofilterstreambuf>
    
    class NoDigits: public FBB::OFilterStreambuf
    {
        private:
            int overflow(int ch) override
            {
                if (not isdigit(ch))
                    out()\&.put(ch);
                return ch;
            }
            int sync() override
            {
                out() << flush;
                return 0;
            }
    };
    
    using namespace FBB;
    using namespace std;
    
    int main()
    {
        NoDigits nod(cout);     // no digits to cout
        ostream out(&nod);
    
        out << in\&.rdbuf();      // rm digits from cin
    }
        
.fi 

.PP 
.SH "FILES"
\fIbobcat/ofilterstreambuf\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBifilterstreambuf\fP(3bobcat)
.PP 
.SH "BUGS"
None Reported\&.
.PP 
.SH "DISTRIBUTION FILES"
.IP o 
\fIbobcat_4\&.08\&.06\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_4\&.08\&.06\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_4\&.08\&.06\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_4\&.08\&.06\-x_*\&.deb\fP: debian package holding the
libraries;
.IP o 
\fIlibbobcat1\-dev_4\&.08\&.06\-x_*\&.deb\fP: debian package holding the
libraries, headers and manual pages;
.IP o 
\fIhttp://sourceforge\&.net/projects/bobcat\fP: public archive location;

.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