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;

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

{

{

    unsigned char* p_ = nullptr;

    unsigned char* p_ = nullptr;

    std::size_t n_ = 0;

    std::size_t n_ = 0;

public:

public:

    /// Construct an empty buffer.

    /// Construct an empty buffer.

    /// Construct a copy.

    /// Construct a copy.

    mutable_buffer(

    mutable_buffer(

        mutable_buffer const&) = default;

        mutable_buffer const&) = default;

    /// Assign by copying.

    /// Assign by copying.

    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

    {

    {

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

{

{

    unsigned char const* p_ = nullptr;

    unsigned char const* p_ = nullptr;

    std::size_t n_ = 0;

    std::size_t n_ = 0;

public:

public:

    /// Construct an empty buffer.

    /// Construct an empty buffer.

    /// Construct a copy.

    /// Construct a copy.

    const_buffer(const_buffer const&) = default;

    const_buffer(const_buffer const&) = default;

    /// Assign by copying.

    /// Assign by copying.

    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

    {

    {

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