restinio::http_header_fields_t Class Reference

Header fields map. More...

`#include <http_headers.hpp>`

Inheritance diagram for restinio::http_header_fields_t:

## Public Types

enum class | handling_result_t { continue_enumeration , stop_enumeration }
| The result of handling yet another field value. More...
using | fields_container_t = std::vector< http_header_field_t >
using | const_iterator = fields_container_t::const_iterator
| Type of const_iterator for enumeration of fields. More...

## Public Member Functions

| http_header_fields_t ()
| http_header_fields_t (const http_header_fields_t &)=default
| http_header_fields_t (http_header_fields_t &&)=default
virtual | ~http_header_fields_t ()
http_header_fields_t & | operator= (const http_header_fields_t &)=default
http_header_fields_t & | operator= (http_header_fields_t &&)=default
void | swap_fields (http_header_fields_t &http_header_fields)
bool | has_field (string_view_t field_name) const noexcept
| Check field by name. More...
bool | has_field (http_field_t field_id) const noexcept
| Check field by field-id. More...
void | set_field (http_header_field_t http_header_field)
| Set header field via http_header_field_t. More...
void | set_field (std::string field_name, std::string field_value)
| Set field with string pair. More...
void | set_field (http_field_t field_id, std::string field_value)
| Set field with id-value pair. More...
void | add_field (http_field_t field_id, std::string field_value)
| Add a field in the form of id-value pair. More...
void | add_field (std::string field_name, std::string field_value)
| Add a field in the form of name-value pair. More...
void | add_field (http_header_field_t http_header_field)
| Add a field in the form of http_header_field object. More...
void | append_field (string_view_t field_name, string_view_t field_value)
| Append field with name. More...
void | append_field (http_field_t field_id, string_view_t field_value)
| Append field with id. More...
const std::string & | get_field (string_view_t field_name) const
| Get field by name. More...
nullable_pointer_t< const std::string > | try_get_field (string_view_t field_name) const noexcept
| Try to get the value of a field by field name. More...
const std::string & | get_field (http_field_t field_id) const
| Get field by id. More...
nullable_pointer_t< const std::string > | try_get_field (http_field_t field_id) const noexcept
| Try to get the value of a field by field ID. More...
std::string | get_field_or (string_view_t field_name, string_view_t default_value) const
| Get field value by field name or default value if the field not found. More...
std::string | get_field_or (string_view_t field_name, std::string &&default_value) const
| Get field value by field name or default value if the field not found. More...
auto | get_field_or (string_view_t field_name, const char *default_value) const
| Get field by name or default value if the field not found. More...
auto | get_field_or (string_view_t field_name, const std::string &default_value) const
| Get field by name or default value if the field not found. More...
std::string | get_field_or (http_field_t field_id, string_view_t default_value) const
| Get field by id or default value if the field not found. More...
auto | get_field_or (http_field_t field_id, const char *default_value) const
| Get field by id or default value if the field not found. More...
auto | get_field_or (http_field_t field_id, const std::string &default_value) const
| Get field by id or default value if the field not found. More...
std::string | get_field_or (http_field_t field_id, std::string &&default_value) const
| Get field by id or default value if the field not found. More...
bool | remove_field (string_view_t field_name) noexcept
| Remove field by name. More...
bool | remove_field (http_field_t field_id) noexcept
| Remove field by id. More...
std::size_t | remove_all_of (string_view_t field_name) noexcept
| Remove all occurences of a field with specified name. More...
std::size_t | remove_all_of (http_field_t field_id) noexcept
| Remove all occurences of a field with specified id. More...
template<typename Lambda >
void | for_each_field (Lambda &&lambda) const noexcept(noexcept(lambda(std::declval< const http_header_field_t & >())))
| Enumeration of fields. More...
template<typename Lambda >
void | for_each_value_of (http_field_t field_id, Lambda &&lambda) const noexcept(noexcept(lambda(std::declval< const string_view_t & >())))
| Enumeration of each value of a field. More...
template<typename Lambda >
void | for_each_value_of (string_view_t field_name, Lambda &&lambda) const noexcept(noexcept(lambda(std::declval< const string_view_t & >())))
| Enumeration of each value of a field. More...
const_iterator | begin () const noexcept
const_iterator | end () const noexcept
auto | fields_count () const noexcept
Getters of field value which return string_view.
string_view_t | value_of (string_view_t name) const
| Get the value of a field or throw if the field not found. More...
string_view_t | value_of (http_field_t field_id) const
| Get the value of a field or throw if the field not found. More...
optional_t< string_view_t > | opt_value_of (string_view_t name) const noexcept
| Get optional value of a field. More...
optional_t< string_view_t > | opt_value_of (http_field_t field_id) const noexcept
| Get optional value of a field. More...

