Refactor TextUtils.join() and add documentation

Added documentation to clarify what happens in the case of null or
empty arguments.

Change-Id: I694dc0f6a6d95ab6ca7ed95b51d81938618eb75f
Fixes: 36861796
Test: bit CtsTextTestCases:*
Test: bit CtsGraphicsTestCases:android.graphics.cts.FontVariationAxisTest

1 files changed, 31 insertions, 22 deletions

diff --git a/core/java/android/text/TextUtils.java b/core/java/android/text/TextUtils.java
index 440c88e8cabb..f981e740dcfb 100644
--- a/core/java/android/text/TextUtils.java
+++ b/core/java/android/text/TextUtils.java
@@ -297,37 +297,46 @@ public class TextUtils {
 
     /**
      * Returns a string containing the tokens joined by delimiters.
-     * @param tokens an array objects to be joined. Strings will be formed from
-     *     the objects by calling object.toString().
+     *
+     * @param delimiter a CharSequence that will be inserted between the tokens. If null, the string
+     *     "null" will be used as the delimiter.
+     * @param tokens an array objects to be joined. Strings will be formed from the objects by
+     *     calling object.toString(). If tokens is null, a NullPointerException will be thrown. If
+     *     tokens is an empty array, an empty string will be returned.
      */
-    public static String join(CharSequence delimiter, Object[] tokens) {
-        StringBuilder sb = new StringBuilder();
-        boolean firstTime = true;
-        for (Object token: tokens) {
-            if (firstTime) {
-                firstTime = false;
-            } else {
-                sb.append(delimiter);
-            }
-            sb.append(token);
+    public static String join(@NonNull CharSequence delimiter, @NonNull Object[] tokens) {
+        final int length = tokens.length;
+        if (length == 0) {
+            return "";
+        }
+        final StringBuilder sb = new StringBuilder();
+        sb.append(tokens[0]);
+        for (int i = 1; i < length; i++) {
+            sb.append(delimiter);
+            sb.append(tokens[i]);
         }
         return sb.toString();
     }
 
     /**
      * Returns a string containing the tokens joined by delimiters.
-     * @param tokens an array objects to be joined. Strings will be formed from
-     *     the objects by calling object.toString().
+     *
+     * @param delimiter a CharSequence that will be inserted between the tokens. If null, the string
+     *     "null" will be used as the delimiter.
+     * @param tokens an array objects to be joined. Strings will be formed from the objects by
+     *     calling object.toString(). If tokens is null, a NullPointerException will be thrown. If
+     *     tokens is empty, an empty string will be returned.
      */
-    public static String join(CharSequence delimiter, Iterable tokens) {
-        StringBuilder sb = new StringBuilder();
-        Iterator<?> it = tokens.iterator();
-        if (it.hasNext()) {
+    public static String join(@NonNull CharSequence delimiter, @NonNull Iterable tokens) {
+        final Iterator<?> it = tokens.iterator();
+        if (!it.hasNext()) {
+            return "";
+        }
+        final StringBuilder sb = new StringBuilder();
+        sb.append(it.next());
+        while (it.hasNext()) {
+            sb.append(delimiter);
             sb.append(it.next());
-            while (it.hasNext()) {
-                sb.append(delimiter);
-                sb.append(it.next());
-            }
         }
         return sb.toString();
     }