includefile(include/header)

COMMENT(replace 'classname' by the name of the new class)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::Eoi)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
                    (End-Of-Information Base class)

manpagename(FBB::Eoi)(std::streambuf class offering an eoi manipulator)

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

manpagedescription()
    The class tt(Eoi) inherits from tt(std::streambuf) and may therefore be
used as a base class of classes specializing tt(std::streambuf). It is
particularly useful for classes implementing output operations, as it can be
used to specify the `true end' of the generated output. E.g., an
tt(std::istream in) object may insert its content into a tt(std::ostream out)
object using the familiar tt(out << in.rdbuf()) expression, but that doesn't
allow tt(out) to conclude that it has received all of its information.
Sometimes additional actions are required to complete the output (this happens
with, e.g., tt(EncryptBuf) objects (cf. bf(encryptbuf)(3bobcat)) where after
encrypting all input padding characters may have to be added to the encrypted
document). If tt(out) is initialized with the address of an tt(EncryptBuf
std::streambuf) then the true end of the input can be indicated by inserting
the tt(eoi) manipulator. The resulting expression becomes tt(std::cout <<
in.rdbuf() << eoi), and the manipulator ensures that the correct padding is
handled.

includefile(include/namespace)

manpagesection(INHERITS FROM)
    tt(std::streambuf)

manpagesection(PROTECTED CONSTRUCTOR)
    itemization(
    itb(Eoi())
        Analogously to tt(std::streambuf) only a default protected constructor
        is available.
    )

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

manpagesection(MEMBER FUNCTIONS)
     All members of tt(std:streambuf) are available, as bf(FBB::Eoi) inherits
    from these classes.

manpagesection(VIRTUAL MEMBER FUNCTION)

    itemization(
    itb(virtual void eoi_())
       The virtual member function tt(eoi_) is a private member that can be
        overridden by derived classes. By default it performs no actions.
    )

manpagesection(MANIPULATOR)
    itemization(
    itb(std::ostream &FBB::eoi(std::ostream &out))
        The tt(eoi) manipulator can be inserted into the tt(ostream) using a
streambuf which is inherited from tt(FBB::EoiBuf) to stop further insertions
into the tt(ostream). If it is inserted into a plain
tt(std::ostream) nothing happens.

        tt(eoi) can also be called as a function, receiving the stream that
uses an tt(FBB::EoiBuf) as its tt(streambuf). By default the tt(eoi)
manipulator performs no actions. To use the manipulator in a class derived
from tt(EoiBuf) the following approach can be used:
        verb(
    1. define a tt(bool d_eoi) data member, initialized to tt(false);
    2. define a tt(void eoi_() override) member;
    3. tt(eoi_) returns if tt(d_eoi == true), otherwise:
    4. it sets tt(d_eoi) to tt(true) and performs the actions normally
        performed by the class's destructor;
    5. the class's destructor calls tt(eoi_()).
        )
    )

manpagesection(EXAMPLE)
    See the example provided in the tt(osymcryptstream)(3bobcat) man-page

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

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

manpagebugs()
    None Reported.

includefile(include/trailer)
