< prev index next >

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

Print this page




  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.lang;
  27 
  28 import java.io.ObjectStreamField;
  29 import java.io.UnsupportedEncodingException;
  30 import java.lang.annotation.Native;
  31 import java.lang.invoke.MethodHandles;

  32 import java.lang.constant.Constable;
  33 import java.lang.constant.ConstantDesc;
  34 import java.nio.charset.Charset;
  35 import java.util.ArrayList;
  36 import java.util.Arrays;
  37 import java.util.Comparator;
  38 import java.util.Formatter;
  39 import java.util.Locale;
  40 import java.util.Objects;
  41 import java.util.Optional;
  42 import java.util.Spliterator;
  43 import java.util.StringJoiner;
  44 import java.util.function.Function;
  45 import java.util.regex.Matcher;
  46 import java.util.regex.Pattern;
  47 import java.util.regex.PatternSyntaxException;
  48 import java.util.stream.Collectors;
  49 import java.util.stream.IntStream;
  50 import java.util.stream.Stream;
  51 import java.util.stream.StreamSupport;


2945      * Converts this string to a new character array.
2946      *
2947      * @return  a newly allocated character array whose length is the length
2948      *          of this string and whose contents are initialized to contain
2949      *          the character sequence represented by this string.
2950      */
2951     public char[] toCharArray() {
2952         return isLatin1() ? StringLatin1.toChars(value)
2953                           : StringUTF16.toChars(value);
2954     }
2955 
2956     /**
2957      * Returns a formatted string using the specified format string and
2958      * arguments.
2959      *
2960      * <p> The locale always used is the one returned by {@link
2961      * java.util.Locale#getDefault(java.util.Locale.Category)
2962      * Locale.getDefault(Locale.Category)} with
2963      * {@link java.util.Locale.Category#FORMAT FORMAT} category specified.
2964      *













2965      * @param  format
2966      *         A <a href="../util/Formatter.html#syntax">format string</a>
2967      *
2968      * @param  args
2969      *         Arguments referenced by the format specifiers in the format
2970      *         string.  If there are more arguments than format specifiers, the
2971      *         extra arguments are ignored.  The number of arguments is
2972      *         variable and may be zero.  The maximum number of arguments is
2973      *         limited by the maximum dimension of a Java array as defined by
2974      *         <cite>The Java&trade; Virtual Machine Specification</cite>.
2975      *         The behaviour on a
2976      *         {@code null} argument depends on the <a
2977      *         href="../util/Formatter.html#syntax">conversion</a>.
2978      *
2979      * @throws  java.util.IllegalFormatException
2980      *          If a format string contains an illegal syntax, a format
2981      *          specifier that is incompatible with the given arguments,
2982      *          insufficient arguments given the format string, or other
2983      *          illegal conditions.  For specification of all possible
2984      *          formatting errors, see the <a
2985      *          href="../util/Formatter.html#detail">Details</a> section of the
2986      *          formatter class specification.
2987      *
2988      * @return  A formatted string
2989      *
2990      * @see  java.util.Formatter
2991      * @since  1.5
2992      */

2993     public static String format(String format, Object... args) {
2994         return new Formatter().format(format, args).toString();
2995     }
2996 
2997     /**
2998      * Returns a formatted string using the specified locale, format string,
2999      * and arguments.
3000      *













3001      * @param  l
3002      *         The {@linkplain java.util.Locale locale} to apply during
3003      *         formatting.  If {@code l} is {@code null} then no localization
3004      *         is applied.
3005      *
3006      * @param  format
3007      *         A <a href="../util/Formatter.html#syntax">format string</a>
3008      *
3009      * @param  args
3010      *         Arguments referenced by the format specifiers in the format
3011      *         string.  If there are more arguments than format specifiers, the
3012      *         extra arguments are ignored.  The number of arguments is
3013      *         variable and may be zero.  The maximum number of arguments is
3014      *         limited by the maximum dimension of a Java array as defined by
3015      *         <cite>The Java&trade; Virtual Machine Specification</cite>.
3016      *         The behaviour on a
3017      *         {@code null} argument depends on the
3018      *         <a href="../util/Formatter.html#syntax">conversion</a>.
3019      *
3020      * @throws  java.util.IllegalFormatException
3021      *          If a format string contains an illegal syntax, a format
3022      *          specifier that is incompatible with the given arguments,
3023      *          insufficient arguments given the format string, or other
3024      *          illegal conditions.  For specification of all possible
3025      *          formatting errors, see the <a
3026      *          href="../util/Formatter.html#detail">Details</a> section of the
3027      *          formatter class specification
3028      *
3029      * @return  A formatted string
3030      *
3031      * @see  java.util.Formatter
3032      * @since  1.5
3033      */

