Create new class ParseWithOptions

java/libphonenumber/src/com/google/i18n/phonenumbers/ParsingOptions.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright (C) 2024 The Libphonenumber Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.i18n.phonenumbers;
+
+/** Options for the phone number parser. */
+public class ParsingOptions {
+  /**
+   * Returns the region we are expecting the number to be from. This is ignored if the number being
+   * parsed is written in international format. In case of national format, the country_code will be
+   * set to the one of this default region. If the number is guaranteed to start with a '+' followed
+   * by the country calling code, then RegionCode.ZZ or null can be supplied.
+   */
+
+  private boolean hasDefaultRegion;
+  private String defaultRegion_ = null;
+  public boolean hasDefaultRegion() { return hasDefaultRegion; }
+  public String getDefaultRegion() { return defaultRegion_; }
+  public ParsingOptions setDefaultRegion(String value) {
+    hasDefaultRegion = (value != null);
+    defaultRegion_ = value;
+    return this;
+  }
+
+  /**
+   * Returns whether the raw input should be kept in the PhoneNumber object. If true, the raw_input
+   * field and country_code_source fields will be populated.
+   */
+  private boolean hasKeepRawInput;
+  private boolean keepRawInput_ = false;
+  public boolean hasKeepRawInput() { return hasKeepRawInput; }
+  public boolean isKeepRawInput() { return keepRawInput_; }
+  public ParsingOptions setKeepRawInput(boolean value) {
+    if(value == false) {
+
+    }
+    hasKeepRawInput = true;
+    keepRawInput_ = value;
+    return this;
+  }
+
+  public ParsingOptions withDefaultRegion(String regionCode) {
+    return setDefaultRegion(regionCode);
+  }
+}

java/libphonenumber/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java

@@ -3140,7 +3140,10 @@ private boolean checkRegionForParsing(CharSequence numberToParse, String default
   public PhoneNumber parse(CharSequence numberToParse, String defaultRegion)
       throws NumberParseException {
     PhoneNumber phoneNumber = new PhoneNumber();
-    parse(numberToParse, defaultRegion, phoneNumber);
+    parseWithOptions(
+      numberToParse,
+      new ParsingOptions().setDefaultRegion(defaultRegion),
+      phoneNumber);
     return phoneNumber;
   }
 
@@ -3150,7 +3153,10 @@ public PhoneNumber parse(CharSequence numberToParse, String defaultRegion)
    */
   public void parse(CharSequence numberToParse, String defaultRegion, PhoneNumber phoneNumber)
       throws NumberParseException {
-    parseHelper(numberToParse, defaultRegion, false, true, phoneNumber);
+    parseWithOptions(
+      numberToParse,
+      new ParsingOptions().setDefaultRegion(defaultRegion),
+      phoneNumber);
   }
 
   /**
@@ -3166,22 +3172,77 @@ public void parse(CharSequence numberToParse, String defaultRegion, PhoneNumber
    * @return  a phone number proto buffer filled with the parsed number
    * @throws NumberParseException  if the string is not considered to be a viable phone number or if
    *     no default region was supplied
+   * @deprecated Use {@link #parseWithOptions(CharSequence, ParsingOptions)} instead.
    */
+  @Deprecated
   public PhoneNumber parseAndKeepRawInput(CharSequence numberToParse, String defaultRegion)
       throws NumberParseException {
     PhoneNumber phoneNumber = new PhoneNumber();
-    parseAndKeepRawInput(numberToParse, defaultRegion, phoneNumber);
+    parseWithOptions(
+      numberToParse,
+      new ParsingOptions().setKeepRawInput(true).setDefaultRegion(defaultRegion),
+      phoneNumber);
     return phoneNumber;
   }
 
   /**
    * Same as{@link #parseAndKeepRawInput(CharSequence, String)}, but accepts a mutable
    * PhoneNumber as a parameter to decrease object creation when invoked many times.
+   * @deprecated Use {@link #parseWithOptions(CharSequence, ParsingOptions, PhoneNumber)} instead.
    */
-  public void parseAndKeepRawInput(CharSequence numberToParse, String defaultRegion,
-                                   PhoneNumber phoneNumber)
+  @Deprecated
+  public void parseAndKeepRawInput(CharSequence numberToParse, String defaultRegion, PhoneNumber phoneNumber)
       throws NumberParseException {
-    parseHelper(numberToParse, defaultRegion, true, true, phoneNumber);
+    parseWithOptions(
+      numberToParse,
+      new ParsingOptions().setKeepRawInput(true).setDefaultRegion(defaultRegion),
+      phoneNumber);
+  }
+
+  /**
+   * Parses a string and returns it as a PhoneNumber object. The method is quite lenient and looks
+   * for a number in the input text (raw input) and does not check whether the string is definitely
+   * only a phone number. To do this, it ignores punctuation and white-space, as well as any text
+   * before the number (e.g. a leading "Tel: ") and trims the non-number bits. It will accept a
+   * number in any format (E164, national, international etc), assuming it can be interpreted with
+   * the options supplied. It also attempts to convert any alpha characters into digits if it thinks
+   * this is a vanity number of the type "1800 MICROSOFT".
+   *
+   * <p>This method will throw a {@link com.google.i18n.phonenumbers.NumberParseException} if the
+   * number is not considered to be a possible number. Note that validation of whether the number is
+   * actually a valid number for a particular region is not performed. This can be done separately
+   * with {@link #isValidNumber}.
+   *
+   * <p>Note this method canonicalizes the phone number such that different representations can be
+   * easily compared, no matter what form it was originally entered in (e.g. national,
+   * international). If you want to record context about the number being parsed, such as the raw
+   * input that was entered, how the country code was derived etc. then set the `keepRawInput`
+   * option in the options accordingly.
+   *
+   * @param numberToParse number that we are attempting to parse. This can contain formatting such
+   *     as +, ( and -, as well as a phone number extension. It can also be provided in RFC3966
+   *     format.
+   * @param options options to configure the behavior of the parser. See {@link ParsingOptions} for
+   *     more details.
+   * @return a phone number proto buffer filled with the parsed number.
+   * @throws NumberParseException if the string is not considered to be a viable phone number (e.g.
+   *     too few or too many digits) or if no default region was supplied and the number is not in
+   *     international format (does not start with +).
+   */
+  public PhoneNumber parseWithOptions(CharSequence numberToParse, ParsingOptions options)
+      throws NumberParseException {
+    PhoneNumber phoneNumber = new PhoneNumber();
+    parseWithOptions(numberToParse, options, phoneNumber);
+    return phoneNumber;
+  }
+
+  /**
+   * Same as{@link #parseWithOptions(CharSequence, ParsingOptions)}, but accepts a mutable
+   * PhoneNumber as a parameter to decrease object creation when invoked many times.
+   */
+  public void parseWithOptions(CharSequence numberToParse, ParsingOptions options, PhoneNumber phoneNumber)
+      throws NumberParseException {
+    parseHelper(numberToParse, options.getDefaultRegion(), options.isKeepRawInput(), true, phoneNumber);
   }
 
   /**