< 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 >