< prev index next >

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

Print this page

        

@@ -100,10 +100,14 @@
  * character uses two positions in a {@code String}.
  * <p>The {@code String} class provides methods for dealing with
  * Unicode code points (i.e., characters), in addition to those for
  * dealing with Unicode code units (i.e., {@code char} values).
  *
+ * <p>Unless otherwise noted, methods for comparing Strings do not take locale
+ * into account.  The {@code java.text.Collator} class provides methods for
+ * finer-grain, locale-sensitive String comparison.
+ * 
  * @author  Lee Boynton
  * @author  Arthur van Hoff
  * @author  Martin Buchholz
  * @author  Ulf Zibis
  * @see     java.lang.Object#toString()

@@ -969,18 +973,22 @@
      * Compares this string to the specified object.  The result is {@code
      * true} if and only if the argument is not {@code null} and is a {@code
      * String} object that represents the same sequence of characters as this
      * object.
      *
+     * <p>For finer-grained String comparison, refer to
+     * {@code java.text.Collator}.
+     * 
      * @param  anObject
      *         The object to compare this {@code String} against
      *
      * @return  {@code true} if the given object represents a {@code String}
      *          equivalent to this string, {@code false} otherwise
      *
      * @see  #compareTo(String)
      * @see  #equalsIgnoreCase(String)
