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

Print this page




2809      *          specifier that is incompatible with the given arguments,
2810      *          insufficient arguments given the format string, or other
2811      *          illegal conditions.  For specification of all possible
2812      *          formatting errors, see the <a
2813      *          href="../util/Formatter.html#detail">Details</a> section of the
2814      *          formatter class specification
2815      *
2816      * @throws  NullPointerException
2817      *          If the <tt>format</tt> is <tt>null</tt>
2818      *
2819      * @return  A formatted string
2820      *
2821      * @see  java.util.Formatter
2822      * @since  1.5
2823      */
2824     public static String format(Locale l, String format, Object ... args) {
2825         return new Formatter(l).format(format, args).toString();
2826     }
2827 
2828     /**


























































































2829      * Returns the string representation of the <code>Object</code> argument.
2830      *
2831      * @param   obj   an <code>Object</code>.
2832      * @return  if the argument is <code>null</code>, then a string equal to
2833      *          <code>"null"</code>; otherwise, the value of
2834      *          <code>obj.toString()</code> is returned.
2835      * @see     java.lang.Object#toString()
2836      */
2837     public static String valueOf(Object obj) {
2838         return (obj == null) ? "null" : obj.toString();
2839     }
2840 
2841     /**
2842      * Returns the string representation of the <code>char</code> array
2843      * argument. The contents of the character array are copied; subsequent
2844      * modification of the character array does not affect the newly
2845      * created string.
2846      *
2847      * @param   data   a <code>char</code> array.
2848      * @return  a newly allocated string representing the same sequence of




2809      *          specifier that is incompatible with the given arguments,
2810      *          insufficient arguments given the format string, or other
2811      *          illegal conditions.  For specification of all possible
2812      *          formatting errors, see the <a
2813      *          href="../util/Formatter.html#detail">Details</a> section of the
2814      *          formatter class specification
2815      *
2816      * @throws  NullPointerException
2817      *          If the <tt>format</tt> is <tt>null</tt>
2818      *
2819      * @return  A formatted string
2820      *
2821      * @see  java.util.Formatter
2822      * @since  1.5
2823      */
2824     public static String format(Locale l, String format, Object ... args) {
2825         return new Formatter(l).format(format, args).toString();
2826     }
2827 
2828     /**
2829      * Returns a new String that is a composition of the values returned
2830      * by calling {@link String#valueOf(Object)} on each element and joining them together
2831      * with the current String instance.
2832      *
2833      * <blockquote>An example:
2834      * <pre>
2835      * String message = " ".join("Java", "is", "cool" );
2836      * // message returned is: "Java is cool"
2837      * </pre></blockquote>
2838      *
2839      * @param first the first element to join
2840      * @param elements  the other Object elements to join together with the first one.
2841      * @return a new String that is composed from the first and the elements parameters and
2842      *         the String instance used as delimiter.
2843      *
2844      * @see StringBuilder#join(String,Object,Object[])
2845      *
2846      * @throws  NullPointerException
2847      *          If <tt>elements</tt> is <tt>null</tt>
2848      *
2849      * @since 1.7
2850      */
2851     public String join(Object first, Object... elements) {
2852         if (elements.length==0)
2853           return String.valueOf(first);
2854         return new StringBuilder().join(this, first, elements).toString();
2855     }
2856 
2857     /**
2858      * Returns a new String that is a composition of the values returned
2859      * by calling {@link String#valueOf(Object)} on each array element
2860      * and joining them together with the current String instance.
2861      *
2862      * <blockquote>An example:
2863      * <pre>
2864      * String[] strings = new String[]{ "Java", "is", "cool" };
2865      * String message = " ".join( strings );
2866      * // message returned is: "Java is cool"
2867      * </pre></blockquote>
2868      *
2869      * @param elements an array of Object element to join together.
2870      * @return a new String that is composed from the elements parameters joining
2871      *         with the current String instance.
2872      *
2873      * @see #join(Object[])
2874      * @see StringBuilder#join(String,Object[])
2875      *
2876      * @throws  NullPointerException
2877      *          If <tt>elements</tt> is <tt>null</tt>
2878      *
2879      * @since 1.7
2880      */
2881     public String join(Object[] elements) {
2882         return new StringBuilder().join(this, elements).toString();
2883     }
2884     
2885     /**
2886      * Returns a new String that is a composition of the values returned by
2887      * calling {@link String#valueOf(Object)} on each of the elements
2888      * parameter and joining them together with the current String instance.
2889      *
2890      * <blockquote>Two examples:
2891      * <pre>
2892      * List&lt;String&gt; strings = new LinkedList&lt;String&gt;();
2893      * strings.add( "Java" ); strings.add( "is" ); strings.add( "cool" );
2894      * String message = " ".join( strings );
2895      * //message returned is: "Java is cool"
2896      * Set&lt;String&gt; strings = new HashSet&lt;String&gt;();
2897      * strings.add( "Java" ); strings.add( "is" ); strings.add( "cool" );
2898      * String message = " ".join( strings );
2899      * //message returned is: "Java is cool"
2900      * </pre></blockquote>
2901      *
2902      * @param elements an Iterable that will have its elements joined together.
2903      * @return a new String that is composed from the elements parameters
2904      *         and the current String instance.
2905      *
2906      * @see #join(Object[])
2907      * @see StringBuilder#join(String,Iterable)
2908      *
2909      * @throws  NullPointerException
2910      *          If <tt>elements</tt> is <tt>null</tt>
2911      *
2912      * @since 1.7
2913      */
2914     public String join(Iterable<?> elements) {
2915       return new StringBuilder().join(this, elements).toString();
2916     } 
2917     
2918     /**
2919      * Returns the string representation of the <code>Object</code> argument.
2920      *
2921      * @param   obj   an <code>Object</code>.
2922      * @return  if the argument is <code>null</code>, then a string equal to
2923      *          <code>"null"</code>; otherwise, the value of
2924      *          <code>obj.toString()</code> is returned.
2925      * @see     java.lang.Object#toString()
2926      */
2927     public static String valueOf(Object obj) {
2928         return (obj == null) ? "null" : obj.toString();
2929     }
2930 
2931     /**
2932      * Returns the string representation of the <code>char</code> array
2933      * argument. The contents of the character array are copied; subsequent
2934      * modification of the character array does not affect the newly
2935      * created string.
2936      *
2937      * @param   data   a <code>char</code> array.
2938      * @return  a newly allocated string representing the same sequence of