This is the mail archive of the
libstdc++@gcc.gnu.org
mailing list for the libstdc++ project.
doxygen comments for stl_algo.h
Here is a patch for include/bits/stl_algo.h that adds doxygen hooks for:
for_each find find_if adjacent_find count count_if search search_n
That's about 20% of the file covered, so I'd like to get feedback on
whether what I'm writing is suitable, particularly for search, which is
quite a complicated algorithm to explain without being too vague or too
technical (I thought so anyway)
There are lots of things not done yet, such as general descriptions of the
sequence operations, and linking to definition of Binary Predicates,
because (as far as I know) those definitions don't exist yet, but there
are descriptions of the functions and their return values etc..
a copy of the generated html is here:
http://www.redi.uklinux.net/libstdc++/namespacestd.html
Are the comments too technical? Too much [first1, last1 - last2 + first2)
techno-babble for the users who'll be referring to it? Or not technical
enough?
I think they're ok, but I've just been immersed in the standard and
references to write them, so might have lost perspective!
If these comments are suitable I will finish the rest of the file and
submit a patch for the whole thing (with changelog etc.)
Grateful for any feedback,
Jon
Index: include/bits/stl_algo.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/stl_algo.h,v
retrieving revision 1.19
diff -c -3 -p -r1.19 stl_algo.h
*** stl_algo.h 2002/01/25 04:14:38 1.19
--- stl_algo.h 2002/02/05 01:56:12
***************
*** 1,4 ****
! // Algorithm implimentation -*- C++ -*-
// Copyright (C) 2001, 2002 Free Software Foundation, Inc.
//
--- 1,4 ----
! // Algorithm implementation -*- C++ -*-
// Copyright (C) 2001, 2002 Free Software Foundation, Inc.
//
***************
*** 69,76 ****
namespace std
{
! // __median (an extension, not present in the C++ standard).
!
template<typename _Tp>
inline const _Tp&
__median(const _Tp& __a, const _Tp& __b, const _Tp& __c)
--- 69,79 ----
namespace std
{
! /**
! * @maint
! * This is an extension, not present in the C++ standard.
! * @endmaint
! */
template<typename _Tp>
inline const _Tp&
__median(const _Tp& __a, const _Tp& __b, const _Tp& __c)
*************** namespace std
*** 92,97 ****
--- 95,105 ----
return __b;
}
+ /**
+ * @maint
+ * This is an extension, not present in the C++ standard.
+ * @endmaint
+ */
template<typename _Tp, typename _Compare>
inline const _Tp&
__median(const _Tp& __a, const _Tp& __b, const _Tp& __c, _Compare __comp)
*************** namespace std
*** 113,119 ****
return __b;
}
! // for_each. Apply a function to every element of a range.
template<typename _InputIter, typename _Function>
_Function
for_each(_InputIter __first, _InputIter __last, _Function __f)
--- 121,138 ----
return __b;
}
! /**
! * @brief Apply a function to every element of a sequence.
! * @param first An input iterator.
! * @param last An input iterator.
! * @param f The function object.
! * @return @a f.
! *
! * Applies the function object @a f to each element in the range
! * @a [first,last).
! * @a f should not modify its argument.
! * If @a f has a return value it is ignored.
! */
template<typename _InputIter, typename _Function>
_Function
for_each(_InputIter __first, _InputIter __last, _Function __f)
*************** namespace std
*** 124,132 ****
__f(*__first);
return __f;
}
-
- // find and find_if.
template<typename _InputIter, typename _Tp>
inline _InputIter
find(_InputIter __first, _InputIter __last,
--- 143,154 ----
__f(*__first);
return __f;
}
+ /**
+ * @maint
+ * This is an overload used by find() for the Input Iterator case.
+ * @endmaint
+ */
template<typename _InputIter, typename _Tp>
inline _InputIter
find(_InputIter __first, _InputIter __last,
*************** namespace std
*** 138,143 ****
--- 160,170 ----
return __first;
}
+ /**
+ * @maint
+ * This is an overload used by find_if() for the Input Iterator case.
+ * @endmaint
+ */
template<typename _InputIter, typename _Predicate>
inline _InputIter
find_if(_InputIter __first, _InputIter __last,
*************** namespace std
*** 149,154 ****
--- 176,186 ----
return __first;
}
+ /**
+ * @maint
+ * This is an overload used by find() for the Random Access Iterator case.
+ * @endmaint
+ */
template<typename _RandomAccessIter, typename _Tp>
_RandomAccessIter
find(_RandomAccessIter __first, _RandomAccessIter __last,
*************** namespace std
*** 188,193 ****
--- 220,230 ----
}
}
+ /**
+ * @maint
+ * This is an overload used by find_if() for the Random Access Iterator case.
+ * @endmaint
+ */
template<typename _RandomAccessIter, typename _Predicate>
_RandomAccessIter
find_if(_RandomAccessIter __first, _RandomAccessIter __last,
*************** namespace std
*** 227,232 ****
--- 264,279 ----
}
}
+ /**
+ * @brief Find the first occurrence of a value in a sequence.
+ * @param first An input iterator.
+ * @param last An input iterator.
+ * @param val The value to find in the range.
+ * @return The first iterator @c i in the range @p [first,last)
+ * such that @c *i == @p val, or @p last if no such iterator exists.
+ *
+ * @p val must be equality comparable so that @c *i == @p val works.
+ */
template<typename _InputIter, typename _Tp>
inline _InputIter
find(_InputIter __first, _InputIter __last,
*************** namespace std
*** 239,244 ****
--- 286,302 ----
return find(__first, __last, __val, __iterator_category(__first));
}
+ /**
+ * @brief Find the first element in a sequence for which a predicate is true.
+ * @param first An input iterator.
+ * @param last An input iterator.
+ * @param pred The predicate.
+ * @return The first iterator @c i in the range @p [first,last) such that
+ * @c pred(*i) is true, or @p last if no such iterator exists.
+ *
+ * @p val must be equality comparable so that @c *i == @p val works.
+ * The predicate is evaluated at most @p last - @p first times.
+ */
template<typename _InputIter, typename _Predicate>
inline _InputIter
find_if(_InputIter __first, _InputIter __last,
*************** namespace std
*** 250,258 ****
typename iterator_traits<_InputIter>::value_type>)
return find_if(__first, __last, __pred, __iterator_category(__first));
}
-
- // adjacent_find.
template<typename _ForwardIter>
_ForwardIter
adjacent_find(_ForwardIter __first, _ForwardIter __last)
--- 308,322 ----
typename iterator_traits<_InputIter>::value_type>)
return find_if(__first, __last, __pred, __iterator_category(__first));
}
+ /**
+ * @brief Find two equal adjacent values in a sequence.
+ * @param first A forward iterator.
+ * @param last A forward iterator.
+ * @return The first iterator @c i such that @c i and @c i+1 are both
+ * valid iterators in @p [first,last) and such that @c *i == @c *(i+1),
+ * or @p last if no such iterator exists.
+ */
template<typename _ForwardIter>
_ForwardIter
adjacent_find(_ForwardIter __first, _ForwardIter __last)
*************** namespace std
*** 272,277 ****
--- 336,350 ----
return __last;
}
+ /**
+ * @brief Find two adjacent values in a sequence for which a predicate
+ * is true for both values.
+ * @param first A forward iterator.
+ * @param last A forward iterator.
+ * @return The first iterator @c i such that @c i and @c i+1 are both
+ * valid iterators in @p [first,last) and such that @c binary_pred(*i,*(i+1))
+ * is true, or @p last if no such iterator exists.
+ */
template<typename _ForwardIter, typename _BinaryPredicate>
_ForwardIter
adjacent_find(_ForwardIter __first, _ForwardIter __last,
*************** namespace std
*** 293,300 ****
return __last;
}
! // count and count_if.
!
template<typename _InputIter, typename _Tp>
typename iterator_traits<_InputIter>::difference_type
count(_InputIter __first, _InputIter __last, const _Tp& __value)
--- 366,381 ----
return __last;
}
! /**
! * @brief Count the number of copies of a value in a sequence.
! * @param first An input iterator.
! * @param last An input iterator.
! * @param value The value.
! * @return The number of iterators @c i in the range @p [first,last)
! * for which @c *i == @p value
! *
! * @a value must be an object of an equality comparable type.
! */
template<typename _InputIter, typename _Tp>
typename iterator_traits<_InputIter>::difference_type
count(_InputIter __first, _InputIter __last, const _Tp& __value)
*************** namespace std
*** 311,316 ****
--- 392,407 ----
return __n;
}
+ /**
+ * @brief Count the elements of a sequence for which a predicate is true.
+ * @param first An input iterator.
+ * @param last An input iterator.
+ * @param pred The predicate.
+ * @return The number of iterators @c i in the range @p [first,last)
+ * for which @c pred(*i) is true.
+ *
+ * The predicate is evaluated exactly @p last - @p first times.
+ */
template<typename _InputIter, typename _Predicate>
typename iterator_traits<_InputIter>::difference_type
count_if(_InputIter __first, _InputIter __last, _Predicate __pred)
*************** namespace std
*** 326,334 ****
return __n;
}
-
- // search.
template<typename _ForwardIter1, typename _ForwardIter2>
_ForwardIter1
search(_ForwardIter1 __first1, _ForwardIter1 __last1,
--- 417,444 ----
return __n;
}
+ /**
+ * @brief Search a sequence for a matching sub-sequence.
+ * @param first1 A forward iterator.
+ * @param last1 A forward iterator.
+ * @param first2 A forward iterator.
+ * @param last2 A forward iterator.
+ * @return The first iterator @c i in the range
+ * @p [first1,last1-(last2-first2)) such that @c *(i+N) == @c *(first2+N)
+ * for each @c N in the range @c [0,last2-first2), or @p last1 if no
+ * such iterator exists.
+ *
+ * Searches the range @p [first1,last1) for a sub-sequence that compares
+ * equal value-by-value with the sequence given by @p [first2,last2)
+ * and returns an iterator to the first element of the sub-sequence if found.
+ * Because the sub-sequence must lie completely within the range
+ * @p [first1,last1) it must start at a position less than
+ * @p last1-(last2-first2) where @p last2-first2 is the length of the
+ * sub-sequence.
+ * This means that the returned iterator @c i will be in the range
+ * @p [first1,last1-(last2-first2))
+ */
template<typename _ForwardIter1, typename _ForwardIter2>
_ForwardIter1
search(_ForwardIter1 __first1, _ForwardIter1 __last1,
*************** namespace std
*** 381,386 ****
--- 491,514 ----
return __first1;
}
+ /**
+ * @brief Search a sequence for a matching sub-sequence using a predicate.
+ * @param first1 A forward iterator.
+ * @param last1 A forward iterator.
+ * @param first2 A forward iterator.
+ * @param last2 A forward iterator.
+ * @param pred A binary predicate.
+ * @return The first iterator @c i in the range
+ * @p [first1,last1-(last2-first2)) such that @p pred(*(i+N),*(first2+N))
+ * is true for each @c N in the range @p [0,last2-first2),
+ * or @p last1 if no such iterator exists.
+ *
+ * Searches the range @p [first1,last1) for a sub-sequence that compares
+ * equal value-by-value with the sequence given by @p [first2,last2),
+ * using @p predicate to determine equality,
+ * and returns an iterator to the first element of the sub-sequence if found.
+ * @see search(_ForwardIter1, _ForwardIter1, _ForwardIter2, _ForwardIter2)
+ */
template<typename _ForwardIter1, typename _ForwardIter2, typename _BinaryPred>
_ForwardIter1
search(_ForwardIter1 __first1, _ForwardIter1 __last1,
*************** namespace std
*** 441,449 ****
}
return __first1;
}
-
- // search_n. Search for __count consecutive copies of __val.
template<typename _ForwardIter, typename _Integer, typename _Tp>
_ForwardIter
search_n(_ForwardIter __first, _ForwardIter __last,
--- 569,588 ----
}
return __first1;
}
+ /**
+ * @brief Search a sequence for a number of consecutive values.
+ * @param first A forward iterator.
+ * @param last A forward iterator.
+ * @param count The number of consecutive values to search for.
+ * @param val The value to search for.
+ * @return The first iterator @c i in the range @p [first,last-count)
+ * such that @c *(i+N) == @p val for each @c N in the range @p [0,count),
+ * or @p last if no such iterator exists.
+ *
+ * Searches the range @p [first,last) for @p count consecutive copies
+ * of @p val.
+ */
template<typename _ForwardIter, typename _Integer, typename _Tp>
_ForwardIter
search_n(_ForwardIter __first, _ForwardIter __last,
*************** namespace std
*** 476,481 ****
--- 615,635 ----
}
}
+ /**
+ * @brief Search a sequence for a number of consecutive values using a
+ * predicate.
+ * @param first A forward iterator.
+ * @param last A forward iterator.
+ * @param count The number of consecutive values to search for.
+ * @param val The value to search for.
+ * @param pred A binary predicate.
+ * @return The first iterator @c i in the range
+ * @p [first,last-count) such that @p pred(*(i+N),val) is true for each
+ * @c N in the range @p [0,count), or @p last if no such iterator exists.
+ *
+ * Searches the range @p [first,last) for @p count consecutive values
+ * that compare equal to @p val according to @p pred.
+ */
template<typename _ForwardIter, typename _Integer, typename _Tp,
typename _BinaryPred>
_ForwardIter