Skip to content

Commit d4021d7

Browse files
committed
docs: remove references to nonexistent cat() buffer-composition function
Four pages cited a `cat()` function that was never part of the public buffer API. The Antora build did not flag these because the references appeared inside `[source,cpp]` blocks (not xrefs), but readers following the examples would hit a compilation error. Fixes: * `5a.overview.adoc` — removed the `Zero-Allocation Composition` section; the conceptual point ("any composition of the above without allocation") is preserved in the bullet list above and in `5c.sequences.adoc`. * `5c.sequences.adoc` — removed the `Zero-Allocation Composition` section; `Heterogeneous Composition` already covers the same idea. * `5e.algorithms.adoc` — rewrote the Zero-Copy I/O example to use `std::array` directly, mirroring the Scatter/Gather example on the same page. * `8c.buffer-composition.adoc` — removed the exercise that referenced `cat()`; the other two exercises remain.
1 parent c82ae26 commit d4021d7

4 files changed

Lines changed: 3 additions & 37 deletions

File tree

doc/modules/ROOT/pages/5.buffers/5a.overview.adoc

Lines changed: 0 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -99,23 +99,6 @@ This single signature accepts:
9999
* A custom composite type
100100
* *Any composition of the above—without allocation*
101101

102-
== Zero-Allocation Composition
103-
104-
With concepts, composition creates views, not copies:
105-
106-
[source,cpp]
107-
----
108-
HeaderBuffers headers = /* ... */;
109-
BodyBuffers body = /* ... */;
110-
111-
// cat() creates a view that iterates both sequences
112-
auto combined = cat(headers, body); // No allocation!
113-
114-
write_data(combined); // Works because combined satisfies ConstBufferSequence
115-
----
116-
117-
The `cat` function returns a lightweight object that, when iterated, first yields buffers from `headers`, then from `body`. The buffers themselves are not copied—only iterators are composed.
118-
119102
== STL Parallel
120103

121104
This design follows Stepanov's insight from the STL: algorithms parameterized on concepts (iterators), not concrete types (containers), enable composition that concrete types forbid.

doc/modules/ROOT/pages/5.buffers/5c.sequences.adoc

Lines changed: 0 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -133,23 +133,6 @@ task<std::size_t> read_all(Stream& stream, Buffers buffers)
133133
* Iteration over unconsumed buffers
134134
* `buffer_size()` of remaining bytes
135135

136-
== Zero-Allocation Composition
137-
138-
The `cat()` function composes buffer sequences without allocation:
139-
140-
[source,cpp]
141-
----
142-
auto headers = std::array{header_buf1, header_buf2};
143-
auto body = body_buffer;
144-
145-
auto combined = cat(headers, body); // No allocation
146-
147-
// combined satisfies ConstBufferSequence
148-
// Iteration yields: header_buf1, header_buf2, body_buffer
149-
----
150-
151-
The returned object stores references (or small copies for single buffers) and iterates through the composed sequence on demand.
152-
153136
== Why Bidirectional?
154137

155138
The concepts require bidirectional ranges (not just forward ranges) for two reasons:

doc/modules/ROOT/pages/5.buffers/5e.algorithms.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -202,7 +202,8 @@ std::string header = build_header();
202202
std::vector<char> body = load_body();
203203
204204
// No copying—header and body are written directly
205-
co_await write(stream, cat(make_buffer(header), make_buffer(body)));
205+
std::array buffers = {make_buffer(header), make_buffer(body)};
206+
co_await write(stream, buffers);
206207
----
207208

208209
=== Scatter/Gather Operations

doc/modules/ROOT/pages/8.examples/8c.buffer-composition.adoc

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -223,8 +223,7 @@ Prepared 2 buffers with 128 bytes total capacity
223223
== Exercises
224224

225225
1. Create a function that takes any `ConstBufferSequence` and prints its contents
226-
2. Measure the difference between copying data into a single buffer vs. using `cat()`
227-
3. Implement a simple message framing protocol using buffer composition
226+
2. Implement a simple message framing protocol using buffer composition
228227

229228
== Next Steps
230229

0 commit comments

Comments
 (0)