Add parsingOptions to OpenSource

I have added the new parsing methode ParsingOptions to the OpenSource version.

Author: KarolJakubKrawiec

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

@@ -0,0 +1,61 @@
+/*
+ * 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) {
+    if (value == null) {
+      throw new NullPointerException();
+    }
+    hasDefaultRegion = true;
+    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

@@ -3136,7 +3136,9 @@ private boolean checkRegionForParsing(CharSequence numberToParse, String default
    * @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 +)
+   * @deprecated Use {@link #parseWithOptions(CharSequence, ParsingOptions)} instead.
    */
+  @Deprecated
   public PhoneNumber parse(CharSequence numberToParse, String defaultRegion)
       throws NumberParseException {
     PhoneNumber phoneNumber = new PhoneNumber();
@@ -3147,7 +3149,9 @@ public PhoneNumber parse(CharSequence numberToParse, String defaultRegion)
   /**
    * Same as {@link #parse(CharSequence, String)}, but accepts mutable PhoneNumber as a
    * parameter to decrease object creation when invoked many times.
+   * @deprecated Use {@link #parseWithOptions(CharSequence, ParsingOptions, PhoneNumber)} instead.
    */
+  @Deprecated
   public void parse(CharSequence numberToParse, String defaultRegion, PhoneNumber phoneNumber)
       throws NumberParseException {
     parseHelper(numberToParse, defaultRegion, false, true, phoneNumber);
@@ -3166,7 +3170,9 @@ 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();
@@ -3177,13 +3183,26 @@ public PhoneNumber parseAndKeepRawInput(CharSequence numberToParse, String defau
   /**
    * 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);
   }
 
+  public PhoneNumber parseWithOptions(CharSequence numberToParse, ParsingOptions options)
+      throws NumberParseException {
+    PhoneNumber phoneNumber = new PhoneNumber();
+    parseHelper(numberToParse, options.getDefaultRegion(), options.hasKeepRawInput(), options.hasDefaultRegion(), phoneNumber);
+    return phoneNumber;
+  }
+
+  public void parseWithOptions(CharSequence numberToParse, ParsingOptions options, PhoneNumber phoneNumber)
+      throws NumberParseException {
+        parseHelper(numberToParse, options.getDefaultRegion(), options.hasKeepRawInput(), options.hasDefaultRegion(), phoneNumber);
+      }
+
   /**
    * Returns an iterable over all {@link PhoneNumberMatch PhoneNumberMatches} in {@code text}. This
    * is a shortcut for {@link #findNumbers(CharSequence, String, Leniency, long)