## Static Public Member Functions

static constexpr handling_result_t | continue_enumeration () noexcept
static constexpr handling_result_t | stop_enumeration () noexcept

## Private Member Functions

void | append_last_field (string_view_t field_value)
| Appends last added field. More...
fields_container_t::iterator | find (string_view_t field_name) noexcept
fields_container_t::const_iterator | cfind (string_view_t field_name) const noexcept
fields_container_t::iterator | find (http_field_t field_id) noexcept
fields_container_t::const_iterator | cfind (http_field_t field_id) const noexcept

## Private Attributes

fields_container_t | m_fields

## Friends

void | impl::append_last_field_accessor (http_header_fields_t &, string_view_t)

## Detailed Description

Header fields map.

This class holds a collection of header fields.

There are 2 special cases for fields: `Connection` and `Content-Length` This cases are handled separetely from the rest of the fields. And as the implementation of http_header_fields_t doesn't have checks on each field manipulation checking whether field name is `Connection` or `Content-Length` it is important to use proper member functions in derived classes for manipulating them.

Getting values of fields

Since v.0.4.9 there are two groups of methods for accessing values of fields. The first group returns `std::string` (or references/pointers to `std::string`). This group includes the following methods: get_field(), get_field_or(), try_get_field().

The second group returns `string_view_t` or `optional_t<string_view_t>`. This group includes the following methods: value_of() and opt_value_of().

The first group was created in early versions of RESTinio and is present here for historical and compatibility reasons. They are not deprecated yet but they could be deprecated in newer versions of RESTinio. Because of that the usage of value_of() and opt_value_of() is more preferable.

Definition at line 702 of file http_headers.hpp.

## Member Typedef Documentation

## const_iterator

using restinio::http_header_fields_t::const_iterator = fields_container_t::const_iterator

Type of const_iterator for enumeration of fields.

Definition at line 711 of file http_headers.hpp.

## fields_container_t

using restinio::http_header_fields_t::fields_container_t = std::vector< http_header_field_t >

Definition at line 708 of file http_headers.hpp.

## Member Enumeration Documentation

## handling_result_t

enum class restinio::http_header_fields_t::handling_result_t

strong

The result of handling yet another field value.

A value of that enumeration should be returned by a lambda-function passed to for_each_value_of() method.

Since
  v.0.6.9

Enumerator
continue_enumeration | Next value of field should be found and passed to the next invocation of handler.
stop_enumeration | The loop on field values should be stopped.

Definition at line 720 of file http_headers.hpp.

## Constructor & Destructor Documentation

## http_header_fields_t() [1/3]

restinio::http_header_fields_t::http_header_fields_t | ( |  | ) |

inline

Definition at line 735 of file http_headers.hpp.

## http_header_fields_t() [2/3]

restinio::http_header_fields_t::http_header_fields_t | ( | const http_header_fields_t & |  | ) |

default

## http_header_fields_t() [3/3]

restinio::http_header_fields_t::http_header_fields_t | ( | http_header_fields_t && |  | ) |

default

## ~http_header_fields_t()

virtual restinio::http_header_fields_t::~http_header_fields_t | ( |  | ) |

inlinevirtual

Definition at line 741 of file http_headers.hpp.

