[/
    Copyright (c) 2013-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)
]

[section:BodyWriter BodyWriter]

A [*BodyWriter] provides an online algorithm to transfer a series of zero
or more buffers containing parsed body octets into a message container. The
__parser__ creates an instance of this type when needed, and calls into
it zero or more times to transfer buffers. The interface of [*BodyWriter]
is intended to allow the conversion of buffers into these scenarios for
representation:

* Storing a body in a dynamic buffer
* Storing a body in a user defined container with a custom allocator
* Transformation of incoming body data before storage, for example
  to compress it first.
* Saving body data to a file

In the table below:

* `X` denotes a type meeting the requirements of [*BodyWriter].

* `B` denotes a __Body__ where
      `std::is_same<X, B::writer>::value == true`.

* `a` denotes a value of type `X`.

* `length` is a value of type `boost::optional<std::uint64_t>`.

* `b` is an object whose type meets the requirements of __ConstBufferSequence__

* `m` denotes a value of type `message&` where
    `std::is_same<decltype(m.body), Body::value_type>::value == true`.

* `ec` is a value of type [link beast.ref.error_code `error_code&`].

[table Writer requirements
[[expression] [type] [semantics, pre/post-conditions]]
[
    [`X(m);`]
    []
    [
        Constructible from `m`. The lifetime of `m` is guaranteed
        to end no earlier than after the `X` is destroyed. The constructor
        will be called the complete header is stored in `m`, and before
        parsing body octets for messages indicating that a body is present.
    ]
]
[
    [`a.init(length,ec)`]
    []
    [
        This function is called after construction and before any body
        octets are presented to the writer. The value of `length` will
        be set to the content length of the body if known, otherwise
        `length` will be equal to `boost::none`. Implementations of
        [*BodyWriter] may use this information to optimize allocation.
        If `ec` is set, the error will be propagated to the caller.
    ]
]
[
    [`a.put(b,ec)`]
    []
    [
        This function is called to append the buffers specified by `b`
        into the body representation.
        If `ec` is set, the error will be propagated to the caller.
    ]
]
[
    [`a.finish(ec)`]
    []
    [
        This function is called when no more body octets are remaining.
        If `ec` is set, the error will be propagated to the caller.
    ]
]
[
    [`is_body_writer<B>`]
    [`std::true_type`]
    [
        An alias for `std::true_type` for `B`, otherwise an alias
        for `std::false_type`.
    ]
]
]
[note
    Definitions for required [*BodyWriter] member functions should be declared
    inline so the generated code can become part of the implementation.
]

Exemplar:
```
struct writer
{
    /** Construct the writer.

        @param msg The message whose body is to be stored.
    */
    template<bool isRequest, class Body, class Fields>
    explicit
    writer(message<isRequest, Body, Fields>& msg);

    /** Initialization.

        Called once immediately before storing any buffers.

        @param content_length The content length if known, else `boost::none`.

        @param ec Set to the error, if any occurred.
    */
    void
    init(boost::optional<std::uint64_t> content_length, error_code& ec);

    /** Store buffers.

        This is called zero or more times with parsed body octets.

        @param buffers The constant buffer sequence to store.

        @param ec Set to the error, if any occurred.
    */
    template<class ConstBufferSequence>
    void
    put(ConstBufferSequence const& buffers, error_code& ec);

    /** Called when the body is complete.

        @param ec Set to the error, if any occurred.
    */
    void
    finish(error_code& ec);
};
```

[endsect]