Fields::writer replaces Fields::reader (API Change):

* Fields::writer replaces Fields::reader
* The FieldsWriter concept is renamed from FieldsReader

Actions Required:

* Rename reader to writer for user defined Fields

CHANGELOG.md

@@ -5,6 +5,14 @@ Version 132:
 * Add ref-qualified overloads for message::body
 * Tidy up FieldsReader doc
 
+API Changes:
+
+* Fields::writer replaces Fields::reader
+
+Actions Required:
+
+* Rename reader to writer for user defined Fields
+
 --------------------------------------------------------------------------------
 
 Version 131:

doc/qbk/00_main.qbk

@@ -70,7 +70,7 @@
 [def __BodyWriter__             [link beast.concepts.BodyWriter [*BodyWriter]]]
 [def __DynamicBuffer__          [link beast.concepts.DynamicBuffer [*DynamicBuffer]]]
 [def __Fields__                 [link beast.concepts.Fields [*Fields]]]
-[def __FieldsReader__           [link beast.concepts.FieldsReader [*FieldsReader]]]
+[def __FieldsWriter__           [link beast.concepts.FieldsWriter [*FieldsWriter]]]
 [def __File__                   [link beast.concepts.File [*File]]]
 [def __Stream__                 [link beast.concepts.streams [*Stream]]]
 [def __SyncStream__             [link beast.concepts.streams.SyncStream [*SyncStream]]]

doc/qbk/07_concepts.qbk

@@ -17,7 +17,7 @@ This section describes all of the concepts defined by the library.
 [include 07_concepts/BufferSequence.qbk]
 [include 07_concepts/DynamicBuffer.qbk]
 [include 07_concepts/Fields.qbk]
-[include 07_concepts/FieldsReader.qbk]
+[include 07_concepts/FieldsWriter.qbk]
 [include 07_concepts/File.qbk]
 [include 07_concepts/Streams.qbk]
 

doc/qbk/07_concepts/Fields.qbk

@@ -18,14 +18,14 @@ be serialized.
 [heading Associated Types]
 
 * [link beast.ref.boost__beast__http__is_fields `is_fields`]
-* __FieldsReader__
+* __FieldsWriter__
 
 [heading Requirements]
 
 In this table:
 
 * `F` denotes a type that meets the requirements of [*Fields].
-* `R` denotes a type meeting the requirements of __FieldsReader__.
+* `W` denotes a type meeting the requirements of __FieldsWriter__.
 * `a` denotes a value of type `F`.
 * `c` denotes a (possibly const) value of type `F`.
 * `b` is a value of type `bool`
@@ -36,10 +36,10 @@ In this table:
 [table Valid expressions
 [[Expression] [Type] [Semantics, Pre/Post-conditions]]
 [
-    [`F::reader`]
+    [`F::writer`]
-    [`R`]
+    [`W`]
     [
-        A type which meets the requirements of __FieldsReader__.
+        A type which meets the requirements of __FieldsWriter__.
     ]
 ][
     [`c.get_method_impl()`]
@@ -159,7 +159,7 @@ In this table:
             list of encodings if it appears last in the list.
             If the result of the removal leaves the list of encodings
             empty, the Transfer-Encoding field shall not appear when
-            the associated __FieldsReader__ serializes the fields.
+            the associated __FieldsWriter__ serializes the fields.
         ]]
 
         If the result of adjusting the field value produces an empty

doc/qbk/07_concepts/FieldsWriter.qbk

@@ -7,25 +7,25 @@
     Official repository: https://github.com/boostorg/beast
 ]
 
-[section:FieldsReader FieldsReader]
+[section:FieldsWriter FieldsWriter]
 
-A [*FieldsReader] provides a algorithm to obtain a sequence of buffers
+A [*FieldsWriter] provides a algorithm to obtain a sequence of buffers
 representing the complete serialized HTTP/1 header for a set of fields.
 The implementation constructs an instance of this type when needed, and
 calls into it once to retrieve the buffers.
 
 [heading Associated Types]
 
-* __FieldsReader__
+* __FieldsWriter__
 
 [heading Requirements]
 
 In this table:
 
-* `R` denotes a type that meets the requirements of [*FieldsReader].
+* `W` denotes a type that meets the requirements of [*FieldsWriter].
 * `F` denotes a __Fields__ where
-      `std::is_same<R, F::reader>::value == true`.
+      `std::is_same<W, F::reader>::value == true`.
-* `a` is a value of type `R`.
+* `a` is a value of type `W`.
 * `f` is a value of type `F`.
 * `v` is an `unsigned` value representing the HTTP version.
 * `c` is an `unsigned` representing the HTTP status-code.
