From ad0a4eaf8dede47a971eaa1a2b3b3bd3debbcf6c Mon Sep 17 00:00:00 2001 From: Giuseppe D'Angelo Date: Thu, 7 Feb 2013 16:49:04 +0000 Subject: Improve QRegularExpression captureCount / namedCaptureGroups docs We need to clarify what's the status of the implicit capturing group #0 in both of this methods. The former doesn't include it, while the latter does for convenience/consistency in the way we count the capturing groups. (Note that this last behavior is actually autotested.) Change-Id: I2170842c2a6dffa34fa56389ceead61a92c07cd1 Reviewed-by: Thiago Macieira --- src/corelib/tools/qregularexpression.cpp | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) (limited to 'src/corelib/tools/qregularexpression.cpp') diff --git a/src/corelib/tools/qregularexpression.cpp b/src/corelib/tools/qregularexpression.cpp index 9f29c1b576..19b492a505 100644 --- a/src/corelib/tools/qregularexpression.cpp +++ b/src/corelib/tools/qregularexpression.cpp @@ -1496,6 +1496,8 @@ void QRegularExpression::setPatternOptions(PatternOptions options) Returns the number of capturing groups inside the pattern string, or -1 if the regular expression is not valid. + \note The implicit capturing group 0 is \e{not} included in the returned number. + \sa isValid() */ int QRegularExpression::captureCount() const @@ -1508,10 +1510,27 @@ int QRegularExpression::captureCount() const /*! \since 5.1 - Returns a list of captureCount() elements, containing the names of the named - capturing groups in the pattern string. The list is sorted such that the - i-th element of the list is the name of the i-th capturing group, if it has - a name, or an empty string if the capturing group is unnamed. + Returns a list of captureCount() + 1 elements, containing the names of the + named capturing groups in the pattern string. The list is sorted such that + the element of the list at position \c{i} is the name of the \c{i}-th + capturing group, if it has a name, or an empty string if that capturing + group is unnamed. + + For instance, given the regular expression + + \code + (?\d\d)-(?\d\d)-(?\d\d\d\d) (\w+) (?\w+) + \endcode + + namedCaptureGroups() will return the following list: + + \code + ("", "day", "month", "year", "", "name") + \endcode + + which corresponds to the fact that the capturing group #0 (corresponding to + the whole match) has no name, the capturing group #1 has name "day", the + capturing group #2 has name "month", etc. If the regular expression is not valid, returns an empty list. -- cgit v1.2.3