# FBB::OFilterBuf(3bobcat)

## ostream filtering
(libbobcat-dev_5.07.03)

## 2005-2021

## NAME

FBB::OFilterBuf - Base class for std::ostream filtering

## SYNOPSIS

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

## DESCRIPTION

The FBB::OFilterBuf class is a specialization of the std::streambuf class and can be used as a base class for classes implementing 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) ostream object (or they may be rejected). The filtering may also result in inserting additional information into the filtered ostream.

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

As OFilterBuf inherits from std::streambuf an OFilterBuf object can be used to provide an ostream object with a std::streambuf. Information inserted into such a stream travels the following route:

- The information is converted to characters using the standard conversion facilities implemented by std::ostream objects. E.g., when inserting the value 123 this value is converted to the characters '1', '2' and '3', respectively.
- Each of the characters is then offered (in turn) to the std::streambuf that is associated with the ostream object. In particular, the std::streambuf's overflow() member is called.
- OFstreamBuf's default overflow() function ignores characters, but specializations can override overflow() to process the received characters ad lib.
- A overriding overflow() function has access to the member OFstreambuf::out() which is a reference to the 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 OFilterBuf providing an overriding implementation of overflow(), e.g., as follows:

        int DerivedClass::overflow(int ch)
        {
            out().put(ch);
        }

Next this std::streambuf specialization can be associated with an ostream into which information to be `copy filtered' can be inserted (cf. the EXAMPLE section below).

## NAMESPACE

FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace FBB.

## INHERITS FROM

std::streambuf

## CONSTRUCTORS

As OFilterBuf should be used as a base class all its constructors are protected.

- OFilterBuf():
  This constructor creates a OFilterBuf object without associating it with a destination (filtered) ostream.

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

- OFilterBuf(std::ostream &out):
  This constructor creates a OFilterBuf object and will insert any filtered information into the provided ostream object.

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

## PROTECTED MEMBER FUNCTIONS

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

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

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

- void reset(std::ostream &out):
  This member flushes the current destination (filtered) std::ostream object and associates the OFilterBuf object with the provided ostream object.

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

## EXAMPLE

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

## FILES

bobcat/ofilterbuf - defines the class interface

## SEE ALSO

bobcat(7), ifilterbuf(3bobcat)

## BUGS

None Reported.

## BOBCAT PROJECT FILES

- https://fbb-git.gitlab.io/bobcat/: gitlab project page;
- bobcat_5.07.03-x.dsc: detached signature;
- bobcat_5.07.03-x.tar.gz: source archive;
- bobcat_5.07.03-x_i386.changes: change log;
- libbobcat1_5.07.03-x_*.deb: debian package containing the libraries;
- libbobcat1-dev_5.07.03-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).