## Member Function Documentation

## add_field() [1/3]

void restinio::http_header_fields_t::add_field | ( | http_field_t | field_id,
|  | std::string | field_value
| ) |  |

inline

Add a field in the form of id-value pair.

If `field_id=http_field_t::field_unspecified` then function does nothing.

Note
  This method doesn't check the presence of the field. So it can be used for storing of several values of HTTP-field.

Since
  v.0.6.9

Definition at line 860 of file http_headers.hpp.

## add_field() [2/3]

void restinio::http_header_fields_t::add_field | ( | http_header_field_t | http_header_field | ) |

inline

Add a field in the form of http_header_field object.

Note
  This method doesn't check the presence of the field. So it can be used for storing of several values of HTTP-field.

Since
  v.0.6.9

Definition at line 901 of file http_headers.hpp.

## add_field() [3/3]

void restinio::http_header_fields_t::add_field | ( | std::string | field_name,
|  | std::string | field_value
| ) |  |

inline

Add a field in the form of name-value pair.

Note
  This method doesn't check the presence of the field. So it can be used for storing of several values of HTTP-field.

Since
  v.0.6.9

Definition at line 882 of file http_headers.hpp.

## append_field() [1/2]

void restinio::http_header_fields_t::append_field | ( | http_field_t | field_id,
|  | string_view_t | field_value
| ) |  |

inline

Append field with id.

If `field_id=http_field_t::field_unspecified` then function does nothing.

Definition at line 930 of file http_headers.hpp.

## append_field() [2/2]

void restinio::http_header_fields_t::append_field | ( | string_view_t | field_name,
|  | string_view_t | field_value
| ) |  |

inline

Append field with name.

Definition at line 908 of file http_headers.hpp.

## append_last_field()

void restinio::http_header_fields_t::append_last_field | ( | string_view_t | field_value | ) |

inlineprivate

Appends last added field.

This is function is used by http-parser when field value is created by 2 separate invocation of on-header-field-value callback

Function doesn't check if at least one field exists, so it is not in the public interface.

Definition at line 1509 of file http_headers.hpp.

## begin()

const_iterator restinio::http_header_fields_t::begin | ( |  | ) | const

inlinenoexcept

Definition at line 1482 of file http_headers.hpp.

## cfind() [1/2]

fields_container_t::const_iterator restinio::http_header_fields_t::cfind | ( | http_field_t | field_id | ) | const

inlineprivatenoexcept

Definition at line 1548 of file http_headers.hpp.

## cfind() [2/2]

fields_container_t::const_iterator restinio::http_header_fields_t::cfind | ( | string_view_t | field_name | ) | const

inlineprivatenoexcept

Definition at line 1526 of file http_headers.hpp.

## continue_enumeration()

static constexpr handling_result_t restinio::http_header_fields_t::continue_enumeration | ( |  | ) |

inlinestaticconstexprnoexcept

Definition at line 729 of file http_headers.hpp.

## end()

const_iterator restinio::http_header_fields_t::end | ( |  | ) | const

inlinenoexcept

Definition at line 1488 of file http_headers.hpp.

## fields_count()

auto restinio::http_header_fields_t::fields_count | ( |  | ) | const

inlinenoexcept

Definition at line 1493 of file http_headers.hpp.

## find() [1/2]

fields_container_t::iterator restinio::http_header_fields_t::find | ( | http_field_t | field_id | ) |

inlineprivatenoexcept

Definition at line 1537 of file http_headers.hpp.

## find() [2/2]

fields_container_t::iterator restinio::http_header_fields_t::find | ( | string_view_t | field_name | ) |

inlineprivatenoexcept

Definition at line 1515 of file http_headers.hpp.

## for_each_field()

template<typename Lambda >

void restinio::http_header_fields_t::for_each_field | ( | Lambda && | lambda | ) | const

inlinenoexcept

Enumeration of fields.

Calls lambda for each field in the container.

Lambda should have one of the following formats:

void(const http_header_field_t &);
void(http_header_field_t);

