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

Manages memory buffers for building cords&period;

== Synopsis

Declared in `&lt;absl&sol;strings&sol;cord&lowbar;buffer&period;h&gt;`

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

== Description

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

absl&colon;&colon;Cord CreateRandomCord(size&lowbar;t length) &lcub; absl&colon;&colon;Cord cord&semi; while (length &gt; 0) &lcub; CordBuffer buffer &equals; CordBuffer&colon;&colon;CreateWithDefaultLimit(length)&semi; absl&colon;&colon;Span&lt;char&gt; data &equals; buffer&period;available&lowbar;up&lowbar;to(length)&semi; FillRandomValues(data&period;data(), data&period;size())&semi; buffer&period;IncreaseLengthBy(data&period;size())&semi; cord&period;Append(std&colon;&colon;move(buffer))&semi; length &hyphen;&equals; data&period;size()&semi; &rcub; return cord&semi; &rcub;

CordBuffer instances are by default limited to a capacity of `kDefaultLimit` bytes&period; `kDefaultLimit` is currently just under 4KiB, but this default may change in the future and&sol;or for specific architectures&period; The default limit is aimed to provide a good trade&hyphen;off between performance and memory overhead&period; 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&period; Using larger buffers may also increase the risk of memory fragmentation&period;

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

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&period; The usage of `CreateWithCustomLimit()` should be limited to only those use cases where the distribution of the input is relatively well known, and&sol;or where the trade&hyphen;off between the efficiency gains outweigh the risk of memory fragmentation&period; See the documentation for `CreateWithCustomLimit()` for more information on using larger custom limits&period;

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&period; Applications should use the `capacity` method to obtain the effective capacity of the returned instance as demonstrated in the provided example above&period;

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

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

== Member Functions

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


== 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&lowbar;size`&period; Requires `block&lowbar;size` to be a power of 2&period;
| xref:absl/CordBuffer/CreateWithDefaultLimit.adoc[`CreateWithDefaultLimit`] 
| Creates a CordBuffer instance of the desired `capacity`, capped at the default limit `kDefaultLimit`&period; The returned buffer has a guaranteed capacity of at least `min(kDefaultLimit, capacity)`&period; See the class comments for more information on buffer capacities and intended usage&period;
| 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&period;
| xref:absl/CordBuffer/kDefaultLimit.adoc[`kDefaultLimit`] 
| Default capacity limits of allocated CordBuffers&period;
|===


== Friends

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


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