[/
    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` 的实例是一个用于存储 HTTP 报文字段及其值的容器。该实现还会根据需要调用此容器来存储请求目标，以及非标准的方法字符串和过时的原因短语字符串。满足这些要求的类型始终可以进行序列化。

[heading 关联类型]

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

[heading 要求]

在下表中:

* `F` 表示满足 [*Fields] 要求的类型。
* `W` 表示满足 __FieldsWriter__ 要求的类型。
* `a` 表示类型为 `F` 的值。
* `c` 表示类型为 `F` 的值（可能带有 const 限定）。
* `b` 表示类型为 `bool` 的值。
* `n` 表示类型为 `boost::optional<std::uint64_t>` 的值。
* `s` 表示类型为 [link beast.ref.boost__beast__string_view `string_view`] 的值。
* `v` 表示类型为 `unsigned int` 的值，用于表示 HTTP 版本。

[table 有效表达式
[[表达式] [类型] [语义，前置条件 / 后置条件]]
[
    [`F::writer`]
    [`W`]
    [满足 __FieldsWriter__ 要求的类型。]
][
    [`c.get_method_impl()`]
    [`string_view`]
    [返回方法文本。仅当使用非空字符串调用 `set_method_impl` 设置了方法文本后，在检索请求头时，实现才会调用此函数。]
][
    [`c.get_target_impl()`]
    [`string_view`]
    [返回目标字符串。该函数仅在处理请求头时由实现调用。]
][
    [`c.get_reason_impl()`]
    [`string_view`]
    [返回过时的请求文本。仅当使用非空字符串调用 `set_reason_impl` 设置了原因文本后，在检索响应头时，实现才会调用此函数。]
][
    [`c.get_chunked_impl()`]
    [`bool`]
    [如果 [@https://tools.ietf.org/html/rfc7230#section-3.3.1 [*Transfer-Encoding]] 字段值表明负载已进行分块编码，则返回 `true`。必须同时满足以下两个条件：[itemized_list [ 消息中存在 Transfer-Encoding 字段。 ][ 该字段值的最后一项为 "chunked"。 ]]]
][
    [`c.get_keep_alive_impl(v)`]
    [`bool`]
    [如果 [@https://tools.ietf.org/html/rfc7230#section-6.1 [*Connection]] 字段的语义和版本表明，在发送或接收相应响应后连接应保持打开，则返回 true：
[itemized_list [ 如果 (v < 11)，当 Connection 字段值中存在 "keep-alive" 标记时函数返回 true，否则返回 false。 ][ 如果 (v == 11)，当 Connection 字段值中存在 "close" 标记时函数返回 false，否则返回 true。 ]]]
][
    [`c.has_content_length()`]
    [`bool`]
    [如果存在 @https://tools.ietf.org/html/rfc7230#section-3.3.2 [Content-Length] 字段，则返回 true。]
][
    [`a.set_method_impl(s)`]
    []
    [将 `s` 的副本存储为方法文本；若 `s` 为空，则擦除先前存储的值。此函数仅由实现对请求头进行调用。如果容器不支持该操作，函数可能会抛出 `std::invalid_argument` 异常。]
][
    [`a.set_target_impl(s)`]
    []
    [将 `s` 的副本存储为目标；若 `s` 为空，则擦除先前存储的值。此函数仅由实现对请求头进行调用。如果容器不支持该操作，函数可能会抛出 `std::invalid_argument` 异常。]
][
    [`a.set_reason_impl(s)`]
    []
    [将 `s` 的副本存储为原因文本；若 `s` 为空，则擦除先前存储的原因文本。此函数仅由实现对请求头进行调用。如果容器不支持该操作，函数可能会抛出 `std::invalid_argument` 异常。]
][
    [`a.set_chunked_impl(b)`]
    []
    [根据 [@https://tools.ietf.org/html/rfc7230#section-3.3.1 [*Transfer-Encoding]] 字段值进行调整：

- 如果 `b` 为 `true`，且 "chunked" 标记尚未位于编码列表末尾，则将其追加到列表末尾。如果不存在 Transfer-Encoding 字段，则向容器插入该字段，其值为 "chunked"。
- 如果 `b` 为 `false`，且 "chunked" 标记位于编码列表末尾，则将其从列表中移除。如果移除后编码列表为空，则当关联的 `__FieldsWriter__` 序列化字段时，Transfer-Encoding 字段不应出现。

如果调整字段值的结果产生空字符串，则从容器中移除该字段。]

][
    [`a.set_content_length_impl(n)`]
    []
    [根据 [@https://tools.ietf.org/html/rfc7230#section-3.3.2 [*Content-Length]] 字段值进行如下调整：

- 如果 `n` 包含一个值，则将 Content-Length 字段设置为该值的文本表示。从容器中移除任何先前存在的 Content-Length 字段。
- 如果 `n` 不包含值，则从容器中移除任何存在的 Content-Length 字段。]

][
    [`a.set_keep_alive_impl(v,b)`]
    []
    [根据 [@https://tools.ietf.org/html/rfc7230#section-6.1 [*Connection]] 字段值以及 `v` 和 `b` 的值进行如下调整。该字段值被视为 [@https://tools.ietf.org/html/rfc7230#section-6.1 ['connection-option]] (rfc7230)。

- 如果 `(v < 11 && b)`，则从字段值中移除所有 "close" 标记，若 "keep-alive" 标记尚不存在，则将其添加到字段值中。
- 如果 `(v < 11 && !b)`，则从字段值中移除所有 "close" 和 "keep-alive" 标记。
- 如果 `(v == 11 && b)`，则从字段值中移除所有 "keep-alive" 和 "close" 标记。
- 如果 `(v == 11 && !b)`，则从字段值中移除所有 "keep-alive" 标记，若 "close" 标记尚不存在，则将其添加到字段值中。

如果调整字段值的结果产生空字符串，则从容器中移除该字段。]

]]

[heading 示例]

[concept_Fields]

[heading 模型]

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

[endsect]