This method is `noexcept` if lambda is `noexcept`.

Usage example:

headers().for_each_field( [](const auto & f) {
std::cout << f.name() << ": " << f.value() << std::endl;
} );

Definition at line 1361 of file http_headers.hpp.

## for_each_value_of() [1/2]

template<typename Lambda >

void restinio::http_header_fields_t::for_each_value_of | ( | http_field_t | field_id,
|  | Lambda && | lambda
| ) |  | const

inlinenoexcept

Enumeration of each value of a field.

Calls lambda for each value of a field field_id.

Lambda should has one of the following formats:

restinio::http_header_fields_t::handling_result_t
(const restinio::string_view_t &);
restinio::http_header_fields_t::handling_result_t
(restinio::string_view_t);
restinio::http_header_fields_t::handling_result_t
handling_result_t
The result of handling yet another field value.
Definition: http_headers.hpp:721
restinio::string_view_t
nonstd::string_view string_view_t
Definition: string_view.hpp:19

Note
  The lambda can throw.

Attention
  The content of this http_header_fields_t shouldn't be changed during the enumeration (it means that fields can't be removed and new fields can't be added).

Usage example:

headers().for_each_value_of(restinio::http_field_t::transfer_encoding,
[](auto value) {
std::cout << "encoding: " << value << std::endl;
return restinio::http_header_fields_t::continue_enumeration();
} );
restinio::http_header_fields_t::continue_enumeration
static constexpr handling_result_t continue_enumeration() noexcept
Definition: http_headers.hpp:729

Definition at line 1401 of file http_headers.hpp.

## for_each_value_of() [2/2]

template<typename Lambda >

void restinio::http_header_fields_t::for_each_value_of | ( | string_view_t | field_name,
|  | Lambda && | lambda
| ) |  | const

inlinenoexcept

Enumeration of each value of a field.

Calls lambda for each value of a field field_name.

Lambda should has one of the following formats:

restinio::http_header_fields_t::handling_result_t
(const restinio::string_view_t &);
restinio::http_header_fields_t::handling_result_t
(restinio::string_view_t);

Note
  The lambda can throw.

Attention
  The content of this http_header_fields_t shouldn't be changed during the enumeration (it means that fields can't be removed and new fields can't be added).

Usage example:

headers().for_each_value_of("Transfer-Encoding",
[](auto value) {
std::cout << "encoding: " << value << std::endl;
return restinio::http_header_fields_t::continue_enumeration();
} );

Definition at line 1457 of file http_headers.hpp.

## get_field() [1/2]

const std::string & restinio::http_header_fields_t::get_field | ( | http_field_t | field_id | ) | const

inline

Get field by id.

Definition at line 986 of file http_headers.hpp.

## get_field() [2/2]

const std::string & restinio::http_header_fields_t::get_field | ( | string_view_t | field_name | ) | const

inline

Get field by name.

Definition at line 951 of file http_headers.hpp.

## get_field_or() [1/8]

auto restinio::http_header_fields_t::get_field_or | ( | http_field_t | field_id,
|  | const char * | default_value
| ) |  | const

inline

Get field by id or default value if the field not found.

This is just overload for get_field_or(http_field_t,string_view_t);

Definition at line 1122 of file http_headers.hpp.

## get_field_or() [2/8]

auto restinio::http_header_fields_t::get_field_or | ( | http_field_t | field_id,
|  | const std::string & | default_value
| ) |  | const

inline

Get field by id or default value if the field not found.

This is just overload for get_field_or(http_field_t,string_view_t);

Definition at line 1134 of file http_headers.hpp.

## get_field_or() [3/8]

std::string restinio::http_header_fields_t::get_field_or | ( | http_field_t | field_id,
|  | std::string && | default_value
| ) |  | const

inline

Get field by id or default value if the field not found.

Note
  This method returns field value as a new std::string instance, not a const reference to std::string.

Definition at line 1148 of file http_headers.hpp.

## get_field_or() [4/8]

