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