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.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 */ PhoneNumberMatch(int start, String rawString, PhoneNumber number)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. */ number()84 public PhoneNumber number() { 85 return number; 86 } 87 88 /** Returns the start index of the matched phone number within the searched text. */ start()89 public int start() { 90 return start; 91 } 92 93 /** Returns the exclusive end index of the matched phone number within the searched text. */ end()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. */ rawString()99 public String rawString() { 100 return rawString; 101 } 102 103 @Override hashCode()104 public int hashCode() { 105 return Arrays.hashCode(new Object[]{start, rawString, number}); 106 } 107 108 @Override equals(Object obj)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 toString()122 public String toString() { 123 return "PhoneNumberMatch [" + start() + "," + end() + ") " + rawString; 124 } 125 } 126