class Cord

Creates an empty Cord.

Creates a Cord from an existing Cord. Cord is copyable and efficiently

movable. The moved-from state is valid but unspecified.

Creates a Cord from a `src` string. This constructor is marked explicit to

prevent implicit Cord constructions from arguments convertible to an

`absl::string_view`.

Creates a Cord from a `std::string

&

&

` rvalue. These constructors are

templated to avoid ambiguities for types that are convertible to both

`absl::string_view` and `std::string`, such as `const char*`.

Cord::~Cord()

Destructs the Cord.

Cord::Clear()

Releases the Cord data. Any nodes that share data with other Cords, if

applicable, will have their reference counts reduced by 1.

Cord::Append()

Appends data to the Cord, which may come from another Cord or other string

data.

Appends `buffer` to this cord, unless `buffer` has a zero length in which

case this method has no effect on this cord instance.

This method is guaranteed to consume `buffer`.

Returns a CordBuffer, re-using potential existing capacity in this cord.

Cord instances may have additional unused capacity in the last (or first)

nodes of the underlying tree to facilitate amortized growth. This method

allows applications to explicitly use this spare capacity if available,

or create a new CordBuffer instance otherwise.

If this cord has a final non-shared node with at least `min_capacity`

available, then this method will return that buffer including its data

contents. I.e.; the returned buffer will have a non-zero length, and

a capacity of at least `buffer.length + min_capacity`. Otherwise, this

method will return `CordBuffer::CreateWithDefaultLimit(capacity)`.

Below an example of using GetAppendBuffer. Notice that in this example we

use `GetAppendBuffer()` only on the first iteration. As we know nothing

about any initial extra capacity in `cord`, we may be able to use the extra

capacity. But as we add new buffers with fully utilized contents after that

we avoid calling `GetAppendBuffer()` on subsequent iterations: while this

works fine, it results in an unnecessary inspection of cord contents:

void AppendRandomDataToCord(absl::Cord

&cord

, size_t n) {

bool first = true;

while (n > 0) {

CordBuffer buffer = first ? cord.GetAppendBuffer(n)

: CordBuffer::CreateWithDefaultLimit(n);

absl::Span

<char

> data = buffer.available_up_to(n);

FillRandomValues(data.data(), data.size());

buffer.IncreaseLengthBy(data.size());

cord.Append(std::move(buffer));

n -= data.size();

first = false;

}

}

Returns a CordBuffer, re-using potential existing capacity in this cord.

This function is identical to `GetAppendBuffer`, except that in the case

where a new `CordBuffer` is allocated, it is allocated using the provided

custom limit instead of the default limit. `GetAppendBuffer` will default

to `CordBuffer::CreateWithDefaultLimit(capacity)` whereas this method

will default to `CordBuffer::CreateWithCustomLimit(block_size, capacity)`.

This method is equivalent to `GetAppendBuffer` if `block_size` is zero.

See the documentation for `CreateWithCustomLimit` for more details on the

restrictions and legal values for `block_size`.

Cord::Prepend()

Prepends data to the Cord, which may come from another Cord or other string

data.

Prepends `buffer` to this cord, unless `buffer` has a zero length in which

case this method has no effect on this cord instance.

This method is guaranteed to consume `buffer`.

Cord::RemovePrefix()

Removes the first `n` bytes of a Cord.

Cord::Subcord()

Returns a new Cord representing the subrange [pos, pos + new_size) of

*this. If pos >= size(), the result is empty(). If

(pos + new_size) >= size(), the result is the subrange [pos, size()).

Cord::swap()

Swaps the contents of the Cord with `other`.

Cord::size()

Returns the size of the Cord.

Cord::empty()

Determines whether the given Cord is empty, returning `true` if so.

Cord::EstimatedMemoryUsage()

Returns the *approximate* number of bytes held by this cord.

See CordMemoryAccounting for more information on the accounting method.

Cord::Compare()

Compares 'this' Cord with rhs. This function and its relatives treat Cords

as sequences of unsigned bytes. The comparison is a straightforward

lexicographic comparison. `Cord::Compare()` returns values as follows:

-1 'this' Cord is smaller

0 two Cords are equal

1 'this' Cord is larger

Cord::StartsWith()

Determines whether the Cord starts with the passed string data `rhs`.

Cord::EndsWith()

Determines whether the Cord ends with the passed string data `rhs`.

Cord::Contains()

Determines whether the Cord contains the passed string data `rhs`.

Cord::operator std::string()

Converts a Cord into a `std::string()`. This operator is marked explicit to

prevent unintended Cord usage in functions that take a string.

