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™ 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™ 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™ 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™ 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 }
|