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

Print this page
rev 5380 : 7126277: Alternative hashing implementation


   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&trade; 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&trade; 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 }