ICU-8.11.4.tar.gz

[apple/icu.git] / icuSources / i18n / unicode / uregex.h

diff --git a/icuSources/i18n/unicode/uregex.h b/icuSources/i18n/unicode/uregex.h
index 5c37bc84e886b5e5dd110fe0998135c80e20f717..862cf3446417e55431549f188b894d05a26591d2 100644 (file)
--- a/icuSources/i18n/unicode/uregex.h
+++ b/icuSources/i18n/unicode/uregex.h
@@ -1,6 +1,6 @@
 /*
 **********************************************************************
 /*
 **********************************************************************

-*   Copyright (C) 2004, International Business Machines
+*   Copyright (C) 2004-2006, International Business Machines

 *   Corporation and others.  All Rights Reserved.
 **********************************************************************
 *   file name:  regex.h
 *   Corporation and others.  All Rights Reserved.
 **********************************************************************
 *   file name:  regex.h


@@ -29,27 +29,27 @@
 
 #include "unicode/parseerr.h"
 
 
 #include "unicode/parseerr.h"
 

-#ifndef U_HIDE_DRAFT_API
-

 struct URegularExpression;
 /**
   * Structure represeting a compiled regular rexpression, plus the results
   *    of a match operation.
 struct URegularExpression;
 /**
   * Structure represeting a compiled regular rexpression, plus the results
   *    of a match operation.

-  * @draft ICU 3.0
+  * @stable ICU 3.0

   */
 typedef struct URegularExpression URegularExpression;
 
   */
 typedef struct URegularExpression URegularExpression;
 

