Diff coverage report for

//

//

// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)

// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)

//

//

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// 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)

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

//

//

// Official repository: https://github.com/cppalliance/capy

// Official repository: https://github.com/cppalliance/capy

//

//

#ifndef BOOST_CAPY_BUFFERS_HPP

#ifndef BOOST_CAPY_BUFFERS_HPP

#define BOOST_CAPY_BUFFERS_HPP

#define BOOST_CAPY_BUFFERS_HPP

#include <boost/capy/detail/config.hpp>

#include <boost/capy/detail/config.hpp>

#include <concepts>

#include <concepts>

#include <cstddef>

#include <cstddef>

#include <iterator>

#include <iterator>

#include <memory>

#include <memory>

#include <ranges>

#include <ranges>

#include <type_traits>

#include <type_traits>

// https://www.boost.org/doc/libs/1_65_0/doc/html/boost_asio/reference/ConstBufferSequence.html

// https://www.boost.org/doc/libs/1_65_0/doc/html/boost_asio/reference/ConstBufferSequence.html

namespace boost {

namespace boost {

namespace asio {

namespace asio {

class const_buffer;

class const_buffer;

class mutable_buffer;

class mutable_buffer;

} // asio

} // asio

namespace capy {

namespace capy {

class const_buffer;

class const_buffer;

class mutable_buffer;

class mutable_buffer;

namespace detail {

namespace detail {

// satisfies Asio's buffer constructors, CANNOT be removed!

// satisfies Asio's buffer constructors, CANNOT be removed!

template<class T, std::size_t Extent = (std::size_t)(-1)>

template<class T, std::size_t Extent = (std::size_t)(-1)>

class basic_buffer

class basic_buffer

{

{

    constexpr auto data() const noexcept ->

    constexpr auto data() const noexcept ->

        std::conditional_t<std::is_const_v<T>, void const*, void*>

        std::conditional_t<std::is_const_v<T>, void const*, void*>

    {

    {

        return p_;

        return p_;

    }

    }

    constexpr std::size_t size() const noexcept

    constexpr std::size_t size() const noexcept

    {

    {

        return n_;

        return n_;

    }

    }

    friend class capy::const_buffer;

    friend class capy::const_buffer;

    friend class capy::mutable_buffer;

    friend class capy::mutable_buffer;

    friend class asio::const_buffer;

    friend class asio::const_buffer;

    friend class asio::mutable_buffer;

    friend class asio::mutable_buffer;

    constexpr basic_buffer<T, (std::size_t)(-1)> subspan(

    constexpr basic_buffer<T, (std::size_t)(-1)> subspan(

        std::size_t, std::size_t = (std::size_t)(-1)) const noexcept;

        std::size_t, std::size_t = (std::size_t)(-1)) const noexcept;

    T* p_ = nullptr;

    T* p_ = nullptr;

    std::size_t n_ = 0;

    std::size_t n_ = 0;

};

};

} // detail

} // detail

//------------------------------------------------

//------------------------------------------------

/// Tag type for customizing `buffer_size` via `tag_invoke`.

/// Tag type for customizing `buffer_size` via `tag_invoke`.

struct size_tag {};

struct size_tag {};

/// Tag type for customizing slice operations via `tag_invoke`.

/// Tag type for customizing slice operations via `tag_invoke`.

struct slice_tag {};

struct slice_tag {};

/** Constants for slice customization.

/** Constants for slice customization.

    Passed to `tag_invoke` overloads to specify which portion

    Passed to `tag_invoke` overloads to specify which portion

    of a buffer sequence to retain.

    of a buffer sequence to retain.

*/

*/

enum class slice_how

enum class slice_how

{

{

    /// Remove bytes from the front of the sequence.

    /// Remove bytes from the front of the sequence.

    remove_prefix,

    remove_prefix,

    /// Keep only the first N bytes.

    /// Keep only the first N bytes.

    keep_prefix

    keep_prefix

};

};

//------------------------------------------------

//------------------------------------------------

/** A reference to a contiguous region of writable memory.

/** A reference to a contiguous region of writable memory.

    Represents a pointer and size pair for a modifiable byte range.

    Represents a pointer and size pair for a modifiable byte range.

    Does not own the memory. Satisfies `MutableBufferSequence` (as a

    Does not own the memory. Satisfies `MutableBufferSequence` (as a

    single-element sequence) and is implicitly convertible to

    single-element sequence) and is implicitly convertible to

    `const_buffer`.

    `const_buffer`.

    @see const_buffer, MutableBufferSequence

    @see const_buffer, MutableBufferSequence

*/

*/

class mutable_buffer

class mutable_buffer

