options refactoring, lists are used instead of strings. Tests updated (#1118)

Author: korshaknn

samples/src/main/java/com/mapbox/samples/BasicDirectionsRefresh.java

@@ -31,7 +31,7 @@ private static String simpleMapboxDirectionsRequest() throws IOException {
       .destination(Point.fromLngLat(-95.3591, 29.7576))
       .overview(OVERVIEW_FULL)
       .profile(PROFILE_DRIVING_TRAFFIC)
-      .annotations(ANNOTATION_CONGESTION).build();
+      .addAnnotation(ANNOTATION_CONGESTION).build();
 
     Response<DirectionsResponse> response = directions.executeCall();
     System.out.println("Directions response: " + response);

services-core/src/main/java/com/mapbox/core/utils/TextUtils.java

@@ -93,7 +93,9 @@ public static String formatCoordinate(double coordinate, int precision) {
    * @param radiuses a double array which represents the radius values
    * @return a String ready for being passed into the Retrofit call
    * @since 3.0.0
+   * @deprecated use FormatUtils.formatRadiuses(List)
    */
+  @Deprecated
   public static String formatRadiuses(double[] radiuses) {
     if (radiuses == null || radiuses.length == 0) {
       return null;
@@ -118,7 +120,9 @@ public static String formatRadiuses(double[] radiuses) {
    * @param bearings a List of doubles representing bearing values
    * @return a string with the bearing values
    * @since 3.0.0
+   * @deprecated use FormatUtils.formatBearing(List)
    */
+  @Deprecated
   public static String formatBearing(List<Double[]> bearings) {
     if (bearings.isEmpty()) {
       return null;
@@ -143,7 +147,9 @@ public static String formatBearing(List<Double[]> bearings) {
    * @param distributions the list of integer arrays representing the distribution
    * @return a string with the distribution values
    * @since 3.0.0
+   * @deprecated use FormatUtils.formatDistributions(List)
    */
+  @Deprecated
   public static String formatDistributions(List<Integer[]> distributions) {
     if (distributions.isEmpty()) {
       return null;
@@ -170,13 +176,15 @@ public static String formatDistributions(List<Integer[]> distributions) {
    * @param approaches a string representing approaches to each coordinate.
    * @return a formatted string.
    * @since 3.2.0
+   * @deprecated use FormatUtils.formatApproaches(List)
    */
+  @Deprecated
   public static String formatApproaches(String[] approaches) {
     for (int i = 0; i < approaches.length; i++) {
       if (approaches[i] == null) {
         approaches[i] = "";
       } else if (!approaches[i].equals("unrestricted")
-        && !approaches[i].equals("curb") && !approaches[i].isEmpty()) {
+          && !approaches[i].equals("curb") && !approaches[i].isEmpty()) {
         return null;
       }
     }
@@ -190,7 +198,9 @@ public static String formatApproaches(String[] approaches) {
    * @param waypointNames a string representing approaches to each coordinate.
    * @return a formatted string.
    * @since 3.3.0
+   * @deprecated use FormatUtils.formatWaypointNames(List)
    */
+  @Deprecated
   public static String formatWaypointNames(String[] waypointNames) {
     for (int i = 0; i < waypointNames.length; i++) {
       if (waypointNames[i] == null) {

services-directions-models/src/main/java/com/mapbox/api/directions/v5/models/RouteOptions.java

@@ -0,0 +1,243 @@
+package com.mapbox.api.directions.v5.utils;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+import com.mapbox.geojson.Point;
+import java.text.DecimalFormat;
+import java.text.DecimalFormatSymbols;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+
+/**
+ * Methods to convert models to Strings.
+ */
+public class FormatUtils {
+  /**
+   * Returns a string containing the tokens joined by delimiters. Doesn't remove trailing nulls.
+   *
+   * @param delimiter the delimiter on which to split.
+   * @param tokens A list of objects to be joined. Strings will be formed from the objects by
+   *               calling object.toString().
+   * @return {@link String}
+   */
+  @Nullable
+  public static String join(@NonNull CharSequence delimiter, @Nullable List<?> tokens) {
+    return join(delimiter, tokens, false);
+  }
+
+  /**
+   * Returns a string containing the tokens joined by delimiters.
+   *
+   * @param delimiter the delimiter on which to split.
+   * @param tokens A list of objects to be joined. Strings will be formed from the objects by
+   *               calling object.toString().
+   * @param removeTrailingNulls true if trailing nulls should be removed.
+   * @return {@link String}
+   */
+  @Nullable
+  public static String join(@NonNull CharSequence delimiter, @Nullable List<?> tokens,
+      boolean removeTrailingNulls) {
+    if (tokens == null || tokens.size() < 1) {
+      return null;
+    }
+
+    int lastNonNullToken = tokens.size() - 1;
+    if (removeTrailingNulls) {
+      for (int i = tokens.size() - 1; i >= 0; i--) {
+        Object token = tokens.get(i);
+        if (token != null) {
+          break;
+        } else {
+          lastNonNullToken--;
+        }
+      }
+    }
+
+    StringBuilder sb = new StringBuilder();
+    boolean firstTime = true;
+    for (int i = 0; i <= lastNonNullToken; i++) {
+      if (firstTime) {
+        firstTime = false;
+      } else {
+        sb.append(delimiter);
+      }
+      Object token = tokens.get(i);
+      if (token != null) {
+        sb.append(token);
+      }
+    }
+    return sb.toString();
+  }
+
+  /**
+   * Useful to remove any trailing zeros and prevent a coordinate being over 7 significant figures.
+   *
+   * @param coordinate a double value representing a coordinate.
+   * @return a formatted string.
+   */
+  @NonNull
+  public static String formatCoordinate(double coordinate) {
+    DecimalFormat decimalFormat = new DecimalFormat("0.######",
+        new DecimalFormatSymbols(Locale.US));
+    return String.format(Locale.US, "%s",
+        decimalFormat.format(coordinate));
+  }
+
+  /**
+   * Used in various APIs to format the user provided radiuses to a String matching the APIs
+   * format.
+   *
+   * @param radiuses a list of doubles represents the radius values
+   * @return a String ready for being passed into the Retrofit call
+   */
+  @Nullable
+  public static String formatRadiuses(@Nullable List<Double> radiuses) {
+    if (radiuses == null || radiuses.size() == 0) {
+      return null;
+    }
+
+    List<String> radiusesToJoin = new ArrayList<>();
+    for (Double radius : radiuses) {
+      if (radius == null) {
+        radiusesToJoin.add(null);
+      } else if (radius == Double.POSITIVE_INFINITY) {
+        radiusesToJoin.add("unlimited");
+      } else {
+        radiusesToJoin.add(String.format(Locale.US, "%s", formatCoordinate(radius)));
+      }
+    }
+    return join(";", radiusesToJoin);
+  }
+
+  /**
+   * Formats the bearing variables from the raw values to a string which can than be used for the
+   * request URL.
+   *
+   * @param bearings a List of list of doubles representing bearing values
+   * @return a string with the bearing values
+   */
+  @Nullable
+  public static String formatBearings(@Nullable List<List<Double>> bearings) {
+    if (bearings == null || bearings.isEmpty()) {
+      return null;
+    }
+
+    List<String> bearingsToJoin = new ArrayList<>();
+    for (List<Double> bearing : bearings) {
+      if (bearing == null || bearing.size() == 0) {
+        bearingsToJoin.add(null);
+      } else {
+        bearingsToJoin.add(String.format(Locale.US, "%s,%s",
+            formatCoordinate(bearing.get(0)),
+            formatCoordinate(bearing.get(1))));
+      }
+    }
+    return join(";", bearingsToJoin);
+  }
+
+  /**
+   * Converts the list of integer arrays to a string ready for API consumption.
+   *
+   * @param distributions the list of integer arrays representing the distribution
+   * @return a string with the distribution values
+   */
+  @Nullable
+  public static String formatDistributions(@Nullable List<Integer[]> distributions) {
+    if (distributions == null || distributions.isEmpty()) {
+      return null;
+    }
+
+    List<String> distributionsToJoin = new ArrayList<>();
+    for (Integer[] array : distributions) {
+      if (array.length == 0) {
+        distributionsToJoin.add(null);
+      } else {
+        distributionsToJoin.add(String.format(Locale.US, "%s,%s",
+            formatCoordinate(array[0]),
+            formatCoordinate(array[1])));
+      }
+    }
+    return join(";", distributionsToJoin);
+  }
+
+  /**
+   * Converts String list with approaches values to a string ready for API consumption. An approach
+   * could be unrestricted, curb or null.
+   *
+   * @param approaches a list representing approaches to each coordinate.
+   * @return a formatted string.
+   */
+  @Nullable
+  public static String formatApproaches(@Nullable List<String> approaches) {
+    if (approaches == null || approaches.isEmpty()) {
+      return null;
+    }
+
+    for (String approach : approaches) {
+      if (approach != null && !approach.equals("unrestricted") && !approach.equals("curb")
+          && !approach.isEmpty()) {
+        return null;
+      }
+    }
+    return join(";", approaches);
+  }
+
+  /**
+   * Converts String list with waypoint_names values to a string ready for API consumption.
+   *
+   * @param waypointNames a string representing approaches to each coordinate.
+   * @return a formatted string.
+   */
+  @Nullable
+  public static String formatWaypointNames(@Nullable List<String> waypointNames) {
+    if (waypointNames == null || waypointNames.isEmpty()) {
+      return null;
+    }
+
+    return join(";", waypointNames);
+  }
+
+  /**
+   * Converts a list of Points to String.
+   *
+   * @param coordinates a list of coordinates.
+   * @return a formatted string.
+   */
+  @Nullable
+  public static String formatCoordinates(@NonNull List<Point> coordinates) {
+    List<String> coordinatesToJoin = new ArrayList<>();
+    for (Point point : coordinates) {
+      coordinatesToJoin.add(String.format(Locale.US, "%s,%s",
+          formatCoordinate(point.longitude()),
+          formatCoordinate(point.latitude())));
+    }
+
+    return join(";", coordinatesToJoin);
+  }
+
+  /**
+   * Converts array of Points with waypoint_targets values to a string ready for API consumption.
+   *
+   * @param points a list representing approaches to each coordinate.
+   * @return a formatted string.
+   */
+  @Nullable
+  public static String formatPointsList(@Nullable List<Point> points) {
+    if (points == null || points.isEmpty()) {
+      return null;
+    }
+
+    List<String> coordinatesToJoin = new ArrayList<>();
+    for (Point point : points) {
+      if (point == null) {
+        coordinatesToJoin.add(null);
+      } else {
+        coordinatesToJoin.add(String.format(Locale.US, "%s,%s",
+            formatCoordinate(point.longitude()),
+            formatCoordinate(point.latitude())));
+      }
+    }
+    return join(";", coordinatesToJoin);
+  }
+}