beast/core/ostream.hpp

0001 //
0002 // Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
0003 //
0004 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0005 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0006 //
0007 // Official repository: https://github.com/boostorg/beast
0008 //
0009
0010 #ifndef BOOST_BEAST_WRITE_OSTREAM_HPP
0011 #define BOOST_BEAST_WRITE_OSTREAM_HPP
0012
0013 #include <boost/beast/core/detail/config.hpp>
0014 #include <boost/beast/core/detail/ostream.hpp>
0015 #include <type_traits>
0016 #include <streambuf>
0017 #include <utility>
0018
0019 #ifdef BOOST_BEAST_ALLOW_DEPRECATED
0020 #include <boost/beast/core/make_printable.hpp>
0021 #endif
0022
0023 namespace boost {
0024 namespace beast {
0025
0026 /** Return an output stream that formats values into a <em>DynamicBuffer</em>.
0027
0028     This function wraps the caller provided <em>DynamicBuffer</em> into
0029     a `std::ostream` derived class, to allow `operator<<` stream style
0030     formatting operations.
0031
0032     @par Example
0033     @code
0034         ostream(buffer) << "Hello, world!" << std::endl;
0035     @endcode
0036
0037     @note Calling members of the underlying buffer before the output
0038     stream is destroyed results in undefined behavior.
0039
0040     @param buffer An object meeting the requirements of <em>DynamicBuffer</em>
0041     into which the formatted output will be placed.
0042
0043     @return An object derived from `std::ostream` which redirects output
0044     The wrapped dynamic buffer is not modified, a copy is made instead.
0045     Ownership of the underlying memory is not transferred, the application
0046     is still responsible for managing its lifetime. The caller is
0047     responsible for ensuring the dynamic buffer is not destroyed for the
0048     lifetime of the output stream.
0049 */
0050 template<class DynamicBuffer>
0051 #if BOOST_BEAST_DOXYGEN
0052 __implementation_defined__
0053 #else
0054 detail::ostream_helper<
0055     DynamicBuffer, char, std::char_traits<char>,
0056         detail::basic_streambuf_movable::value>
0057 #endif
0058 ostream(DynamicBuffer& buffer)
0059 {
0060     static_assert(
0061         net::is_dynamic_buffer<DynamicBuffer>::value,
0062         "DynamicBuffer type requirements not met");
0063     return detail::ostream_helper<
0064         DynamicBuffer, char, std::char_traits<char>,
0065             detail::basic_streambuf_movable::value>{buffer};
0066 }
0067
0068 //------------------------------------------------------------------------------
0069
0070 #ifdef BOOST_BEAST_ALLOW_DEPRECATED
0071 template<class T>
0072 detail::make_printable_adaptor<T>
0073 buffers(T const& t)
0074 {
0075     return make_printable(t);
0076 }
0077 #else
0078 template<class T>
0079 void buffers(T const&)
0080 {
0081     static_assert(sizeof(T) == 0,
0082         "The function buffers() is deprecated, use make_printable() instead, "
0083         "or define BOOST_BEAST_ALLOW_DEPRECATED to silence this error.");
0084 }
0085 #endif
0086
0087 } // beast
0088 } // boost
0089
0090 #endif