Home | History | Annotate | Download | only in phonenumbers 
      1 /*
      2  * Copyright (C) 2011 Google Inc.
      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 com.android.i18n.phonenumbers;
     18 
     19 import com.android.i18n.phonenumbers.Phonenumber.PhoneNumber;
     20 
     21 import java.util.Arrays;
     22 
     23 /**
     24  * The immutable match of a phone number within a piece of text. Matches may be found using
     25  * {@link PhoneNumberUtil#findNumbers}.
     26  *
     27  * <p>A match consists of the {@linkplain #number() phone number} as well as the
     28  * {@linkplain #start() start} and {@linkplain #end() end} offsets of the corresponding subsequence
     29  * of the searched text. Use {@link #rawString()} to obtain a copy of the matched subsequence.
     30  *
     31  * <p>The following annotated example clarifies the relationship between the searched text, the
     32  * match offsets, and the parsed number:
     33 
     34  * <pre>
     35  * CharSequence text = "Call me at +1 425 882-8080 for details.";
     36  * RegionCode country = RegionCode.US;
     37  * PhoneNumberUtil util = PhoneNumberUtil.getInstance();
     38  *
     39  * // Find the first phone number match:
     40  * PhoneNumberMatch m = util.findNumbers(text, country).iterator().next();
     41  *
     42  * // rawString() contains the phone number as it appears in the text.
     43  * "+1 425 882-8080".equals(m.rawString());
     44  *
     45  * // start() and end() define the range of the matched subsequence.
     46  * CharSequence subsequence = text.subSequence(m.start(), m.end());
     47  * "+1 425 882-8080".contentEquals(subsequence);
     48  *
     49  * // number() returns the the same result as PhoneNumberUtil.{@link PhoneNumberUtil#parse parse()}
     50  * // invoked on rawString().
     51  * util.parse(m.rawString(), country).equals(m.number());
     52  * </pre>
     53  *
     54  * @author Tom Hofmann
     55  */
     56 public final class PhoneNumberMatch {
     57   /** The start index into the text. */
     58   private final int start;
     59   /** The raw substring matched. */
     60   private final String rawString;
     61   /** The matched phone number. */
     62   private final PhoneNumber number;
     63 
     64   /**
     65    * Creates a new match.
     66    *
     67    * @param start  the start index into the target text
     68    * @param rawString  the matched substring of the target text
     69    * @param number  the matched phone number
     70    */
     71   PhoneNumberMatch(int start, String rawString, PhoneNumber number) {
     72     if (start < 0) {
     73       throw new IllegalArgumentException("Start index must be >= 0.");
     74     }
     75     if (rawString == null || number == null) {
     76       throw new NullPointerException();
     77     }
     78     this.start = start;
     79     this.rawString = rawString;
     80     this.number = number;
     81   }
     82 
     83   /** Returns the phone number matched by the receiver. */
     84   public PhoneNumber number() {
     85     return number;
     86   }
     87 
     88   /** Returns the start index of the matched phone number within the searched text. */
     89   public int start() {
     90     return start;
     91   }
     92 
     93   /** Returns the exclusive end index of the matched phone number within the searched text. */
     94   public int end() {
     95     return start + rawString.length();
     96   }
     97 
     98   /** Returns the raw string matched as a phone number in the searched text. */
     99   public String rawString() {
    100     return rawString;
    101   }
    102 
    103   @Override
    104   public int hashCode() {
    105     return Arrays.hashCode(new Object[]{start, rawString, number});
    106   }
    107 
    108   @Override
    109   public boolean equals(Object obj) {
    110     if (this == obj) {
    111       return true;
    112     }
    113     if (!(obj instanceof PhoneNumberMatch)) {
    114       return false;
    115     }
    116     PhoneNumberMatch other = (PhoneNumberMatch) obj;
    117     return rawString.equals(other.rawString) && (start == other.start) &&
    118         number.equals(other.number);
    119   }
    120 
    121   @Override
    122   public String toString() {
    123     return "PhoneNumberMatch [" + start() + "," + end() + ") " + rawString;
    124   }
    125 }
    126