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

[section:Fields Fields]

An instance of [*Fields] is a container for holding HTTP header fields
and their values. The implementation also calls upon the container to
store the request target and non-standard strings for method and obsolete
reason phrase as needed. Types which meet these requirements can always
be serialized.

[heading Associated Types]

* [link beast.ref.boost__beast__http__is_fields `is_fields`]
* __FieldsWriter__

[heading Requirements]

In this table:

* `F` denotes a type that meets the requirements of [*Fields].
* `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`
* `n` is a value of type `boost::optional<std::uint64_t>`.
* `s` is a value of type [link beast.ref.boost__beast__string_view `string_view`].
* `v` is a value of type `unsigned int` representing the HTTP-version.

[table Valid expressions
[[Expression] [Type] [Semantics, Pre/Post-conditions]]
[
    [`F::writer`]
    [`W`]
    [
        A type which meets the requirements of __FieldsWriter__.
    ]
][
    [`c.get_method_impl()`]
    [`string_view`]
    [
        Returns the method text.
        The implementation only calls this function for request
        headers when retrieving the method text previously set
        with a call to `set_method_impl` using a non-empty string.
    ]
][
    [`c.get_target_impl()`]
    [`string_view`]
    [
        Returns the target string.
        The implementation only calls this function for request headers.
    ]
][
    [`c.get_reason_impl()`]
    [`string_view`]
    [
        Returns the obsolete request text.
        The implementation only calls this for response headers when
        retrieving the reason text previously set with a call to
        `set_reason_impl` using a non-empty string.
    ]
][
    [`c.get_chunked_impl()`]
    [`bool`]
    [
        Returns `true` if the
        [@https://tools.ietf.org/html/rfc7230#section-3.3.1 [*Transfer-Encoding]]
        field value indicates that the payload is chunk encoded. Both
        of these conditions must be true:
        [itemized_list
        [
            The Transfer-Encoding field is present in the message.
        ][
            The last item in value of the field is "chunked".
        ]]
    ]
][
    [`c.get_keep_alive_impl(v)`]
    [`bool`]
    [
        Returns `true` if the semantics of the
        [@https://tools.ietf.org/html/rfc7230#section-6.1 [*Connection]]
        field and version indicate that the connection should remain
        open after the corresponding response is transmitted or received:

        [itemized_list
        [
            If `(v < 11)` the function returns `true` if the "keep-alive"
            token is present in the Connection field value. Otherwise the
            function returns `false`.
        ][
            If `(v == 11)`, the function returns `false` if the "close"
            token is present in the Connection field value. Otherwise the
            function returns `true`.
        ]]
    ]
][
    [`c.has_content_length()`]
    [`bool`]
    [
        Returns `true` if the
        [@https://tools.ietf.org/html/rfc7230#section-3.3.2 [*Content-Length]]
        field is present.
    ]
][
    [`a.set_method_impl(s)`]
    []
    [
        Stores a copy of `s` as the method text, or erases the previously
        stored value if `s` is empty.
        The implementation only calls this function for request headers.
        This function may throw `std::invalid_argument` if the operation
        is not supported by the container.
    ]
][
    [`a.set_target_impl(s)`]
    []
    [
        Stores a copy of `s` as the target, or erases the previously
        stored value if `s` is empty.
        The implementation only calls this function for request headers.
        This function may throw `std::invalid_argument` if the operation
        is not supported by the container.
    ]
][
    [`a.set_reason_impl(s)`]
    []
    [
        Stores a copy of `s` as the reason text, or erases the previously
        stored value of the reason text if `s` is empty.
        The implementation only calls this function for request headers.
        This function may throw `std::invalid_argument` if the operation
        is not supported by the container.
    ]
][
    [`a.set_chunked_impl(b)`]
    []
    [
        Adjusts the
        [@https://tools.ietf.org/html/rfc7230#section-3.3.1 [*Transfer-Encoding]]
        field value as follows:

        [itemized_list
        [
            If `b` is `true`, the "chunked" token is appended
            to the list of encodings if it does not already appear
            last in the list.
            If the Transfer-Encoding field is absent, the field will
            be inserted to the container with the value "chunked".
        ][
            If `b` is `false, the "chunked" token is removed from the
            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 __FieldsWriter__ serializes the fields.
        ]]

        If the result of adjusting the field value produces an empty
        string, the field is removed from the container.
    ]

][
    [`a.set_content_length_impl(n)`]
    []
    [
        Adjusts the
        [@https://tools.ietf.org/html/rfc7230#section-3.3.2 [*Content-Length]]
        field value as follows:

        [itemized_list
        [
            If `n` contains a value, the Content-Length field
            will be set to the text representation of the value.
            Any previous Content-Length fields are removed from
            the container.
        ][
            If `n` does not contain a value, any present Content-Length
            fields are removed from the container.
        ]]
    ]

][
    [`a.set_keep_alive_impl(v,b)`]
    []
    [
        Adjusts the
        [@https://tools.ietf.org/html/rfc7230#section-6.1 [*Connection]]
        field value depending on the values of `v` and `b`. The field
        value is treated as
        [@https://tools.ietf.org/html/rfc7230#section-6.1 ['connection-option]]
        (rfc7230).

        [itemized_list
        [
            If `(v < 11 && b)`, then all "close" tokens present in the
            value are removed, and the "keep-alive" token is added to
            the value if it is not already present.
        ][
            If `(v < 11 && ! b)`, then all "close" and "keep-alive"
            tokens present in the value are removed.

        ][
            If `(v == 11 && b)`, then all "keep-alive" and "close"
            tokens present in the value are removed.
        ][
            If `(v == 11 && ! b)`, then all "keep-alive" tokens present
            in the value are removed, and the "close" token is added to
            the value if it is not already present.
        ]]

        If the result of adjusting the field value produces an empty
        string, the field is removed from the container.
    ]

]]

[heading Exemplar]

[concept_Fields]

[heading Models]

* [link beast.ref.boost__beast__http__basic_fields `basic_fields`]
* [link beast.ref.boost__beast__http__fields `fields`]

[endsect]