[/
    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 this table:

* `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`.

* `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`.

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

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

[table Writer requirements
[[expression] [type] [semantics, pre/post-conditions]]
[
    [`X(m,n,ec);`]
    []
    [
        Constructible from `m`. The lifetime of `m` is guaranteed
        to end no earlier than after the `X` is destroyed. The constructor
        will be called after a complete header is stored in `m`, and before
        parsing body octets for messages indicating that a body is present.
        The value of `n` will be set to the content length of the
        body if known, otherwise `n` will be equal to `boost::none`.
        Implementations of [*BodyWriter] may use this information to
        optimize allocation.
        The function will ensure that `!ec` is `true` if there was
        no error or set to the appropriate error code if there was one. 
    ]
][
    [`a.put(b,ec)`]
    [`std::size_t`]
    [
        This function is called to append some or all of the buffers
        specified by `b` into the body representation. The number of
        bytes inserted from `b` is returned. If the number of bytes
        inserted is less than the total input, the remainder of the
        input will be presented in the next call to `put`.
        The function will ensure that `!ec` is `true` if there was
        no error or set to the appropriate error code if there was one. 
    ]
][
    [`a.finish(ec)`]
    []
    [
        This function is called when no more body octets are remaining.
        The function will ensure that `!ec` is `true` if there was
        no error or set to the appropriate error code if there was one. 
    ]
][
    [`is_body_writer<B>`]
    [`std::true_type`]
    [
        An alias for `std::true_type` for `B`, otherwise an alias
        for `std::false_type`.
    ]
]
]

[heading Exemplar]

[concept_BodyWriter]

[endsect]