x::headersbase
is a non reference-counted container for
something that looks like a set of HTTP or MIME headers. This class
is typically not used directly, but via one of its two subclasses:
x::headersimpl<x::headersbase::crlf_endl>
or
x::headersimpl<x::headersbase::lf_endl>.
x::headersbase provides methods for using headers
that were already parsed. The two template-based subclasses provide methods
for parsing headers in environments where individual lines of text are
terminated by either the CRLF or
LF character sequence:
x::headersbase::lf_endl
Each header line is terminated by the LF
character.
x::headersbase::crlf_endl
Each header line is terminated by the
CRLF
character sequence.
Lone CR and LF characters
are syntactically considered to be a part of the header's contents.
x::headersimpl<x::headersbase::crlf_endl> headers; headers.parse(std::cin);
This example parses headers from an input stream. The headers may be also parsed from some arbitrary input sequence that's defined by an beginning and ending input iterators:
x::headersimpl<x::headersbase::crlf_endl> headers; headers.parse(buf.begin(), buf.end());
parse() interprets each line as
“header: value”. A line that begins with a whitespace
character is considered to be a continuation of the value from the
previous line. The combined, or “folded” value includes the
intervening LF or
CRLF.
x::headersbase::iterator and x::headersbase::const_iterator define opaque type that iterate over an associative multimap keyed by headers' names:
x::headersbase::const_iterator p(headers.find("Mime-Version")); if (p != headers.end()) std::cout << p->second.value() << std::endl;
x::headers defines a small subset of methods of a
std::multimap:
begin(),
end(),
find(),
equal_range(), and
erase() (several overloaded flavors).
Use equal_range() to process headers which may occur
more than once.
The multimap's iterators point to a pair whose
second value is
x::headersbase::header_map_val_t.
This class defines three methods:
name()Returns this header's name.
value()
Returns the value of the header. The leading and trailing whitespace
is trimmed off (but any internal
LF or
CRLF
sequences in folded headers are preserved as is).
begin() and end()
Returns a beginning and an ending iterator for a sequence that
defines the header's value. This is less expensive than
value().
x::headerbase's
list() returns a
const std::list<x::headerbase::header> & that contains
the entire set of headers, in their original order.
x::headerbase::header is a subclass of
std::string that
also implements the same
name(),
value(), and
nameiter() methods that are implemented by
x::headersbase::header_map_val_t.
The x::headersimpl
template subclass provides additional methods.
parse() was described previously.
to_string() is the opposite of
parse(), it formats the headers into an output
iterator.
append() adds a line of text to the parsed headers.
If the line starts with a space, the line is appended to the most recently
appended header.
replace() removes any existing header and replaces it.
These classes are not reference-counted objects, and must remain in scope as long as any instantiated iterator remains in scope.