Home | History | Annotate | Download | only in phonenumbers 
      1 /*
      2  * Copyright (C) 2011 The Libphonenumber Authors
      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.google.i18n.phonenumbers;
     18 
     19 import com.google.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  * String country = "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 public final class PhoneNumberMatch {
     55   /** The start index into the text. */
     56   private final int start;
     57   /** The raw substring matched. */
     58   private final String rawString;
     59   /** The matched phone number. */
     60   private final PhoneNumber number;
     61 
     62   /**
     63    * Creates a new match.
     64    *
     65    * @param start  the start index into the target text
     66    * @param rawString  the matched substring of the target text
     67    * @param number  the matched phone number
     68    */
     69   PhoneNumberMatch(int start, String rawString, PhoneNumber number) {
     70     if (start < 0) {
     71       throw new IllegalArgumentException("Start index must be >= 0.");
     72     }
     73     if (rawString == null || number == null) {
     74       throw new NullPointerException();
     75     }
     76     this.start = start;
     77     this.rawString = rawString;
     78     this.number = number;
     79   }
     80 
     81   /** Returns the phone number matched by the receiver. */
     82   public PhoneNumber number() {
     83     return number;
     84   }
     85 
     86   /** Returns the start index of the matched phone number within the searched text. */
     87   public int start() {
     88     return start;
     89   }
     90 
     91   /** Returns the exclusive end index of the matched phone number within the searched text. */
     92   public int end() {
     93     return start + rawString.length();
     94   }
     95 
     96   /** Returns the raw string matched as a phone number in the searched text. */
     97   public String rawString() {
     98     return rawString;
     99   }
    100 
    101   @Override
    102   public int hashCode() {
    103     return Arrays.hashCode(new Object[]{start, rawString, number});
    104   }
    105 
    106   @Override
    107   public boolean equals(Object obj) {
    108     if (this == obj) {
    109       return true;
    110     }
    111     if (!(obj instanceof PhoneNumberMatch)) {
    112       return false;
    113     }
    114     PhoneNumberMatch other = (PhoneNumberMatch) obj;
    115     return rawString.equals(other.rawString) && (start == other.start) &&
    116         number.equals(other.number);
    117   }
    118 
    119   @Override
    120   public String toString() {
    121     return "PhoneNumberMatch [" + start() + "," + end() + ") " + rawString;
    122   }
    123 }
    124