Cord::chunk_begin()

Returns an iterator to the first chunk of the `Cord`.

Generally, prefer using `Cord::Chunks()` within a range-based for loop for

iterating over the chunks of a Cord. This method may be useful for getting

a `ChunkIterator` where range-based for-loops are not useful.

Example:

absl::Cord::ChunkIterator FindAsChunk(const absl::Cord

&

c,

absl::string_view s) {

return std::find(c.chunk_begin(), c.chunk_end(), s);

}

Cord::chunk_end()

Returns an iterator one increment past the last chunk of the `Cord`.

Generally, prefer using `Cord::Chunks()` within a range-based for loop for

iterating over the chunks of a Cord. This method may be useful for getting

a `ChunkIterator` where range-based for-loops may not be available.

Cord::Chunks()

Returns a `Cord::ChunkRange` for iterating over the chunks of a `Cord` with

a range-based for-loop. For most iteration tasks on a Cord, use

`Cord::Chunks()` to retrieve this iterator.

Example:

void ProcessChunks(const Cord

&

cord) {

for (absl::string_view chunk : cord.Chunks()) { ... }

}

Note that the ordinary caveats of temporary lifetime extension apply:

void Process() {

for (absl::string_view chunk : CordFactory().Chunks()) {

// The temporary Cord returned by CordFactory has been destroyed!

}

}

Cord::AdvanceAndRead()

Advances the `Cord::CharIterator` by `n_bytes` and returns the bytes

advanced as a separate `Cord`. `n_bytes` must be less than or equal to the

number of bytes within the Cord; otherwise, behavior is undefined. It is

valid to pass `char_end()` and `0`.

Cord::Advance()

Advances the `Cord::CharIterator` by `n_bytes`. `n_bytes` must be less than

or equal to the number of bytes remaining within the Cord; otherwise,

behavior is undefined. It is valid to pass `char_end()` and `0`.

Cord::ChunkRemaining()

Returns the longest contiguous view starting at the iterator's position.

`it` must be dereferenceable.

Cord::char_begin()

Returns an iterator to the first character of the `Cord`.

Generally, prefer using `Cord::Chars()` within a range-based for loop for

iterating over the chunks of a Cord. This method may be useful for getting

a `CharIterator` where range-based for-loops may not be available.

Cord::char_end()

Returns an iterator to one past the last character of the `Cord`.

Generally, prefer using `Cord::Chars()` within a range-based for loop for

iterating over the chunks of a Cord. This method may be useful for getting

a `CharIterator` where range-based for-loops are not useful.

Cord::Chars()

Returns a `Cord::CharRange` for iterating over the characters of a `Cord`

with a range-based for-loop. For most character-based iteration tasks on a

Cord, use `Cord::Chars()` to retrieve this iterator.

Example:

void ProcessCord(const Cord

&

cord) {

for (char c : cord.Chars()) { ... }

}

Note that the ordinary caveats of temporary lifetime extension apply:

void Process() {

for (char c : CordFactory().Chars()) {

// The temporary Cord returned by CordFactory has been destroyed!

}

}

Cord::operator[]

Gets the "i"th character of the Cord and returns it, provided that

0

<

= i

<

Cord.size().

NOTE: This routine is reasonably efficient. It is roughly

logarithmic based on the number of chunks that make up the cord. Still,

if you need to iterate over the contents of a cord, you should

use a CharIterator/ChunkIterator rather than call operator[] or Get()

repeatedly in a loop.

Cord::TryFlat()

If this cord's representation is a single flat array, returns a

string_view referencing that array. Otherwise returns nullopt.

Cord::Flatten()

Flattens the cord into a single array and returns a view of the data.

If the cord was already flat, the contents are not modified.

Cord::Find()

Returns an iterator to the first occurrance of the substring `needle`.

If the substring `needle` does not occur, `Cord::char_end()` is returned.

Cord::SetExpectedChecksum()

Stores a checksum value with this non-empty cord instance, for later

retrieval.

The expected checksum is a number stored out-of-band, alongside the data.

It is preserved across copies and assignments, but any mutations to a cord

will cause it to lose its expected checksum.

The expected checksum is not part of a Cord's value, and does not affect

operations such as equality or hashing.

This field is intended to store a CRC32C checksum for later validation, to

help support end-to-end checksum workflows. However, the Cord API itself

does no CRC validation, and assigns no meaning to this number.

This call has no effect if this cord is empty.

Returns this cord's expected checksum, if it has one. Otherwise, returns

nullopt.

NOLINTNEXTLINE(google-explicit-constructor)