diff --git a/CHANGELOG.md b/CHANGELOG.md index a88d89b0..77926efa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,7 @@ Version 117: +* Add buffers_to_string + API Changes: * buffers_suffix replaces consuming_buffers diff --git a/doc/qbk/03_core/3_buffers.qbk b/doc/qbk/03_core/3_buffers.qbk index 78df936f..93d869f1 100644 --- a/doc/qbk/03_core/3_buffers.qbk +++ b/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 diff --git a/doc/qbk/quickref.xml b/doc/qbk/quickref.xml index d5aaf191..837ac750 100644 --- a/doc/qbk/quickref.xml +++ b/doc/qbk/quickref.xml @@ -219,6 +219,7 @@ buffer_cat buffers_front buffers_prefix + buffers_to_string generic_category iequals ostream diff --git a/include/boost/beast/core.hpp b/include/boost/beast/core.hpp index 966a0b8a..c5701df4 100644 --- a/include/boost/beast/core.hpp +++ b/include/boost/beast/core.hpp @@ -14,11 +14,12 @@ #include #include -#include -#include #include #include +#include +#include #include +#include #include #include #include @@ -26,13 +27,14 @@ #include #include #include +#include #include #include #include #include #include #include -#include +#include #include #include #include diff --git a/include/boost/beast/core/buffers_suffix.hpp b/include/boost/beast/core/buffers_suffix.hpp index d182d6e8..f23b23fd 100644 --- a/include/boost/beast/core/buffers_suffix.hpp +++ b/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 + void send(SyncWriteStream& stream, ConstBufferSequence const& buffers) + { + buffers_suffix bs{buffers}; + while(boost::asio::buffer_size(bs) > 0) + bs.consume(stream.write_some(bs)); + } + @endcode */ template class buffers_suffix diff --git a/include/boost/beast/core/buffers_to_string.hpp b/include/boost/beast/core/buffers_to_string.hpp new file mode 100644 index 00000000..a62a76c9 --- /dev/null +++ b/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 +#include +#include + +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 + void print(ConstBufferSequence const& buffers) + { + std::cout << buffers_to_string(buffers) << std::endl; + } + @endcode +*/ +template +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(buffer), + boost::asio::buffer_size(buffer)); + return result; +} + +} // beast +} // boost + +#endif diff --git a/test/beast/core/CMakeLists.txt b/test/beast/core/CMakeLists.txt index f7450209..884311b6 100644 --- a/test/beast/core/CMakeLists.txt +++ b/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 diff --git a/test/beast/core/Jamfile b/test/beast/core/Jamfile index 771273ad..661feec0 100644 --- a/test/beast/core/Jamfile +++ b/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 diff --git a/test/beast/core/buffers_to_string.cpp b/test/beast/core/buffers_to_string.cpp new file mode 100644 index 00000000..e6848bf6 --- /dev/null +++ b/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 + +#include +#include +#include + +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