Add buffers_to_string

fix #772

include/boost/beast/core.hpp

@@ -14,11 +14,12 @@
 
 #include <boost/beast/core/async_result.hpp>
 #include <boost/beast/core/bind_handler.hpp>
-#include <boost/beast/core/buffers_cat.hpp>
-#include <boost/beast/core/buffers_prefix.hpp>
 #include <boost/beast/core/buffered_read_stream.hpp>
 #include <boost/beast/core/buffers_adapter.hpp>
+#include <boost/beast/core/buffers_cat.hpp>
+#include <boost/beast/core/buffers_prefix.hpp>
 #include <boost/beast/core/buffers_suffix.hpp>
+#include <boost/beast/core/buffers_to_string.hpp>
 #include <boost/beast/core/error.hpp>
 #include <boost/beast/core/file.hpp>
 #include <boost/beast/core/file_base.hpp>
@@ -26,13 +27,14 @@
 #include <boost/beast/core/file_stdio.hpp>
 #include <boost/beast/core/file_win32.hpp>
 #include <boost/beast/core/flat_buffer.hpp>
+#include <boost/beast/core/flat_static_buffer.hpp>
 #include <boost/beast/core/handler_alloc.hpp>
 #include <boost/beast/core/handler_ptr.hpp>
 #include <boost/beast/core/multi_buffer.hpp>
 #include <boost/beast/core/ostream.hpp>
 #include <boost/beast/core/read_size.hpp>
 #include <boost/beast/core/span.hpp>
-#include <boost/beast/core/flat_static_buffer.hpp>
+#include <boost/beast/core/static_buffer.hpp>
 #include <boost/beast/core/static_string.hpp>
 #include <boost/beast/core/string.hpp>
 #include <boost/beast/core/string_param.hpp>

include/boost/beast/core/buffers_suffix.hpp

@@ -35,6 +35,21 @@ namespace beast {
     is still responsible for managing its lifetime.
 
     @tparam BufferSequence The buffer sequence to wrap.
+
+    @par Example
+
+    This function writes the entire contents of a buffer sequence
+    to the specified stream.
+
+    @code
+    template<class SyncWriteStream, class ConstBufferSequence>
+    void send(SyncWriteStream& stream, ConstBufferSequence const& buffers)
+    {
+        buffers_suffix<ConstBufferSequence> bs{buffers};
+        while(boost::asio::buffer_size(bs) > 0)
+            bs.consume(stream.write_some(bs));
+    }
+    @endcode
 */
 template<class BufferSequence>
 class buffers_suffix

include/boost/beast/core/buffers_to_string.hpp

@@ -0,0 +1,58 @@
+//
+// Copyright (c) 2016-2017 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/boostorg/beast
+//
+
+#ifndef BOOST_BEAST_BUFFERS_TO_STRING_HPP
+#define BOOST_BEAST_BUFFERS_TO_STRING_HPP
+
+#include <boost/beast/config.hpp>
+#include <boost/asio/buffer.hpp>
+#include <string>
+
+namespace boost {
+namespace beast {
+
+/** Return a string representing the contents of a buffer sequence.
+
+    This function returns a string representing an entire buffer
+    sequence. Nulls and unprintable characters in the buffer
+    sequence are inserted to the resulting string as-is. No
+    character conversions are performed.
+
+    @param buffers The buffer sequence to convert
+
+    @par Example
+
+    This function writes a buffer sequence converted to a string
+    to `std::cout`.
+
+    @code
+    template<class ConstBufferSequence>
+    void print(ConstBufferSequence const& buffers)
+    {
+        std::cout << buffers_to_string(buffers) << std::endl;
+    }
+    @endcode
+*/
+template<class ConstBufferSequence>
+std::string
+buffers_to_string(ConstBufferSequence const& buffers)
+{
+    std::string result;
+    result.reserve(boost::asio::buffer_size(buffers));
+    for(boost::asio::const_buffer buffer : buffers)
+        result.append(
+            boost::asio::buffer_cast<char const*>(buffer),
+            boost::asio::buffer_size(buffer));
+    return result;
+}
+
+} // beast
+} // boost
+
+#endif