    : public detail::basic_buffer<unsigned char>

    : public detail::basic_buffer<unsigned char>

{

{

public:

public:

    /// Construct an empty buffer.

    /// Construct an empty buffer.

    /// Copy constructor.

    /// Copy constructor.

    mutable_buffer(

    mutable_buffer(

        mutable_buffer const&) = default;

        mutable_buffer const&) = default;

    /// Copy assignment.

    /// Copy assignment.

    mutable_buffer& operator=(

    mutable_buffer& operator=(

        mutable_buffer const&) = default;

        mutable_buffer const&) = default;

    /// Construct from pointer and size.

    /// Construct from pointer and size.

        void* data, std::size_t size) noexcept

        void* data, std::size_t size) noexcept

    {

    {

    /// Construct from Asio mutable_buffer.

    /// Construct from Asio mutable_buffer.

    template<class MutableBuffer>

    template<class MutableBuffer>

        requires std::same_as<MutableBuffer, asio::mutable_buffer>

        requires std::same_as<MutableBuffer, asio::mutable_buffer>

    constexpr mutable_buffer(

    constexpr mutable_buffer(

        MutableBuffer const& b) noexcept

        MutableBuffer const& b) noexcept

        : basic_buffer<unsigned char>(

        : basic_buffer<unsigned char>(

            static_cast<unsigned char*>(

            static_cast<unsigned char*>(

                b.data()), b.size())

                b.data()), b.size())

    {

    {

    }

    }

    /// Return a pointer to the memory region.

    /// Return a pointer to the memory region.

    {

    {

    }

    }

    /// Return the size in bytes.

    /// Return the size in bytes.

    {

    {

    }

    }

    /** Advance the buffer start, shrinking the region.

    /** Advance the buffer start, shrinking the region.

        @param n Bytes to skip. Clamped to `size()`.

        @param n Bytes to skip. Clamped to `size()`.

    */

    */

    mutable_buffer&

    mutable_buffer&

    {

    {

    }

    }

    /// Slice customization point for `tag_invoke`.

    /// Slice customization point for `tag_invoke`.

    friend

    friend

    void

    void

        slice_tag const&,

        slice_tag const&,

        mutable_buffer& b,

        mutable_buffer& b,

        slice_how how,

        slice_how how,

        std::size_t n) noexcept

        std::size_t n) noexcept

    {

    {

private:

private:

        slice_how how, std::size_t n) noexcept

        slice_how how, std::size_t n) noexcept

    {

    {

        {

        {

        }

        }

    }

    }

};

};

//------------------------------------------------

//------------------------------------------------

/** A reference to a contiguous region of read-only memory.

/** A reference to a contiguous region of read-only memory.

    Represents a pointer and size pair for a non-modifiable byte range.

    Represents a pointer and size pair for a non-modifiable byte range.

    Does not own the memory. Satisfies `ConstBufferSequence` (as a

    Does not own the memory. Satisfies `ConstBufferSequence` (as a

    single-element sequence). Implicitly constructible from

    single-element sequence). Implicitly constructible from

    `mutable_buffer`.

    `mutable_buffer`.

    @see mutable_buffer, ConstBufferSequence

    @see mutable_buffer, ConstBufferSequence

*/

*/

class const_buffer

class const_buffer

