From 1cf19898c01b49f09cfb9b6287e66ccf94d54a46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ion=20Gazta=C3=B1aga?= Date: Sat, 19 Oct 2019 22:55:46 +0200 Subject: [PATCH] Fixes #132: flat_map::lower_bound and upper_bound have wrong/misleading docs --- doc/container.qbk | 10 +++++- include/boost/container/flat_map.hpp | 44 ++++++++++++------------- include/boost/container/flat_set.hpp | 22 ++++++------- include/boost/container/map.hpp | 48 ++++++++++++++-------------- include/boost/container/set.hpp | 22 ++++++------- 5 files changed, 77 insertions(+), 69 deletions(-) diff --git a/doc/container.qbk b/doc/container.qbk index 644f510..95d58ee 100644 --- a/doc/container.qbk +++ b/doc/container.qbk @@ -1319,6 +1319,14 @@ use [*Boost.Container]? There are several reasons for that: [section:release_notes Release Notes] +[section:release_notes_boost_1_72_00 Boost 1.72 Release] + +* Fixed bugs: + * [@https://github.com/boostorg/container/issues/132 GitHub #132: ['"flat_map::lower_bound and upper_bound have wrong/misleading docs"]]. + + +[endsect] + [section:release_notes_boost_1_71_00 Boost 1.71 Release] * Fixed bugs: @@ -1341,7 +1349,7 @@ use [*Boost.Container]? There are several reasons for that: * [classref boost::container::static_vector static_vector] can now have options, using [classref boost::container::static_vector_options static_vector_options]. Alignment and throwing behaviour can be be specified. - * [classref boost::container::small_vector small_vector] can now have options, using [classref boost::container::small_vector_options small_vector_options]. +* [classref boost::container::small_vector small_vector] can now have options, using [classref boost::container::small_vector_options small_vector_options]. Alignment and growth factor can be be specified. [endsect] diff --git a/include/boost/container/flat_map.hpp b/include/boost/container/flat_map.hpp index f1d5ed2..63e7ab1 100644 --- a/include/boost/container/flat_map.hpp +++ b/include/boost/container/flat_map.hpp @@ -1199,7 +1199,7 @@ class flat_map //! //! Throws: Nothing unless the comparison object throws. //! - //! Complexity: N log(a.size() + N) (N has the value source.size()) + //! Complexity: N log(size() + N) (N has the value source.size()) template BOOST_CONTAINER_FORCEINLINE void merge(flat_map& source) { m_flat_tree.merge_unique(source.tree()); } @@ -1269,7 +1269,7 @@ class flat_map && boost::container::dtl::is_nothrow_swappable::value ) { m_flat_tree.swap(x.m_flat_tree); } - //! Effects: erase(a.begin(),a.end()). + //! Effects: erase(begin(),end()). //! //! Postcondition: size() == 0. //! @@ -1376,14 +1376,14 @@ class flat_map { return m_flat_tree.find(x) != m_flat_tree.end(); } //! Returns: An iterator pointing to the first element with key not less - //! than k, or a.end() if such an element is not found. + //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic. BOOST_CONTAINER_FORCEINLINE iterator lower_bound(const key_type& x) { return dtl::force_copy(m_flat_tree.lower_bound(x)); } //! Returns: A const iterator pointing to the first element with key not - //! less than k, or a.end() if such an element is not found. + //! less than x, or end() if such an element is not found. //! //! Complexity: Logarithmic. BOOST_CONTAINER_FORCEINLINE const_iterator lower_bound(const key_type& x) const @@ -1393,7 +1393,7 @@ class flat_map //! key_compare::is_transparent exists. //! //! Returns: An iterator pointing to the first element with key not less - //! than k, or a.end() if such an element is not found. + //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic. template @@ -1404,22 +1404,22 @@ class flat_map //! key_compare::is_transparent exists. //! //! Returns: A const iterator pointing to the first element with key not - //! less than k, or a.end() if such an element is not found. + //! less than x, or end() if such an element is not found. //! //! Complexity: Logarithmic. template BOOST_CONTAINER_FORCEINLINE const_iterator lower_bound(const K& x) const { return dtl::force_copy(m_flat_tree.lower_bound(x)); } - //! Returns: An iterator pointing to the first element with key not less + //! Returns: An iterator pointing to the first element with key greater //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic. BOOST_CONTAINER_FORCEINLINE iterator upper_bound(const key_type& x) { return dtl::force_copy(m_flat_tree.upper_bound(x)); } - //! Returns: A const iterator pointing to the first element with key not - //! less than x, or end() if such an element is not found. + //! Returns: A const iterator pointing to the first element with key + //! greater than x, or end() if such an element is not found. //! //! Complexity: Logarithmic. BOOST_CONTAINER_FORCEINLINE const_iterator upper_bound(const key_type& x) const @@ -1428,7 +1428,7 @@ class flat_map //! Requires: This overload is available only if //! key_compare::is_transparent exists. //! - //! Returns: An iterator pointing to the first element with key not less + //! Returns: An iterator pointing to the first element with key greater //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic. @@ -1439,8 +1439,8 @@ class flat_map //! Requires: This overload is available only if //! key_compare::is_transparent exists. //! - //! Returns: A const iterator pointing to the first element with key not - //! less than x, or end() if such an element is not found. + //! Returns: A const iterator pointing to the first element with key + //! greater than x, or end() if such an element is not found. //! //! Complexity: Logarithmic. template @@ -2539,7 +2539,7 @@ class flat_multimap //! //! Throws: Nothing unless the comparison object throws. //! - //! Complexity: N log(a.size() + N) (N has the value source.size()) + //! Complexity: N log(size() + N) (N has the value source.size()) template BOOST_CONTAINER_FORCEINLINE void merge(flat_multimap& source) { m_flat_tree.merge_equal(source.tree()); } @@ -2609,7 +2609,7 @@ class flat_multimap && boost::container::dtl::is_nothrow_swappable::value ) { m_flat_tree.swap(x.m_flat_tree); } - //! Effects: erase(a.begin(),a.end()). + //! Effects: erase(begin(),end()). //! //! Postcondition: size() == 0. //! @@ -2714,14 +2714,14 @@ class flat_multimap { return m_flat_tree.find(x) != m_flat_tree.end(); } //! Returns: An iterator pointing to the first element with key not less - //! than k, or a.end() if such an element is not found. + //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic BOOST_CONTAINER_FORCEINLINE iterator lower_bound(const key_type& x) { return dtl::force_copy(m_flat_tree.lower_bound(x)); } //! Returns: An iterator pointing to the first element with key not less - //! than k, or a.end() if such an element is not found. + //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic BOOST_CONTAINER_FORCEINLINE const_iterator lower_bound(const key_type& x) const @@ -2731,7 +2731,7 @@ class flat_multimap //! key_compare::is_transparent exists. //! //! Returns: An iterator pointing to the first element with key not less - //! than k, or a.end() if such an element is not found. + //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic template @@ -2742,14 +2742,14 @@ class flat_multimap //! key_compare::is_transparent exists. //! //! Returns: An iterator pointing to the first element with key not less - //! than k, or a.end() if such an element is not found. + //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic template BOOST_CONTAINER_FORCEINLINE const_iterator lower_bound(const K& x) const { return dtl::force_copy(m_flat_tree.lower_bound(x)); } - //! Returns: An iterator pointing to the first element with key not less + //! Returns: An iterator pointing to the first element with key greater //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic @@ -2757,7 +2757,7 @@ class flat_multimap {return dtl::force_copy(m_flat_tree.upper_bound(x)); } //! Returns: A const iterator pointing to the first element with key - //! not less than x, or end() if such an element is not found. + //! greater than x, or end() if such an element is not found. //! //! Complexity: Logarithmic BOOST_CONTAINER_FORCEINLINE const_iterator upper_bound(const key_type& x) const @@ -2766,7 +2766,7 @@ class flat_multimap //! Requires: This overload is available only if //! key_compare::is_transparent exists. //! - //! Returns: An iterator pointing to the first element with key not less + //! Returns: An iterator pointing to the first element with key greater //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic @@ -2778,7 +2778,7 @@ class flat_multimap //! key_compare::is_transparent exists. //! //! Returns: A const iterator pointing to the first element with key - //! not less than x, or end() if such an element is not found. + //! greater than x, or end() if such an element is not found. //! //! Complexity: Logarithmic template diff --git a/include/boost/container/flat_set.hpp b/include/boost/container/flat_set.hpp index 7cb1d5c..7af8395 100644 --- a/include/boost/container/flat_set.hpp +++ b/include/boost/container/flat_set.hpp @@ -808,7 +808,7 @@ class flat_set BOOST_NOEXCEPT_IF( allocator_traits_type::is_always_equal::value && boost::container::dtl::is_nothrow_swappable::value ); - //! Effects: erase(a.begin(),a.end()). + //! Effects: erase(begin(),end()). //! //! Postcondition: size() == 0. //! @@ -948,13 +948,13 @@ class flat_set bool contains(const K& x) const; //! Returns: An iterator pointing to the first element with key not less - //! than k, or a.end() if such an element is not found. + //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic iterator lower_bound(const key_type& x); //! Returns: A const iterator pointing to the first element with key not - //! less than k, or a.end() if such an element is not found. + //! less than x, or end() if such an element is not found. //! //! Complexity: Logarithmic const_iterator lower_bound(const key_type& x) const; @@ -963,7 +963,7 @@ class flat_set //! key_compare::is_transparent exists. //! //! Returns: An iterator pointing to the first element with key not less - //! than k, or a.end() if such an element is not found. + //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic template @@ -973,20 +973,20 @@ class flat_set //! key_compare::is_transparent exists. //! //! Returns: A const iterator pointing to the first element with key not - //! less than k, or a.end() if such an element is not found. + //! less than x, or end() if such an element is not found. //! //! Complexity: Logarithmic template const_iterator lower_bound(const K& x) const; - //! Returns: An iterator pointing to the first element with key not less + //! Returns: An iterator pointing to the first element with key greater //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic iterator upper_bound(const key_type& x); - //! Returns: A const iterator pointing to the first element with key not - //! less than x, or end() if such an element is not found. + //! Returns: A const iterator pointing to the first element with key + //! greater than x, or end() if such an element is not found. //! //! Complexity: Logarithmic const_iterator upper_bound(const key_type& x) const; @@ -994,7 +994,7 @@ class flat_set //! Requires: This overload is available only if //! key_compare::is_transparent exists. //! - //! Returns: An iterator pointing to the first element with key not less + //! Returns: An iterator pointing to the first element with key greater //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic @@ -1004,8 +1004,8 @@ class flat_set //! Requires: This overload is available only if //! key_compare::is_transparent exists. //! - //! Returns: A const iterator pointing to the first element with key not - //! less than x, or end() if such an element is not found. + //! Returns: A const iterator pointing to the first element with key + //! greater than x, or end() if such an element is not found. //! //! Complexity: Logarithmic template diff --git a/include/boost/container/map.hpp b/include/boost/container/map.hpp index 447f4ad..477dcc1 100644 --- a/include/boost/container/map.hpp +++ b/include/boost/container/map.hpp @@ -993,7 +993,7 @@ class map //! //! Returns: A node_type owning the element if found, otherwise an empty node_type. //! - //! Complexity: log(a.size()). + //! Complexity: log(size()). node_type extract(const key_type& k) { typename base_t::node_type base_nh(this->base_t::extract(k)); @@ -1026,7 +1026,7 @@ class map //! //! Throws: Nothing unless the comparison object throws. //! - //! Complexity: N log(a.size() + N) (N has the value source.size()) + //! Complexity: N log(size() + N) (N has the value source.size()) template BOOST_CONTAINER_FORCEINLINE void merge(map& source) { @@ -1064,7 +1064,7 @@ class map BOOST_NOEXCEPT_IF( allocator_traits_type::is_always_equal::value && boost::container::dtl::is_nothrow_swappable::value ) - //! Effects: erase(a.begin(),a.end()). + //! Effects: erase(begin(),end()). //! //! Postcondition: size() == 0. //! @@ -1152,13 +1152,13 @@ class map bool contains(const K& x) const; //! Returns: An iterator pointing to the first element with key not less - //! than k, or a.end() if such an element is not found. + //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic iterator lower_bound(const key_type& x); //! Returns: A const iterator pointing to the first element with key not - //! less than k, or a.end() if such an element is not found. + //! less than x, or end() if such an element is not found. //! //! Complexity: Logarithmic const_iterator lower_bound(const key_type& x) const; @@ -1167,7 +1167,7 @@ class map //! key_compare::is_transparent exists. //! //! Returns: An iterator pointing to the first element with key not less - //! than k, or a.end() if such an element is not found. + //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic template @@ -1177,20 +1177,20 @@ class map //! key_compare::is_transparent exists. //! //! Returns: A const iterator pointing to the first element with key not - //! less than k, or a.end() if such an element is not found. + //! less than x, or end() if such an element is not found. //! //! Complexity: Logarithmic template const_iterator lower_bound(const K& x) const; - //! Returns: An iterator pointing to the first element with key not less + //! Returns: An iterator pointing to the first element with key greater //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic iterator upper_bound(const key_type& x); - //! Returns: A const iterator pointing to the first element with key not - //! less than x, or end() if such an element is not found. + //! Returns: A const iterator pointing to the first element with key + //! greater than x, or end() if such an element is not found. //! //! Complexity: Logarithmic const_iterator upper_bound(const key_type& x) const; @@ -1198,7 +1198,7 @@ class map //! Requires: This overload is available only if //! key_compare::is_transparent exists. //! - //! Returns: An iterator pointing to the first element with key not less + //! Returns: An iterator pointing to the first element with key greater //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic @@ -1208,8 +1208,8 @@ class map //! Requires: This overload is available only if //! key_compare::is_transparent exists. //! - //! Returns: A const iterator pointing to the first element with key not - //! less than x, or end() if such an element is not found. + //! Returns: A const iterator pointing to the first element with key + //! greater than x, or end() if such an element is not found. //! //! Complexity: Logarithmic template @@ -1981,7 +1981,7 @@ class multimap //! //! Throws: Nothing unless the comparison object throws. //! - //! Complexity: N log(a.size() + N) (N has the value source.size()) + //! Complexity: N log(size() + N) (N has the value source.size()) template BOOST_CONTAINER_FORCEINLINE void merge(multimap& source) { @@ -2087,13 +2087,13 @@ class multimap bool contains(const K& x) const; //! Returns: An iterator pointing to the first element with key not less - //! than k, or a.end() if such an element is not found. + //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic iterator lower_bound(const key_type& x); //! Returns: A const iterator pointing to the first element with key not - //! less than k, or a.end() if such an element is not found. + //! less than x, or end() if such an element is not found. //! //! Complexity: Logarithmic const_iterator lower_bound(const key_type& x) const; @@ -2102,7 +2102,7 @@ class multimap //! key_compare::is_transparent exists. //! //! Returns: An iterator pointing to the first element with key not less - //! than k, or a.end() if such an element is not found. + //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic template @@ -2112,20 +2112,20 @@ class multimap //! key_compare::is_transparent exists. //! //! Returns: A const iterator pointing to the first element with key not - //! less than k, or a.end() if such an element is not found. + //! less than x, or end() if such an element is not found. //! //! Complexity: Logarithmic template const_iterator lower_bound(const K& x) const; - //! Returns: An iterator pointing to the first element with key not less + //! Returns: An iterator pointing to the first element with key greater //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic iterator upper_bound(const key_type& x); - //! Returns: A const iterator pointing to the first element with key not - //! less than x, or end() if such an element is not found. + //! Returns: A const iterator pointing to the first element with key + //! greater than x, or end() if such an element is not found. //! //! Complexity: Logarithmic const_iterator upper_bound(const key_type& x) const; @@ -2133,7 +2133,7 @@ class multimap //! Requires: This overload is available only if //! key_compare::is_transparent exists. //! - //! Returns: An iterator pointing to the first element with key not less + //! Returns: An iterator pointing to the first element with key greater //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic @@ -2143,8 +2143,8 @@ class multimap //! Requires: This overload is available only if //! key_compare::is_transparent exists. //! - //! Returns: A const iterator pointing to the first element with key not - //! less than x, or end() if such an element is not found. + //! Returns: A const iterator pointing to the first element with key + //! greater than x, or end() if such an element is not found. //! //! Complexity: Logarithmic template diff --git a/include/boost/container/set.hpp b/include/boost/container/set.hpp index ca6334f..b216c01 100644 --- a/include/boost/container/set.hpp +++ b/include/boost/container/set.hpp @@ -718,7 +718,7 @@ class set BOOST_NOEXCEPT_IF( allocator_traits_type::is_always_equal::value && boost::container::dtl::is_nothrow_swappable::value ); - //! Effects: erase(a.begin(),a.end()). + //! Effects: erase(begin(),end()). //! //! Postcondition: size() == 0. //! @@ -806,13 +806,13 @@ class set bool contains(const K& x) const; //! Returns: An iterator pointing to the first element with key not less - //! than k, or a.end() if such an element is not found. + //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic iterator lower_bound(const key_type& x); //! Returns: A const iterator pointing to the first element with key not - //! less than k, or a.end() if such an element is not found. + //! less than x, or end() if such an element is not found. //! //! Complexity: Logarithmic const_iterator lower_bound(const key_type& x) const; @@ -821,7 +821,7 @@ class set //! key_compare::is_transparent exists. //! //! Returns: An iterator pointing to the first element with key not less - //! than k, or a.end() if such an element is not found. + //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic template @@ -831,20 +831,20 @@ class set //! key_compare::is_transparent exists. //! //! Returns: A const iterator pointing to the first element with key not - //! less than k, or a.end() if such an element is not found. + //! less than x, or end() if such an element is not found. //! //! Complexity: Logarithmic template const_iterator lower_bound(const K& x) const; - //! Returns: An iterator pointing to the first element with key not less + //! Returns: An iterator pointing to the first element with key greater //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic iterator upper_bound(const key_type& x); - //! Returns: A const iterator pointing to the first element with key not - //! less than x, or end() if such an element is not found. + //! Returns: A const iterator pointing to the first element with key + //! greater than x, or end() if such an element is not found. //! //! Complexity: Logarithmic const_iterator upper_bound(const key_type& x) const; @@ -852,7 +852,7 @@ class set //! Requires: This overload is available only if //! key_compare::is_transparent exists. //! - //! Returns: An iterator pointing to the first element with key not less + //! Returns: An iterator pointing to the first element with key greater //! than x, or end() if such an element is not found. //! //! Complexity: Logarithmic @@ -862,8 +862,8 @@ class set //! Requires: This overload is available only if //! key_compare::is_transparent exists. //! - //! Returns: A const iterator pointing to the first element with key not - //! less than x, or end() if such an element is not found. + //! Returns: A const iterator pointing to the first element with key + //! greater than x, or end() if such an element is not found. //! //! Complexity: Logarithmic template