3034     public static String format(Locale l, String format, Object... args) {
3035         return new Formatter(l).format(format, args).toString();












































































































3036     }
3037 
3038     /**
3039      * Returns the string representation of the {@code Object} argument.
3040      *
3041      * @param   obj   an {@code Object}.
3042      * @return  if the argument is {@code null}, then a string equal to
3043      *          {@code "null"}; otherwise, the value of
3044      *          {@code obj.toString()} is returned.
3045      * @see     java.lang.Object#toString()
3046      */
3047     public static String valueOf(Object obj) {
3048         return (obj == null) ? "null" : obj.toString();
3049     }
3050 
3051     /**
3052      * Returns the string representation of the {@code char} array
3053      * argument. The contents of the character array are copied; subsequent
3054      * modification of the character array does not affect the returned
3055      * string.




  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.lang;
  27 
  28 import java.io.ObjectStreamField;
  29 import java.io.UnsupportedEncodingException;
  30 import java.lang.annotation.Native;
  31 import java.lang.invoke.MethodHandles;
  32 import java.lang.compiler.IntrinsicCandidate;
  33 import java.lang.constant.Constable;
  34 import java.lang.constant.ConstantDesc;
  35 import java.nio.charset.Charset;
  36 import java.util.ArrayList;
  37 import java.util.Arrays;
  38 import java.util.Comparator;
  39 import java.util.Formatter;
  40 import java.util.Locale;
  41 import java.util.Objects;
  42 import java.util.Optional;
  43 import java.util.Spliterator;
  44 import java.util.StringJoiner;
  45 import java.util.function.Function;
  46 import java.util.regex.Matcher;
  47 import java.util.regex.Pattern;
  48 import java.util.regex.PatternSyntaxException;
  49 import java.util.stream.Collectors;
  50 import java.util.stream.IntStream;
  51 import java.util.stream.Stream;
  52 import java.util.stream.StreamSupport;


2946      * Converts this string to a new character array.
2947      *
2948      * @return  a newly allocated character array whose length is the length
2949      *          of this string and whose contents are initialized to contain
2950      *          the character sequence represented by this string.
2951      */
2952     public char[] toCharArray() {
2953         return isLatin1() ? StringLatin1.toChars(value)
2954                           : StringUTF16.toChars(value);
2955     }
2956 
2957     /**
2958      * Returns a formatted string using the specified format string and
2959      * arguments.
2960      *
2961      * <p> The locale always used is the one returned by {@link
2962      * java.util.Locale#getDefault(java.util.Locale.Category)
2963      * Locale.getDefault(Locale.Category)} with
2964      * {@link java.util.Locale.Category#FORMAT FORMAT} category specified.
2965      *
2966      * @implNote
2967      * An invocation of this method may be intrinsified {@link java.lang.compiler.IntrinsicCandidate}
2968      * if the {@code format} string is a constant expression. Intrinsification replaces the method
2969      * invocation with a string concatenation operation. No checks are made during intrinsification
2970      * on the content of the {@code format} string, so an IllegalFormatException is possible at
2971      * run time.
2972      * <p>
2973      * The treatment of subsequent arguments is the same as without intrinsification: arguments that
2974      * are constant expressions are evaluated at compile time, and arguments that are not constant
2975      * expressions are evaluated at run time. (An argument that is a nested invocation of an
2976      * intrinsifiable method may be evaluated at compile time and/or run time, per the compiler's
2977      * usual discretion on when and how to intrinsify.)
2978      *
2979      * @param  format
2980      *         A <a href="../util/Formatter.html#syntax">format string</a>
2981      *
2982      * @param  args
2983      *         Arguments referenced by the format specifiers in the format
2984      *         string.  If there are more arguments than format specifiers, the
2985      *         extra arguments are ignored.  The number of arguments is
2986      *         variable and may be zero.  The maximum number of arguments is
2987      *         limited by the maximum dimension of a Java array as defined by
2988      *         <cite>The Java&trade; Virtual Machine Specification</cite>.
2989      *         The behaviour on a
2990      *         {@code null} argument depends on the <a
2991      *         href="../util/Formatter.html#syntax">conversion</a>.
2992      *
2993      * @throws  java.util.IllegalFormatException
2994      *          If a format string contains an illegal syntax, a format
2995      *          specifier that is incompatible with the given arguments,
2996      *          insufficient arguments given the format string, or other
2997      *          illegal conditions.  For specification of all possible
2998      *          formatting errors, see the <a
2999      *          href="../util/Formatter.html#detail">Details</a> section of the
3000      *          formatter class specification.
3001      *
3002      * @return  A formatted string
3003      *
3004      * @see  java.util.Formatter
3005      * @since  1.5
3006      */
3007     @IntrinsicCandidate
3008     public static String format(String format, Object... args) {
3009         return new Formatter().format(format, args).toString();
3010     }
3011 
3012     /**
3013      * Returns a formatted string using the specified locale, format string,
3014      * and arguments.
3015      *
3016      * @implNote
3017      * An invocation of this method may be intrinsified {@link java.lang.compiler.IntrinsicCandidate}
3018      * if the {@code format} string is a constant expression. Intrinsification replaces the method
3019      * invocation with a string concatenation operation. No checks are made during intrinsification
3020      * on the content of the {@code format} string, so an IllegalFormatException is possible at
3021      * run time.
3022      * <p>
3023      * The treatment of subsequent arguments is the same as without intrinsification: arguments that
3024      * are constant expressions are evaluated at compile time, and arguments that are not constant
3025      * expressions are evaluated at run time. (An argument that is a nested invocation of an
3026      * intrinsifiable method may be evaluated at compile time and/or run time, per the compiler's
3027      * usual discretion on when and how to intrinsify.)
3028      *
3029      * @param  l
3030      *         The {@linkplain java.util.Locale locale} to apply during
3031      *         formatting.  If {@code l} is {@code null} then no localization
3032      *         is applied.
3033      *
3034      * @param  format
3035      *         A <a href="../util/Formatter.html#syntax">format string</a>
3036      *
3037      * @param  args
3038      *         Arguments referenced by the format specifiers in the format
3039      *         string.  If there are more arguments than format specifiers, the
3040      *         extra arguments are ignored.  The number of arguments is
3041      *         variable and may be zero.  The maximum number of arguments is
3042      *         limited by the maximum dimension of a Java array as defined by
3043      *         <cite>The Java&trade; Virtual Machine Specification</cite>.
3044      *         The behaviour on a
3045      *         {@code null} argument depends on the
3046      *         <a href="../util/Formatter.html#syntax">conversion</a>.
3047      *
3048      * @throws  java.util.IllegalFormatException
3049      *          If a format string contains an illegal syntax, a format
3050      *          specifier that is incompatible with the given arguments,
3051      *          insufficient arguments given the format string, or other
3052      *          illegal conditions.  For specification of all possible
3053      *          formatting errors, see the <a
3054      *          href="../util/Formatter.html#detail">Details</a> section of the
3055      *          formatter class specification
3056      *
3057      * @return  A formatted string
3058      *
3059      * @see  java.util.Formatter
3060      * @since  1.5
3061      */
3062     @IntrinsicCandidate
3063     public static String format(Locale l, String format, Object... args) {
3064         return new Formatter(l).format(format, args).toString();
3065     }
3066 
3067     /**
3068      * Returns a formatted string using this string, as the specified
3069      * <a href="../util/Formatter.html#syntax">format</a>, and
3070      * arguments.
3071      *
3072      * <p> The locale always used is the one returned by {@link
3073      * java.util.Locale#getDefault(java.util.Locale.Category)
3074      * Locale.getDefault(Locale.Category)} with
3075      * {@link java.util.Locale.Category#FORMAT FORMAT} category specified.
3076      *
3077      * @implNote
3078      * An invocation of this method may be intrinsified {@link java.lang.compiler.IntrinsicCandidate}
3079      * if the {@code format} string is a constant expression. Intrinsification replaces the method
3080      * invocation with a string concatenation operation. No checks are made during intrinsification
3081      * on the content of the {@code format} string, so an IllegalFormatException is possible at
3082      * run time.
3083      * <p>
3084      * The treatment of subsequent arguments is the same as without intrinsification: arguments that
3085      * are constant expressions are evaluated at compile time, and arguments that are not constant
3086      * expressions are evaluated at run time. (An argument that is a nested invocation of an
3087      * intrinsifiable method may be evaluated at compile time and/or run time, per the compiler's
3088      * usual discretion on when and how to intrinsify.)
3089      *
3090      * @param  args
3091      *         Arguments referenced by the format specifiers in the format
3092      *         string.  If there are more arguments than format specifiers, the
3093      *         extra arguments are ignored.  The number of arguments is
3094      *         variable and may be zero.  The maximum number of arguments is
3095      *         limited by the maximum dimension of a Java array as defined by
3096      *         <cite>The Java&trade; Virtual Machine Specification</cite>.
3097      *         The behaviour on a
3098      *         {@code null} argument depends on the <a
3099      *         href="../util/Formatter.html#syntax">conversion</a>.
3100      *
3101      * @throws  java.util.IllegalFormatException
3102      *          If a format string contains an illegal syntax, a format
3103      *          specifier that is incompatible with the given arguments,
3104      *          insufficient arguments given the format string, or other
3105      *          illegal conditions.  For specification of all possible
3106      *          formatting errors, see the <a
3107      *          href="../util/Formatter.html#detail">Details</a> section of the
3108      *          formatter class specification.
3109      *
3110      * @return  A formatted string
3111      *
3112      * @see  java.util.Formatter
3113      *
3114      * @since  12
3115      */
3116     @IntrinsicCandidate
3117     public String format(Object... args) {
3118         return new Formatter().format(this, args).toString();
3119     }
3120 
3121     /**
3122      * Returns a formatted string using this string, as the specified
3123      * <a href="../util/Formatter.html#syntax">format</a>, the specified locale,
3124      * and  arguments.
3125      *
3126      * @implNote
3127      * An invocation of this method may be intrinsified {@link java.lang.compiler.IntrinsicCandidate}
3128      * if the {@code format} string is a constant expression. Intrinsification replaces the method
3129      * invocation with a string concatenation operation. No checks are made during intrinsification
3130      * on the content of the {@code format} string, so an IllegalFormatException is possible at
3131      * run time.
3132      * <p>
3133      * The treatment of subsequent arguments is the same as without intrinsification: arguments that
3134      * are constant expressions are evaluated at compile time, and arguments that are not constant
3135      * expressions are evaluated at run time. (An argument that is a nested invocation of an
3136      * intrinsifiable method may be evaluated at compile time and/or run time, per the compiler's
3137      * usual discretion on when and how to intrinsify.)
3138      *
3139      * @param  l
3140      *         The {@linkplain java.util.Locale locale} to apply during
3141      *         formatting.  If {@code l} is {@code null} then no localization
3142      *         is applied.
3143      *
3144      * @param  args
3145      *         Arguments referenced by the format specifiers in the format
3146      *         string.  If there are more arguments than format specifiers, the
3147      *         extra arguments are ignored.  The number of arguments is
3148      *         variable and may be zero.  The maximum number of arguments is
3149      *         limited by the maximum dimension of a Java array as defined by
3150      *         <cite>The Java&trade; Virtual Machine Specification</cite>.
3151      *         The behaviour on a
3152      *         {@code null} argument depends on the
3153      *         <a href="../util/Formatter.html#syntax">conversion</a>.
3154      *
3155      * @throws  java.util.IllegalFormatException
3156      *          If a format string contains an illegal syntax, a format
3157      *          specifier that is incompatible with the given arguments,
3158      *          insufficient arguments given the format string, or other
3159      *          illegal conditions.  For specification of all possible
3160      *          formatting errors, see the <a
3161      *          href="../util/Formatter.html#detail">Details</a> section of the
3162      *          formatter class specification
3163      *
3164      * @return  A formatted string
3165      *
3166      * @see  java.util.Formatter
3167      *
3168      * @since  12
3169      */
3170     @IntrinsicCandidate
3171     public String format(Locale l, Object... args) {
3172         return new Formatter(l).format(this, args).toString();
3173     }
3174 
3175     /**
3176      * Returns the string representation of the {@code Object} argument.
3177      *
3178      * @param   obj   an {@code Object}.
3179      * @return  if the argument is {@code null}, then a string equal to
3180      *          {@code "null"}; otherwise, the value of
3181      *          {@code obj.toString()} is returned.
3182      * @see     java.lang.Object#toString()
3183      */
3184     public static String valueOf(Object obj) {
3185         return (obj == null) ? "null" : obj.toString();
3186     }
3187 
3188     /**
3189      * Returns the string representation of the {@code char} array
3190      * argument. The contents of the character array are copied; subsequent
3191      * modification of the character array does not affect the returned
3192      * string.


< prev index next >