temporary_buffer<ForwardIterator, T>


Category: allocators	Component type: type

Description

Some algorithms, such as stable_sort and inplace_merge, are adaptive: they attempt to use extra temporary memory to store intermediate results, and their run-time complexity is better if that extra memory is available. These algorithms use temporary_buffer to allocate that extra memory.

temporary_buffer's constructor takes two arguments, first and last, of type ForwardIterator; the constructor allocates a buffer that is large enough to contain N objects of type T, where 0 <= N <= last - first [1], and it fills the buffer with objects of type T. The member functions begin() and end() return iterators that point to the beginning and the end of the buffer.

Note that the elements in the buffer are guaranteed to be initialized; that is, begin() points to an object of type T, not to raw memory. However, the initial values of the buffer's elements are unspecified. You should not rely on them to be initialized to any particular value.

temporary_buffer does not have a copy constructor, or an assignment operator. Those operations would have complicated, and not terribly useful, semantics.

(Earlier versions of the STL used get_temporary_buffer and return_temporary_buffer instead of temporary_buffer. temporary_buffer is more convenient, because it does not require using uninitialized_copy, and in some cases it is also more efficient. Additionally, it is much easier to write exception-safe code with temporary_buffer than with get_temporary_buffer and return_temporary_buffer.)

Example

int main()
{
  vector<int> V(50);
  iota(V.begin(), V.end(), 1);

  temporary_buffer<vector<int>::iterator, int> buf(V.begin(), V.end());
  copy(V.rbegin(), V.rbegin() + buf.size(), buf.begin());
  copy(buf.begin(), buf.end(), ostream_iterator<int>(cout, "\n"));
}

Definition

Defined in the standard header memory, and in the nonstandard backward-compatibility header algo.h. This class is an SGI extension; it is not part of the C++ standard.

Template parameters

Parameter	Description	Default
`ForwardIterator`	The type of the iterators passed as arguments to `temporary_buffer`'s constructor.
`T`	The type of object stored in the temporary buffer.	`iterator_traits<ForwardIterator>::value_type` [2]

Model of

None. temporary_buffer is vaguely similar to a Container, but it does not provide the entire Container interface. In particular, it is not a model of DefaultConstructible or Assignable.

Type requirements

ForwardIterator is a model of Forward Iterator
ForwardIterator is mutable.
T has a constructor that can take a single argument of ForwardIterator's value type.

Public base classes

None.

Members

Member	Description
temporary_buffer(ForwardIterator first, ForwardIterator last)	Allocates a temporary buffer that holds at most `last - first` elements of type `T`, and constructs those elements. The initial values of the elements are unspecified. Precondition: `[first, last)` is a valid range.
`~temporary_buffer()`	Destroys the elements in the temporary buffer, and deallocates the buffer itself.
`T* begin()`	Returns a pointer to the first element in the buffer.
`T* end()`	Returns a pointer that points one past the last element in the buffer.
`ptrdiff_t requested_size() const`	Returns the value `last - first`, where `first` and `last` are the arguments that were passed to the constructor.
`ptrdiff_t size() const`	Returns the number of elements in the temporary buffer, `end() - begin()`. The return value satisfies the constraint `0 <= size() <= requested_size()`.

New members

Notes

[1] The requested size is last - first. The size of the temporary buffer is never larger than the requested size, but it might well be smaller; the size might even be zero. The intention is that temporary_buffer will allocate as large a buffer as is possible without hurting performance. Note that determining this maximum size is quite difficult: it depends on cache size, physical versus virtual memory, heap fragmentation, and so on. A good implementation of temporary_buffer must be nonportable.

[2] The iterator_traits mechanism relies on partial specialization of templates. If your compiler does not yet implement this features, then you will not be able to use this default parameter; you will have to provide both template arguments.