libcore/regex/src/main/java/java/util/regex/Pattern.java

   1 /*
   2  * Copyright (C) 2007 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 package java.util.regex;
  18
  19 import java.io.Serializable;
  20 import java.util.ArrayList;
  21 import com.ibm.icu4jni.regex.NativeRegEx;
  22
  23 /**
  24  * Represents a pattern used for matching, searching, or replacing strings.
  25  * {@code Pattern}s are specified in terms of regular expressions and compiled
  26  * using an instance of this class. They are then used in conjunction with a
  27  * {@link Matcher} to perform the actual search.
  28  * <p/>
  29  * A typical use case looks like this:
  30  * <p/>
  31  * <pre>
  32  * Pattern p = Pattern.compile("Hello, A[a-z]*!");
  33  *
  34  * Matcher m = p.matcher("Hello, Android!");
  35  * boolean b1 = m.matches(); // true
  36  *
  37  * m.setInput("Hello, Robot!");
  38  * boolean b2 = m.matches(); // false
  39  * </pre>
  40  * <p/>
  41  * The above code could also be written in a more compact fashion, though this
  42  * variant is less efficient, since {@code Pattern} and {@code Matcher} objects
  43  * are created on the fly instead of being reused.
  44  * fashion:
  45  * <pre>
  46  *     boolean b1 = Pattern.matches("Hello, A[a-z]*!", "Hello, Android!"); // true
  47  *     boolean b2 = Pattern.matches("Hello, A[a-z]*!", "Hello, Robot!");   // false
  48  * </pre>
  49  * <p/>
  50  * Please consult the <a href="package-summary.html">package documentation</a> for an
  51  * overview of the regular expression syntax used in this class as well as
  52  * Android-specific implementation details.
  53  *
  54  * @see Matcher
  55  * @since Android 1.0
  56  */
  57 public final class Pattern implements Serializable {
  58
  59     private static final long serialVersionUID = 5073258162644648461L;
  60
  61     /**
  62      * This constant specifies that a pattern matches Unix line endings ('\n')
  63      * only against the '.', '^', and '$' meta characters.
  64      *
  65      * @since Android 1.0
  66      */
  67     public static final int UNIX_LINES = 0x01;
  68
  69     /**
  70      * This constant specifies that a {@code Pattern} is matched
  71      * case-insensitively. That is, the patterns "a+" and "A+" would both match
  72      * the string "aAaAaA".
  73      * <p>
  74      * Note: For Android, the {@code CASE_INSENSITIVE} constant
  75      * (currently) always includes the meaning of the {@link #UNICODE_CASE}
  76      * constant. So if case insensitivity is enabled, this automatically extends
  77      * to all Unicode characters. The {@code UNICODE_CASE} constant itself has
  78      * no special consequences.
  79      *
  80      * @since Android 1.0
  81      */
  82     public static final int CASE_INSENSITIVE = 0x02;
  83
  84     /**
  85      * This constant specifies that a {@code Pattern} may contain whitespace or
  86      * comments. Otherwise comments and whitespace are taken as literal
  87      * characters.
  88      *
  89      * @since Android 1.0
  90      */
  91     public static final int COMMENTS = 0x04;
  92
  93     /**
  94      * This constant specifies that the meta characters '^' and '$' match only
  95      * the beginning and end end of an input line, respectively. Normally, they
  96      * match the beginning and the end of the complete input.
  97      *
  98      * @since Android 1.0
  99      */
 100     public static final int MULTILINE = 0x08;
 101
 102     /**
 103      * This constant specifies that the whole {@code Pattern} is to be taken
 104      * literally, that is, all meta characters lose their meanings.
 105      *
 106      * @since Android 1.0
 107      */
 108     public static final int LITERAL = 0x10;
 109
 110     /**
 111      * This constant specifies that the '.' meta character matches arbitrary
 112      * characters, including line endings, which is normally not the case.
 113      *
 114      * @since Android 1.0
 115      */
 116     public static final int DOTALL = 0x20;
 117
 118     /**
 119      * This constant specifies that a {@code Pattern} is matched
 120      * case-insensitively with regard to all Unicode characters. It is used in
 121      * conjunction with the {@link #CASE_INSENSITIVE} constant to extend its
 122      * meaning to all Unicode characters.
 123      * <p>
 124      * Note: For Android, the {@code CASE_INSENSITIVE} constant
 125      * (currently) always includes the meaning of the {@code UNICODE_CASE}
 126      * constant. So if case insensitivity is enabled, this automatically extends
 127      * to all Unicode characters. The {@code UNICODE_CASE} constant then has no
 128      * special consequences.
 129      *
 130      * @since Android 1.0
 131      */
 132     public static final int UNICODE_CASE = 0x40;
 133
 134     /**
 135      * This constant specifies that a character in a {@code Pattern} and a
 136      * character in the input string only match if they are canonically
 137      * equivalent. It is (currently) not supported in Android.
 138      *
 139      * @since Android 1.0
 140      */
 141     public static final int CANON_EQ = 0x80;
 142
 143     /**
 144      * Holds the regular expression.
 145      */
 146     private String pattern;
 147
 148     /**
 149      * Holds the flags used when compiling this pattern.
 150      */
 151     private int flags;
 152
 153     /**
 154      * Holds a handle (a pointer, actually) for the native ICU pattern.
 155      */
 156     transient int mNativePattern;
 157
 158     /**
 159      * Holds the number of groups in the pattern.
 160      */
 161     transient int mGroupCount;
 162
 163     /**
 164      * Compiles a regular expression, creating a new Pattern instance in the
 165      * process. This is actually a convenience method that calls {@link
 166      * #compile(String, int)} with a {@code flags} value of zero.
 167      *
 168      * @param pattern
 169      *            the regular expression.
 170      *
 171      * @return the new {@code Pattern} instance.
 172      *
 173      * @throws PatternSyntaxException
 174      *             if the regular expression is syntactically incorrect.
 175      *
 176      * @since Android 1.0
 177      */
 178     public static Pattern compile(String pattern) throws PatternSyntaxException {
 179         return new Pattern(pattern, 0);
 180     }
 181
 182     /**
 183      * Compiles a regular expression, creating a new {@code Pattern} instance in
 184      * the process. Allows to set some flags that modify the behavior of the
 185      * {@code Pattern}.
 186      *
 187      * @param pattern
 188      *            the regular expression.
 189      * @param flags
 190      *            the flags to set. Basically, any combination of the constants
 191      *            defined in this class is valid.
 192      *            <p>
 193      *            Note: Currently, the {@link #CASE_INSENSITIVE} and
 194      *            {@link #UNICODE_CASE} constants have slightly special behavior
 195      *            in Android, and the {@link #CANON_EQ} constant is not
 196      *            supported at all.
 197      *
 198      * @return the new {@code Pattern} instance.
 199      *
 200      * @throws PatternSyntaxException
 201      *             if the regular expression is syntactically incorrect.
 202      *
 203      * @see #CANON_EQ
 204      * @see #CASE_INSENSITIVE
 205      * @see #COMMENTS
 206      * @see #DOTALL
 207      * @see #LITERAL
 208      * @see #MULTILINE
 209      * @see #UNICODE_CASE
 210      * @see #UNIX_LINES
 211      *
 212      * @since Android 1.0
 213      */
 214     public static Pattern compile(String pattern, int flags) throws PatternSyntaxException {
 215         return new Pattern(pattern, flags);
 216     }
 217
 218     /**
 219      * Creates a new {@code Pattern} instance from a given regular expression
 220      * and flags.
 221      *
 222      * @param pattern
 223      *            the regular expression.
 224      * @param flags
 225      *            the flags to set. Any combination of the constants defined in
 226      *            this class is valid.
 227      *
 228      * @throws PatternSyntaxException
 229      *             if the regular expression is syntactically incorrect.
 230      */
 231     private Pattern(String pattern, int flags) throws PatternSyntaxException {
 232         if ((flags & CANON_EQ) != 0) {
 233             throw new UnsupportedOperationException("CANON_EQ flag not supported");
 234         }
 235
 236         this.pattern = pattern;
 237         this.flags = flags;
 238
 239         compileImpl(pattern, flags);
 240     }
 241
 242     /**
 243      * Compiles the given regular expression using the given flags. Used
 244      * internally only.
 245      *
 246      * @param pattern
 247      *            the regular expression.
 248      * @param flags
 249      *            the flags.
 250      */
 251     private void compileImpl(String pattern, int flags) throws PatternSyntaxException {
 252         if (pattern == null) {
 253             throw new NullPointerException();
 254         }
 255
 256         if ((flags & LITERAL) != 0) {
 257             pattern = quote(pattern);
 258         }
 259
 260         // These are the flags natively supported by ICU.
 261         // They even have the same value in native code.
 262         flags = flags & (CASE_INSENSITIVE | COMMENTS | MULTILINE | DOTALL | UNIX_LINES);
 263
 264         mNativePattern = NativeRegEx.open(pattern, flags);
 265         mGroupCount = NativeRegEx.groupCount(mNativePattern);
 266     }
 267
 268     /**
 269      * Returns the regular expression that was compiled into this
 270      * {@code Pattern}.
 271      *
 272      * @return the regular expression.
 273      *
 274      * @since Android 1.0
 275      */
 276     public String pattern() {
 277         return pattern;
 278     }
 279
 280     /**
 281      * Returns the flags that have been set for this {@code Pattern}.
 282      *
 283      * @return the flags that have been set. A combination of the constants
 284      *         defined in this class.
 285      *
 286      * @see #CANON_EQ
 287      * @see #CASE_INSENSITIVE
 288      * @see #COMMENTS
 289      * @see #DOTALL
 290      * @see #LITERAL
 291      * @see #MULTILINE
 292      * @see #UNICODE_CASE
 293      * @see #UNIX_LINES
 294      *
 295      * @since Android 1.0
 296      */
 297     public int flags() {
 298         return flags;
 299     }
 300
 301     /**
 302      * Returns a {@link Matcher} for the {@code Pattern} and a given input. The
 303      * {@code Matcher} can be used to match the {@code Pattern} against the
 304      * whole input, find occurrences of the {@code Pattern} in the input, or
 305      * replace parts of the input.
 306      *
 307      * @param input
 308      *            the input to process.
 309      *
 310      * @return the resulting {@code Matcher}.
 311      *
 312      * @since Android 1.0
 313      */
 314     public Matcher matcher(CharSequence input) {
 315         return new Matcher(this, input);
 316     }
 317
 318     /**
 319      * Tries to match a given regular expression against a given input. This is
 320      * actually nothing but a convenience method that compiles the regular
 321      * expression into a {@code Pattern}, builds a {@link Matcher} for it, and
 322      * then does the match. If the same regular expression is used for multiple
 323      * operations, it is recommended to compile it into a {@code Pattern}
 324      * explicitly and request a reusable {@code Matcher}.
 325      *
 326      * @param regex
 327      *            the regular expression.
 328      * @param input
 329      *            the input to process.
 330      *
 331      * @return true if and only if the {@code Pattern} matches the input.
 332      *
 333      * @see Pattern#compile(java.lang.String, int)
 334      * @see Matcher#matches()
 335      *
 336      * @since Android 1.0
 337      */
 338     static public boolean matches(String regex, CharSequence input) {
 339         return new Matcher(new Pattern(regex, 0), input).matches();
 340     }
 341
 342     /**
 343      * Splits a given input around occurrences of a regular expression. This is
 344      * a convenience method that is equivalent to calling the method
 345      * {@link #split(java.lang.CharSequence, int)} with a limit of 0.
 346      *
 347      * @param input
 348      *            the input sequence.
 349      *
 350      * @return the resulting array.
 351      *
 352      * @since Android 1.0
 353      */
 354     public String[] split(CharSequence input) {
 355         return split(input, 0);
 356     }
 357
 358     /**
 359      * Splits the given input sequence around occurrences of the {@code Pattern}.
 360      * The function first determines all occurrences of the {@code Pattern}
 361      * inside the input sequence. It then builds an array of the
 362      * &quot;remaining&quot; strings before, in-between, and after these
 363      * occurrences. An additional parameter determines the maximal number of
 364      * entries in the resulting array and the handling of trailing empty
 365      * strings.
 366      *
 367      * @param inputSeq
 368      *            the input sequence.
 369      * @param limit
 370      *            Determines the maximal number of entries in the resulting
 371      *            array.
 372      *            <ul>
 373      *            <li>For n &gt; 0, it is guaranteed that the resulting array
 374      *            contains at most n entries.
 375      *            <li>For n &lt; 0, the length of the resulting array is
 376      *            exactly the number of occurrences of the {@code Pattern} +1.
 377      *            All entries are included.
 378      *            <li>For n == 0, the length of the resulting array is at most
 379      *            the number of occurrences of the {@code Pattern} +1. Empty
 380      *            strings at the end of the array are not included.
 381      *            </ul>
 382      *
 383      * @return the resulting array.
 384      *
 385      * @since Android 1.0
 386      */
 387     public String[] split(CharSequence inputSeq, int limit) {
 388         int maxLength = limit <= 0 ? Integer.MAX_VALUE : limit;
 389
 390         String input = inputSeq.toString();
 391         ArrayList<String> list = new ArrayList<String>();
 392
 393         Matcher matcher = new Matcher(this, inputSeq);
 394         int savedPos = 0;
 395
 396         // Add text preceding each occurrence, if enough space. Only do this for
 397         // non-empty input sequences, because otherwise we'd add the "trailing
 398         // empty string" twice.
 399         if (inputSeq.length() != 0) {
 400             while(matcher.find() && list.size() + 1 < maxLength) {
 401                 list.add(input.substring(savedPos, matcher.start()));
 402                 savedPos = matcher.end();
 403             }
 404         }
 405
 406         // Add trailing text if enough space.
 407         if (list.size() < maxLength) {
 408             if (savedPos < input.length()) {
 409                 list.add(input.substring(savedPos));
 410             } else {
 411                 list.add("");
 412             }
 413         }
 414
 415         // Remove trailing spaces, if limit == 0 is requested.
 416         if (limit == 0) {
 417             int i = list.size() - 1;
 418             // Don't remove 1st element, since array must not be empty.
 419             while(i > 0 && "".equals(list.get(i))) {
 420                 list.remove(i);
 421                 i--;
 422             }
 423         }
 424
 425         return list.toArray(new String[list.size()]);
 426     }
 427
 428     /**
 429      * Quotes a given string using "\Q" and "\E", so that all other
 430      * meta-characters lose their special meaning. If the string is used for a
 431      * {@code Pattern} afterwards, it can only be matched literally.
 432      *
 433      * @param s
 434      *            the string to quote.
 435      *
 436      * @return the quoted string.
 437      *
 438      * @since Android 1.0
 439      */
 440     public static String quote(String s) {
 441         StringBuffer sb = new StringBuffer().append("\\Q");
 442         int apos = 0;
 443         int k;
 444         while ((k = s.indexOf("\\E", apos)) >= 0) {
 445             sb.append(s.substring(apos, k + 2)).append("\\\\E\\Q");
 446             apos = k + 2;
 447         }
 448
 449         return sb.append(s.substring(apos)).append("\\E").toString();
 450     }
 451
 452     @Override
 453     public String toString() {
 454         return pattern;
 455     }
 456
 457     @Override
 458     protected void finalize() throws Throwable {
 459         try {
 460             if (mNativePattern != 0) {
 461                 NativeRegEx.close(mNativePattern);
 462             }
 463         }
 464         finally {
 465             super.finalize();
 466         }
 467     }
 468
 469     /**
 470      * Provides serialization support
 471      */
 472     private void readObject(java.io.ObjectInputStream s)
 473             throws java.io.IOException, ClassNotFoundException {
 474         s.defaultReadObject();
 475
 476         compileImpl(pattern, flags);
 477     }
 478
 479 }