    : public detail::basic_buffer<unsigned char const>

    : public detail::basic_buffer<unsigned char const>

{

{

public:

public:

    /// Construct an empty buffer.

    /// Construct an empty buffer.

    /// Copy constructor.

    /// Copy constructor.

    const_buffer(const_buffer const&) = default;

    const_buffer(const_buffer const&) = default;

    /// Copy assignment.

    /// Copy assignment.

    const_buffer& operator=(

    const_buffer& operator=(

        const_buffer const& other) = default;

        const_buffer const& other) = default;

    /// Construct from pointer and size.

    /// Construct from pointer and size.

        void const* data, std::size_t size) noexcept

        void const* data, std::size_t size) noexcept

    {

    {

    /// Construct from mutable_buffer.

    /// Construct from mutable_buffer.

        mutable_buffer const& b) noexcept

        mutable_buffer const& b) noexcept

    {

    {

    /// Construct from Asio buffer types.

    /// Construct from Asio buffer types.

    template<class ConstBuffer>

    template<class ConstBuffer>

        requires (std::same_as<ConstBuffer, asio::const_buffer> ||

        requires (std::same_as<ConstBuffer, asio::const_buffer> ||

                  std::same_as<ConstBuffer, asio::mutable_buffer>)

                  std::same_as<ConstBuffer, asio::mutable_buffer>)

    constexpr const_buffer(

    constexpr const_buffer(

        ConstBuffer const& b) noexcept

        ConstBuffer const& b) noexcept

        : basic_buffer<unsigned char const>(

        : basic_buffer<unsigned char const>(

            static_cast<unsigned char const*>(

            static_cast<unsigned char const*>(

                b.data()), b.size())

                b.data()), b.size())

    {

    {

    }

    }

    /// Return a pointer to the memory region.

    /// Return a pointer to the memory region.

    {

    {

    }

    }

    /// Return the size in bytes.

    /// Return the size in bytes.

    {

    {

    }

    }

    /** Advance the buffer start, shrinking the region.

    /** Advance the buffer start, shrinking the region.

        @param n Bytes to skip. Clamped to `size()`.

        @param n Bytes to skip. Clamped to `size()`.

    */

    */

    const_buffer&

    const_buffer&

    {

    {

    }

    }

    /// Slice customization point for `tag_invoke`.

    /// Slice customization point for `tag_invoke`.

    friend

    friend

    void

    void

        slice_tag const&,

        slice_tag const&,

        const_buffer& b,

        const_buffer& b,

        slice_how how,

        slice_how how,

        std::size_t n) noexcept

        std::size_t n) noexcept

    {

    {

private:

private:

        slice_how how, std::size_t n) noexcept

        slice_how how, std::size_t n) noexcept

    {

    {

        {

        {

        }

        }

    }

    }

};

};

//------------------------------------------------

//------------------------------------------------

/** Concept for sequences of read-only buffer regions.

/** Concept for sequences of read-only buffer regions.

    A type satisfies `ConstBufferSequence` if it represents one or more

    A type satisfies `ConstBufferSequence` if it represents one or more

    contiguous memory regions that can be read. This includes single

    contiguous memory regions that can be read. This includes single

    buffers (convertible to `const_buffer`) and ranges of buffers.

    buffers (convertible to `const_buffer`) and ranges of buffers.

    @par Syntactic Requirements

    @par Syntactic Requirements

    @li Convertible to `const_buffer`, OR

    @li Convertible to `const_buffer`, OR

    @li A bidirectional range with value type convertible to `const_buffer`

    @li A bidirectional range with value type convertible to `const_buffer`

    @see const_buffer, MutableBufferSequence

    @see const_buffer, MutableBufferSequence

*/

*/

template<typename T>

template<typename T>

concept ConstBufferSequence =

