# sequence_buffer<Container, buf_sz>

Categories: iterators, adaptors | Component type: type

### Description

`Sequence_buffer` is similar to `back_insert_iterator`: it is an output iterator adaptor that appends elements to the end of a container.

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`.

### Example

    int main()
    {
      const char* const s = "this is a test";
      const int N = strlen(s);

      crope r;
      transform(s, s + N,
                sequence_buffer<crope>(r),
                toupper);
      cout << "r = " << r << endl;
    }

### Definition

Defined in the header rope, and in the backward-compatibility header rope.h. The `sequence_buffer` class, and the rope header, are SGI extensions; they are not part of the C++ standard.

### Template parameters

Parameter | Description | Default
--- | --- | ---
`Container` | The type of the underlying container that elements are being written to. [1] |
`buf_sz` | Number of elements in the buffer. This is a number, not a type. `buf_sz` has type `size_t`. | 100

### Model of

Output Iterator.

### Type requirements

- `Container` is a variable-sized Forward Container
- `Container`'s value type `T` is a model of Default Constructible, as well as Assignable.
- `Container` has a member function that appends a range. Specifically: If `x` is an object of type `Container` and `f` and `l` are of type `T*`, then `x.append(f, l)` appends the range `[f, l)` to `x`. [1]

### Public base classes

`output_iterator`

### Members

Member | Where defined | Description
--- | --- | ---
`value_type` | `sequence_buffer` | The underlying container's value type.
`sequence_buffer(Container& C)` | `sequence_buffer` | Create a `sequence_buffer` whose underlying container is `C`.
`sequence_buffer()` | `Default Constructible` | The default constructor. The resulting iterator is singular.
`sequence_buffer(const sequence_buffer&)` | Assignable | Copy constructor.
`sequence_buffer& operator=(const sequence_buffer& s)` | Assignable | Assignment operator.
`sequence_buffer& operator=(sequence_buffer& s)` | Assignable | Faster version of assignment operator.
`sequence_buffer& operator=(const value_type&)` | Output Iterator | Used to implement the Output Iterator requirement `*i = t`. [2]
`sequence_buffer& operator*()` | Output Iterator | Used to implement the Output Iterator requirement `*i = t`. [2]
`sequence_buffer& operator++()` | Output Iterator | Preincrement
`sequence_buffer& operator++(int)` | Output Iterator | Postincrement
`void flush()` | `sequence_buffer` | Flush the buffer.
`void push_back(value_type)` | `sequence_buffer` | `i.push_back(x)` is equivalent to `*i = x`.
`void append(value_type* s, size_t len)` | `sequence_buffer` | Append multiple values.

### New members

These members are not defined in the Output Iterator requirements, but are specific to `sequence_buffer`.

Function | Description
--- | ---
`value_type` | The underlying container's value type. That is, `typename Container::value_type`.
`sequence_buffer(Container& C)` | 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.

### See also

Output Iterator, `rope`, `front_insert_iterator`, `back_insert_iterator`, `insert_iterator`

Copyright © 1999 Silicon Graphics, Inc. All Rights Reserved. TrademarkInformation