Add buffer_front

CHANGELOG.md

@@ -1,6 +1,7 @@
 Version 83:
 
 * Add flat_static_buffer::mutable_data
+* Add buffer_front
 
 --------------------------------------------------------------------------------
 

doc/qbk/03_core/3_buffers.qbk

@@ -118,6 +118,12 @@ transferred.
     two or more buffer sequences. This is type of object returned by
     [link beast.ref.beast__buffer_cat `buffer_cat`].
 ]]
+[[
+    [link beast.ref.beast__buffer_front `buffer_front`]
+][
+    This function returns the first buffer in a buffer sequence,
+    or a buffer of size zero if the buffer sequence has no elements.
+]]
 [[
     [link beast.ref.beast__buffer_prefix `buffer_prefix`]
 ][

doc/qbk/quickref.xml

@@ -215,6 +215,7 @@
           <simplelist type="vert" columns="1">
             <member><link linkend="beast.ref.beast__bind_handler">bind_handler</link></member>
             <member><link linkend="beast.ref.beast__buffer_cat">buffer_cat</link></member>
+            <member><link linkend="beast.ref.beast__buffer_front">buffer_front</link></member>
             <member><link linkend="beast.ref.beast__buffer_prefix">buffer_prefix</link></member>
             <member><link linkend="beast.ref.beast__buffers">buffers</link></member>
             <member><link linkend="beast.ref.beast__generic_category">generic_category</link></member>

include/beast/core/buffer_prefix.hpp

@@ -206,6 +206,29 @@ buffer_prefix(std::size_t size, BufferSequence const& buffers)
     return buffer_prefix_view<BufferSequence>(size, buffers);
 }
 
+/** Returns the first buffer in a buffer sequence
+
+    This returns the first buffer in the buffer sequence.
+    If the buffer sequence is an empty range, the returned
+    buffer will have a zero buffer size.
+
+    @param buffers The buffer sequence. If the sequence is
+    mutable, the returned buffer sequence will also be mutable.
+    Otherwise, the returned buffer sequence will be constant.
+*/
+template<class BufferSequence>
+typename std::conditional<
+    is_mutable_buffer_sequence<BufferSequence>::value,
+    boost::asio::mutable_buffer,
+    boost::asio::const_buffer>::type
+buffer_front(BufferSequence const& buffers)
+{
+    auto const first = buffers.begin();
+    if(first == buffers.end())
+        return {nullptr, 0};
+    return *first;
+}
+
 } // beast
 
 #include <beast/core/impl/buffer_prefix.ipp>