+     * @see  java.text.Collator
      */
     @HotSpotIntrinsicCandidate
     public boolean equals(Object anObject) {
         if (this == anObject) {
             return true;

@@ -1006,16 +1014,20 @@
      * Compares this string to the specified {@code StringBuffer}.  The result
      * is {@code true} if and only if this {@code String} represents the same
      * sequence of characters as the specified {@code StringBuffer}. This method
      * synchronizes on the {@code StringBuffer}.
      *
+     * <p>For finer-grained String comparison, refer to
+     * {@code java.text.Collator}.
+     *
      * @param  sb
      *         The {@code StringBuffer} to compare this {@code String} against
      *
      * @return  {@code true} if this {@code String} represents the same
      *          sequence of characters as the specified {@code StringBuffer},
      *          {@code false} otherwise
+     * @see  java.text.Collator
      *
      * @since  1.4
      */
     public boolean contentEquals(StringBuffer sb) {
         return contentEquals((CharSequence)sb);

@@ -1041,16 +1053,20 @@
      * result is {@code true} if and only if this {@code String} represents the
      * same sequence of char values as the specified sequence. Note that if the
      * {@code CharSequence} is a {@code StringBuffer} then the method
      * synchronizes on it.
      *
+     * <p>For finer-grained String comparison, refer to
+     * {@code java.text.Collator}.
+     *
      * @param  cs
      *         The sequence to compare this {@code String} against
      *
      * @return  {@code true} if this {@code String} represents the same
      *          sequence of char values as the specified sequence, {@code
      *          false} otherwise
+     * @see  java.text.Collator
      *
      * @since  1.5
      */
     public boolean contentEquals(CharSequence cs) {
         // Argument is a StringBuffer, StringBuilder

@@ -1090,25 +1106,26 @@
      * <p> Two characters {@code c1} and {@code c2} are considered the same
      * ignoring case if at least one of the following is true:
      * <ul>
      *   <li> The two characters are the same (as compared by the
      *        {@code ==} operator)
-     *   <li> Applying the method {@link
-     *        java.lang.Character#toUpperCase(char)} to each character
-     *        produces the same result
-     *   <li> Applying the method {@link
-     *        java.lang.Character#toLowerCase(char)} to each character
-     *        produces the same result
+     *   <li> Calling {@code Character.toLowerCase(Character.toUpperCase(character))}
+     *        on each character produces the same result
      * </ul>
      *
+     * <p>Note that this method does <em>not</em> take locale into account, and
+     * will result in unsatisfactory results for certain locales.  The
+     * {@code java.text.Collator} class provides locale-sensitive comparison.
+     * 
      * @param  anotherString
      *         The {@code String} to compare this {@code String} against
      *
      * @return  {@code true} if the argument is not {@code null} and it
      *          represents an equivalent {@code String} ignoring case; {@code
      *          false} otherwise
      *
+     * @see  java.text.Collator
      * @see  #equals(Object)
      */
     public boolean equalsIgnoreCase(String anotherString) {
         return (this == anotherString) ? true
                 : (anotherString != null)

@@ -1148,16 +1165,20 @@
      * strings -- that is, the value:
      * <blockquote><pre>
      * this.length()-anotherString.length()
      * </pre></blockquote>
      *
+     * <p>For finer-grained String comparison, refer to
+     * {@code java.text.Collator}.
+     * 
      * @param   anotherString   the {@code String} to be compared.
      * @return  the value {@code 0} if the argument string is equal to
      *          this string; a value less than {@code 0} if this string
      *          is lexicographically less than the string argument; and a
      *          value greater than {@code 0} if this string is
      *          lexicographically greater than the string argument.
+     * @see     java.text.Collator
      */
     @HotSpotIntrinsicCandidate
     public int compareTo(String anotherString) {
         char[] v1 = value;
         char[] v2 = anotherString.value;

@@ -1179,14 +1200,13 @@
      * A Comparator that orders {@code String} objects as by
      * {@code compareToIgnoreCase}. This comparator is serializable.
      * <p>
      * Note that this Comparator does <em>not</em> take locale into account,
      * and will result in an unsatisfactory ordering for certain locales.
-     * The java.text package provides <em>Collators</em> to allow
-     * locale-sensitive ordering.
+     * The {@code java.text.Collator} class provides locale-sensitive comparison.
      *
-     * @see     java.text.Collator#compare(String, String)
+     * @see     java.text.Collator
      * @since   1.2
      */
     public static final Comparator<String> CASE_INSENSITIVE_ORDER
                                          = new CaseInsensitiveComparator();
     private static class CaseInsensitiveComparator

@@ -1229,18 +1249,17 @@
      * {@code Character.toLowerCase(Character.toUpperCase(character))} on
      * each character.
      * <p>
      * Note that this method does <em>not</em> take locale into account,
      * and will result in an unsatisfactory ordering for certain locales.
-     * The java.text package provides <em>collators</em> to allow
-     * locale-sensitive ordering.
+     * The {@code java.text.Collator} class provides locale-sensitive comparison.
      *
      * @param   str   the {@code String} to be compared.
      * @return  a negative integer, zero, or a positive integer as the
      *          specified String is greater than, equal to, or less
      *          than this String, ignoring case considerations.
-     * @see     java.text.Collator#compare(String, String)
+     * @see     java.text.Collator
      * @since   1.2
      */
     public int compareToIgnoreCase(String str) {
         return CASE_INSENSITIVE_ORDER.compare(this, str);
     }

@@ -1266,18 +1285,22 @@
      * such that:
      * {@code this.charAt(toffset + }<i>k</i>{@code ) != other.charAt(ooffset + }
      * <i>k</i>{@code )}
      * </ul>
      *
+     * <p>Note that this method does <em>not</em> take locale into account.  The
+     * {@code java.text.Collator} class provides locale-sensitive comparison.
+     * 
      * @param   toffset   the starting offset of the subregion in this string.
      * @param   other     the string argument.
      * @param   ooffset   the starting offset of the subregion in the string
      *                    argument.
      * @param   len       the number of characters to compare.
      * @return  {@code true} if the specified subregion of this string
      *          exactly matches the specified subregion of the string argument;
      *          {@code false} otherwise.
+     * @see     java.text.Collator
      */
     public boolean regionMatches(int toffset, String other, int ooffset,
             int len) {
         char[] ta = value;
         int to = toffset;

@@ -1321,20 +1344,20 @@
      * this.charAt(toffset+k) != other.charAt(ooffset+k)
      * </pre></blockquote>
      * <li>{@code ignoreCase} is {@code true} and there is some nonnegative
      * integer <i>k</i> less than {@code len} such that:
      * <blockquote><pre>
-     * Character.toLowerCase(this.charAt(toffset+k)) !=
-     Character.toLowerCase(other.charAt(ooffset+k))
-     * </pre></blockquote>
-     * and:
-     * <blockquote><pre>
-     * Character.toUpperCase(this.charAt(toffset+k)) !=
-     *         Character.toUpperCase(other.charAt(ooffset+k))
+     * Character.toLowerCase(Character.toUpperCase(this.charAt(toffset+k))) !=
+     Character.toLowerCase(Character.toUpperCase(other.charAt(ooffset+k)))
      * </pre></blockquote>
      * </ul>
      *
+     * <p>Note that this method does <em>not</em> take locale into account,
+     * and will result in unsatisfactory results for certain locales when
+     * {@code ignoreCase} is {@code true}.  The {@code java.text.Collator} class
+     * provides locale-sensitive comparison.
+     * 
      * @param   ignoreCase   if {@code true}, ignore case when comparing
      *                       characters.
      * @param   toffset      the starting offset of the subregion in this
      *                       string.
      * @param   other        the string argument.

@@ -1344,10 +1367,11 @@
      * @return  {@code true} if the specified subregion of this string
      *          matches the specified subregion of the string argument;
      *          {@code false} otherwise. Whether the matching is exact
      *          or case insensitive depends on the {@code ignoreCase}
      *          argument.
+     * @see     java.text.Collator
      */
     public boolean regionMatches(boolean ignoreCase, int toffset,
             String other, int ooffset, int len) {
         char[] ta = value;
         int to = toffset;
< prev index next >