src/share/classes/java/lang/String.java

Print this page

        

@@ -2824,10 +2824,100 @@
     public static String format(Locale l, String format, Object ... args) {
         return new Formatter(l).format(format, args).toString();
     }
 
     /**
+     * Returns a new String that is a composition of the values returned
+     * by calling {@link String#valueOf(Object)} on each element and joining them together
+     * with the current String instance.
+     *
+     * <blockquote>An example:
+     * <pre>
+     * String message = " ".join("Java", "is", "cool" );
+     * // message returned is: "Java is cool"
+     * </pre></blockquote>
+     *
+     * @param first the first element to join
+     * @param elements  the other Object elements to join together with the first one.
+     * @return a new String that is composed from the first and the elements parameters and
+     *         the String instance used as delimiter.
+     *
+     * @see StringBuilder#join(String,Object,Object[])
+     *
+     * @throws  NullPointerException
+     *          If <tt>elements</tt> is <tt>null</tt>
+     *
+     * @since 1.7
+     */
+    public String join(Object first, Object... elements) {
+        if (elements.length==0)
+          return String.valueOf(first);
+        return new StringBuilder().join(this, first, elements).toString();
+    }
+
+    /**
+     * Returns a new String that is a composition of the values returned
+     * by calling {@link String#valueOf(Object)} on each array element
+     * and joining them together with the current String instance.
+     *
+     * <blockquote>An example:
+     * <pre>
+     * String[] strings = new String[]{ "Java", "is", "cool" };
+     * String message = " ".join( strings );
+     * // message returned is: "Java is cool"
+     * </pre></blockquote>
+     *
+     * @param elements an array of Object element to join together.
+     * @return a new String that is composed from the elements parameters joining
+     *         with the current String instance.
+     *
+     * @see #join(Object[])
+     * @see StringBuilder#join(String,Object[])
+     *
+     * @throws  NullPointerException
+     *          If <tt>elements</tt> is <tt>null</tt>
+     *
+     * @since 1.7
+     */
+    public String join(Object[] elements) {
+        return new StringBuilder().join(this, elements).toString();
+    }
+    
+    /**
+     * Returns a new String that is a composition of the values returned by
+     * calling {@link String#valueOf(Object)} on each of the elements
+     * parameter and joining them together with the current String instance.
+     *
+     * <blockquote>Two examples:
+     * <pre>
+     * List&lt;String&gt; strings = new LinkedList&lt;String&gt;();
+     * strings.add( "Java" ); strings.add( "is" ); strings.add( "cool" );
+     * String message = " ".join( strings );
+     * //message returned is: "Java is cool"
+     * Set&lt;String&gt; strings = new HashSet&lt;String&gt;();
+     * strings.add( "Java" ); strings.add( "is" ); strings.add( "cool" );
+     * String message = " ".join( strings );
+     * //message returned is: "Java is cool"
+     * </pre></blockquote>
+     *
+     * @param elements an Iterable that will have its elements joined together.
+     * @return a new String that is composed from the elements parameters
+     *         and the current String instance.
+     *
+     * @see #join(Object[])
+     * @see StringBuilder#join(String,Iterable)
+     *
+     * @throws  NullPointerException
+     *          If <tt>elements</tt> is <tt>null</tt>
+     *
+     * @since 1.7
+     */
+    public String join(Iterable<?> elements) {
+      return new StringBuilder().join(this, elements).toString();
+    } 
+    
+    /**
      * Returns the string representation of the <code>Object</code> argument.
      *
      * @param   obj   an <code>Object</code>.
      * @return  if the argument is <code>null</code>, then a string equal to
      *          <code>"null"</code>; otherwise, the value of