< prev index next >
src/java.base/share/classes/java/lang/String.java
Print this page
*** 100,109 ****
--- 100,113 ----
* 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 {@link 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,978 ****
--- 973,985 ----
* 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
+ * {@link 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
*** 1006,1015 ****
--- 1013,1025 ----
* 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
+ * {@link 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},
*** 1041,1050 ****
--- 1051,1063 ----
* 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
+ * {@link 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
*** 1090,1107 ****
* <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
* </ul>
*
* @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
--- 1103,1120 ----
* <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> Calling {@code Character.toLowerCase(Character.toUpperCase(char))}
! * 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
+ * {@link 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
*** 1148,1157 ****
--- 1161,1173 ----
* strings -- that is, the value:
* <blockquote><pre>
* this.length()-anotherString.length()
* </pre></blockquote>
*
+ * <p>For finer-grained String comparison, refer to
+ * {@link 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
*** 1179,1192 ****
* 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.
*
! * @see java.text.Collator#compare(String, String)
* @since 1.2
*/
public static final Comparator<String> CASE_INSENSITIVE_ORDER
= new CaseInsensitiveComparator();
private static class CaseInsensitiveComparator
--- 1195,1207 ----
* 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 {@link java.text.Collator} class provides locale-sensitive comparison.
*
! * @see java.text.Collator
* @since 1.2
*/
public static final Comparator<String> CASE_INSENSITIVE_ORDER
= new CaseInsensitiveComparator();
private static class CaseInsensitiveComparator
*** 1229,1246 ****
* {@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.
*
* @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)
* @since 1.2
*/
public int compareToIgnoreCase(String str) {
return CASE_INSENSITIVE_ORDER.compare(this, str);
}
--- 1244,1260 ----
* {@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 {@link 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
* @since 1.2
*/
public int compareToIgnoreCase(String str) {
return CASE_INSENSITIVE_ORDER.compare(this, str);
}
*** 1266,1275 ****
--- 1280,1292 ----
* 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
+ * {@link 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.
*** 1321,1340 ****
* 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))
* </pre></blockquote>
* </ul>
*
* @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.
--- 1338,1357 ----
* 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(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 {@link 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.
< prev index next >