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

Print this page
rev 5431 : 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:


  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
 132      * following format:


3059      * class {@code String}.
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 
  40 /**
  41  * The {@code String} class represents character strings. All
  42  * string literals in Java programs, such as {@code "abc"}, are
  43  * implemented as instances of this class.
  44  * <p>
  45  * Strings are constant; their values cannot be changed after they
  46  * are created. String buffers support mutable strings.
  47  * Because String objects are immutable they can be shared. For example:


  90  * Character Representations</a> in the {@code Character} class for
  91  * more information).
  92  * Index values refer to {@code char} code units, so a supplementary
  93  * character uses two positions in a {@code String}.
  94  * <p>The {@code String} class provides methods for dealing with
  95  * Unicode code points (i.e., characters), in addition to those for
  96  * dealing with Unicode code units (i.e., {@code char} values).
  97  *
  98  * @author  Lee Boynton
  99  * @author  Arthur van Hoff
 100  * @author  Martin Buchholz
 101  * @author  Ulf Zibis
 102  * @see     java.lang.Object#toString()
 103  * @see     java.lang.StringBuffer
 104  * @see     java.lang.StringBuilder
 105  * @see     java.nio.charset.Charset
 106  * @since   JDK1.0
 107  */
 108 
 109 public final class String
 110     implements java.io.Serializable, Comparable<String>, CharSequence {

 111     /** The value is used for character storage. */
 112     private final char value[];
 113 
 114     /** The offset is the first index of the storage that is used. */
 115     private final int offset;
 116 
 117     /** The count is the number of characters in the String. */
 118     private final int count;
 119 
 120     /** Cache the hash code for the string */
 121     private int hash; // Default to 0
 122 
 123     /** use serialVersionUID from JDK 1.0.2 for interoperability */
 124     private static final long serialVersionUID = -6849794470754667710L;
 125 
 126     /**
 127      * Class String is special cased within the Serialization Stream Protocol.
 128      *
 129      * A String instance is written initially into an ObjectOutputStream in the
 130      * following format:


3057      * class {@code String}.
3058      * <p>
3059      * When the intern method is invoked, if the pool already contains a
3060      * string equal to this {@code String} object as determined by
3061      * the {@link #equals(Object)} method, then the string from the pool is
3062      * returned. Otherwise, this {@code String} object is added to the
3063      * pool and a reference to this {@code String} object is returned.
3064      * <p>
3065      * It follows that for any two strings {@code s} and {@code t},
3066      * {@code s.intern() == t.intern()} is {@code true}
3067      * if and only if {@code s.equals(t)} is {@code true}.
3068      * <p>
3069      * All literal strings and string-valued constant expressions are
3070      * interned. String literals are defined in section 3.10.5 of the
3071      * <cite>The Java&trade; Language Specification</cite>.
3072      *
3073      * @return  a string that has the same contents as this string, but is
3074      *          guaranteed to be from a pool of unique strings.
3075      */
3076     public native String intern();
3077     
3078     /**
3079      * Seed value used for each alternative hash calculated.
3080      */
3081     private static final int HASHING_SEED;
3082     
3083     static {
3084         long nanos = System.nanoTime();
3085         long now = System.currentTimeMillis();
3086         int SEED_MATERIAL[] = { 
3087                 System.identityHashCode(String.class),
3088                 System.identityHashCode(System.class),
3089                 System.identityHashCode(Thread.currentThread()),
3090                 (int) (nanos >>> 32),
3091                 (int) nanos,
3092                 (int) (now >>> 32),
3093                 (int) now,
3094                 (int) (System.nanoTime() >> 2)                
3095         }; 
3096         
3097         HASHING_SEED = sun.misc.Hashing.murmur3_32(SEED_MATERIAL);
3098     }
3099     
3100     /**
3101      * Cached value of the hashing algorithm result
3102      */
3103     private transient int hash32 = 0;
3104 
3105     /**
3106      * {@inheritDoc}
3107      * 
3108      * <p/>
3109      * The hash value will never be zero.
3110      */
3111     public int hash32() {
3112         int h = hash32;
3113         if (0 == h) {
3114            // harmless data race on hash32 here.            
3115            h = sun.misc.Hashing.murmur3_32(HASHING_SEED, value, offset, count);
3116            
3117            // ensure result is not zero to avoid recalcing
3118            h = (0 != h) ? h : 1;
3119            
3120            hash32 = h;
3121         }
3122 
3123         return h;
3124     }
3125 
3126 }