Tidy up basic_headers for documentation

CHANGELOG.md

@@ -7,6 +7,7 @@
 * Parser callbacks may not throw
 * Fix Reader concept doc typo
 * Add is_Reader trait
+* Tidy up basic_headers for documentation
 
 API Changes:
 

include/beast/http/basic_headers.hpp

@@ -8,12 +8,9 @@
 #ifndef BEAST_HTTP_BASIC_HEADERS_HPP
 #define BEAST_HTTP_BASIC_HEADERS_HPP
 
-#include <beast/core/detail/ci_char_traits.hpp>
 #include <beast/core/detail/empty_base_optimization.hpp>
-#include <boost/intrusive/list.hpp>
-#include <boost/intrusive/set.hpp>
+#include <beast/http/detail/basic_headers.hpp>
 #include <boost/lexical_cast.hpp>
-#include <boost/utility/string_ref.hpp>
 #include <algorithm>
 #include <cctype>
 #include <memory>
@@ -24,217 +21,6 @@
 namespace beast {
 namespace http {
 
-template<class Allocator>
-class basic_headers;
-
-namespace detail {
-
-class basic_headers_base
-{
-public:
-    struct value_type
-    {
-        std::string first;
-        std::string second;
-
-        value_type(boost::string_ref const& name_,
-                boost::string_ref const& value_)
-            : first(name_)
-            , second(value_)
-        {
-        }
-
-        boost::string_ref
-        name() const
-        {
-            return first;
-        }
-
-        boost::string_ref
-        value() const
-        {
-            return second;
-        }
-    };
-
-protected:
-    template<class Allocator>
-    friend class beast::http::basic_headers;
-
-    struct element
-        : boost::intrusive::set_base_hook <
-            boost::intrusive::link_mode <
-                boost::intrusive::normal_link>>
-        , boost::intrusive::list_base_hook <
-            boost::intrusive::link_mode <
-                boost::intrusive::normal_link>>
-    {
-        value_type data;
-
-        element(boost::string_ref const& name,
-                boost::string_ref const& value)
-            : data(name, value)
-        {
-        }
-    };
-
-    struct less : private beast::detail::ci_less
-    {
-        template<class String>
-        bool
-        operator()(String const& lhs, element const& rhs) const
-        {
-            return ci_less::operator()(lhs, rhs.data.first);
-        }
-
-        template<class String>
-        bool
-        operator()(element const& lhs, String const& rhs) const
-        {
-            return ci_less::operator()(lhs.data.first, rhs);
-        }
-
-        bool
-        operator()(element const& lhs, element const& rhs) const
-        {
-            return ci_less::operator()(
-                lhs.data.first, rhs.data.first);
-        }
-    };
-
-    using list_t = typename boost::intrusive::make_list<
-        element, boost::intrusive::constant_time_size<false>>::type;
-
-    using set_t = typename boost::intrusive::make_multiset<
-        element, boost::intrusive::constant_time_size<true>,
-            boost::intrusive::compare<less>>::type;
-
-    // data
-    set_t set_;
-    list_t list_;
-
-    basic_headers_base(set_t&& set, list_t&& list)
-        : set_(std::move(set))
-        , list_(std::move(list))
-    {
-    }
-
-public:
-    class const_iterator;
-
-    using iterator = const_iterator;
-
-    basic_headers_base() = default;
-
-    /// Returns an iterator to the beginning of the field sequence.
-    iterator
-    begin() const;
-
-    /// Returns an iterator to the end of the field sequence.
-    iterator
-    end() const;
-
-    /// Returns an iterator to the beginning of the field sequence.
-    iterator
-    cbegin() const;
-
-    /// Returns an iterator to the end of the field sequence.
-    iterator
-    cend() const;
-};
-
-//------------------------------------------------------------------------------
-
-class basic_headers_base::const_iterator
-{
-    using iter_type = list_t::const_iterator;
-
-    iter_type it_;
-
-    template<class Allocator>
-    friend class beast::http::basic_headers;
-
-    friend class basic_headers_base;
-
-    const_iterator(iter_type it)
-        : it_(it)
-    {
-    }
-
-public:
-    using value_type =
-        typename basic_headers_base::value_type;
-    using pointer = value_type const*;
-    using reference = value_type const&;
-    using difference_type = std::ptrdiff_t;
-    using iterator_category =
-        std::bidirectional_iterator_tag;
-
-    const_iterator() = default;
-    const_iterator(const_iterator&& other) = default;
-    const_iterator(const_iterator const& other) = default;
-    const_iterator& operator=(const_iterator&& other) = default;
-    const_iterator& operator=(const_iterator const& other) = default;
-
-    bool
-    operator==(const_iterator const& other) const
-    {
-        return it_ == other.it_;
-    }
-
-    bool
-    operator!=(const_iterator const& other) const
-    {
-        return !(*this == other);
-    }
-
-    reference
-    operator*() const
-    {
-        return it_->data;
-    }
-
-    pointer
-    operator->() const
-    {
-        return &**this;
-    }
-
-    const_iterator&
-    operator++()
-    {
-        ++it_;
-        return *this;
-    }
-
-    const_iterator
-    operator++(int)
-    {
-        auto temp = *this;
-        ++(*this);
-        return temp;
-    }
-
-    const_iterator&
-    operator--()
-    {
-        --it_;
-        return *this;
-    }
-
-    const_iterator
-    operator--(int)
-    {
-        auto temp = *this;
-        --(*this);
-        return temp;
-    }
-};
-
-} // detail
-
-//------------------------------------------------------------------------------
-
 /** A container for storing HTTP headers.
 
     This container is designed to store the field value pairs that make
@@ -298,6 +84,24 @@ public:
     /// The type of allocator used.
     using allocator_type = Allocator;
 
+    /** The value type of the field sequence.
+
+        Meets the requirements of @b Field.
+    */
+#if GENERATING_DOCS
+    using value_type = implementation_defined;
+#endif
+
+    /// A const iterator to the field sequence
+#if GENERATING_DOCS
+    using iterator = implementation_defined;
+#endif
+
+    /// A const iterator to the field sequence
+#if GENERATING_DOCS
+    using const_iterator = implementation_defined;
+#endif
+
     /// Default constructor.
     basic_headers() = default;
 
@@ -359,6 +163,34 @@ public:
         return set_.size();
     }
 
+    /// Returns a const iterator to the beginning of the field sequence.
+    const_iterator
+    begin() const
+    {
+        return list_.cbegin();
+    }
+
+    /// Returns a const iterator to the end of the field sequence.
+    const_iterator
+    end() const
+    {
+        return list_.cend();
+    }
+
+    /// Returns a const iterator to the beginning of the field sequence.
+    const_iterator
+    cbegin() const
+    {
+        return list_.cbegin();
+    }
+
+    /// Returns a const iterator to the end of the field sequence.
+    const_iterator
+    cend() const
+    {
+        return list_.cend();
+    }
+
     /// Returns `true` if the specified field exists.
     bool
     exists(boost::string_ref const& name) const

include/beast/http/detail/basic_headers.hpp

@@ -0,0 +1,214 @@
+//
+// Copyright (c) 2013-2016 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)
+//
+
+#ifndef BEAST_HTTP_DETAIL_BASIC_HEADERS_HPP
+#define BEAST_HTTP_DETAIL_BASIC_HEADERS_HPP
+
+#include <beast/core/detail/ci_char_traits.hpp>
+#include <boost/intrusive/list.hpp>
+#include <boost/intrusive/set.hpp>
+#include <boost/utility/string_ref.hpp>
+
+namespace beast {
+namespace http {
+
+template<class Allocator>
+class basic_headers;
+
+namespace detail {
+
+class basic_headers_base
+{
+public:
+    struct value_type
+    {
+        std::string first;
+        std::string second;
+
+        value_type(boost::string_ref const& name_,
+                boost::string_ref const& value_)
+            : first(name_)
+            , second(value_)
+        {
+        }
+
+        boost::string_ref
+        name() const
+        {
+            return first;
+        }
+
+        boost::string_ref
+        value() const
+        {
+            return second;
+        }
+    };
+
+protected:
+    template<class Allocator>
+    friend class beast::http::basic_headers;
+
+    struct element
+        : boost::intrusive::set_base_hook <
+            boost::intrusive::link_mode <
+                boost::intrusive::normal_link>>
+        , boost::intrusive::list_base_hook <
+            boost::intrusive::link_mode <
+                boost::intrusive::normal_link>>
+    {
+        value_type data;
+
+        element(boost::string_ref const& name,
+                boost::string_ref const& value)
+            : data(name, value)
+        {
+        }
+    };
+
+    struct less : private beast::detail::ci_less
+    {
+        template<class String>
+        bool
+        operator()(String const& lhs, element const& rhs) const
+        {
+            return ci_less::operator()(lhs, rhs.data.first);
+        }
+
+        template<class String>
+        bool
+        operator()(element const& lhs, String const& rhs) const
+        {
+            return ci_less::operator()(lhs.data.first, rhs);
+        }
+
+        bool
+        operator()(element const& lhs, element const& rhs) const
+        {
+            return ci_less::operator()(
+                lhs.data.first, rhs.data.first);
+        }
+    };
+
+    using list_t = typename boost::intrusive::make_list<
+        element, boost::intrusive::constant_time_size<false>>::type;
+
+    using set_t = typename boost::intrusive::make_multiset<
+        element, boost::intrusive::constant_time_size<true>,
+            boost::intrusive::compare<less>>::type;
+
+    // data
+    set_t set_;
+    list_t list_;
+
+    basic_headers_base(set_t&& set, list_t&& list)
+        : set_(std::move(set))
+        , list_(std::move(list))
+    {
+    }
+
+public:
+    class const_iterator;
+
+    using iterator = const_iterator;
+
+    basic_headers_base() = default;
+};
+
+//------------------------------------------------------------------------------
+
+class basic_headers_base::const_iterator
+{
+    using iter_type = list_t::const_iterator;
+
+    iter_type it_;
+
+    template<class Allocator>
+    friend class beast::http::basic_headers;
+
+    friend class basic_headers_base;
+
+    const_iterator(iter_type it)
+        : it_(it)
+    {
+    }
+
+public:
+    using value_type =
+        typename basic_headers_base::value_type;
+    using pointer = value_type const*;
+    using reference = value_type const&;
+    using difference_type = std::ptrdiff_t;
+    using iterator_category =
+        std::bidirectional_iterator_tag;
+
+    const_iterator() = default;
+    const_iterator(const_iterator&& other) = default;
+    const_iterator(const_iterator const& other) = default;
+    const_iterator& operator=(const_iterator&& other) = default;
+    const_iterator& operator=(const_iterator const& other) = default;
+
+    bool
+    operator==(const_iterator const& other) const
+    {
+        return it_ == other.it_;
+    }
+
+    bool
+    operator!=(const_iterator const& other) const
+    {
+        return !(*this == other);
+    }
+
+    reference
+    operator*() const
+    {
+        return it_->data;
+    }
+
+    pointer
+    operator->() const
+    {
+        return &**this;
+    }
+
+    const_iterator&
+    operator++()
+    {
+        ++it_;
+        return *this;
+    }
+
+    const_iterator
+    operator++(int)
+    {
+        auto temp = *this;
+        ++(*this);
+        return temp;
+    }
+
+    const_iterator&
+    operator--()
+    {
+        --it_;
+        return *this;
+    }
+
+    const_iterator
+    operator--(int)
+    {
+        auto temp = *this;
+        --(*this);
+        return temp;
+    }
+};
+
+} // detail
+} // http
+} // beast
+
+#endif

include/beast/http/impl/basic_headers.ipp

@@ -14,44 +14,6 @@
 namespace beast {
 namespace http {
 
-namespace detail {
-
-inline
-auto
-basic_headers_base::begin() const ->
-    const_iterator
-{
-    return list_.cbegin();
-}
-
-inline
-auto
-basic_headers_base::end() const ->
-    const_iterator
-{
-    return list_.cend();
-}
-
-inline
-auto
-basic_headers_base::cbegin() const ->
-    const_iterator
-{
-    return list_.cbegin();
-}
-
-inline
-auto
-basic_headers_base::cend() const ->
-    const_iterator
-{
-    return list_.cend();
-}
-
-} // detail
-
-//------------------------------------------------------------------------------
-
 template<class Allocator>
 void
 basic_headers<Allocator>::