std::string restinio::http_header_fields_t::get_field_or | ( | http_field_t | field_id,
|  | string_view_t | default_value
| ) |  | const

inline

Get field by id or default value if the field not found.

Note
  This method returns field value as a new std::string instance, not a const reference to std::string.

Definition at line 1102 of file http_headers.hpp.

## get_field_or() [5/8]

auto restinio::http_header_fields_t::get_field_or | ( | string_view_t | field_name,
|  | const char * | default_value
| ) |  | const

inline

Get field by name or default value if the field not found.

This is just overload for get_field_or(string_view_t,string_view_t);

Definition at line 1076 of file http_headers.hpp.

## get_field_or() [6/8]

auto restinio::http_header_fields_t::get_field_or | ( | string_view_t | field_name,
|  | const std::string & | default_value
| ) |  | const

inline

Get field by name or default value if the field not found.

This is just overload for get_field_or(string_view_t,string_view_t);

Definition at line 1088 of file http_headers.hpp.

## get_field_or() [7/8]

std::string restinio::http_header_fields_t::get_field_or | ( | string_view_t | field_name,
|  | std::string && | default_value
| ) |  | const

inline

Get field value by field name or default value if the field not found.

Note
  This method returns field value as a new std::string instance, not a const reference to std::string.

Definition at line 1059 of file http_headers.hpp.

## get_field_or() [8/8]

std::string restinio::http_header_fields_t::get_field_or | ( | string_view_t | field_name,
|  | string_view_t | default_value
| ) |  | const

inline

Get field value by field name or default value if the field not found.

Note
  This method returns field value as a new std::string instance, not a const reference to std::string.

Definition at line 1040 of file http_headers.hpp.

## has_field() [1/2]

bool restinio::http_header_fields_t::has_field | ( | http_field_t | field_id | ) | const

inlinenoexcept

Check field by field-id.

Note
  If `field_id=http_field_t::field_unspecified` then function returns not more than just a fact whether there is at least one unspecified field.

Definition at line 766 of file http_headers.hpp.

## has_field() [2/2]

bool restinio::http_header_fields_t::has_field | ( | string_view_t | field_name | ) | const

inlinenoexcept

Check field by name.

Definition at line 754 of file http_headers.hpp.

## operator=() [1/2]

http_header_fields_t & restinio::http_header_fields_t::operator= | ( | const http_header_fields_t & |  | ) |

default

## operator=() [2/2]

http_header_fields_t & restinio::http_header_fields_t::operator= | ( | http_header_fields_t && |  | ) |

default

## opt_value_of() [1/2]

optional_t< string_view_t > restinio::http_header_fields_t::opt_value_of | ( | http_field_t | field_id | ) | const

inlinenoexcept

Get optional value of a field.

Doesn't throw exception if the field is not found. Empty optional will be returned instead.

Usage example:

auto f = headers().opt_value_of(restinio::http_field::content_type);
if(f && *f == "text/plain")
...

Parameters

  field_id | ID of a field.

Definition at line 1325 of file http_headers.hpp.

## opt_value_of() [2/2]

optional_t< string_view_t > restinio::http_header_fields_t::opt_value_of | ( | string_view_t | name | ) | const

inlinenoexcept

Get optional value of a field.

Doesn't throw exception if the field is not found. Empty optional will be returned instead.

Usage example:

auto f = headers().opt_value_of("Content-Type");
if(f && *f == "text/plain")
...

Parameters

  name | Name of a field.

Definition at line 1300 of file http_headers.hpp.

## remove_all_of() [1/2]

std::size_t restinio::http_header_fields_t::remove_all_of | ( | http_field_t | field_id | ) |

inlinenoexcept

Remove all occurences of a field with specified id.

Returns
  the count of removed occurences.

Since
  v.0.6.9

Definition at line 1245 of file http_headers.hpp.

## remove_all_of() [2/2]

std::size_t restinio::http_header_fields_t::remove_all_of | ( | string_view_t | field_name | ) |

inlinenoexcept

