Summary
-------
Add a static method to CharSequence to allow comparison between
two CharSequence implementations; Add support for the Comparable
interface to StringBuilder and StringBuffer.
Problem
-------
A CharSequence is semantically comparable. It is expected therefore
its implementations, specifically, StringBuffer and StringBuilder are comparable.
String is already comparable.
Solution
--------
1. Add a static method to CharSequence
It would be desirable for CharSequence to implement Comparable.
Unfortunately since String that implements CharSequence already
implements Comparable<String>, it is not feasible to change CharSequence
to implement Comparable<CharSequence>. For more detailed discussion,
please refer to the comment section of the original enhancement request.
The alternative solution therefore is to introduce a static method to CharSequence:
static int compare(CharSequence cs1, CharSequence cs2)
This compare method will allow the comparison between CharSequence
implementations such as String, StringBuilder and StringBuffer.<br><br>
2. Implement Comparable for StringBuilder and StringBuffer
The StringBuilder and StringBuffer shall implement Comparable<StringBuilder>
and Comparable<StringBuffer> respectively, the same way as String implements
Comparable<String>. The addition will extend the functionality to allow a
StringBuilder to StringBuilder, or StringBuffer to StringBuffer comparison.
Specification
-------------
* CharSequence: change in general description (the wording changes are in bold)
>`- ` This interface does not refine the general contracts of the equals and hashCode methods. The result of __comparing__ two objects that implement CharSequence is therefore, in general, undefined. Each object may be implemented by a different class, and there is no guarantee that each class will be capable of testing its instances for equality with those of the other. It is therefore inappropriate to use arbitrary CharSequence instances as elements in a set or as keys in a map
>`+ ` This interface does not refine the general contracts of the equals and hashCode methods. The result of **testing** two objects that implement CharSequence **for equality** is therefore, in general, undefined. Each object may be implemented by a different class, and there is no guarantee that each class will be capable of testing its instances for equality with those of the other. It is therefore inappropriate to use arbitrary CharSequence instances as elements in a set or as keys in a map
* CharSequence: add a static method
static int compare(CharSequence cs1, CharSequence cs2)
>Compares two `CharSequence` instances lexicographically. Returns a negative value, zero, or a positive value if the first sequence is lexicographically less than, equal to, or greater than the second, respectively.
>The lexicographical ordering of `CharSequence` is defined as follows. Consider a `CharSequence` `cs` of length `len` to be a sequence of char values, `cs[0]` to `cs[len-1]`. Suppose `k` is the lowest index at which the corresponding char values from each sequence differ. The lexicographic ordering of the sequences is determined by a numeric comparison of the char values `cs1[k]` with `cs2[k]`. If there is no such index `k`, the shorter sequence is considered lexicographically less than the other. If the sequences have the same length, the sequences are considered lexicographically equal.
>Parameters:<br>
> cs1 - the first `CharSequence`. <br>
> cs2 - the second `CharSequence`.
>Returns:
> the value 0 if the two `CharSequence` are equal; a negative integer if the first `CharSequence` is lexicographically less than the second; and a positive integer if the first `CharSequence` is lexicographically greater than the second.
>Since:
> `11 `
<br>
* StringBuilder
`public final class StringBuilder
extends AbstractStringBuilder
implements java.io.Serializable, Comparable<StringBuilder>, CharSequence`
>API Note:
> `StringBuilder` implements `Comparable` but does not override `equals`. Thus, the natural ordering of `StringBuilder` is inconsistent with equals. Care should be exercised if `StringBuilder` objects are used as keys in a `SortedMap` or elements in a `SortedSet`. See `Comparable`, `SortedMap`, or `SortedSet` for more information.
public int compareTo(StringBuilder another)
>Compares two `StringBuilder` instances lexicographically. This method follows the same rules for lexicographical comparison as defined in the `CharSequence.compare(this, another)` method.
> For finer-grained, locale-sensitive String comparison, refer to `Collator`.
>Specified by:
> `compareTo` in interface `Comparable<StringBuilder> `
>Parameters:
> another - the `StringBuilder` to be compared with.
>Returns:
> the value 0 if this `StringBuilder` contains the same character sequence as that of the argument `StringBuilder`; a negative integer if this `StringBuilder` is lexicographically less than the `StringBuilder` argument; and a positive integer if this `StringBuilder` is lexicographically greater than the `StringBuilder` argument.
>Since:
> 11
* StringBuffer: implements Comparable<StringBuffer>
`public final class StringBuffer
extends AbstractStringBuilder
implements java.io.Serializable, Comparable<StringBuffer>, CharSequence`
>API Note:
> `StringBuffer` implements `Comparable` but does not override `equals`. Thus, the natural ordering of `StringBuffer` is inconsistent with equals. Care should be exercised if `StringBuffer` objects are used as keys in a `SortedMap` or elements in a `SortedSet`. See `Comparable`, `SortedMap`, or `SortedSet` for more information.
public int compareTo(`StringBuffer` another)
>Compares two `StringBuffer` instances lexicographically. This method follows the same rules for lexicographical comparison as defined in the `CharSequence.compare(this, another)` method.
> For finer-grained, locale-sensitive String comparison, refer to `Collator`.
>Specified by:
> `compareTo` in interface `Comparable<StringBuffer> `
>Implementation Note:
> This method synchronizes on `this`, the current object, but not `StringBuffer another` with which `this StringBuffer` is compared.
>Parameters:
> another - the `StringBuffer` to be compared with.
>Returns:
> the value 0 if this `StringBuffer` contains the same character sequence as that of the argument `StringBuffer`; a negative integer if this `StringBuffer` is lexicographically less than the `StringBuffer` argument; and a positive integer if this `StringBuffer` is lexicographically greater than the `StringBuffer` argument.
>Since:
> 11
<br><br>
specdiffs attached. Below is a convenient link:<br>
http://cr.openjdk.java.net/~joehw/jdk11/8137326/specdiff/overview-summary.html
<br><br>