106: Shall we also use ParsePosition in UnitFormat?

Task-Url: https://github.com/unitsofmeasurement/unit-api/issues/issues/106

Author: keilw

src/main/java/javax/measure/format/UnitFormat.java

@@ -30,6 +30,7 @@
 package javax.measure.format;
 
 import java.io.IOException;
+import java.text.ParsePosition;
 
 import javax.measure.Unit;
 
@@ -45,7 +46,7 @@
  * @author <a href="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
  * @author <a href="mailto:werner@uom.technology">Werner Keil</a>
  *
- * @version 1.2, June 25, 2018
+ * @version 1.3, August 8, 2018
  * @since 1.0
  *
  * @see Unit
@@ -111,6 +112,20 @@ public interface UnitFormat {
   default boolean isLocaleSensitive() {
       return false;
   }
+  
+  /**
+   * Parses a portion of the specified <code>CharSequence</code> from the specified position to produce a {@link Unit}. If parsing succeeds, then
+   * the index of the <code>cursor</code> argument is updated to the index after the last character used.
+   *
+   * @param csq
+   *          the <code>CharSequence</code> to parse.
+   * @param cursor
+   *          the cursor holding the current parsing index.
+   * @return the unit parsed from the specified character sub-sequence.
+   * @throws IllegalArgumentException
+   *           if any problem occurs while parsing the specified character sequence (e.g. illegal syntax).
+   */
+  Unit<?> parse(CharSequence csq, ParsePosition cursor) throws IllegalArgumentException, MeasurementParseException;
 
   /**
    * Parses the text into an instance of {@link Unit}.
@@ -126,6 +141,7 @@ default boolean isLocaleSensitive() {
    *           if any problem occurs while parsing the specified character sequence (e.g. illegal syntax).
    * @throws UnsupportedOperationException
    *           if the {@link UnitFormat} is unable to parse.
+   * @since 2.0
    */
   Unit<?> parse(CharSequence csq) throws MeasurementParseException;
 }

src/test/java/javax/measure/test/format/SimpleTestUnitFormat.java

@@ -41,7 +41,7 @@
  * Provides a simple interface for formatting and parsing {@linkplain Unit units}.
  *
  * @author <a href="mailto:units@catmedia.us">Werner Keil</a>
- * @version 0.5
+ * @version 0.6
  */
 public class SimpleTestUnitFormat extends TestUnitFormat {
   private final Map<String, String> symbolMap = new HashMap<>();

src/test/java/javax/measure/test/format/TestUnitFormat.java

@@ -30,6 +30,7 @@
 package javax.measure.test.format;
 
 import java.io.IOException;
+import java.text.ParsePosition;
 import java.util.HashMap;
 import java.util.Map;
 
@@ -119,6 +120,20 @@ public final Unit<?> parse(CharSequence csq) throws MeasurementParseException {
     return parse(csq, 0);
   }
 
+  /**
+   * Parses the specified character sequence to produce a unit (convenience method). If the specified sequence is empty, the unitary unit
+   * (dimensionless) is returned.
+   *
+   * @param csq
+   *          the <code>CharSequence</code> to parse.
+   * @return the unit parsed from the specified character sub-sequence.
+   * @throws ParseException
+   *           if any problem occurs while parsing the specified character sequence (e.g. illegal syntax).
+   */
+  public final Unit<?> parse(CharSequence csq, ParsePosition pos) throws MeasurementParseException {
+    return parse(csq, pos.getIndex());
+  }
+
   /**
    * Formats an object to produce a string. This is equivalent to <blockquote> {@link #format(Unit, Appendable) format}<code>(unit,
    *         new StringBuilder()).toString();</code> </blockquote>