Adobe Software Technology Lab: sequence

Documentation

Overview
Building ASL
Documentation
Library Wiki Docs
Indices
Browse Perforce

More Info

Release Notes
Wiki
Site Search
License
Success Stories
Contributors

Media

Download
Perforce Depots

Other Resources

Boost
RIAForge
SGI STL



Categories: iterators, adaptors	Component type: type

Description

Sequence_buffer is similar to back_insert_iterator: it is an OutputIterator 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

OutputIterator.

Type requirements

Container is a variable-sized ForwardContainer
Container's value type T is a model of DefaultConstructible, 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()`	`DefaultConstructible`	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&)`	OutputIterator	Used to implement the OutputIterator requirement `*i = t`. [2]
`sequence_buffer& operator*()`	OutputIterator	Used to implement the OutputIterator requirement `*i = t`. [2]
`sequence_buffer& operator++()`	OutputIterator	Preincrement
`sequence_buffer& operator++(int)`	OutputIterator	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 OutputIterator 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.