diff --git a/doc/modules/ROOT/nav.adoc b/doc/modules/ROOT/nav.adoc index 6f7562ca..29e2e5f2 100644 --- a/doc/modules/ROOT/nav.adoc +++ b/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] diff --git a/doc/modules/ROOT/pages/5.1.ConstBufferSequence.adoc b/doc/modules/ROOT/pages/ConstBufferSequence.adoc similarity index 99% rename from doc/modules/ROOT/pages/5.1.ConstBufferSequence.adoc rename to doc/modules/ROOT/pages/ConstBufferSequence.adoc index b741c423..0a9a3400 100644 --- a/doc/modules/ROOT/pages/5.1.ConstBufferSequence.adoc +++ b/doc/modules/ROOT/pages/ConstBufferSequence.adoc @@ -55,3 +55,4 @@ assert( std::equal( * cpp:mutable_buffer_1[] * cpp:mutable_buffer_pair[] * cpp:slice_of[] + diff --git a/doc/modules/ROOT/pages/DataSource.adoc b/doc/modules/ROOT/pages/DataSource.adoc new file mode 100644 index 00000000..2483edf2 --- /dev/null +++ b/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::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 + diff --git a/doc/modules/ROOT/pages/5.3.DynamicBuffer.adoc b/doc/modules/ROOT/pages/DynamicBuffer.adoc similarity index 93% rename from doc/modules/ROOT/pages/5.3.DynamicBuffer.adoc rename to doc/modules/ROOT/pages/DynamicBuffer.adoc index eaad2202..73f6ea5c 100644 --- a/doc/modules/ROOT/pages/5.3.DynamicBuffer.adoc +++ b/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` + diff --git a/doc/modules/ROOT/pages/5.2.MutableBufferSequence.adoc b/doc/modules/ROOT/pages/MutableBufferSequence.adoc similarity index 99% rename from doc/modules/ROOT/pages/5.2.MutableBufferSequence.adoc rename to doc/modules/ROOT/pages/MutableBufferSequence.adoc index 859d8a0b..b288b9b9 100644 --- a/doc/modules/ROOT/pages/5.2.MutableBufferSequence.adoc +++ b/doc/modules/ROOT/pages/MutableBufferSequence.adoc @@ -53,3 +53,4 @@ assert( std::equal( * cpp:mutable_buffer_1[] * cpp:mutable_buffer_pair[] * cpp:slice_of[] + diff --git a/doc/modules/ROOT/pages/ReadSource.adoc b/doc/modules/ROOT/pages/ReadSource.adoc new file mode 100644 index 00000000..d0acf635 --- /dev/null +++ b/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 + 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::value, ""); +static_assert(has_size::value, ""); +static_assert(has_rewind::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 + diff --git a/doc/modules/ROOT/pages/2.algorithms.adoc b/doc/modules/ROOT/pages/algorithms.adoc similarity index 99% rename from doc/modules/ROOT/pages/2.algorithms.adoc rename to doc/modules/ROOT/pages/algorithms.adoc index 8727cfb0..943b5d7d 100644 --- a/doc/modules/ROOT/pages/2.algorithms.adoc +++ b/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. + diff --git a/doc/modules/ROOT/pages/5.asio-buffers.adoc b/doc/modules/ROOT/pages/asio-buffers.adoc similarity index 99% rename from doc/modules/ROOT/pages/5.asio-buffers.adoc rename to doc/modules/ROOT/pages/asio-buffers.adoc index 4041f1e6..7ffe6316 100644 --- a/doc/modules/ROOT/pages/5.asio-buffers.adoc +++ b/doc/modules/ROOT/pages/asio-buffers.adoc @@ -26,3 +26,4 @@ https://github.com/cppalliance/http_proto[Boost.WS.Proto] (proposed) libraries. * + diff --git a/doc/modules/ROOT/pages/4.custom-sequences.adoc b/doc/modules/ROOT/pages/custom-sequences.adoc similarity index 99% rename from doc/modules/ROOT/pages/4.custom-sequences.adoc rename to doc/modules/ROOT/pages/custom-sequences.adoc index da392c1c..2b544a9a 100644 --- a/doc/modules/ROOT/pages/4.custom-sequences.adoc +++ b/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)] + diff --git a/doc/modules/ROOT/pages/3.dynamic-buffers.adoc b/doc/modules/ROOT/pages/dynamic-buffers.adoc similarity index 99% rename from doc/modules/ROOT/pages/3.dynamic-buffers.adoc rename to doc/modules/ROOT/pages/dynamic-buffers.adoc index 1f6d9ffd..d713185c 100644 --- a/doc/modules/ROOT/pages/3.dynamic-buffers.adoc +++ b/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)` + diff --git a/doc/modules/ROOT/pages/1.intro.adoc b/doc/modules/ROOT/pages/intro.adoc similarity index 97% rename from doc/modules/ROOT/pages/1.intro.adoc rename to doc/modules/ROOT/pages/intro.adoc index 02c19be3..25861afc 100644 --- a/doc/modules/ROOT/pages/1.intro.adoc +++ b/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. +