Remove all occurences of a field with specified name.

Returns
  the count of removed occurences.

Since
  v.0.6.9

Definition at line 1221 of file http_headers.hpp.

## remove_field() [1/2]

bool restinio::http_header_fields_t::remove_field | ( | http_field_t | field_id | ) |

inlinenoexcept

Remove field by id.

If there are several occurences of field_id only the first one will be removed.

Note
  Since v.0.6.9 returns `true` if an occurence of a field with id field_id has been removed. The value `false` returned if there is no field with id field_id.

Definition at line 1198 of file http_headers.hpp.

## remove_field() [2/2]

bool restinio::http_header_fields_t::remove_field | ( | string_view_t | field_name | ) |

inlinenoexcept

Remove field by name.

If there are several occurences of field_name only the first one will be removed.

Note
  Since v.0.6.9 returns `true` if an occurence of a field with name field_name has been removed. The value `false` returned if there is no field with name field_name.

Definition at line 1174 of file http_headers.hpp.

## set_field() [1/3]

void restinio::http_header_fields_t::set_field | ( | http_field_t | field_id,
|  | std::string | field_value
| ) |  |

inline

Set field with id-value pair.

If `field_id=http_field_t::field_unspecified` then function does nothing.

Definition at line 826 of file http_headers.hpp.

## set_field() [2/3]

void restinio::http_header_fields_t::set_field | ( | http_header_field_t | http_header_field | ) |

inline

Set header field via http_header_field_t.

Definition at line 773 of file http_headers.hpp.

## set_field() [3/3]

void restinio::http_header_fields_t::set_field | ( | std::string | field_name,
|  | std::string | field_value
| ) |  |

inline

Set field with string pair.

Definition at line 801 of file http_headers.hpp.

## stop_enumeration()

static constexpr handling_result_t restinio::http_header_fields_t::stop_enumeration | ( |  | ) |

inlinestaticconstexprnoexcept

Definition at line 732 of file http_headers.hpp.

## swap_fields()

void restinio::http_header_fields_t::swap_fields | ( | http_header_fields_t & | http_header_fields | ) |

inline

Definition at line 747 of file http_headers.hpp.

## try_get_field() [1/2]

nullable_pointer_t< const std::string > restinio::http_header_fields_t::try_get_field | ( | http_field_t | field_id | ) | const

inlinenoexcept

Try to get the value of a field by field ID.

Note
  Returns nullptr if the field is not found.

Usage example:

auto f = headers().try_get_field(restinio::http_field::content_type);
if(f && *f == "text/plain")
...

Definition at line 1021 of file http_headers.hpp.

## try_get_field() [2/2]

nullable_pointer_t< const std::string > restinio::http_header_fields_t::try_get_field | ( | string_view_t | field_name | ) | const

inlinenoexcept

Try to get the value of a field by field name.

Note
  Returns nullptr if the field is not found.

Usage example:

auto f = headers().try_get_field("Content-Type");
if(f && *f == "text/plain")
...

Definition at line 975 of file http_headers.hpp.

## value_of() [1/2]

string_view_t restinio::http_header_fields_t::value_of | ( | http_field_t | field_id | ) | const

inline

Get the value of a field or throw if the field not found.

Parameters

  field_id | ID of a field.

Definition at line 1280 of file http_headers.hpp.

## value_of() [2/2]

string_view_t restinio::http_header_fields_t::value_of | ( | string_view_t | name | ) | const

inline

Get the value of a field or throw if the field not found.

Parameters

  name | Name of a field.

Definition at line 1271 of file http_headers.hpp.

## Friends And Related Function Documentation

## impl::append_last_field_accessor

void impl::append_last_field_accessor | ( | http_header_fields_t & | ,
|  | string_view_t |
| ) |  |

friend

## Member Data Documentation

## m_fields

fields_container_t restinio::http_header_fields_t::m_fields

private

Definition at line 1558 of file http_headers.hpp.

The documentation for this class was generated from the following file:

- restinio/http_headers.hpp