Add documents and comments.

2013-07-25  Tim Shen  <timshen91@gmail.com>

	Add documents and comments.
	* include/bits/regex.h: Documents and comments.
	* include/bits/regex_grep_matcher.h: Likewise.
	* include/bits/regex_grep_matcher.tcc: Likewise.
	* testsuite/28_regex/iterators/regex_iterator/char/string_position_01.cc:
	New.

From-SVN: r201244

libstdc++-v3/ChangeLog

+2013-07-25  Tim Shen  <timshen91@gmail.com>
+
+	Add documents and comments.
+	* include/bits/regex.h: Documents and comments.
+	* include/bits/regex_grep_matcher.h: Likewise.
+	* include/bits/regex_grep_matcher.tcc: Likewise.
+	* testsuite/28_regex/iterators/regex_iterator/char/string_position_01.cc:
+	New.
+
 2013-07-24  Paolo Carlini  <paolo.carlini@oracle.com>
 
 	PR libstdc++/57976

libstdc++-v3/include/bits/regex.h

@@ -61,7 +61,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
           _BaseType _M_base;
           unsigned char _M_extended;
           static constexpr unsigned char _S_under = 1 << 0;
-          // _S_blank should be removed in the future, when locale's complete.
+          // FIXME: _S_blank should be removed in the future, when locale's complete.
           static constexpr unsigned char _S_blank = 1 << 1;
           static constexpr unsigned char _S_valid_mask = 0x3;
 
@@ -2364,7 +2364,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    * @param __flags [IN]  Search policy flags.
    * @retval true  A match was found within the string.
    * @retval false No match was found within the string.
-   * @doctodo
    *
    * @throws an exception of type regex_error.
    */
@@ -2388,7 +2387,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    * @retval true  A match was found within the string.
    * @retval false No match was found within the string, the content of %m is
    *               undefined.
-   * @doctodo
    *
    * @throws an exception of type regex_error.
    */
@@ -2408,7 +2406,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    * @param __f [IN]  Search policy flags.
    * @retval true  A match was found within the string.
    * @retval false No match was found within the string.
-   * @doctodo
    *
    * @throws an exception of type regex_error.
    */
@@ -2427,7 +2424,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    * @param __flags [IN]  Search policy flags.
    * @retval true  A match was found within the string.
    * @retval false No match was found within the string.
-   * @doctodo
    *
    * @throws an exception of type regex_error.
    */
@@ -2538,7 +2534,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       /**
        * @brief Provides a singular iterator, useful for indicating
        * one-past-the-end of a range.
-       * @doctodo
        */
       regex_iterator()
       : _M_match()
@@ -2550,7 +2545,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
        * @param __b  [IN] One-past-the-end of the text range to search.
        * @param __re [IN] The regular expression to match.
        * @param __m  [IN] Policy flags for match rules.
-       * @doctodo
        */
       regex_iterator(_Bi_iter __a, _Bi_iter __b, const regex_type& __re,
 		     regex_constants::match_flag_type __m
@@ -2560,51 +2554,50 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
       /**
        * Copy constructs a %regex_iterator.
-       * @doctodo
        */
       regex_iterator(const regex_iterator& __rhs) = default;
       
       /**
-       * @doctodo
+       * @brief Assigns one %regex_iterator to another.
        */
       regex_iterator&
       operator=(const regex_iterator& __rhs) = default;
       
       /**
-       * @doctodo
+       * @brief Tests the equivalence of two regex iterators.
        */
       bool
       operator==(const regex_iterator& __rhs) const;
       
       /**
-       * @doctodo
+       * @brief Tests the inequivalence of two regex iterators.
        */
       bool
       operator!=(const regex_iterator& __rhs) const
       { return !(*this == __rhs); }
       
       /**
-       * @doctodo
+       * @brief Dereferences a %regex_iterator.
        */
       const value_type&
       operator*() const
       { return _M_match; }
       
       /**
-       * @doctodo
+       * @brief Selects a %regex_iterator member.
        */
       const value_type*
       operator->() const
       { return &_M_match; }
       
       /**
-       * @doctodo
+       * @brief Increments a %regex_iterator.
        */
       regex_iterator&
       operator++();
       
       /**
-       * @doctodo
+       * @brief Postincrements a %regex_iterator.
        */
       regex_iterator
       operator++(int)
@@ -2615,7 +2608,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       }
       
     private:
-      // these members are shown for exposition only:
       _Bi_iter                         _M_begin;
       _Bi_iter                         _M_end;
       const regex_type*                _M_pregex;
