helper for single-buffer algorithms

[vinniefalco]

The API of the ReadSource concept in buffers/read_source.hpp has a read function template which accepts any mutable buffer sequence. We should offer a helper free function that models of ReadSource can use to invoke a lambda accepting a buffers::mutable_buffer and system::error_code& and returning the number of bytes read , where the lambda is invoked repeatedly and the helper integrates the results, with special care to handle error::eof. The implementation of any_read_source here https://github.com/cppalliance/buffers/blob/develop/include/boost/buffers/any_buffers.hpp can be used for guidance.

[vinniefalco]

@claude

[claude]

Claude finished @vinniefalco's task —— View job • claude/issue-59-20251129-1831 • Create PR ➔

---

Todo List

• Read and understand the ReadSource concept
• Study the reference implementation in any_buffers.hpp
• Design and implement the helper function
• Add proper documentation
• Add comprehensive tests
• Commit and push changes
• Provide PR creation link

Implementation Summary

I've implemented the read_from_single_buffer() helper function as requested in issue #59.

Location: include/boost/buffers/read_source.hpp:100-177

Key Features:

• Template function accepting any MutableBufferSequence and a callable with signature std::size_t(mutable_buffer, system::error_code&)
• Iterates through the buffer sequence, invoking the lambda for each buffer
• Aggregates the total bytes read across all buffers
• Special EOF handling (following the pattern from any_read_source::read()):
  • If EOF occurs after reading some bytes: returns success with total byte count (does not propagate EOF)
  • If EOF occurs on first call with zero bytes: propagates EOF error
  • This allows partial reads to succeed before EOF
• Skips empty buffers automatically
• Full Javadoc documentation following Boost conventions

Tests Added: test/unit/read_source.cpp:143-255

• Basic functionality test
• EOF on first call
• EOF after partial read
• Empty buffer handling
• Error propagation

Usage Example:

template<class MutableBufferSequence>
std::size_t
my_read_source::read(
    MutableBufferSequence const& buffers,
    system::error_code& ec)
{
    return read_from_single_buffer(buffers, ec,
        [this](mutable_buffer mb, system::error_code& ec_) -> std::size_t
        {
            // Read into single buffer mb
            // Return bytes read, set ec_ on error
        });
}

--- | Branch