ICU 56 update step 1

source/i18n/unicode/uregex.h

 /*
 **********************************************************************
-*   Copyright (C) 2004-2013, International Business Machines
+*   Copyright (C) 2004-2015, International Business Machines
 *   Corporation and others.  All Rights Reserved.
 **********************************************************************
 *   file name:  uregex.h
 *   encoding:   US-ASCII
 *   indentation:4
 *
 *   created on: 2004mar09
 *   created by: Andy Heninger
 *
 *   ICU Regular Expressions, API for C
@@ skipping 466 matching lines @@
   *
   *   <p>If startIndex is >= 0 any input region that was set for this
   *   URegularExpression is reset before the operation begins.
   *
   *   <p>If the specified starting index == -1 the match begins at the start of the input 
   *   region, or at the start of the full string if no region has been specified.
   *   This corresponds directly with Matcher.lookingAt() in Java.
   *
   *   <p>If the match succeeds then more information can be obtained via the
   *    <code>uregexp_start()</code>, <code>uregexp_end()</code>,
-  *    and <code>uregexp_group()</code> functions.</p>
+  *    and <code>uregex_group()</code> functions.</p>
   *
   *    @param   regexp      The compiled regular expression.
   *    @param   startIndex  The input string (native) index at which to begin matching, or
   *                         -1 to match the Input Region
   *    @param   status      A reference to a UErrorCode to receive any errors.
   *    @return  TRUE if there is a match.
   *    @stable ICU 3.0
   */
 U_STABLE UBool U_EXPORT2 
 uregex_lookingAt(URegularExpression *regexp,
                  int32_t             startIndex,
                  UErrorCode         *status);
 
 /**
   *   64bit version of uregex_lookingAt.
   *   Attempts to match the input string, starting from the specified index, against the pattern.
   *   The match may be of any length, and is not required to extend to the end
   *   of the input string.  Contrast with uregex_matches().
   *
   *   <p>If startIndex is >= 0 any input region that was set for this
   *   URegularExpression is reset before the operation begins.
   *
   *   <p>If the specified starting index == -1 the match begins at the start of the input 
   *   region, or at the start of the full string if no region has been specified.
   *   This corresponds directly with Matcher.lookingAt() in Java.
   *
   *   <p>If the match succeeds then more information can be obtained via the
   *    <code>uregexp_start()</code>, <code>uregexp_end()</code>,
-  *    and <code>uregexp_group()</code> functions.</p>
+  *    and <code>uregex_group()</code> functions.</p>
   *
   *    @param   regexp      The compiled regular expression.
   *    @param   startIndex  The input string (native) index at which to begin matching, or
   *                         -1 to match the Input Region
   *    @param   status      A reference to a UErrorCode to receive any errors.
   *    @return  TRUE if there is a match.
   *    @stable ICU 4.6
   */
 U_STABLE UBool U_EXPORT2 
 uregex_lookingAt64(URegularExpression *regexp,
@@ skipping 70 matching lines @@
   *   Get the number of capturing groups in this regular expression's pattern.
   *   @param   regexp      The compiled regular expression.
   *   @param   status      A reference to a UErrorCode to receive any errors.
   *   @return the number of capture groups
   *   @stable ICU 3.0
   */
 U_STABLE int32_t U_EXPORT2 
 uregex_groupCount(URegularExpression *regexp,
                   UErrorCode         *status);
 
+#ifndef U_HIDE_DRAFT_API
+/**
+  * Get the group number corresponding to a named capture group.
+  * The returned number can be used with any function that access
+  * capture groups by number.
+  *
+  * The function returns an error status if the specified name does not
+  * appear in the pattern.
+  *
+  * @param  regexp      The compiled regular expression.
+  * @param  groupName   The capture group name.
+  * @param  nameLength  The length of the name, or -1 if the name is a
+  *                     nul-terminated string.
+  * @param  status      A pointer to a UErrorCode to receive any errors.
+  *
+  * @draft ICU 55
+  */
+U_DRAFT int32_t U_EXPORT2
+uregex_groupNumberFromName(URegularExpression *regexp,
+                           const UChar        *groupName,
+                           int32_t             nameLength,
+                           UErrorCode          *status);
+
+
+/**
+  * Get the group number corresponding to a named capture group.
+  * The returned number can be used with any function that access
+  * capture groups by number.
+  *
+  * The function returns an error status if the specified name does not
+  * appear in the pattern.
+  *
+  * @param  regexp      The compiled regular expression.
+  * @param  groupName   The capture group name,
+  *                     platform invariant characters only.
+  * @param  nameLength  The length of the name, or -1 if the name is
+  *                     nul-terminated.
+  * @param  status      A pointer to a UErrorCode to receive any errors.
+  *
+  * @draft ICU 55
+  */
+U_DRAFT int32_t U_EXPORT2
+uregex_groupNumberFromCName(URegularExpression *regexp,
+                            const char         *groupName,
+                            int32_t             nameLength,
+                            UErrorCode          *status);
+#endif  /* U_HIDE_DRAFT_API */
+
 /** Extract the string for the specified matching expression or subexpression.
   * Group #0 is the complete string of matched text.
   * Group #1 is the text matched by the first set of capturing parentheses.
   *
   *   @param   regexp       The compiled regular expression.
   *   @param   groupNum     The capture group to extract.  Group 0 is the complete
   *                         match.  The value of this parameter must be
   *                         less than or equal to the number of capture groups in
   *                         the pattern.
   *   @param   dest         Buffer to receive the matching string data
   *   @param   destCapacity Capacity of the dest buffer.
   *   @param   status       A reference to a UErrorCode to receive any errors.
   *   @return               Length of matching data,
   *                         or -1 if no applicable match.
   *   @stable ICU 3.0
   */
 U_STABLE int32_t U_EXPORT2 
 uregex_group(URegularExpression *regexp,
              int32_t             groupNum,
              UChar              *dest,
              int32_t             destCapacity,
              UErrorCode          *status);
 
-/** Returns a shallow immutable clone of the entire input string.  The returned UText current native index
-  *   is set to the beginning of the requested capture group.  The capture group length is also
+/** Returns a shallow immutable clone of the entire input string with the current index set
+  *   to the beginning of the requested capture group.  The capture group length is also
   *   returned via groupLength.
   * Group #0 is the complete string of matched text.
   * Group #1 is the text matched by the first set of capturing parentheses.
   *
   *   @param   regexp       The compiled regular expression.
   *   @param   groupNum     The capture group to extract.  Group 0 is the complete
   *                         match.  The value of this parameter must be
   *                         less than or equal to the number of capture groups in
   *                         the pattern.
   *   @param   dest         A mutable UText in which to store the current input.
   *                         If NULL, a new UText will be created as an immutable shallow clone
   *                         of the entire input string.
-  *   @param   groupLength  The group length of the desired capture group.
+  *   @param   groupLength  The group length of the desired capture group. Output parameter.
   *   @param   status       A reference to a UErrorCode to receive any errors.
   *   @return               The subject text currently associated with this regular expression.
   *                         If a pre-allocated UText was provided, it will always be used and returned.
 
   *
   *   @stable ICU 4.6
   */
 U_STABLE UText * U_EXPORT2 
 uregex_groupUText(URegularExpression *regexp,
                   int32_t             groupNum,
                   UText              *dest,
                   int64_t            *groupLength,
                   UErrorCode         *status);
 
-#ifndef U_HIDE_INTERNAL_API
-/** Extract the string for the specified matching expression or subexpression.
-  * Group #0 is the complete string of matched text.
-  * Group #1 is the text matched by the first set of capturing parentheses.
-  *
-  *   @param   regexp       The compiled regular expression.
-  *   @param   groupNum     The capture group to extract.  Group 0 is the complete
-  *                         match.  The value of this parameter must be
-  *                         less than or equal to the number of capture groups in
-  *                         the pattern.
-  *   @param   dest         Mutable UText to receive the matching string data.
-  *                         If NULL, a new UText will be created (which may not be mutable).
-  *   @param   status       A reference to a UErrorCode to receive any errors.
-  *   @return               The matching string data. If a pre-allocated UText was provided,
-  *                          it will always be used and returned.
-  *
-  *   @internal ICU 4.4 technology preview
-  */
-U_INTERNAL UText * U_EXPORT2 
-uregex_groupUTextDeep(URegularExpression *regexp,
-                  int32_t             groupNum,
-                  UText              *dest,
-                  UErrorCode         *status);
-#endif  /* U_HIDE_INTERNAL_API */
-
 /**
   *   Returns the index in the input string of the start of the text matched by the
   *   specified capture group during the previous match operation.  Return -1 if
   *   the capture group was not part of the last match.
   *   Group #0 refers to the complete range of matched text.
   *   Group #1 refers to the text matched by the first set of capturing parentheses.
   *
   *    @param   regexp      The compiled regular expression.
   *    @param   groupNum    The capture group number
   *    @param   status      A reference to a UErrorCode to receive any errors.
@@ skipping 885 matching lines @@
  * @stable ICU 4.6
  */
 U_STABLE void U_EXPORT2
 uregex_getFindProgressCallback(const URegularExpression          *regexp,
                                 URegexFindProgressCallback        **callback,
                                 const void                        **context,
                                 UErrorCode                        *status);
 
 #endif   /*  !UCONFIG_NO_REGULAR_EXPRESSIONS  */
 #endif   /*  UREGEX_H  */