Library: Containers

Code documentation: Containers.

Summary

This library contains the following types of containers:

Buffers

Provides two types of containers. Both containers are used to store sequences of bytes, and both have the following two properties:

• There is a cursor pointing to a position within the container, where by convention the user stores data before the cursor, the "read part", and the space after the buffer, the "write part", may be uninitialized.
• The user can request the container to grow. How much it grows is controlled by a "grow policy", which the user can control and fine-tune.

The two types of containers are:

• buffer: a single, contiguous block of bytes. The structure is similar to a vector, but with the addition of the cursor position and the controllable grow policy.
• buffer sequence: a sequence of contiguous buffers. The structure is similar to a deque, but with the addition of the cursor position and the controllable grow policy. Also, provides iterators over the sequence of contiguous sub-segments, rather than a flat non-contiguous sequence.

Both data structures are intended for the use case where a third-party API requires the user to provide buffers for the API to write to, where the exact size is not known beforehand. Both data structures conveniently provide the cursor position to track the write position, and the grow policy to control memory usage when a bound on the memory is known. The buffer, just like a vector, guarantees that the stored bytes are contiguous in memory, for the price of having to copy existing data to a new location when it grows. The buffer sequence, just like a deque, never needs to copy existing data during a grow operation, but stores bytes non-contiguously.

Both the buffer and the buffer sequence exist as two classes:

• Managed_buffer and Managed_buffer_sequence manage their own memory, and can grow, and have a cursor position.
• Buffer_view and Buffer_sequence_view are non-owning, non-growable, without a cursor position. They are used to represent views over the read part and the write part of their managed counterparts.
• (Rw_buffer and Rw_buffer_sequence are non-owning, non-growable, but have a cursor position. They are not normally used directly, but rather exist in order to separate the "managing" part from the "cursor" part in the implementation.)