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.
   
   

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:

cs1 - the first CharSequence.
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

• 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

specdiffs attached. Below is a convenient link:
http://cr.openjdk.java.net/~joehw/jdk11/8137326/specdiff/overview-summary.html