concept ConstBufferSequence =

    std::is_convertible_v<T, const_buffer> || (

    std::is_convertible_v<T, const_buffer> || (

        std::ranges::bidirectional_range<T> &&

        std::ranges::bidirectional_range<T> &&

        std::is_convertible_v<std::ranges::range_value_t<T>, const_buffer>);

        std::is_convertible_v<std::ranges::range_value_t<T>, const_buffer>);

/** Concept for sequences of writable buffer regions.

/** Concept for sequences of writable buffer regions.

    A type satisfies `MutableBufferSequence` if it represents one or more

    A type satisfies `MutableBufferSequence` if it represents one or more

    contiguous memory regions that can be written. This includes single

    contiguous memory regions that can be written. This includes single

    buffers (convertible to `mutable_buffer`) and ranges of buffers.

    buffers (convertible to `mutable_buffer`) and ranges of buffers.

    Every `MutableBufferSequence` also satisfies `ConstBufferSequence`.

    Every `MutableBufferSequence` also satisfies `ConstBufferSequence`.

    @par Syntactic Requirements

    @par Syntactic Requirements

    @li Convertible to `mutable_buffer`, OR

    @li Convertible to `mutable_buffer`, OR

    @li A bidirectional range with value type convertible to `mutable_buffer`

    @li A bidirectional range with value type convertible to `mutable_buffer`

    @see mutable_buffer, ConstBufferSequence

    @see mutable_buffer, ConstBufferSequence

*/

*/

template<typename T>

template<typename T>

concept MutableBufferSequence =

concept MutableBufferSequence =

    std::is_convertible_v<T, mutable_buffer> || (

    std::is_convertible_v<T, mutable_buffer> || (

        std::ranges::bidirectional_range<T> &&

        std::ranges::bidirectional_range<T> &&

        std::is_convertible_v<std::ranges::range_value_t<T>, mutable_buffer>);

        std::is_convertible_v<std::ranges::range_value_t<T>, mutable_buffer>);

//------------------------------------------------------------------------------

//------------------------------------------------------------------------------

/** Return an iterator to the first buffer in a sequence.

/** Return an iterator to the first buffer in a sequence.

    Handles single buffers and ranges uniformly. For a single buffer,

    Handles single buffers and ranges uniformly. For a single buffer,

    returns a pointer to it (forming a one-element range).

    returns a pointer to it (forming a one-element range).

*/

*/

constexpr struct begin_mrdocs_workaround_t

constexpr struct begin_mrdocs_workaround_t

{

{

    template<std::convertible_to<const_buffer> ConvertibleToBuffer>

    template<std::convertible_to<const_buffer> ConvertibleToBuffer>

    {

    {

    }

    }

    template<ConstBufferSequence BS>

    template<ConstBufferSequence BS>

        requires (!std::convertible_to<BS, const_buffer>)

        requires (!std::convertible_to<BS, const_buffer>)

    {

    {

    }

    }

    template<ConstBufferSequence BS>

    template<ConstBufferSequence BS>

        requires (!std::convertible_to<BS, const_buffer>)

        requires (!std::convertible_to<BS, const_buffer>)

    {

    {

    }

    }

} begin {};

} begin {};

/** Return an iterator past the last buffer in a sequence.

/** Return an iterator past the last buffer in a sequence.

    Handles single buffers and ranges uniformly. For a single buffer,

    Handles single buffers and ranges uniformly. For a single buffer,

    returns a pointer one past it.

    returns a pointer one past it.

*/

*/

constexpr struct end_mrdocs_workaround_t

constexpr struct end_mrdocs_workaround_t

{

{

    template<std::convertible_to<const_buffer> ConvertibleToBuffer>

    template<std::convertible_to<const_buffer> ConvertibleToBuffer>

    {

    {

    }

    }

    template<ConstBufferSequence BS>

    template<ConstBufferSequence BS>

        requires (!std::convertible_to<BS, const_buffer>)

        requires (!std::convertible_to<BS, const_buffer>)

    {

    {

    }

    }

    template<ConstBufferSequence BS>

    template<ConstBufferSequence BS>

        requires (!std::convertible_to<BS, const_buffer>)

        requires (!std::convertible_to<BS, const_buffer>)

    {

    {

    }

    }

} end {};

} end {};