@@ -34,47 +34,52 @@ In this table:
 [table Valid expressions
 [[expression][type][semantics, pre/post-conditions]]
 [
-    [`R::const_buffers_type`]
+    [`W::const_buffers_type`]
     []
     [
         A type which meets the requirements of __ConstBufferSequence__.
-        This is the type of buffer returned by `R::get`.
+        This is the type of buffer returned by `W::get`.
     ]
 ][
-    [`R{f,v,m}`]
+    [`W{f,v,m}`]
     []
     [
         The implementation calls this constructor to indicate
         that the fields being serialized form part of an HTTP
         request. The lifetime of `f` is guaranteed
-        to end no earlier than after the `R` is destroyed.
+        to end no earlier than after the `W` is destroyed.
     ]
 ][
-    [`R{f,v,c}`]
+    [`W{f,v,c}`]
     []
     [
         The implementation calls this constructor to indicate
         that the fields being serialized form part of an HTTP
         response. The lifetime of `f` is guaranteed
-        to end no earlier than after the `R` is destroyed.
+        to end no earlier than after the `W` is destroyed.
     ]
 ][
     [`a.get()`]
-    [`R::const_buffers_type`]
+    [`W::const_buffers_type`]
     [
         Called once after construction, this function returns
         a constant buffer sequence containing the serialized
         representation of the HTTP request or response including
         the final carriage return linefeed sequence (`"\r\n"`).
+
+        Copies may be made of the returned sequence, but the
+        underlying memory is still owned by the writer. The
+        implementation will destroy all copies of the buffer
+        sequence before destroying `a`.
     ]
 ]]
 
 [heading Exemplar]
 
-[concept_FieldsReader]
+[concept_FieldsWriter]
 
 [heading Models]
 
-* [link beast.ref.boost__beast__http__basic_fields.reader `basic_fields::reader`]
+* [link beast.ref.boost__beast__http__basic_fields.writer `basic_fields::writer`]
 
 [endsect]

doc/qbk/quickref.xml

@@ -121,7 +121,7 @@
             <member><link linkend="beast.concepts.BodyReader">BodyReader</link></member>
             <member><link linkend="beast.concepts.BodyWriter">BodyWriter</link></member>
             <member><link linkend="beast.concepts.Fields">Fields</link></member>
-            <member><link linkend="beast.concepts.FieldsReader">FieldsReader</link></member>
+            <member><link linkend="beast.concepts.FieldsWriter">FieldsWriter</link></member>
           </simplelist>
         </entry>
         <entry valign="top">

include/boost/beast/http/detail/chunk_encode.hpp

@@ -245,7 +245,7 @@ template<class T,
 struct buffers_or_fields
 {
     using type = typename
-        T::reader::const_buffers_type;
+        T::writer::const_buffers_type;
 };
 
 template<class T>

include/boost/beast/http/detail/type_traits.hpp

