ICU 56 update step 1

source/i18n/unicode/regex.h

 /*
 **********************************************************************
-*   Copyright (C) 2002-2014, International Business Machines
+*   Copyright (C) 2002-2015, International Business Machines
 *   Corporation and others.  All Rights Reserved.
 **********************************************************************
 *   file name:  regex.h
 *   encoding:   US-ASCII
 *   indentation:4
 *
 *   created on: 2002oct22
 *   created by: Andy Heninger
 *
 *   ICU Regular Expressions, API for C++
@@ skipping 34 matching lines @@
 
 #include "unicode/uobject.h"
 #include "unicode/unistr.h"
 #include "unicode/utext.h"
 #include "unicode/parseerr.h"
 
 #include "unicode/uregex.h"
 
 // Forward Declarations
 
+struct UHashtable;
+
 U_NAMESPACE_BEGIN
 
 struct Regex8BitSet;
 class  RegexCImpl;
 class  RegexMatcher;
 class  RegexPattern;
 struct REStackFrame;
 class  RuleBasedBreakIterator;
 class  UnicodeSet;
 class  UVector;
@@ skipping 61 matching lines @@
 
     /**
      * Assignment operator.  After assignment, this RegexPattern will behave identically
      *     to the source object.
      * @stable ICU 2.4
      */
     RegexPattern  &operator =(const RegexPattern &source);
 
     /**
      * Create an exact copy of this RegexPattern object.  Since RegexPattern is not
-     * intended to be subclasses, <code>clone()</code> and the copy construction are
+     * intended to be subclassed, <code>clone()</code> and the copy construction are
      * equivalent operations.
      * @return the copy of this RegexPattern
      * @stable ICU 2.4
      */
     virtual RegexPattern  *clone() const;
 
 
    /**
     * Compiles the regular expression in string form into a RegexPattern
     * object.  These compile methods, rather than the constructors, are the usual
@@ skipping 281 matching lines @@
     * Note: This is the original input, not a clone. If the pattern was originally compiled from a
     * UText, and that UText was modified, the returned UText may no longer reflect the RegexPattern
     * object.
     *
     * @stable ICU 4.6
     */
     virtual UText *patternText(UErrorCode      &status) const;
 
 
     /**
+     * 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  groupName   The capture group name.
+     * @param  status      A UErrorCode to receive any errors.
+     *
+     * @draft ICU 55
+     */
+    virtual int32_t groupNumberFromName(const UnicodeString &groupName, UErrorCode &status) const;
+
+
+    /**
+     * 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  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 UErrorCode to receive any errors.
+     *
+     * @draft ICU 55
+     */
+    virtual int32_t groupNumberFromName(const char *groupName, int32_t nameLength, UErrorCode &status) const;
+
+
+    /**
      * Split a string into fields.  Somewhat like split() from Perl or Java.
      * Pattern matches identify delimiters that separate the input
      * into fields.  The input data between the delimiters becomes the
      * fields themselves.
      *
      * If the delimiter pattern includes capture groups, the captured text will
      * also appear in the destination array of output strings, interspersed
      * with the fields.  This is similar to Perl, but differs from Java, 
      * which ignores the presence of capture groups in the pattern.
      * 
@@ skipping 115 matching lines @@
     int32_t         fFrameSize;    // Size of a state stack frame in the
                                    //   execution engine.
 
     int32_t         fDataSize;     // The size of the data needed by the pattern that
                                    //   does not go on the state stack, but has just
                                    //   a single copy per matcher.
 
     UVector32       *fGroupMap;    // Map from capture group number to position of
                                    //   the group's variables in the matcher stack frame.
 
-    int32_t         fMaxCaptureDigits;
-
     UnicodeSet     **fStaticSets;  // Ptr to static (shared) sets for predefined
                                    //   regex character classes, e.g. Word.
 
     Regex8BitSet   *fStaticSets8;  // Ptr to the static (shared) latin-1 only
                                    //  sets for predefined regex classes.
 
     int32_t         fStartType;    // Info on how a match must start.
     int32_t         fInitialStringIdx;     //
     int32_t         fInitialStringLen;
     UnicodeSet     *fInitialChars;
     UChar32         fInitialChar;
     Regex8BitSet   *fInitialChars8;
     UBool           fNeedsAltInput;
 
+    UHashtable     *fNamedCaptureMap;  // Map from capture group names to numbers.
+
     friend class RegexCompile;
     friend class RegexMatcher;
     friend class RegexCImpl;
 
     //
     //  Implementation Methods
     //
     void        init();            // Common initialization, for use by constructors.
     void        zap();             // Common cleanup
 
@@ skipping 203 matching lines @@
     *  Find the next pattern match in the input string.
     *  The find begins searching the input at the location following the end of
     *  the previous match, or at the start of the string if there is no previous match.
     *  If a match is found, <code>start(), end()</code> and <code>group()</code>
     *  will provide more information regarding the match.
     *  <p>Note that if the input string is changed by the application,
     *     use find(startPos, status) instead of find(), because the saved starting
     *     position may not be valid with the altered input string.</p>
     *  @param   status  A reference to a UErrorCode to receive any errors.
     *  @return  TRUE if a match is found.
-    *  @internal
+    *  @draft ICU 55
     */
     virtual UBool find(UErrorCode &status);
 
    /**
     *   Resets this RegexMatcher and then attempts to find the next substring of the
     *   input string that matches the pattern, starting at the specified index.
     *
     *   @param   start     The (native) index in the input string to begin the search.
     *   @param   status    A reference to a UErrorCode to receive any errors.
     *   @return  TRUE if a match is found.
@@ skipping 11 matching lines @@
     *   @return  a string containing the matched input text.
     *   @stable ICU 2.4
     */
     virtual UnicodeString group(UErrorCode &status) const;
 
 
    /**
     *    Returns a string containing the text captured by the given group
     *    during the previous match operation.  Group(0) is the entire match.
     *
+    *    A zero length string is returned both for capture groups that did not
+    *    participate in the match and for actual zero length matches.
+    *    To distinguish between these two cases use the function start(),
+    *    which returns -1 for non-participating groups.
+    *
     *    @param groupNum the capture group number
     *    @param   status     A reference to a UErrorCode to receive any errors.
     *                        Possible errors are  U_REGEX_INVALID_STATE if no match
     *                        has been attempted or the last match failed and
     *                        U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.
     *    @return the captured text
     *    @stable ICU 2.4
     */
     virtual UnicodeString group(int32_t groupNum, UErrorCode &status) const;
 