//------------------------------------------------------------------------------

//------------------------------------------------------------------------------

template<ConstBufferSequence CB>

template<ConstBufferSequence CB>

std::size_t

std::size_t

    size_tag const&,

    size_tag const&,

    CB const& bs) noexcept

    CB const& bs) noexcept

{

{

}

}

//------------------------------------------------------------------------------

//------------------------------------------------------------------------------

/** Return the total byte count across all buffers in a sequence.

/** Return the total byte count across all buffers in a sequence.

    Sums the `size()` of each buffer in the sequence. This differs

    Sums the `size()` of each buffer in the sequence. This differs

    from `buffer_length` which counts the number of buffer elements.

    from `buffer_length` which counts the number of buffer elements.

    @par Example

    @par Example

    @code

    @code

    std::array<mutable_buffer, 2> bufs = { ... };

    std::array<mutable_buffer, 2> bufs = { ... };

    std::size_t total = buffer_size( bufs );  // sum of both sizes

    std::size_t total = buffer_size( bufs );  // sum of both sizes

    @endcode

    @endcode

*/

*/

constexpr struct buffer_size_mrdocs_workaround_t

constexpr struct buffer_size_mrdocs_workaround_t

{

{

    template<ConstBufferSequence CB>

    template<ConstBufferSequence CB>

        CB const& bs) const noexcept

        CB const& bs) const noexcept

    {

    {

    }

    }

} buffer_size {};

} buffer_size {};

/** Check if a buffer sequence contains no data.

/** Check if a buffer sequence contains no data.

    @return `true` if all buffers have size zero or the sequence

    @return `true` if all buffers have size zero or the sequence

        is empty.

        is empty.

*/

*/

constexpr struct buffer_empty_mrdocs_workaround_t

constexpr struct buffer_empty_mrdocs_workaround_t

{

{

    template<ConstBufferSequence CB>

    template<ConstBufferSequence CB>

        CB const& bs) const noexcept

        CB const& bs) const noexcept

    {

    {

        {

        {

        }

        }

    }

    }

} buffer_empty {};

} buffer_empty {};

//-----------------------------------------------

//-----------------------------------------------

namespace detail {

namespace detail {

template<class It>

template<class It>

auto

auto

    -> decltype(static_cast<std::size_t>(last - first))

    -> decltype(static_cast<std::size_t>(last - first))

{

{

}

}

template<class It>

template<class It>

std::size_t

std::size_t

length_impl(It first, It last, long)

length_impl(It first, It last, long)

{

{

    std::size_t n = 0;

    std::size_t n = 0;

    while(first != last)

    while(first != last)

    {

    {

        ++first;

        ++first;

        ++n;

        ++n;

    }

    }

    return n;

    return n;

}

}

} // detail

} // detail

/** Return the number of buffer elements in a sequence.

/** Return the number of buffer elements in a sequence.

    Counts the number of individual buffer objects, not bytes.

    Counts the number of individual buffer objects, not bytes.

    For a single buffer, returns 1. For a range, returns the

    For a single buffer, returns 1. For a range, returns the

    distance from `begin` to `end`.

    distance from `begin` to `end`.

    @see buffer_size

    @see buffer_size

*/

*/

template<ConstBufferSequence CB>

template<ConstBufferSequence CB>

std::size_t

std::size_t

{

{

}

}

/// Alias for `mutable_buffer` or `const_buffer` based on sequence type.

/// Alias for `mutable_buffer` or `const_buffer` based on sequence type.

template<typename BS>

template<typename BS>

using buffer_type = std::conditional_t<

using buffer_type = std::conditional_t<

    MutableBufferSequence<BS>,

    MutableBufferSequence<BS>,

    mutable_buffer, const_buffer>;

    mutable_buffer, const_buffer>;

} // capy

} // capy

} // boost

} // boost

#endif

#endif