1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
includefile(include/header)
COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::IFilterBuf)(3bobcat)(_CurYrs_)
(libbobcat-dev__CurVers_)(Filtering Input Stream Buffer)
manpagename(FBB::IFilterBuf)
(Filtering stream buffer initialized by a std::istream object)
manpagesynopsis()
bf(#include <bobcat/ifilterbuf>)nl()
Linking option: tt(-lbobcat)
manpagedescription()
bf(FBB::IFilterBuf) objects may be used as a bf(std::streambuf) for
tt(std::istream) objects, filtering the information produced by those objects.
Because tt(IFilterBuf) is a tt(streambuf) its member tt(underflow) is
automatically called when reading operations are requested from the tt(stream)
object using the tt(IFilterBuf) as its tt(streambuf). If no chars are
currently available (i.e., tt(srcBegin == srcEnd), see the description of the
tt(filter) member below), then tt(filter) is called, which may store
characters in a (local) buffer of at most tt(maxSize) characters (see the
description of the tt(IFilterBuf) constructor below). Once this buffer has
been filled tt(filter) updates the tt(*srcBegin) and tt(*srcEnd) pointers so
that they point to, respectively, the the location of the first character in
the local buffer and beyond the location of the last character in the local
buffer.
The class tt(IFilterBuf) was designed with the bf(openSSL BIO)
(cf. bf(bio)(3ssl)) in mind. Since the BIO concept was developed in the
context of the bf(C) programming language, BIOs do not support bf(C++)
streams. Nonetheless, the concept of a filtering device is an attractive one,
and is offered by the bf(FBB::IFilterBuf) class.
In addition to filtering, bf(IFilterBuf) offers flexible internal buffer
management: derived classes can put characters back on the internal buffer
until the beginning of the buffer has been reached, but may then continue
pushing characters on the buffer until the buffer has reached its maximum
size. This maximum size is defined by the constructor's tt(maxSize) parameter
(see below).
The class bf(IFilterBuf) is an abstract base class. It is used via
classes that are derived from bf(IFilterBuf), implementing its pure
virtual tt(load) member (see below at bf(PRIVATE VIRTUAL MEMBER FUNCTIONS)).
includefile(include/namespace)
manpagesection(INHERITS FROM)
bf(std::streambuf)
manpagesection(MEMBER FUNCTIONS)
All members of bf(std::streambuf) are available, as bf(IFilterBuf)
inherits from this class.
manpagesection(PROTECTED CONSTRUCTOR)
itemization(
itb(IFilterBuf(size_t maxSize = 1000))
This constructor initializes the streambuf. While the streambuf is
being used, its internally used buffer is gradually filled. It may be filled
with up to tt(maxSize) characters, but the actual number of characters that is
stored in the buffer is determined by the member tt(filter) (see below) and by
using the member tt(streambuf::sputbackc).
)
Copy and move constructors (and assignment operators) are not available.
manpagesection(PROTECTED MEMBER FUNCTION)
itemization(
itb(void setBuffer())
This member initializes the base class's buffer pointers (i.e.,
tt(eback, gptr,) and tt(egptr)) with the initial range of characters retrieved
by tt(filter) (see below).
Derived classes do not have to call this member, but if they do they
should only call tt(setBuffer) once from their constructors. Once
tt(setBuffer) has been called, the tt(peek) member of the tt(std::istream)
that is available to bf(IFilterBuf) objects can be called to inspect the
next available character, even if no other stream operation has as yet been
performed. If it is not called by the derived class's constructor, then
tt(peek) returns 0 until at least one character has been retrieved from the
tt(istream) object.
)
manpagesection(PRIVATE VIRTUAL MEMBER FUNCTIONS)
itemization(
itb(virtual bool filter(char const **srcBegin, char const **srcEnd) = 0)
The tt(filter) member is declared as a pure virtual member: derived
classes em(must) override tt(filter) with their own implementation.
Derived class objects are responsible for obtaining information (in any
amount) from the device with which they interact. This information is then
passed on to the tt(IFilterBuf) via two pointers, pointing,
respectively, to the first available character and beyond the last available
character. The characters indicated by this range are subsequently transferred
by the bf(IFilterBuf) object to its own buffer, from where they are then
retrieved (or to where they can be pushed back) by the application.
The tt(filter) member allows implementations to filter and/or modify the
information that is obtained by this member. The bf(EXAMPLE) section below
provides an example filtering out a configurable set of characters from a
provided tt(std::istream). Bobcat's classes bf(ISymCryptStreambuf)(3bobcat)
and bf(IBase64Buf)(3bobcat) provide additional examples of classes
derived from bf(IFilterBuf).
The tt(filter) member should return tt(false) if no (more) information is
available. It should return tt(true) if information is available, in which
case tt(*srcBegin) and tt(*srcEnd) should be pointing to, respectively, the
first character and beyond the last character made available by tt(filter);
itb(int pbackfail(int ch) override)
If tt(IFilterBuf's) internally used buffer has reached its
maximmum size then EOF is returned. Otherwise, tt(ch) is inserted at
the beginning of the internally used buffer, becoming the next
character that's retrieved from the object's buffer;
itb(std::streamsize showmanyc() override)
The sum of the number of not yet processed characters in the internally
used buffer and the number of not yet processed characters returned
by the latest tt(filter) call is returned;
itb(int underflow() override)
Once the internally used buffer is empty tt(filter) is called to obtain
a new series of filtered characters. If tt(filter) returns tt(false
underflow) returns EOF. Otherwise the series of characters returned by
tt(filter) are transferred to the tt(IFilterBuf's) internal
buffer to be processed by the tt(std::istream) that's initialized with
the tt(IFilterBuf) object.
)
manpagesection(EXAMPLE)
Here is a class, derived from tt(IFilterBuf), filtering out a
predefined set of characters. It is used twice to filter digits and
vowels, illustrating chaining of bf(IFilterBuf) objects.
verbinclude(../../ifilterbuf/driver/driver.cc)
manpagefiles()
em(bobcat/ifdbuf) - defines the class interface
manpageseealso()
bf(bobcat)(7), bf(isymcryptstreambuf)(3bobcat),
bf(ibase64buf)(3bobcat),
bf(ofilterbuf)(3bobcat). bf(std::streambuf)
manpagebugs()
None reported.
includefile(include/trailer)
|
