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
17package com.android.i18n.phonenumbers;
18
19import com.android.i18n.phonenumbers.Phonenumber.PhoneNumber;
20
21import 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 */
54public 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