8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
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.ObjectStreamClass;
29 import java.io.ObjectStreamField;
30 import java.io.UnsupportedEncodingException;
31 import java.nio.charset.Charset;
32 import java.util.ArrayList;
33 import java.util.Arrays;
34 import java.util.Comparator;
35 import java.util.Formatter;
36 import java.util.Locale;
37 import java.util.regex.Matcher;
38 import java.util.regex.Pattern;
39 import java.util.regex.PatternSyntaxException;
40
41 /**
42 * The {@code String} class represents character strings. All
43 * string literals in Java programs, such as {@code "abc"}, are
44 * implemented as instances of this class.
45 * <p>
46 * Strings are constant; their values cannot be changed after they
47 * are created. String buffers support mutable strings.
48 * Because String objects are immutable they can be shared. For example:
49 * <p><blockquote><pre>
50 * String str = "abc";
51 * </pre></blockquote><p>
52 * is equivalent to:
53 * <p><blockquote><pre>
54 * char data[] = {'a', 'b', 'c'};
55 * String str = new String(data);
56 * </pre></blockquote><p>
57 * Here are some more examples of how strings can be used:
58 * <p><blockquote><pre>
59 * System.out.println("abc");
91 * Character Representations</a> in the {@code Character} class for
92 * more information).
93 * Index values refer to {@code char} code units, so a supplementary
94 * character uses two positions in a {@code String}.
95 * <p>The {@code String} class provides methods for dealing with
96 * Unicode code points (i.e., characters), in addition to those for
97 * dealing with Unicode code units (i.e., {@code char} values).
98 *
99 * @author Lee Boynton
100 * @author Arthur van Hoff
101 * @author Martin Buchholz
102 * @author Ulf Zibis
103 * @see java.lang.Object#toString()
104 * @see java.lang.StringBuffer
105 * @see java.lang.StringBuilder
106 * @see java.nio.charset.Charset
107 * @since JDK1.0
108 */
109
110 public final class String
111 implements java.io.Serializable, Comparable<String>, CharSequence
112 {
113 /** The value is used for character storage. */
114 private final char value[];
115
116 /** The offset is the first index of the storage that is used. */
117 private final int offset;
118
119 /** The count is the number of characters in the String. */
120 private final int count;
121
122 /** Cache the hash code for the string */
123 private int hash; // Default to 0
124
125 /** use serialVersionUID from JDK 1.0.2 for interoperability */
126 private static final long serialVersionUID = -6849794470754667710L;
127
128 /**
129 * Class String is special cased within the Serialization Stream Protocol.
130 *
131 * A String instance is written initially into an ObjectOutputStream in the
3060 * <p>
3061 * When the intern method is invoked, if the pool already contains a
3062 * string equal to this {@code String} object as determined by
3063 * the {@link #equals(Object)} method, then the string from the pool is
3064 * returned. Otherwise, this {@code String} object is added to the
3065 * pool and a reference to this {@code String} object is returned.
3066 * <p>
3067 * It follows that for any two strings {@code s} and {@code t},
3068 * {@code s.intern() == t.intern()} is {@code true}
3069 * if and only if {@code s.equals(t)} is {@code true}.
3070 * <p>
3071 * All literal strings and string-valued constant expressions are
3072 * interned. String literals are defined in section 3.10.5 of the
3073 * <cite>The Java™ Language Specification</cite>.
3074 *
3075 * @return a string that has the same contents as this string, but is
3076 * guaranteed to be from a pool of unique strings.
3077 */
3078 public native String intern();
3079
3080 }
|
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
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.regex.Matcher;
37 import java.util.regex.Pattern;
38 import java.util.regex.PatternSyntaxException;
39 import sun.misc.Hashing;
40
41 /**
42 * The {@code String} class represents character strings. All
43 * string literals in Java programs, such as {@code "abc"}, are
44 * implemented as instances of this class.
45 * <p>
46 * Strings are constant; their values cannot be changed after they
47 * are created. String buffers support mutable strings.
48 * Because String objects are immutable they can be shared. For example:
49 * <p><blockquote><pre>
50 * String str = "abc";
51 * </pre></blockquote><p>
52 * is equivalent to:
53 * <p><blockquote><pre>
54 * char data[] = {'a', 'b', 'c'};
55 * String str = new String(data);
56 * </pre></blockquote><p>
57 * Here are some more examples of how strings can be used:
58 * <p><blockquote><pre>
59 * System.out.println("abc");
91 * Character Representations</a> in the {@code Character} class for
92 * more information).
93 * Index values refer to {@code char} code units, so a supplementary
94 * character uses two positions in a {@code String}.
95 * <p>The {@code String} class provides methods for dealing with
96 * Unicode code points (i.e., characters), in addition to those for
97 * dealing with Unicode code units (i.e., {@code char} values).
98 *
99 * @author Lee Boynton
100 * @author Arthur van Hoff
101 * @author Martin Buchholz
102 * @author Ulf Zibis
103 * @see java.lang.Object#toString()
104 * @see java.lang.StringBuffer
105 * @see java.lang.StringBuilder
106 * @see java.nio.charset.Charset
107 * @since JDK1.0
108 */
109
110 public final class String
111 implements java.io.Serializable, Comparable<String>, CharSequence, Hashable32
112 {
113 /** The value is used for character storage. */
114 private final char value[];
115
116 /** The offset is the first index of the storage that is used. */
117 private final int offset;
118
119 /** The count is the number of characters in the String. */
120 private final int count;
121
122 /** Cache the hash code for the string */
123 private int hash; // Default to 0
124
125 /** use serialVersionUID from JDK 1.0.2 for interoperability */
126 private static final long serialVersionUID = -6849794470754667710L;
127
128 /**
129 * Class String is special cased within the Serialization Stream Protocol.
130 *
131 * A String instance is written initially into an ObjectOutputStream in the
3060 * <p>
3061 * When the intern method is invoked, if the pool already contains a
3062 * string equal to this {@code String} object as determined by
3063 * the {@link #equals(Object)} method, then the string from the pool is
3064 * returned. Otherwise, this {@code String} object is added to the
3065 * pool and a reference to this {@code String} object is returned.
3066 * <p>
3067 * It follows that for any two strings {@code s} and {@code t},
3068 * {@code s.intern() == t.intern()} is {@code true}
3069 * if and only if {@code s.equals(t)} is {@code true}.
3070 * <p>
3071 * All literal strings and string-valued constant expressions are
3072 * interned. String literals are defined in section 3.10.5 of the
3073 * <cite>The Java™ Language Specification</cite>.
3074 *
3075 * @return a string that has the same contents as this string, but is
3076 * guaranteed to be from a pool of unique strings.
3077 */
3078 public native String intern();
3079
3080 /**
3081 * Seed value used for each alternative hash calculated.
3082 */
3083 private static final int HASHING_SEED;
3084
3085 static {
3086 // ??? Stronger random source? (Random/SecureRandom is not available)
3087 HASHING_SEED = System.identityHashCode(String.class)
3088 ^ System.identityHashCode(System.class)
3089 ^ System.identityHashCode(Thread.currentThread())
3090 ^ (int) (System.currentTimeMillis() >>> 2) // resolution is poor
3091 ^ (int) (System.nanoTime() >>> 5); // resolution is poor
3092 }
3093
3094 /**
3095 * Cached value of the hashing algorithm result
3096 */
3097 private transient int hash32 = 0;
3098
3099 /**
3100 * {@inheritDoc}
3101 *
3102 * <p/>
3103 * The hash value will never be zero.
3104 */
3105 public int hash32() {
3106 int h = hash32;
3107 if (0 == h) {
3108 // harmless data race on hash32 here.
3109 h = Hashing.murmur3_32(HASHING_SEED, value, offset, count);
3110
3111 // ensure result is not zero to avoid recalcing
3112 h = (0 != h) ? h : 1;
3113
3114 hash32 = h;
3115 }
3116
3117 return h;
3118 }
3119 }
|