add doc: min_element, max_element, minmax_element

source/libs/sprout/algorithm/index.rst

@@ -42,6 +42,9 @@ Sprout.Algorithm
     min
     max
     minmax
+    min_element
+    max_element
+    minmax_element
 
 .. _sprout-algorithm-non_modifying:
 *******************************************************************************

source/libs/sprout/algorithm/max.rst

@@ -70,7 +70,7 @@ Remarks
 ========================================
 
 | Returns a copy of the leftmost argument when several arguments are equivalent to the largest.
-| If an implementation not support C++14 initializer_list (SPROUT_NO_CXX14_INITIALIZER_LIST defined), then this function is not specified constexpr.
+| If an implementation not support C++14 initializer_list (``SPROUT_NO_CXX14_INITIALIZER_LIST`` defined), then this function is not specified constexpr.
 
 Complexity
 ========================================

source/libs/sprout/algorithm/max_element.rst

@@ -0,0 +1,49 @@
+.. _sprout-algorithm-max_element:
+###############################################################################
+max_element
+###############################################################################
+
+Interface
+========================================
+.. sourcecode:: c++
+
+  template<typename ForwardIterator>
+  inline SPROUT_CONSTEXPR ForwardIterator
+  max_element(ForwardIterator first, ForwardIterator last);
+  
+  template<typename ForwardIterator, typename Compare>
+  inline SPROUT_CONSTEXPR ForwardIterator
+  max_element(ForwardIterator first, ForwardIterator last, Compare comp);
+
+Returns
+========================================
+
+| The first iterator i in the range [first,last) such that for any iterator j in the range [first,last) the following corresponding conditions hold: ``!(*i < *j)`` or ``!comp(*i, *j)``.
+| Returns last if ``first == last``.
+
+Examples
+========================================
+.. sourcecode:: c++
+
+  #include <sprout/algorithm/max_element.hpp>
+  #include <sprout/array.hpp>
+  #include <sprout/container.hpp>
+  using namespace sprout;
+
+  SPROUT_STATIC_CONSTEXPR auto input = array<int, 10>{{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}};
+  SPROUT_STATIC_CONSTEXPR auto result = sprout::max_element(begin(input), end(input));
+  static_assert(*result == 10, "a min element is 10.");
+  static_assert(result - begin(input) == 9, "a min element position is 9.");
+
+Complexity
+========================================
+
+| Exactly ``max((last - first) - 1, 0)`` applications of the corresponding comparisons.
+| Recursive function invocations in *O(logN)* (logarithmic) depth.
+
+Header
+========================================
+
+| ``sprout/algorithm/max_element.hpp``
+| Convenience header: ``sprout/algorithm.hpp``
+

source/libs/sprout/algorithm/min.rst

@@ -70,7 +70,7 @@ Remarks
 ========================================
 
 | Returns a copy of the leftmost argument when several arguments are equivalent to the smallest.
-| If an implementation not support C++14 initializer_list (SPROUT_NO_CXX14_INITIALIZER_LIST defined), then this function is not specified constexpr.
+| If an implementation not support C++14 initializer_list (``SPROUT_NO_CXX14_INITIALIZER_LIST`` defined), then this function is not specified constexpr.
 
 Complexity
 ========================================

source/libs/sprout/algorithm/min_element.rst

