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
|
The class hi(streambuf)tt(std::streambuf) receives the character sequences
processed by streams and defines the interface between stream objects and
devices (like a file on disk). A tt(streambuf) object is usually not directly
constructed, but usually it is used as base class of some derived class
implementing the communication with some concrete device.
The primary reason for existence of the class tt(streambuf) is to decouple
the tt(stream) classes from the devices they operate upon. The rationale here
is to add an extra layer between the classes allowing us to communicate with
devices and the devices themselves. This implements a emi(chain of command)
which is seen regularly in software design.
The em(chain of command) is considered a generic pattern when designing
i(reusable software), encountered also in, e.g., the
i(TCP/IP stack).
A tt(streambuf) can be considered yet another example of the chain of
command pattern. Here the program talks to tt(stream) objects, which in turn
forward their requests to tt(streambuf) objects, which in turn communicate
with the devices. Thus, as we will see shortly, we are able to do in
user-software what had to be done via (expensive) system calls before.
The class tt(streambuf) has no public constructor, but does make available
several public member functions. In addition to these public member functions,
several member functions are only available to classes derived from
tt(streambuf). In section ref(FILEBUF) a predefined specialization of the
class tt(streambuf) is introduced. All public members of tt(streambuf)
discussed here are em(also) available in tt(filebuf).
The next section shows the tt(streambuf) members that may be overridden
when deriving classes from tt(streambuf). Chapter ref(CONCRETE) offers
concrete examples of classes derived from tt(streambuf).
The class tt(streambuf) is used by streams performing input operations and
by streams performing output operations and their member functions can be
ordered likewise. The type tt(std::streamsize)hi(streamsize) used below may,
for all practical purposes, be considered equal to the type tt(size_t).
label(STRBUFLABEL)
hi(streambuf: and exceptions)hi(exception: and streambuf)
When inserting information into tt(ostream) objects the information is
eventually passed on to the tt(ostream)'s tt(streambuf). The tt(streambuf) may
decide to throw an exception. However, this exception does not leave the
tt(ostream) using the tt(streambuf). Rather, the exception is caught by the
tt(ostream), which sets its tt(ios::bad_bit). Exceptions thrown by
manipulators which are inserted into tt(ostream) objects are em(not) caught by
the tt(ostream) objects.
bf(Public members for input operations)
itemization(
ithtq(in_avail)
(std::streamsize in_avail())
(Returns a lower bound on the number of characters that can be read
immediately.)
ithtq(sbumpc)
(int sbumpc())
(The next available character or endOfFile() is returned. The returned
character is removed from the tt(streambuf) object. If no input is
available, tt(sbumpc) calls the (protected) member ti(uflow) (see
section ref(SBPROTECTED) below) to make new characters
available. endOfFile() is returned if no more characters are
available.)
ithtq(sgetc)
(int sgetc())
(The next available character or endOfFile() is returned. The character
is em(not) removed from the tt(streambuf) object. To remove a
character from the tt(streambuf) object, tt(sbumpc) (or tt(sgetn)) can
be used.)
ithtq(sgetn)
(int sgetn(char *buffer, std::streamsize n))
(At most tt(n) characters are retrieved from the input buffer, and
stored in tt(buffer). The actual number of characters read is
returned. The (protected) member ti(xsgetn) (see section
ref(SBPROTECTED) below) is called to obtain the requested number of
characters.)
ithtq(snextc)
(int snextc())
(The current character is obtained from the input buffer and returned as
the next available character or endOfFile() is returned. The character
is em(not) removed from the tt(streambuf) object.)
ithtq(sputbackc)
(int sputbackc(char c))
(Inserts tt(c) into the tt(streambuf)'s buffer to be returned as the
next character to read from the tt(streambuf) object. Caution should
be exercised when using this function: often there is a maximum of
just one character that can be put back.)
ithtq(sungetc)
(int sungetc())
(Returns the last character read to the input buffer, to be read again
at the next input operation. Caution should be exercised when using
this function: often there is a maximum of just one character that
can be put back.)
)
bf(Public members for output operations)
itemization(
ithtq(pubsync)
(int pubsync())
(Synchronizes (i.e., flushes) the buffer by writing any information
currently available in the tt(streambuf)'s buffer to the
device. Normally only used by classes derived from tt(streambuf).)
ithtq(sputc)
(int sputc(char c))
(Character tt(c) is inserted into the tt(streambuf) object. If, after
writing the character, the buffer is full, the function calls the
(protected) member function ti(overflow) to flush the buffer to the
device (see section ref(SBPROTECTED) below).)
ithtq(sputn)
(int sputn(char const *buffer, std::streamsize n))
(At most tt(n) characters from tt(buffer) are inserted into the
tt(streambuf) object. The actual number of characters inserted is
returned. This member function calls the (protected) member ti(xsputn)
(see section ref(SBPROTECTED) below) to insert the requested number of
characters.)
)
bf(Public members for miscellaneous operations)
The next three members are normally only used by classes derived from
tt(streambuf).
itemization(
ithtq(pubseekoff)
(ios::pos_type pubseekoff(ios::off_type offset, ios::seekdir way,
ios::openmode mode = ios::in | ios::out))
(Sets the offset of the next character to be read or written to
tt(offset), relative to the standard hi(seekdir) tt(ios::seekdir)
values indicating the direction of the seeking operation.)
ithtq(pubseekpos)
(ios::pos_type pubseekpos(ios::pos_type offset,
ios::openmode mode = ios::in | ios::out))
(Sets the i(absolute position) of the next character to be read or
written to tt(pos).)
ithtq(pubsetbuf)
(streambuf *pubsetbuf(char* buffer, std::streamsize n))
(The tt(streambuf) object is going to use ti(buffer), which may contain
at least tt(n) characters.)
)
|
