work

doc/modules/ROOT/nav.adoc

@@ -1,9 +1,11 @@
-* xref:1.intro.adoc[]
-* xref:2.algorithms.adoc[]
-* xref:3.dynamic-buffers.adoc[]
-* xref:4.custom-sequences.adoc[]
+* xref:intro.adoc[]
+* xref:algorithms.adoc[]
+* xref:dynamic-buffers.adoc[]
+* xref:custom-sequences.adoc[]
 * Concepts
-** xref:5.1.ConstBufferSequence.adoc[]
-** xref:5.2.MutableBufferSequence.adoc[]
-** xref:5.3.DynamicBuffer.adoc[]
+** xref:ConstBufferSequence.adoc[]
+** xref:MutableBufferSequence.adoc[]
+** xref:DynamicBuffer.adoc[]
+** xref:ReadSource.adoc[]
+** xref:DataSource.adoc[]
 * xref:reference:boost/buffers.adoc[Reference]

doc/modules/ROOT/pages/5.1.ConstBufferSequence.adoc → doc/modules/ROOT/pages/ConstBufferSequence.adoc

@@ -55,3 +55,4 @@ assert( std::equal(
 * cpp:mutable_buffer_1[]
 * cpp:mutable_buffer_pair[]
 * cpp:slice_of[]
+

doc/modules/ROOT/pages/DataSource.adoc

@@ -0,0 +1,100 @@
+//
+// Copyright (c) 2025 Vinnie Falco (vinnie dot falco at gmail dot com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+// Official repository: https://github.com/cppalliance/buffers
+//
+
+= DataSource
+
+A __DataSource__ represents a source of data that is available as a constant
+buffer sequence in memory. Unlike a xref:ReadSource.adoc[_ReadSource_],
+which provides data through a streaming `read` interface, a data source
+exposes its entire contents directly through a `data()` member function.
+
+Data sources are useful for representing objects whose binary representation
+is already available in memory and can be accessed without copying, such as
+strings, byte arrays, or memory-mapped files.
+
+== Related Identifiers
+
+cpp:is_data_source[]
+
+== Requirements
+
+* `D` denotes a data source class.
+* `c` denotes a (possibly const) value of type `D`.
+* `T` denotes a type meeting the requirements for xref:ConstBufferSequence.adoc[_ConstBufferSequence_].
+
+[cols="1a,1a,5a"]
+|===
+// Headers
+|Expression|Type|Semantics, Pre/Post-conditions
+
+|`D(D&&)`
+|
+|Data sources must be nothrow move constructible.
+
+|`c.data()`
+|`T`
+|Returns a constant buffer sequence representing the data. This function must
+be `noexcept`. The returned buffer sequence remains valid for at least as long
+as the data source object exists and is not modified.
+
+|===
+
+== Example
+
+[source,cpp]
+----
+struct my_data_source
+{
+    std::string data_;
+
+    explicit my_data_source(std::string s) noexcept
+        : data_(std::move(s))
+    {
+    }
+
+    // Move constructor required
+    my_data_source(my_data_source&&) noexcept = default;
+
+    const_buffer data() const noexcept
+    {
+        return const_buffer(data_.data(), data_.size());
+    }
+};
+
+static_assert(is_data_source<my_data_source>::value, "");
+----
+
+== Comparison with ReadSource
+
+|===
+|Feature|DataSource|ReadSource
+
+|Data access
+|Direct via `data()` returning buffer sequence
+|Streaming via `read()` into caller-provided buffers
+
+|Memory
+|Data must be in memory
+|Data can be generated or streamed
+
+|Multiple reads
+|Implicit (buffer sequence can be iterated multiple times)
+|Requires `rewind()` if available
+
+|Size
+|Implicit (via `buffers::size(data())`)
+|Optional `size()` member
+
+|===
+
+== See Also
+
+* cpp:any_source[] - a type-erased wrapper that can hold either a _DataSource_ or _ReadSource_
+* xref:ReadSource.adoc[_ReadSource_] - a streaming data source concept
+

doc/modules/ROOT/pages/5.3.DynamicBuffer.adoc → doc/modules/ROOT/pages/DynamicBuffer.adoc

@@ -28,8 +28,8 @@ cpp:is_dynamic_buffer[]
 * `a` denotes a value of type `D`.
 * `c` denotes a (possibly const) value of type `D`.
 * `n` denotes a value of type `std::size_t`.
-* `T` denotes a type meeting the requirements for xref:./5.1.ConstBufferSequence.adoc[_ConstBufferSequence_].
-* `U` denotes a type meeting the requirements for xref:./5.2.MutableBufferSequence.adoc[_MutableBufferSequence_].
+* `T` denotes a type meeting the requirements for xref:ConstBufferSequence.adoc[_ConstBufferSequence_].
+* `U` denotes a type meeting the requirements for xref:MutableBufferSequence.adoc[_MutableBufferSequence_].
 
 [cols="1a,1a,5a"]
 |===
@@ -95,3 +95,4 @@ constant or mutable buffer sequences previously obtained using `data()` or
 * `circular_buffer`
 * `flat_buffer`
 * `string_buffer`
+

doc/modules/ROOT/pages/5.2.MutableBufferSequence.adoc → doc/modules/ROOT/pages/MutableBufferSequence.adoc

@@ -53,3 +53,4 @@ assert( std::equal(
 * cpp:mutable_buffer_1[]
 * cpp:mutable_buffer_pair[]
 * cpp:slice_of[]
+

doc/modules/ROOT/pages/ReadSource.adoc

@@ -0,0 +1,110 @@
+//
+// Copyright (c) 2025 Vinnie Falco (vinnie dot falco at gmail dot com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+// Official repository: https://github.com/cppalliance/buffers
+//
+
+= ReadSource
+
+A __ReadSource__ represents a source of data that can be read into caller-provided
+buffers. Data is obtained by calling the `read` member function one or more times,
+until it sets cpp:error::eof[] in the error code to indicate no more data is
+available.
+
+Read sources are useful for representing streaming data sources where the complete
+data may not be available in memory, such as file streams or generated data.
+
+== Related Identifiers
+
+cpp:is_read_source[], cpp:has_size[], cpp:has_rewind[]
+
+== Requirements
+
+* `S` denotes a read source class.
+* `s` denotes a value of type `S`.
+* `c` denotes a (possibly const) value of type `S`.
+* `ec` denotes a value of type `system::error_code&`.
+* `M` denotes a type meeting the requirements for xref:MutableBufferSequence.adoc[_MutableBufferSequence_].
+* `m` denotes a value of type `M const&`.
+
+[cols="1a,1a,5a"]
+|===
+// Headers
+|Expression|Type|Semantics, Pre/Post-conditions
+
+|`s.read(m, ec)`
+|`std::size_t`
+|Reads data from the source into the mutable buffer sequence `m`. Returns the
+number of bytes written to the buffers. When no more data is available,
+cpp:error::eof[] is set in `ec`. On success, `ec` is cleared.
+
+|`c.size()` (optional)
+|`std::uint64_t`
+|Returns the total size, in bytes, of the data that can be read from the source.
+This member is optional. The metafunction cpp:has_size[] may be used to detect
+its availability.
+
+|`s.rewind()` (optional)
+|
+|Resets the source to its initial state, allowing the data to be read again from
+the beginning. This member is optional. The metafunction cpp:has_rewind[] may be
+used to detect its availability.
+
+|===
+
+== Example
+
+[source,cpp]
+----
+struct my_read_source
+{
+    std::string data_;
+    std::size_t pos_ = 0;
+
+    explicit my_read_source(std::string s)
+        : data_(std::move(s))
+    {
+    }
+
+    std::uint64_t size() const noexcept
+    {
+        return data_.size();
+    }
+
+    void rewind()
+    {
+        pos_ = 0;
+    }
+
+    template<class MutableBufferSequence>
+    std::size_t read(
+        MutableBufferSequence const& buffers,
+        system::error_code& ec)
+    {
+        std::size_t n = buffers::copy(
+            buffers,
+            const_buffer(
+                data_.data() + pos_,
+                data_.size() - pos_));
+        pos_ += n;
+        if(pos_ >= data_.size())
+            ec = error::eof;
+        else
+            ec = {};
+        return n;
+    }
+};
+
+static_assert(is_read_source<my_read_source>::value, "");
+static_assert(has_size<my_read_source>::value, "");
+static_assert(has_rewind<my_read_source>::value, "");
+----
+
+== See Also
+
+* cpp:any_source[] - a type-erased wrapper that can hold either a _ReadSource_ or _DataSource_
+* xref:DataSource.adoc[_DataSource_] - a concept for in-memory data sources
+

doc/modules/ROOT/pages/2.algorithms.adoc → doc/modules/ROOT/pages/algorithms.adoc

@@ -86,3 +86,4 @@ copy(
 This function copies up to `at_most` bytes from the source buffer sequence to
 the destination sequence, or less depending on the size of the smaller of the
 two sequences. The return value indicates the actual number of bytes copied.
+

doc/modules/ROOT/pages/5.asio-buffers.adoc → doc/modules/ROOT/pages/asio-buffers.adoc

@@ -26,3 +26,4 @@ https://github.com/cppalliance/http_proto[Boost.WS.Proto] (proposed) libraries.
 
 * 
 
+

doc/modules/ROOT/pages/4.custom-sequences.adoc → doc/modules/ROOT/pages/custom-sequences.adoc

@@ -84,3 +84,4 @@ tag_invoke(
 |===
 
 \[1\] https://www.youtube.com/watch?v=POa_V15je8Y[Making New Friends (CppCon 2018)]
+

doc/modules/ROOT/pages/3.dynamic-buffers.adoc → doc/modules/ROOT/pages/dynamic-buffers.adoc

@@ -28,3 +28,4 @@ which may be automatically sized as required.
 * The input sequence is returned by calling `data()`
 
 * The input sequence is released by calling `consume(n)`
+

doc/modules/ROOT/pages/1.intro.adoc → doc/modules/ROOT/pages/intro.adoc

@@ -80,8 +80,8 @@ There are some caveats with this approach:
 
 The approach taken by this library is the same as the approach used in the popular
 Boost.Asio network library. That is, to define the concepts
-xref:5.1.ConstBufferSequence.adoc[_ConstBufferSequence_] and
-xref:5.2.MutableBufferSequence.adoc[_MutableBufferSequence_] for
+xref:ConstBufferSequence.adoc[_ConstBufferSequence_] and
+xref:MutableBufferSequence.adoc[_MutableBufferSequence_] for
 representing buffer sequences with these semantics:
 
 * A buffer sequence is cheap to copy.
@@ -111,3 +111,4 @@ frequency that the library provides a custom implementation for representing
 them. Objects of types cpp:const_buffer_pair[] and cpp:mutable_buffer_pair[] are
 buffer sequences of length two. These are the type of sequences returned by
 the cpp:circular_buffer[], discussed later.
+