-
    /**
     *   Returns the number of capturing groups in this matcher's pattern.
     *   @return the number of capture groups
     *   @stable ICU 2.4
     */
     virtual int32_t groupCount() const;
 
 
    /**
     *   Returns a shallow clone of the entire live input string with the UText current native index
     *   set to the beginning of the requested group.
     *
     *   @param   dest        The UText into which the input should be cloned, or NULL to create a new UText
     *   @param   group_len   A reference to receive the length of the desired capture group
     *   @param   status      A reference to a UErrorCode to receive any errors.
     *                        Possible errors are  U_REGEX_INVALID_STATE if no match
     *                        has been attempted or the last match failed and
     *                        U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.
     *   @return dest if non-NULL, a shallow copy of the input text otherwise
     *
     *   @stable ICU 4.6
     */
     virtual UText *group(UText *dest, int64_t &group_len, UErrorCode &status) const; 
 
    /**
     *   Returns a shallow clone of the entire live input string with the UText current native index
     *   set to the beginning of the requested group.
     *
+    *   A group length of zero is returned both for capture groups that did not
+    *   participate in the match and for actual zero length matches.
+    *   To distinguish between these two cases use the function start(),
+    *   which returns -1 for non-participating groups.
+    *
     *   @param   groupNum   The capture group number.
     *   @param   dest        The UText into which the input should be cloned, or NULL to create a new UText.
     *   @param   group_len   A reference to receive the length of the desired capture group
     *   @param   status      A reference to a UErrorCode to receive any errors.
     *                        Possible errors are  U_REGEX_INVALID_STATE if no match
     *                        has been attempted or the last match failed and
     *                        U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.
     *   @return dest if non-NULL, a shallow copy of the input text otherwise
     *
     *   @stable ICU 4.6
     */
     virtual UText *group(int32_t groupNum, UText *dest, int64_t &group_len, UErrorCode &status) const;
 
    /**
-    *   Returns a string containing the text captured by the given group
-    *   during the previous match operation.  Group(0) is the entire match.
-    *
-    *   @param   groupNum    the capture group number
-    *   @param   dest        A mutable UText in which the matching text is placed.
-    *                        If NULL, a new UText will be created (which may not be mutable).
-    *   @param   status      A reference to a UErrorCode to receive any errors.
-    *                        Possible errors are  U_REGEX_INVALID_STATE if no match
-    *                        has been attempted or the last match failed.
-    *   @return  A string containing the matched input text. If a pre-allocated UText
-    *            was provided, it will always be used and returned.
-    *
-    *   @internal ICU 4.4 technology preview
-    */
-    virtual UText *group(int32_t groupNum, UText *dest, UErrorCode &status) const;
-
-
-   /**
     *   Returns the index in the input string of the start of the text matched
     *   during the previous match operation.
     *    @param   status      a reference to a UErrorCode to receive any errors.
     *    @return              The (native) position in the input string of the start of the last match.
     *    @stable ICU 2.4
     */
     virtual int32_t start(UErrorCode &status) const;
 
    /**
     *   Returns the index in the input string of the start of the text matched
@@ skipping 28 matching lines @@
     *    @param  group       the capture group number.
     *    @param  status      A reference to a UErrorCode to receive any errors.  Possible
     *                        errors are  U_REGEX_INVALID_STATE if no match has been
     *                        attempted or the last match failed, and
     *                        U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.
     *    @return the (native) start position of substring matched by the specified group.
     *    @stable ICU 4.6
     */
     virtual int64_t start64(int32_t group, UErrorCode &status) const;
 