@@ -0,0 +1,49 @@
+.. _sprout-algorithm-min_element:
+###############################################################################
+min_element
+###############################################################################
+
+Interface
+========================================
+.. sourcecode:: c++
+
+  template<typename ForwardIterator>
+  inline SPROUT_CONSTEXPR ForwardIterator
+  min_element(ForwardIterator first, ForwardIterator last);
+  
+  template<typename ForwardIterator, typename Compare>
+  inline SPROUT_CONSTEXPR ForwardIterator
+  min_element(ForwardIterator first, ForwardIterator last, Compare comp);
+
+Returns
+========================================
+
+| The first iterator i in the range [first,last) such that for any iterator j in the range [first,last) the following corresponding conditions hold: ``!(*j < *i)`` or ``!comp(*j, *i)``.
+| Returns last if ``first == last``.
+
+Examples
+========================================
+.. sourcecode:: c++
+
+  #include <sprout/algorithm/min_element.hpp>
+  #include <sprout/array.hpp>
+  #include <sprout/container.hpp>
+  using namespace sprout;
+
+  SPROUT_STATIC_CONSTEXPR auto input = array<int, 10>{{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}};
+  SPROUT_STATIC_CONSTEXPR auto result = sprout::min_element(begin(input), end(input));
+  static_assert(*result == 1, "a min element is 1.");
+  static_assert(result - begin(input) == 0, "a min element position is 0.");
+
+Complexity
+========================================
+
+| Exactly ``max((last - first) - 1, 0)`` applications of the corresponding comparisons.
+| Recursive function invocations in *O(logN)* (logarithmic) depth.
+
+Header
+========================================
+
+| ``sprout/algorithm/min_element.hpp``
+| Convenience header: ``sprout/algorithm.hpp``
+

source/libs/sprout/algorithm/minmax.rst

@@ -80,7 +80,7 @@ Remarks
 
 | x is a copy of the leftmost argument when several arguments are equivalent to the smallest.
 | y is a copy of the rightmost argument when several arguments are equivalent to the largest.
-| If an implementation not support C++14 initializer_list (SPROUT_NO_CXX14_INITIALIZER_LIST defined), then this function is not specified constexpr.
+| If an implementation not support C++14 initializer_list (``SPROUT_NO_CXX14_INITIALIZER_LIST`` defined), then this function is not specified constexpr.
 
 Complexity
 ========================================

source/libs/sprout/algorithm/minmax_element.rst

@@ -0,0 +1,50 @@
+.. _sprout-algorithm-minmax_element:
+###############################################################################
+minmax_element
+###############################################################################
+
+Interface
+========================================
+.. sourcecode:: c++
+
+  template<typename ForwardIterator>
+  inline SPROUT_CONSTEXPR sprout::pair<ForwardIterator, ForwardIterator>
+  minmax_element(ForwardIterator first, ForwardIterator last);
+  
+  template<typename ForwardIterator, typename Compare>
+  inline SPROUT_CONSTEXPR sprout::pair<ForwardIterator, ForwardIterator>
+  minmax_element(ForwardIterator first, ForwardIterator last, Compare comp);
+
+Returns
+========================================
+
+| ``make_pair(first, first)`` if [first,last) is empty, otherwise ``make_pair(m, M)``, where m is the first iterator in [first,last) such that no iterator in the range refers to a smaller element, and where M is the last iterator in [first,last) such that no iterator in the range refers to a larger element.
+
+Examples
+========================================
+.. sourcecode:: c++
+
+  #include <sprout/algorithm/minmax_element.hpp>
+  #include <sprout/array.hpp>
+  #include <sprout/container.hpp>
+  using namespace sprout;
+
+  SPROUT_STATIC_CONSTEXPR auto input = array<int, 10>{{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}};
+  SPROUT_STATIC_CONSTEXPR auto result = sprout::minmax_element(begin(input), end(input));
+  static_assert(*result.first == 1, "a min element is 1.");
+  static_assert(*result.second == 10, "a max element is 10.");
+  static_assert(result.first - begin(input) == 0, "a min element position is 0.");
+  static_assert(result.second - begin(input) == 9, "a max element position is 9.");
+
+Complexity
+========================================
+
+| At most ``max(floor((3/2)*(N - 1)), 0)`` applications of the corresponding predicate, where N is ``distance(first, last)``.
+| Recursive function invocations in *O(logN)* (logarithmic) depth.
+
+Header
+========================================
+
+| ``sprout/algorithm/minmax_element.hpp``
+| Convenience header: ``sprout/algorithm.hpp``
+