Add buffers_to_string

fix #772

CHANGELOG.md

@@ -1,5 +1,7 @@
 Version 117:
 
+* Add buffers_to_string
+
 API Changes:
 
 * buffers_suffix replaces consuming_buffers

doc/qbk/03_core/3_buffers.qbk

@@ -149,6 +149,12 @@ transferred.
     may be progressively shortened. This lets callers work with sequential
     increments of a buffer sequence.
 ]]
+[[
+    [link beast.ref.boost__beast__buffers_to_string `buffers_to_string`]
+][
+    This function converts a buffer sequence to a `std::string`. It can
+    be used for diagnostic purposes and tests.
+]]
 ]
 
 These two functions facilitate buffer interoperability with standard

doc/qbk/quickref.xml

@@ -219,6 +219,7 @@
             <member><link linkend="beast.ref.boost__beast__buffers_cat">buffer_cat</link></member>
             <member><link linkend="beast.ref.boost__beast__buffers_front">buffers_front</link></member>
             <member><link linkend="beast.ref.boost__beast__buffers_prefix">buffers_prefix</link></member>
+            <member><link linkend="beast.ref.boost__beast__buffers_to_string">buffers_to_string</link></member>
             <member><link linkend="beast.ref.boost__beast__generic_category">generic_category</link></member>
             <member><link linkend="beast.ref.boost__beast__iequals">iequals</link></member>
             <member><link linkend="beast.ref.boost__beast__ostream">ostream</link></member>

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

test/beast/core/CMakeLists.txt

@@ -25,6 +25,7 @@ add_executable (tests-beast-core
     buffers_cat.cpp
     buffers_prefix.cpp
     buffers_suffix.cpp
+    buffers_to_string.cpp
     error.cpp
     file.cpp
     file_posix.cpp

test/beast/core/Jamfile

@@ -15,6 +15,7 @@ local SOURCES =
     buffers_cat.cpp
     buffers_prefix.cpp
     buffers_suffix.cpp
+    buffers_to_string.cpp
     error.cpp
     file.cpp
     file_posix.cpp

test/beast/core/buffers_to_string.cpp

@@ -0,0 +1,36 @@
+//
+// 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
+//
+
+// Test that header file is self-contained.
+#include <boost/beast/core/buffers_to_string.hpp>
+
+#include <boost/beast/core/multi_buffer.hpp>
+#include <boost/beast/core/ostream.hpp>
+#include <boost/beast/unit_test/suite.hpp>
+
+namespace boost {
+namespace beast {
+
+class buffers_to_string_test : public unit_test::suite
+{
+public:
+    void
+    run() override
+    {
+        multi_buffer b;
+        ostream(b) << "Hello, ";
+        ostream(b) << "world!";
+        BEAST_EXPECT(buffers_to_string(b.data()) == "Hello, world!");
+    }
+};
+
+BEAST_DEFINE_TESTSUITE(beast,core,buffers_to_string);
+
+} // beast
+} // boost