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

Print this page




  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  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.nio.charset.Charset;
  31 import java.util.ArrayList;
  32 import java.util.Arrays;
  33 import java.util.Comparator;
  34 import java.util.Formatter;
  35 import java.util.Locale;
  36 import java.util.Objects;
  37 import java.util.Spliterator;
  38 import java.util.StringJoiner;
  39 import java.util.regex.Matcher;
  40 import java.util.regex.Pattern;
  41 import java.util.regex.PatternSyntaxException;
  42 import java.util.stream.IntStream;
  43 import java.util.stream.StreamSupport;
  44 import jdk.internal.HotSpotIntrinsicCandidate;
  45 import jdk.internal.vm.annotation.Stable;
  46 
  47 /**
  48  * The {@code String} class represents character strings. All
  49  * string literals in Java programs, such as {@code "abc"}, are
  50  * implemented as instances of this class.
  51  * <p>
  52  * Strings are constant; their values cannot be changed after they
  53  * are created. String buffers support mutable strings.
  54  * Because String objects are immutable they can be shared. For example:
  55  * <blockquote><pre>
  56  *     String str = "abc";
  57  * </pre></blockquote><p>
  58  * is equivalent to:
  59  * <blockquote><pre>


 104  * the discretion of a Java compiler, as long as the compiler ultimately conforms
 105  * to <i>The Java&trade; Language Specification</i>. For example, the {@code javac} compiler
 106  * may implement the operator with {@code StringBuffer}, {@code StringBuilder},
 107  * or {@code java.lang.invoke.StringConcatFactory} depending on the JDK version. The
 108  * implementation of string conversion is typically through the method {@code toString},
 109  * defined by {@code Object} and inherited by all classes in Java.
 110  *
 111  * @author  Lee Boynton
 112  * @author  Arthur van Hoff
 113  * @author  Martin Buchholz
 114  * @author  Ulf Zibis
 115  * @see     java.lang.Object#toString()
 116  * @see     java.lang.StringBuffer
 117  * @see     java.lang.StringBuilder
 118  * @see     java.nio.charset.Charset
 119  * @since   1.0
 120  * @jls     15.18.1 String Concatenation Operator +
 121  */
 122 
 123 public final class String
 124     implements java.io.Serializable, Comparable<String>, CharSequence {
 125 
 126     /**
 127      * The value is used for character storage.
 128      *
 129      * @implNote This field is trusted by the VM, and is a subject to
 130      * constant folding if String instance is constant. Overwriting this
 131      * field after construction will cause problems.
 132      *
 133      * Additionally, it is marked with {@link Stable} to trust the contents
 134      * of the array. No other facility in JDK provides this functionality (yet).
 135      * {@link Stable} is safe here, because value is never null.
 136      */
 137     @Stable
 138     private final byte[] value;
 139 
 140     /**
 141      * The identifier of the encoding used to encode the bytes in
 142      * {@code value}. The supported values in this implementation are
 143      *
 144      * LATIN1


2966      * <p>
2967      * When the intern method is invoked, if the pool already contains a
2968      * string equal to this {@code String} object as determined by
2969      * the {@link #equals(Object)} method, then the string from the pool is
2970      * returned. Otherwise, this {@code String} object is added to the
2971      * pool and a reference to this {@code String} object is returned.
2972      * <p>
2973      * It follows that for any two strings {@code s} and {@code t},
2974      * {@code s.intern() == t.intern()} is {@code true}
2975      * if and only if {@code s.equals(t)} is {@code true}.
2976      * <p>
2977      * All literal strings and string-valued constant expressions are
2978      * interned. String literals are defined in section 3.10.5 of the
2979      * <cite>The Java&trade; Language Specification</cite>.
2980      *
2981      * @return  a string that has the same contents as this string, but is
2982      *          guaranteed to be from a pool of unique strings.
2983      * @jls 3.10.5 String Literals
2984      */
2985     public native String intern();





2986 
2987     ////////////////////////////////////////////////////////////////
2988 
2989     /**
2990      * Copy character bytes from this string into dst starting at dstBegin.
2991      * This method doesn't perform any range checking.
2992      *
2993      * Invoker guarantees: dst is in UTF16 (inflate itself for asb), if two
2994      * coders are different, and dst is big enough (range check)
2995      *
2996      * @param dstBegin  the char index, not offset of byte[]
2997      * @param coder     the coder of dst[]
2998      */
2999     void getBytes(byte dst[], int dstBegin, byte coder) {
3000         if (coder() == coder) {
3001             System.arraycopy(value, 0, dst, dstBegin << coder, value.length);
3002         } else {    // this.coder == LATIN && coder == UTF16
3003             StringLatin1.inflate(value, 0, dst, dstBegin, value.length);
3004         }
3005     }




  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  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.invoke.Constable;
  31 import java.lang.invoke.MethodHandles;
  32 import java.nio.charset.Charset;
  33 import java.util.ArrayList;
  34 import java.util.Arrays;
  35 import java.util.Comparator;
  36 import java.util.Formatter;
  37 import java.util.Locale;
  38 import java.util.Objects;
  39 import java.util.Spliterator;
  40 import java.util.StringJoiner;

  41 import java.util.regex.Pattern;
  42 import java.util.regex.PatternSyntaxException;
  43 import java.util.stream.IntStream;
  44 import java.util.stream.StreamSupport;
  45 import jdk.internal.HotSpotIntrinsicCandidate;
  46 import jdk.internal.vm.annotation.Stable;
  47 
  48 /**
  49  * The {@code String} class represents character strings. All
  50  * string literals in Java programs, such as {@code "abc"}, are
  51  * implemented as instances of this class.
  52  * <p>
  53  * Strings are constant; their values cannot be changed after they
  54  * are created. String buffers support mutable strings.
  55  * Because String objects are immutable they can be shared. For example:
  56  * <blockquote><pre>
  57  *     String str = "abc";
  58  * </pre></blockquote><p>
  59  * is equivalent to:
  60  * <blockquote><pre>


 105  * the discretion of a Java compiler, as long as the compiler ultimately conforms
 106  * to <i>The Java&trade; Language Specification</i>. For example, the {@code javac} compiler
 107  * may implement the operator with {@code StringBuffer}, {@code StringBuilder},
 108  * or {@code java.lang.invoke.StringConcatFactory} depending on the JDK version. The
 109  * implementation of string conversion is typically through the method {@code toString},
 110  * defined by {@code Object} and inherited by all classes in Java.
 111  *
 112  * @author  Lee Boynton
 113  * @author  Arthur van Hoff
 114  * @author  Martin Buchholz
 115  * @author  Ulf Zibis
 116  * @see     java.lang.Object#toString()
 117  * @see     java.lang.StringBuffer
 118  * @see     java.lang.StringBuilder
 119  * @see     java.nio.charset.Charset
 120  * @since   1.0
 121  * @jls     15.18.1 String Concatenation Operator +
 122  */
 123 
 124 public final class String
 125     implements java.io.Serializable, Comparable<String>, CharSequence, Constable<String> {
 126 
 127     /**
 128      * The value is used for character storage.
 129      *
 130      * @implNote This field is trusted by the VM, and is a subject to
 131      * constant folding if String instance is constant. Overwriting this
 132      * field after construction will cause problems.
 133      *
 134      * Additionally, it is marked with {@link Stable} to trust the contents
 135      * of the array. No other facility in JDK provides this functionality (yet).
 136      * {@link Stable} is safe here, because value is never null.
 137      */
 138     @Stable
 139     private final byte[] value;
 140 
 141     /**
 142      * The identifier of the encoding used to encode the bytes in
 143      * {@code value}. The supported values in this implementation are
 144      *
 145      * LATIN1


2967      * <p>
2968      * When the intern method is invoked, if the pool already contains a
2969      * string equal to this {@code String} object as determined by
2970      * the {@link #equals(Object)} method, then the string from the pool is
2971      * returned. Otherwise, this {@code String} object is added to the
2972      * pool and a reference to this {@code String} object is returned.
2973      * <p>
2974      * It follows that for any two strings {@code s} and {@code t},
2975      * {@code s.intern() == t.intern()} is {@code true}
2976      * if and only if {@code s.equals(t)} is {@code true}.
2977      * <p>
2978      * All literal strings and string-valued constant expressions are
2979      * interned. String literals are defined in section 3.10.5 of the
2980      * <cite>The Java&trade; Language Specification</cite>.
2981      *
2982      * @return  a string that has the same contents as this string, but is
2983      *          guaranteed to be from a pool of unique strings.
2984      * @jls 3.10.5 String Literals
2985      */
2986     public native String intern();
2987 
2988     @Override
2989     public String resolveConstant(MethodHandles.Lookup lookup) {
2990         return this;
2991     }
2992 
2993     ////////////////////////////////////////////////////////////////
2994 
2995     /**
2996      * Copy character bytes from this string into dst starting at dstBegin.
2997      * This method doesn't perform any range checking.
2998      *
2999      * Invoker guarantees: dst is in UTF16 (inflate itself for asb), if two
3000      * coders are different, and dst is big enough (range check)
3001      *
3002      * @param dstBegin  the char index, not offset of byte[]
3003      * @param coder     the coder of dst[]
3004      */
3005     void getBytes(byte dst[], int dstBegin, byte coder) {
3006         if (coder() == coder) {
3007             System.arraycopy(value, 0, dst, dstBegin << coder, value.length);
3008         } else {    // this.coder == LATIN && coder == UTF16
3009             StringLatin1.inflate(value, 0, dst, dstBegin, value.length);
3010         }
3011     }