@@ -51,6 +51,8 @@ struct is_parser<parser<isRequest, Body, Fields>> : std::true_type {};
 
 struct fields_model
 {
+    struct writer;
+    
     string_view method() const;
     string_view reason() const;
     string_view target() const;

include/boost/beast/http/fields.hpp

@@ -155,9 +155,9 @@ public:
 
     /// The algorithm used to serialize the header
 #if BOOST_BEAST_DOXYGEN
-    using reader = implementation_defined;
+    using writer = implementation_defined;
 #else
-    class reader;
+    class writer;
 #endif
 
 private:

include/boost/beast/http/impl/chunk_encode.ipp

@@ -159,7 +159,7 @@ prepare(Trailer const& trailer, Allocator const& allocator) ->
     buffers_type
 {
     auto sp = std::allocate_shared<typename
-        Trailer::reader>(allocator, trailer);
+        Trailer::writer>(allocator, trailer);
     sp_ = sp;
     return sp->get();
 }
@@ -171,7 +171,7 @@ prepare(Trailer const& trailer, std::true_type) ->
     buffers_type
 {
     auto sp = std::make_shared<
-        typename Trailer::reader>(trailer);
+        typename Trailer::writer>(trailer);
     sp_ = sp;
     return sp->get();
 }

include/boost/beast/http/impl/fields.ipp

@@ -34,7 +34,7 @@ namespace beast {
 namespace http {
 
 template<class Allocator>
-class basic_fields<Allocator>::reader
+class basic_fields<Allocator>::writer
 {
 public:
     using iter_type = typename list_t::const_iterator;
@@ -157,13 +157,13 @@ public:
     using const_buffers_type =
         beast::detail::buffers_ref<view_type>;
 
-    reader(basic_fields const& f,
+    writer(basic_fields const& f,
         unsigned version, verb v);
 
-    reader(basic_fields const& f,
+    writer(basic_fields const& f,
         unsigned version, unsigned code);
 
-    reader(basic_fields const& f);
+    writer(basic_fields const& f);
 
     const_buffers_type
     get() const
@@ -173,8 +173,8 @@ public:
 };
 
 template<class Allocator>
-basic_fields<Allocator>::reader::
+basic_fields<Allocator>::writer::
-reader(basic_fields const& f)
+writer(basic_fields const& f)
     : f_(f)
 {
     view_.emplace(
@@ -186,8 +186,8 @@ reader(basic_fields const& f)
 }
 
 template<class Allocator>
-basic_fields<Allocator>::reader::
+basic_fields<Allocator>::writer::
-reader(basic_fields const& f,
+writer(basic_fields const& f,
         unsigned version, verb v)
     : f_(f)
 {
@@ -228,8 +228,8 @@ reader(basic_fields const& f,
 }
 
 template<class Allocator>
-basic_fields<Allocator>::reader::
+basic_fields<Allocator>::writer::
-reader(basic_fields const& f,
+writer(basic_fields const& f,
         unsigned version, unsigned code)
     : f_(f)
 {
@@ -1230,7 +1230,7 @@ realloc_target(
 {
     // The target string are stored with an
     // extra space at the beginning to help
-    // the reader class.
+    // the writer class.
     if(dest.empty() && s.empty())
         return;
     auto a = typename beast::detail::allocator_traits<

include/boost/beast/http/impl/write.ipp

@@ -838,7 +838,7 @@ std::ostream&
 operator<<(std::ostream& os,
     header<true, Fields> const& h)
 {
-    typename Fields::reader fr{
+    typename Fields::writer fr{
         h, h.version(), h.method()};
     return os << buffers(fr.get());
 }
@@ -848,7 +848,7 @@ std::ostream&
 operator<<(std::ostream& os,
     header<false, Fields> const& h)
 {
-    typename Fields::reader fr{
+    typename Fields::writer fr{
         h, h.version(), h.result_int()};
     return os << buffers(fr.get());
 }

include/boost/beast/http/serializer.hpp

@@ -114,11 +114,11 @@ private:
     using reader = typename Body::reader;
 
     using cb1_t = buffers_suffix<typename
-        Fields::reader::const_buffers_type>;        // header
+        Fields::writer::const_buffers_type>;        // header
     using pcb1_t  = buffers_prefix_view<cb1_t const&>;
 
     using cb2_t = buffers_suffix<buffers_cat_view<
-        typename Fields::reader::const_buffers_type,// header
+        typename Fields::writer::const_buffers_type,// header
         typename reader::const_buffers_type>>;      // body
     using pcb2_t = buffers_prefix_view<cb2_t const&>;
 
@@ -127,7 +127,7 @@ private:
     using pcb3_t = buffers_prefix_view<cb3_t const&>;
 
     using cb4_t = buffers_suffix<buffers_cat_view<
-        typename Fields::reader::const_buffers_type,// header
+        typename Fields::writer::const_buffers_type,// header
         detail::chunk_size,                         // chunk-size
         boost::asio::const_buffer,               // chunk-ext
         chunk_crlf,                                 // crlf
@@ -155,7 +155,7 @@ private:
     using pcb6_t = buffers_prefix_view<cb6_t const&>;
 
     using cb7_t = buffers_suffix<buffers_cat_view<
-        typename Fields::reader::const_buffers_type,// header
+        typename Fields::writer::const_buffers_type,// header
         detail::chunk_size,                         // chunk-size
         boost::asio::const_buffer,               // chunk-ext
         chunk_crlf,                                 // crlf
@@ -174,7 +174,7 @@ private:
 
     value_type& m_;
     reader rd_;
-    boost::optional<typename Fields::reader> frd_;
+    boost::optional<typename Fields::writer> frd_;
     beast::detail::variant<
         cb1_t, cb2_t, cb3_t, cb4_t,
         cb5_t ,cb6_t, cb7_t, cb8_t> v_;

test/doc/exemplars.cpp

@@ -190,7 +190,8 @@ static_assert(is_body_writer<Body_BodyWriter>::value, "");
 class Fields
 {
 public:
-    struct reader;
+    /// Constructed as needed when fields are serialized
+    struct writer;
 
 protected:
     /** Returns the request-method string.
@@ -271,20 +272,20 @@ static_assert(is_fields<Fields>::value,
 
 //]
 
-struct Fields_FieldsReader {
+struct Fields_FieldsWriter {
-    using Fields = Fields_FieldsReader;
+    using Fields = Fields_FieldsWriter;
-//[concept_FieldsReader
+//[concept_FieldsWriter
 
-struct FieldsReader
+struct FieldsWriter
 {
     // The type of buffers returned by `get`
     struct const_buffers_type;
 
     // Constructor for requests
-    FieldsReader(Fields const& f, unsigned version, verb method);
+    FieldsWriter(Fields const& f, unsigned version, verb method);
 
     // Constructor for responses
-    FieldsReader(Fields const& f, unsigned version, unsigned status);
+    FieldsWriter(Fields const& f, unsigned version, unsigned status);
 
     // Returns the serialized header buffers
     const_buffers_type