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

Print this page

        

*** 2824,2833 **** --- 2824,2923 ---- 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