sequence_buffer<Container, buf_sz>

Description

The main difference between sequence_buffer and
back_insert_iterator is that back_insert_iterator
inserts elements into a sequence one element at a time;
sequence_buffer, however, as the "buffer" part of the name
suggests, accumulates elements into a buffer and appends the
entire buffer in a single operation.

Specifically, the expression *it = v adds v
to the end of it's internal buffer. The buffer is automatically
flushed when it gets full, or when it is destroyed; flushing the
buffer means emptying it and appending its contents to
it's underlying container. (It is also possible to flush the
buffer manually, by invoking the flush() member function.)

This difference has two implications. First, sequence_buffer
is only useful if appending an array of N elements is much more
efficient than inserting a single element N times. Second,
sequence_buffer assumes that it can insert elements at the
end of a container using an append member function. This
member function is not part of the Container or
Sequence requirements. The sequence_buffer adaptor can
be used with rope, but not with any of the other containers
in the library. (This is the reason why sequence_buffer is
defined in the file rope.h, instead of in iterator.h.)

If you want to build up a string one character at a time, it is
much more efficient to use sequence_buffer than to repeatedly
add single characters to the end of a rope.

Create a sequence_buffer whose underlying container is C.
Elements appended to the sequence_buffer will be appended to
C whenever the sequence_buffer is flushed.

void flush()

Append all elements in the buffer to the underlying container, and
empty the buffer. That is, make the underlying container consistent
with the sequence_buffer. Note that flush is called automatically
whenever the buffer is full, and also by sequence_buffer's destructor.
Sometimes, however, it is useful to be sure that the buffer is
flushed at a particular time.

void push_back(value_type x)

Append x to the sequence_buffer. Note that this member function is
strictly unnecessary: i.push_back(x) is just alternate syntax for
*i = x.

void append(value_type* s, size_t len)

Append the range [s, s + len) to the sequence_buffer. Note
that i.append(s, n) is just the same as
copy(s, s + n, i). The append member function, however,
is faster.

Notes

[1]
Despite the name "sequence_buffer", this adaptor cannot
actually be used with arbitrary sequences: it requires that the
template argument Container have an append member function that
can insert multiple elements at the end of the container. This
member function is not part of the Sequence requirements. This
means that sequence_buffer can be used with rope, but
not with any of the other predefined container classes.

[2]
Note how assignment through a sequence_buffer is implemented.
In general, unary operator* must be defined so that it returns a
proxy object, where the proxy object defines operator= to perform
the output operation. In this case, for the sake of simplicity, the
proxy object is the sequence_buffer itself. That is, *i simply
returns i, and *i = t is equivalent to i = t. You should not,
however, rely on this behavior. It is an implementation detail,
and it is not guaranteed to remain the same in future versions.