@@ -2645,6 +2637,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     regex_iterator<_Bi_iter, _Ch_type, _Rx_traits>::
     operator++()
     {
+      // FIXME: In all cases in which the call to regex_search returns true,
+      // match.prefix().first shall be equal to the previous value of
+      // match[0].second, and for each index i in the half-open range
+      // [0, match.size()) for which match[i].matched is true,
+      // match[i].position() shall return distance(begin, match[i].first).
+      // [28.12.1.4.5]
       if (_M_match[0].matched)
         {
           auto __start = _M_match[0].second;
@@ -2726,8 +2724,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
        *                        - >0 enumerates only the indicated
        *                          subexpression from a match within the text.
        * @param __m          [IN] Policy flags for match rules.
-       *
-       * @doctodo
        */
       regex_token_iterator(_Bi_iter __a, _Bi_iter __b, const regex_type& __re,
 			   int __submatch = 0,
@@ -2744,8 +2740,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
        * @param __submatches [IN] A list of subexpressions to return for each
        *                          regular expression match within the text.
        * @param __m          [IN] Policy flags for match rules.
-       *
-       * @doctodo
        */
       regex_token_iterator(_Bi_iter __a, _Bi_iter __b,
 			   const regex_type& __re,
@@ -2763,8 +2757,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
        * @param __submatches [IN] A list of subexpressions to return for each
        *                          regular expression match within the text.
        * @param __m          [IN] Policy flags for match rules.
-       *
-       * @doctodo
        */
       regex_token_iterator(_Bi_iter __a, _Bi_iter __b,
 			   const regex_type& __re,
@@ -2782,8 +2774,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
        * @param __submatches [IN] A list of subexpressions to return for each
        *                          regular expression match within the text.
        * @param __m          [IN] Policy flags for match rules.
-       *
-       * @doctodo
        */
       template<std::size_t _Nm>
         regex_token_iterator(_Bi_iter __a, _Bi_iter __b,
@@ -2859,7 +2849,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
         return __tmp;
       }
 
-    private: // data members for exposition only:
+    private:
       typedef regex_iterator<_Bi_iter, _Ch_type, _Rx_traits> _Position;
 
       void
@@ -2884,7 +2874,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       std::size_t       _M_n;
       std::vector<int>  _M_subs;
 
-      bool              _M_has_m1; // subs contains -1
+      // Show whether _M_subs contains -1
+      bool              _M_has_m1;
     };
 
   template<typename _Bi_iter,

libstdc++-v3/include/bits/regex_grep_matcher.h

@@ -127,16 +127,21 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       _M_pattern(__p), _M_results(__r)
     { }
 
+    // Set matched when string exactly match the pattern.
     void
     _M_match();
 
+    // Set matched when some prefix of the string matches the pattern.
     void
     _M_search_from_first();
 
+    // TODO: in the future this function will be _M_match, in another class.
     bool
     _M_dfs_match()
     { return _M_dfs<true>(_M_nfa->_M_start()); }
 
+    // TODO: in the future this function will be _M_search_from_first,
+    // in another class.
     bool
     _M_dfs_search_from_first()
     { return _M_dfs<false>(_M_nfa->_M_start()); }

libstdc++-v3/include/bits/regex_grep_matcher.tcc

@@ -121,6 +121,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
         case _S_opcode_alternative:
           // Greedy mode by default. For non-greedy mode,
           // swap _M_alt and _M_next.
+          // TODO: Add greedy mode option.
           __ret = _M_dfs<__match_mode>(__state._M_alt)
             || _M_dfs<__match_mode>(__state._M_next);
           break;

libstdc++-v3/testsuite/28_regex/iterators/regex_iterator/char/string_position_01.cc

+// { dg-options "-std=gnu++11" }
+// { dg-do run { xfail *-*-* } }
+
+//
+// 2013-07-25  Tim Shen <timshen91@gmail.com>
+//
+// Copyright (C) 2013 Free Software Foundation, Inc.
+//
+// This file is part of the GNU ISO C++ Library.  This library is free
+// software; you can redistribute it and/or modify it under the
+// terms of the GNU General Public License as published by the
+// Free Software Foundation; either version 3, or (at your option)
+// any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along
+// with this library; see the file COPYING3.  If not see
+// <http://www.gnu.org/licenses/>.
+
+// 28.12.1 regex_iterator
+// Tests iter->position() behavior
+
+#include <regex>
+#include <testsuite_hooks.h>
+
+void
+test01()
+{
+  bool test __attribute__((unused)) = true;
+
+  std::regex re("asdf");
+  std::string s("asdfasdfasdf");
+  int i = 0;
+  for (std::sregex_iterator it(s.begin(), s.end(), re);
+       it != std::sregex_iterator();
+       ++it, i++) {
+      VERIFY( it->position() == 4 * i );
+  }
+}
+
+int
+main()
+{
+  test01();
+  return 0;
+}