[#absl-CordBuffer]
= xref:absl.adoc[absl]::CordBuffer
:relfileprefix: ../
:mrdocs:

Manages memory buffers for building cords.

== Synopsis

Declared in `<absl/strings/cord_buffer.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class CordBuffer;
----

== Description

CordBuffer manages memory buffers for purposes such as zero‐copy APIs as well as applications building cords with large data requiring granular control over the allocation and size of cord data. For example, a function creating a cord of random data could use a CordBuffer as follows:

absl::Cord CreateRandomCord(size_t length) { absl::Cord cord; while (length > 0) { CordBuffer buffer = CordBuffer::CreateWithDefaultLimit(length); absl::Span<char> data = buffer.available_up_to(length); FillRandomValues(data.data(), data.size()); buffer.IncreaseLengthBy(data.size()); cord.Append(std::move(buffer)); length ‐= data.size(); } return cord; }

CordBuffer instances are by default limited to a capacity of `kDefaultLimit` bytes. `kDefaultLimit` is currently just under 4KiB, but this default may change in the future and/or for specific architectures. The default limit is aimed to provide a good trade‐off between performance and memory overhead. Smaller buffers typically incur more compute cost while larger buffers are more CPU efficient but create significant memory overhead because of such allocations being less granular. Using larger buffers may also increase the risk of memory fragmentation.

Applications create a buffer using one of the `CreateWithDefaultLimit()` or `CreateWithCustomLimit()` methods. The returned instance will have a non‐zero capacity and a zero length. Applications use the `data()` method to set the contents of the managed memory, and once done filling the buffer, use the `IncreaseLengthBy()` or 'SetLength()' method to specify the length of the initialized data before adding the buffer to a Cord.

The `CreateWithCustomLimit()` method is intended for applications needing larger buffers than the default memory limit, allowing the allocation of up to a capacity of `kCustomLimit` bytes minus some minimum internal overhead. The usage of `CreateWithCustomLimit()` should be limited to only those use cases where the distribution of the input is relatively well known, and/or where the trade‐off between the efficiency gains outweigh the risk of memory fragmentation. See the documentation for `CreateWithCustomLimit()` for more information on using larger custom limits.

The capacity of a `CordBuffer` returned by one of the `Create` methods may be larger than the requested capacity due to rounding, alignment and granularity of the memory allocator. Applications should use the `capacity` method to obtain the effective capacity of the returned instance as demonstrated in the provided example above.

CordBuffer is a move‐only class. All references into the managed memory are invalidated when an instance is moved into either another CordBuffer instance or a Cord. Writing to a location obtained by a previous call to `data()` after an instance was moved will lead to undefined behavior.

A `moved from` CordBuffer instance will have a valid, but empty state. CordBuffer is thread compatible.

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:absl/CordBuffer/2constructor-06.adoc[`CordBuffer`]         [.small]#[constructor]#
| Constructors
| xref:absl/CordBuffer/2destructor.adoc[`~CordBuffer`] [.small]#[destructor]#
| Destroys this CordBuffer instance and, if not empty, releases any memory managed by this instance, invalidating previously returned references.
| xref:absl/CordBuffer/operator_assign-05f.adoc[`operator=`] 
| Assignment operators
| xref:absl/CordBuffer/IncreaseLengthBy.adoc[`IncreaseLengthBy`] 
| Increases the length of this buffer by the specified 'n' bytes.
| xref:absl/CordBuffer/SetLength.adoc[`SetLength`] 
| Sets the data length of this instance. Applications must make sure all data of the specified length has been initialized before adding a CordBuffer to a Cord: failure to do so will lead to undefined behavior. Setting the length to a small value or zero does not release any memory held by this CordBuffer instance. Requires `length <= capacity()`. Applications should preferably use the `IncreaseLengthBy()` method above in combination with the 'available()` or `available_up_to()` methods.
| xref:absl/CordBuffer/available.adoc[`available`] 
| Returns the span delineating the available capacity in this buffer which is defined as `{ data() + length(), capacity() ‐ length() }`.
| xref:absl/CordBuffer/available_up_to.adoc[`available_up_to`] 
| Returns the span delineating the available capacity in this buffer limited to `size` bytes. This is equivalent to `available().subspan(0, size)`.
| xref:absl/CordBuffer/capacity.adoc[`capacity`] 
| Returns the capacity of this instance. All instances have a non‐zero capacity: default and `moved from` instances have a small internal buffer.
| xref:absl/CordBuffer/data-0f.adoc[`data`] 
| `data` overloads
| xref:absl/CordBuffer/length.adoc[`length`] 
| Returns the length of this instance. The default length of a CordBuffer is 0, indicating an 'empty' CordBuffer. Applications must specify the length of the data in a CordBuffer before adding it to a Cord.
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:absl/CordBuffer/CreateWithCustomLimit.adoc[`CreateWithCustomLimit`] 
| Creates a CordBuffer instance of the desired `capacity` rounded to an appropriate power of 2 size less than, or equal to `block_size`. Requires `block_size` to be a power of 2.
| xref:absl/CordBuffer/CreateWithDefaultLimit.adoc[`CreateWithDefaultLimit`] 
| Creates a CordBuffer instance of the desired `capacity`, capped at the default limit `kDefaultLimit`. The returned buffer has a guaranteed capacity of at least `min(kDefaultLimit, capacity)`. See the class comments for more information on buffer capacities and intended usage.
| xref:absl/CordBuffer/MaximumPayload-02.adoc[`MaximumPayload`] 
| `MaximumPayload` overloads
|===


== Static Data Members

[cols="1,4"]
|===
| Name| Description
| xref:absl/CordBuffer/kCustomLimit.adoc[`kCustomLimit`] 
| Maximum size for CreateWithCustomLimit() allocated buffers.
| xref:absl/CordBuffer/kDefaultLimit.adoc[`kDefaultLimit`] 
| Default capacity limits of allocated CordBuffers.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:absl/CordBufferTestPeer.adoc[absl::CordBufferTestPeer]`
| Test‐only accessor for `CordBuffer` internals.
| `xref:absl/Cord.adoc[absl::Cord]`
| A sequence of characters stored as a tree of buffers.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#