-
    /**
     *    Returns the index in the input string of the first character following the
     *    text matched during the previous match operation.
     *
     *   @param   status      A reference to a UErrorCode to receive any errors.  Possible
     *                        errors are  U_REGEX_INVALID_STATE if no match has been
     *                        attempted or the last match failed.
     *    @return the index of the last character matched, plus one.
     *                        The index value returned is a native index, corresponding to
     *                        code units for the underlying encoding type, for example,
@@ skipping 49 matching lines @@
     *    @return  the index of the first character following the text
     *              captured by the specified group during the previous match operation.
     *              Return -1 if the capture group exists in the pattern but was not part of the match.
     *              The index value returned is a native index, corresponding to
     *              code units for the underlying encoding type, for example,
     *              a byte index for UTF8.
     *   @stable ICU 4.6
     */
     virtual int64_t end64(int32_t group, UErrorCode &status) const;
 
-
    /**
     *   Resets this matcher.  The effect is to remove any memory of previous matches,
     *       and to cause subsequent find() operations to begin at the beginning of
     *       the input string.
     *
     *   @return this RegexMatcher.
     *   @stable ICU 2.4
     */
     virtual RegexMatcher &reset();
 
@@ skipping 801 matching lines @@
 
     UErrorCode          fDeferredStatus;   // Save error state that cannot be immediately
                                            //   reported, or that permanently disables this matcher.
 
     RuleBasedBreakIterator  *fWordBreakItr;
 };
 
 U_NAMESPACE_END
 #endif  // UCONFIG_NO_REGULAR_EXPRESSIONS
 #endif