1
Strings can be processed similarly to tt(iostream) objects, if objects of the
2
class tt(istrstream, ostrstream) or tt(strstream) are constructed. Objects of
3
these classes can be used to, respectively, read information from memory,
4
write information to memory, or both.
6
These objects can be created by constructors expecting the address
7
of a block of memory (and its size) as its argument. It is also possible to
8
let the objects to the memory management themselves.
10
Let's go through some examples. To write something into a block of memory
11
using a tt(ostrstream) object, the following code could be used:
16
os(buffer, 100); // construct the ostrstream object
18
// fill 'buffer' with a well-known text
19
os << "Hello world " << '\n' << ends;
21
cout << os.str(); // display the string
23
Note the final tt(ends) that is appended: When an ascii-z string is
24
inserted into an tt(ostrstream) object it will not automatically write a
25
trailing ascii-z sentinel (comparable to the way tt(ostream) objects
26
behave). In order to append a terminating ascii-z, the symbolic value tt(ends)
27
can be used. After inserting an tt(ends) further insertions into the
28
tt(ostrstream) object will succeed, but they will not normally be visible:
33
os(buffer, 100); // construct the ostrstream object
35
os << "Hello world " << ends;
37
os << " More text " << ends;
39
cout << os.str() << '\n'; // this only shows 'Hello world'
41
The information, however, em(is) stored in the string, as shown by the
44
void bytes(ostrstream &str)
49
cout << str.pcount() << ": ";
51
for (int idx = 0; idx < 10; ++idx)
52
cout << setw(3) << static_cast<int>(cp[idx]) << " ";
60
memset(buffer, 10, 10);
82
This little program produces the following output:
84
0: 10 10 10 10 10 10 10 10 10 10
85
1: 65 10 10 10 10 10 10 10 10 10
86
3: 65 66 0 10 10 10 10 10 10 10
87
4: 65 66 0 67 10 10 10 10 10 10
89
This output shows that all insertions succeed, but the tt(ends) writes an
90
ascii-z character. This effectively creating an ascii-z string, preventing the
91
display of the information beyond when the contents of the tt(ostrstream)
92
object are inserted into tt(cout).
94
Furthermore, note the use of the member function tt(str()), returning the
95
string the tt(ostrstream) object operates on. Using tt(str()) the existence of
96
tt(buffer) can be hidden from the users of the tt(ostrstream) object.
98
When an tt(ostrstream) object is created without an external memory buffer
99
(e.g., `tt(ostrstream str;)' is defined), the tt(ostrstream) object allocates
100
the required memory itself. In that case using the tt(str()) member function
101
will result in the em(freezing) of the tt(ostrstream) object: it will no
102
longer create room for new characters when additional text is inserted into
103
the object, and, most important, it will em(not delete allocated memory) when
104
the object itself is deleted.
106
To prevent memory leakage here, the program using the tt(str()) member function
107
can take two actions:
109
it() First, as tt(str()) returns a tt(char *) rather than a tt(char
110
const *) the caller of tt(str()) may consider the returned string its own.
111
Consequently, the caller of tt(str()) is responsible for deleting
112
the string returned by tt(str()). E.g.,
117
ostr << "Hello world" << ends;
120
*cp = ostr.gets(); // freezes ostr
122
cout << cp; // use ostr's string
123
delete cp; // caller deletes ostr's string
125
it() Alternatively, the string can be em(unfrozen), after which
126
insertions are again possible. Now, when the tt(ostrstream) object is
127
destroyed the tt(ostrstream)'s internally stored string is destroyed
133
ostr << "Hello world" << ends;
136
*cp = ostr.gets(); // freezes ostr
138
cout << cp; // use ostr's string
140
ostr.freeze(0); // ostr will now delete its own string, cp
141
// should leave the memory it points to alone.
145
The following member functions are available for tt(strstream) objects:
147
itt(istrstream::istrstream(const char *str [, int size])): This
148
constructor creates an input string class tt(istrstream) object, associating
149
it with an existing buffer starting at tt(str), of size tt(size).
150
If tt(size) is not specified, the buffer is treated as a null-terminated
152
itt(ostrstream::ostrstream()): This constructor creates a new stream for
153
output to a dynamically managed string, which will grow as needed.
154
itt(ostrstream::ostrstream(char *str, int size [, int mode])): This
155
constructor creates a new stream for output to a statically defined string of
156
length tt(size), starting at tt(str). The tt(mode) parameter may
157
optionally be specified as one of the iostream modes. By default tt(ios::out)
159
itt(int ostrstream::pcount()): returns the current length of the string
160
associated with this tt(ostrstream) object.
161
itt(char *ostrstream::str()): The member function returns a pointer to the
162
string managed by this tt(ostrstream) object. This function implies
163
tt(freeze()), see below:
164
itt(void ostrstream::freeze ([int n])): If tt(n) is nonzero (the default),
165
the string associated with this tt(ostrstream) object must not change
166
dynamically anymore. While frozen, it will not be reallocated if it needs
167
more space, and it will not be deallocated when the tt(ostrstream) object is
168
destroyed. tt(freeze(1)) can be used to refer to the string as a pointer
169
after creating it via tt(ostrstream) facilities. tt(freeze(0)) can be used to
170
unfreeze (thaw ?) the object again. Following tt(freeze(0)) the tt(ostrstream)
171
object will delete memory it allocated when the object itself is deleted.
172
itt(int ostrstream::frozen()): This member can be used to
173
test whether tt(freeze(1)) is in effect for this string.
175
In order to use the tt(strstream) classes, the header file tt(strstream)
added
removed
yo/iostreams/src/strings.yo.OFF