-#endif /* U_HIDE_DRAFT_API */
-

 
 /**
  * Constants for Regular Expression Match Modes.
  * @stable ICU 2.4
  */
 typedef enum URegexpFlag{
 
 /**
  * Constants for Regular Expression Match Modes.
  * @stable ICU 2.4
  */
 typedef enum URegexpFlag{

-    /** Forces normalization of pattern and strings.  @draft ICU 2.4 */
-    UREGEX_CANON_EQ         = 128,

 
 

+#ifndef U_HIDE_DRAFT_API 
+    /** Forces normalization of pattern and strings. 
+    Not implemented yet, just a placeholder, hence draft. 
+    @draft ICU 2.4 */
+    UREGEX_CANON_EQ         = 128,
+#endif

     /**  Enable case insensitive matching.  @stable ICU 2.4 */
     UREGEX_CASE_INSENSITIVE = 2,
 
     /**  Enable case insensitive matching.  @stable ICU 2.4 */
     UREGEX_CASE_INSENSITIVE = 2,
 


@@ -71,7 +71,7 @@ typedef enum URegexpFlag{
       *     Warning: Unicode word boundaries are quite different from
       *     traditional regular expression word boundaries.  See
       *     http://unicode.org/reports/tr29/#Word_Boundaries
       *     Warning: Unicode word boundaries are quite different from
       *     traditional regular expression word boundaries.  See
       *     http://unicode.org/reports/tr29/#Word_Boundaries

-      *     @draft ICU 2.8
+      *     @stable ICU 2.8

       */
     UREGEX_UWORD            = 256
 }  URegexpFlag;
       */
     UREGEX_UWORD            = 256
 }  URegexpFlag;


@@ -94,10 +94,10 @@ typedef enum URegexpFlag{
   *                       error within the source regular expression string.  If this
   *                       information is not wanted, pass NULL for this parameter.
   * @param status         Receives error detected by this function.
   *                       error within the source regular expression string.  If this
   *                       information is not wanted, pass NULL for this parameter.
   * @param status         Receives error detected by this function.

-  * @draft ICU 3.0
+  * @stable ICU 3.0

   *
   */
   *
   */

-U_DRAFT URegularExpression * U_EXPORT2
+U_STABLE URegularExpression * U_EXPORT2

 uregex_open( const  UChar          *pattern,
                     int32_t         patternLength,
                     uint32_t        flags,
 uregex_open( const  UChar          *pattern,
                     int32_t         patternLength,
                     uint32_t        flags,


@@ -125,14 +125,15 @@ uregex_open( const  UChar          *pattern,
   * @return               The URegularExpression object representing the compiled
   *                       pattern.
   *
   * @return               The URegularExpression object representing the compiled
   *                       pattern.
   *

-  * @draft ICU 3.0
+  * @stable ICU 3.0

   */
   */

-U_DRAFT URegularExpression * U_EXPORT2
+#if !UCONFIG_NO_CONVERSION
+U_STABLE URegularExpression * U_EXPORT2

 uregex_openC( const char           *pattern,
                     uint32_t        flags,
                     UParseError    *pe,
                     UErrorCode     *status);
 uregex_openC( const char           *pattern,
                     uint32_t        flags,
                     UParseError    *pe,
                     UErrorCode     *status);

-
+#endif

 
 
 
 
 
 


@@ -141,9 +142,9 @@ uregex_openC( const char           *pattern,
   *   was holding.
   *
   * @param regexp   The regular expression to be closed.
   *   was holding.
   *
   * @param regexp   The regular expression to be closed.

-  * @draft ICU 3.0
+  * @stable ICU 3.0

   */
   */

-U_DRAFT void U_EXPORT2 
+U_STABLE void U_EXPORT2 

 uregex_close(URegularExpression *regexp);
 
 /**
 uregex_close(URegularExpression *regexp);
 
 /**


@@ -162,9 +163,9 @@ uregex_close(URegularExpression *regexp);
  * @param regexp   The compiled regular expression to be cloned.
  * @param status   Receives indication of any errors encountered
  * @return the cloned copy of the compiled regular expression.
  * @param regexp   The compiled regular expression to be cloned.
  * @param status   Receives indication of any errors encountered
  * @return the cloned copy of the compiled regular expression.

- * @draft ICU 3.0
+ * @stable ICU 3.0

  */
  */

-U_DRAFT URegularExpression * U_EXPORT2 
+U_STABLE URegularExpression * U_EXPORT2 

 uregex_clone(const URegularExpression *regexp, UErrorCode *status);
 
 /**
 uregex_clone(const URegularExpression *regexp, UErrorCode *status);
 
 /**


@@ -181,9 +182,9 @@ uregex_clone(const URegularExpression *regexp, UErrorCode *status);
  *                   owned by the regular expression object, and must not be
  *                   altered or deleted by the application.  The returned string
  *                   will remain valid until the regular expression is closed.
  *                   owned by the regular expression object, and must not be
  *                   altered or deleted by the application.  The returned string
  *                   will remain valid until the regular expression is closed.

- * @draft ICU 3.0
+ * @stable ICU 3.0

  */
  */

-U_DRAFT const UChar * U_EXPORT2 
+U_STABLE const UChar * U_EXPORT2 

 uregex_pattern(const  URegularExpression   *regexp,
                          int32_t           *patLength,
                          UErrorCode        *status);
 uregex_pattern(const  URegularExpression   *regexp,
                          int32_t           *patLength,
                          UErrorCode        *status);


@@ -195,9 +196,9 @@ uregex_pattern(const  URegularExpression   *regexp,
   * @param regexp   The compiled regular expression.
   * @return         The match mode flags
   * @see URegexpFlag
   * @param regexp   The compiled regular expression.
   * @return         The match mode flags
   * @see URegexpFlag

-  * @draft ICU 3.0
+  * @stable ICU 3.0

   */
   */

-U_DRAFT int32_t U_EXPORT2 
+U_STABLE int32_t U_EXPORT2 

 uregex_flags(const  URegularExpression   *regexp,
                     UErrorCode           *status);
 
 uregex_flags(const  URegularExpression   *regexp,
                     UErrorCode           *status);
 


@@ -220,9 +221,9 @@ uregex_flags(const  URegularExpression   *regexp,
   * @param textLength The length of the subject text, or -1 if the string
   *                   is NUL terminated.
   * @param status     Receives errors detected by this function.
   * @param textLength The length of the subject text, or -1 if the string
   *                   is NUL terminated.
   * @param status     Receives errors detected by this function.

-  * @draft ICU 3.0
+  * @stable ICU 3.0

   */
   */

-U_DRAFT void U_EXPORT2 
+U_STABLE void U_EXPORT2 

 uregex_setText(URegularExpression *regexp,
                const UChar        *text,
                int32_t             textLength,
 uregex_setText(URegularExpression *regexp,
                const UChar        *text,
                int32_t             textLength,


@@ -242,9 +243,9 @@ uregex_setText(URegularExpression *regexp,
   * @param status      Receives errors detected by this function.
   * @return            Poiner to the subject text string currently associated with
   *                    this regular expression.
   * @param status      Receives errors detected by this function.
   * @return            Poiner to the subject text string currently associated with
   *                    this regular expression.

-  * @draft ICU 3.0
+  * @stable ICU 3.0

   */
   */

-U_DRAFT const UChar * U_EXPORT2 
+U_STABLE const UChar * U_EXPORT2 

 uregex_getText(URegularExpression *regexp,
                int32_t            *textLength,
                UErrorCode         *status);
 uregex_getText(URegularExpression *regexp,
                int32_t            *textLength,
                UErrorCode         *status);


@@ -257,9 +258,9 @@ uregex_getText(URegularExpression *regexp,
   *    @param  startIndex  The input string index at which to begin matching.
   *    @param  status      Receives errors detected by this function.
   *    @return             TRUE if there is a match
   *    @param  startIndex  The input string index at which to begin matching.
   *    @param  status      Receives errors detected by this function.
   *    @return             TRUE if there is a match

-  *    @draft ICU 3.0
+  *    @stable ICU 3.0

   */
   */

-U_DRAFT UBool U_EXPORT2 
+U_STABLE UBool U_EXPORT2 

 uregex_matches(URegularExpression *regexp,
                 int32_t            startIndex,
                 UErrorCode        *status);
 uregex_matches(URegularExpression *regexp,
                 int32_t            startIndex,
                 UErrorCode        *status);


@@ -277,9 +278,9 @@ uregex_matches(URegularExpression *regexp,
   *    @param   startIndex  The input string index at which to begin matching.
   *    @param   status      A reference to a UErrorCode to receive any errors.
   *    @return  TRUE if there is a match.
   *    @param   startIndex  The input string index at which to begin matching.
   *    @param   status      A reference to a UErrorCode to receive any errors.
   *    @return  TRUE if there is a match.

-  *    @draft ICU 3.0
+  *    @stable ICU 3.0

   */
   */

-U_DRAFT UBool U_EXPORT2 
+U_STABLE UBool U_EXPORT2 

 uregex_lookingAt(URegularExpression *regexp,
                  int32_t             startIndex,
                  UErrorCode         *status);
 uregex_lookingAt(URegularExpression *regexp,
                  int32_t             startIndex,
                  UErrorCode         *status);


@@ -294,9 +295,9 @@ uregex_lookingAt(URegularExpression *regexp,
   *   @param   startIndex  The position 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.
   *   @param   startIndex  The position 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.

-  *   @draft ICU 3.0
+  *   @stable ICU 3.0

   */
   */

-U_DRAFT UBool U_EXPORT2 
+U_STABLE UBool U_EXPORT2 

 uregex_find(URegularExpression *regexp,
             int32_t             startIndex, 
             UErrorCode         *status);
 uregex_find(URegularExpression *regexp,
             int32_t             startIndex, 
             UErrorCode         *status);


@@ -312,9 +313,9 @@ uregex_find(URegularExpression *regexp,
   *  @param   status      A reference to a UErrorCode to receive any errors.
   *  @return              TRUE if a match is found.
   *  @see uregex_reset
   *  @param   status      A reference to a UErrorCode to receive any errors.
   *  @return              TRUE if a match is found.
   *  @see uregex_reset

-  *  @draft ICU 3.0
+  *  @stable ICU 3.0

   */
   */

-U_DRAFT UBool U_EXPORT2 
+U_STABLE UBool U_EXPORT2 

 uregex_findNext(URegularExpression *regexp,
                 UErrorCode         *status);
 
 uregex_findNext(URegularExpression *regexp,
                 UErrorCode         *status);
 


@@ -323,9 +324,9 @@ uregex_findNext(URegularExpression *regexp,
   *   @param   regexp      The compiled regular expression.
   *   @param   status      A reference to a UErrorCode to receive any errors.
   *   @return the number of capture groups
   *   @param   regexp      The compiled regular expression.
   *   @param   status      A reference to a UErrorCode to receive any errors.
   *   @return the number of capture groups

-  *   @draft ICU 3.0
+  *   @stable ICU 3.0

   */
   */

-U_DRAFT int32_t U_EXPORT2 
+U_STABLE int32_t U_EXPORT2 

 uregex_groupCount(URegularExpression *regexp,
                   UErrorCode         *status);
 
 uregex_groupCount(URegularExpression *regexp,
                   UErrorCode         *status);
 


@@ -343,9 +344,9 @@ uregex_groupCount(URegularExpression *regexp,
   *   @param   status       A reference to a UErrorCode to receive any errors.
   *   @return               Length of matching data,
   *                         or -1 if no applicable match.
   *   @param   status       A reference to a UErrorCode to receive any errors.
   *   @return               Length of matching data,
   *                         or -1 if no applicable match.

-  *   @draft ICU 3.0
+  *   @stable ICU 3.0

   */
   */

-U_DRAFT int32_t U_EXPORT2 
+U_STABLE int32_t U_EXPORT2 

 uregex_group(URegularExpression *regexp,
              int32_t             groupNum,
              UChar              *dest,
 uregex_group(URegularExpression *regexp,
              int32_t             groupNum,
              UChar              *dest,


@@ -365,9 +366,9 @@ uregex_group(URegularExpression *regexp,
   *    @param   status      A reference to a UErrorCode to receive any errors.
   *    @return              the starting position in the input of the text matched 
   *                         by the specified group.
   *    @param   status      A reference to a UErrorCode to receive any errors.
   *    @return              the starting position in the input of the text matched 
   *                         by the specified group.

-  *    @draft ICU 3.0
+  *    @stable ICU 3.0

   */
   */

-U_DRAFT int32_t U_EXPORT2 
+U_STABLE int32_t U_EXPORT2 

 uregex_start(URegularExpression *regexp,
              int32_t             groupNum,
              UErrorCode          *status);
 uregex_start(URegularExpression *regexp,
              int32_t             groupNum,
              UErrorCode          *status);


@@ -383,9 +384,9 @@ uregex_start(URegularExpression *regexp,
   *    @param   groupNum    The capture group number
   *    @param   status      A reference to a UErrorCode to receive any errors.
   *    @return              the index of the position following the last matched character.
   *    @param   groupNum    The capture group number
   *    @param   status      A reference to a UErrorCode to receive any errors.
   *    @return              the index of the position following the last matched character.

-  *    @draft ICU 3.0
+  *    @stable ICU 3.0

   */
   */

-U_DRAFT int32_t U_EXPORT2 
+U_STABLE int32_t U_EXPORT2 

 uregex_end(URegularExpression   *regexp,
            int32_t               groupNum,
            UErrorCode           *status);
 uregex_end(URegularExpression   *regexp,
            int32_t               groupNum,
            UErrorCode           *status);


@@ -400,9 +401,9 @@ uregex_end(URegularExpression   *regexp,
   *    @param   index       The position in the text at which a
   *                         uregex_findNext() should begin searching.
   *    @param   status      A reference to a UErrorCode to receive any errors.
   *    @param   index       The position in the text at which a
   *                         uregex_findNext() should begin searching.
   *    @param   status      A reference to a UErrorCode to receive any errors.

-  *    @draft ICU 3.0
+  *    @stable ICU 3.0

   */
   */

-U_DRAFT void U_EXPORT2 
+U_STABLE void U_EXPORT2 

 uregex_reset(URegularExpression    *regexp,
              int32_t               index,
              UErrorCode            *status);
 uregex_reset(URegularExpression    *regexp,
              int32_t               index,
              UErrorCode            *status);


@@ -429,11 +430,11 @@ uregex_reset(URegularExpression    *regexp,
   *                                and replace operation.  In the event that the
   *                                destination capacity is inadequate, the return value
   *                                is still the full length of the untruncated string.
   *                                and replace operation.  In the event that the
   *                                destination capacity is inadequate, the return value
   *                                is still the full length of the untruncated string.

-  *    @draft ICU 3.0
+  *    @stable ICU 3.0

   */
   */

-U_DRAFT int32_t U_EXPORT2 
+U_STABLE int32_t U_EXPORT2 

 uregex_replaceAll(URegularExpression    *regexp,
 uregex_replaceAll(URegularExpression    *regexp,

-                  UChar                 *replacementText,
+                  const UChar           *replacementText,

                   int32_t                replacementLength,
                   UChar                 *destBuf,
                   int32_t                destCapacity,
                   int32_t                replacementLength,
                   UChar                 *destBuf,
                   int32_t                destCapacity,


@@ -462,11 +463,11 @@ uregex_replaceAll(URegularExpression    *regexp,
   *                                and replace operation.  In the event that the
   *                                destination capacity is inadequate, the return value
   *                                is still the full length of the untruncated string.
   *                                and replace operation.  In the event that the
   *                                destination capacity is inadequate, the return value
   *                                is still the full length of the untruncated string.

-  *    @draft ICU 3.0
+  *    @stable ICU 3.0

   */
   */

-U_DRAFT int32_t U_EXPORT2 
+U_STABLE int32_t U_EXPORT2 

 uregex_replaceFirst(URegularExpression  *regexp,
 uregex_replaceFirst(URegularExpression  *regexp,

-                    UChar               *replacementText,
+                    const UChar         *replacementText,

                     int32_t              replacementLength,
                     UChar               *destBuf,
                     int32_t              destCapacity,
                     int32_t              replacementLength,
                     UChar               *destBuf,
                     int32_t              destCapacity,


@@ -516,12 +517,12 @@ uregex_replaceFirst(URegularExpression  *regexp,
   *                        destCapacity is inadequate, the full length of the
   *                        untruncated output string is returned.
   *
   *                        destCapacity is inadequate, the full length of the
   *                        untruncated output string is returned.
   *

-  *   @draft ICU 3.0
+  *   @stable ICU 3.0

   *
   */
   *
   */

-U_DRAFT int32_t U_EXPORT2 
+U_STABLE int32_t U_EXPORT2 

 uregex_appendReplacement(URegularExpression    *regexp,
 uregex_appendReplacement(URegularExpression    *regexp,

-                  UChar                 *replacementText,
+                  const UChar           *replacementText,

                   int32_t                replacementLength,
                   UChar                **destBuf,
                   int32_t               *destCapacity,
                   int32_t                replacementLength,
                   UChar                **destBuf,
                   int32_t               *destCapacity,


@@ -550,9 +551,9 @@ uregex_appendReplacement(URegularExpression    *regexp,
   *                        destCapacity is inadequate, the full length of the
   *                        untruncated output string is returned.
   *
   *                        destCapacity is inadequate, the full length of the
   *                        untruncated output string is returned.
   *

-  *   @draft ICU 3.0
+  *   @stable ICU 3.0

   */
   */

-U_DRAFT int32_t U_EXPORT2 
+U_STABLE int32_t U_EXPORT2 

 uregex_appendTail(URegularExpression    *regexp,
                   UChar                **destBuf,
                   int32_t               *destCapacity,
 uregex_appendTail(URegularExpression    *regexp,
                   UChar                **destBuf,
                   int32_t               *destCapacity,


@@ -570,6 +571,22 @@ uregex_appendTail(URegularExpression    *regexp,
    *  Each of the fields is copied from the input string to the destination
    *  buffer, and the NUL terminated.  The position of each field within
    *  the destination buffer is returned in the destFields array.
    *  Each of the fields is copied from the input string to the destination
    *  buffer, and the NUL terminated.  The position of each field within
    *  the destination buffer is returned in the destFields array.

+   *
+   *  Note:  another choice for the design of this function would be to not
+   *         copy the resulting fields at all, but to return indexes and
+   *         lengths within the source text.  
+   *           Advantages would be
+   *             o  Faster.  No Copying.
+   *             o  Nothing extra needed when field data may contain embedded NUL chars.
+   *             o  Less memory needed if working on large data.
+   *           Disadvantages
+   *             o  Less consistent with C++ split, which copies into an
+   *                array of UnicodeStrings.
+   *             o  No NUL termination, extracted fields would be less convenient
+   *                to use in most cases.
+   *             o  Possible problems in the future, when support Unicode Normalization
+   *                could cause the fields to not correspond exactly to
+   *                a range of the source text.

    * 
    *    @param   regexp      The compiled regular expression.
    *    @param   destBuf     A (UChar *) buffer to receive the fields that
    * 
    *    @param   regexp      The compiled regular expression.
    *    @param   destBuf     A (UChar *) buffer to receive the fields that


@@ -597,25 +614,9 @@ uregex_appendTail(URegularExpression    *regexp,
    *                positions are used.
    * @param status  A reference to a UErrorCode to receive any errors.
    * @return        The number of fields into which the input string was split.
    *                positions are used.
    * @param status  A reference to a UErrorCode to receive any errors.
    * @return        The number of fields into which the input string was split.

-   * @draft ICU 3.0
-   *
-   *  Note:  another choice for the design of this function would be to not
-   *         copy the resulting fields at all, but to return indexes and
-   *         lengths within the source text.  
-   *           Advantages would be
-   *             o  Faster.  No Copying.
-   *             o  Nothing extra needed when field data may contain embedded NUL chars.
-   *             o  Less memory needed if working on large data.
-   *           Disadvantages
-   *             o  Less consistent with C++ split, which copies into an
-   *                array of UnicodeStrings.
-   *             o  No NUL termination, extracted fields would be less convenient
-   *                to use in most cases.
-   *             o  Possible problems in the future, when support Unicode Normalization
-   *                could cause the fields to not correspond exactly to
-   *                a range of the source text.
+   * @stable ICU 3.0

    */
    */

-U_DRAFT int32_t U_EXPORT2 
+U_STABLE int32_t U_EXPORT2 

 uregex_split(   URegularExpression      *regexp,
                   UChar                 *destBuf,
                   int32_t                destCapacity,
 uregex_split(   URegularExpression      *regexp,
                   UChar                 *destBuf,
                   int32_t                destCapacity,