src/java.base/share/classes/java/util/Comparator.java

rev 17471 : [mq]: 8134512-provide-Alpha-Numeric-logical-Comparator

@@ -524,11 +524,83 @@
      * @return a comparator that compares by an extracted key
      * @see #comparing(Function)
      * @throws NullPointerException if the argument is null
      * @since 1.8
      */
-    public static<T> Comparator<T> comparingDouble(ToDoubleFunction<? super T> keyExtractor) {
+    public static <T> Comparator<T> comparingDouble(ToDoubleFunction<? super T> keyExtractor) {
         Objects.requireNonNull(keyExtractor);
         return (Comparator<T> & Serializable)
             (c1, c2) -> Double.compare(keyExtractor.applyAsDouble(c1), keyExtractor.applyAsDouble(c2));
     }
+
+    /**
+     * Returns a comparator that compares {@link CharSequence} objects,
+     * paying special attention to the decimal digit characters.
+     *
+     * <p>The returned comparator follows the procedure to compare two char
+     * sequences:  first, the common prefix of the sequences is skipped;
+     * then, if the sequences are different at the point lying inside or
+     * at the boundary of a subsequence, consisting of decimal digits, the
+     * corresponding numerical values are compared;  otherwise, the char
+     * sequences are compared literally.
+     *
+     * <p>In the case the numeric values of two compared char sequences
+     * are equal, but their string representations have different number
+     * of leading zeroes, the comparator treats the number with more 
+     * leading zeros as greater.
+     * E.g. {@code "abc 1" < "abc 01" < "abc 001"}.
+     *
+     * @implSpec The returned comparator uses
+     * {@link java.lang.Character#compare(char,char)} to compare pairs of
+     * characters of its arguments.  The comparator uses
+     * {@link java.lang.Character#isDigit(char)} to test if the character
+     * represets a decimal digit.  The comparator uses
+     * {@link java.lang.Character#digit(char, int)} with the second 
+     * argument set to {@code 10} to determine the decimal numeric value
+     * of the character.
+     *
+     * @param  <T> the type of elements to be compared
+     * @return a comparator that is to compare character sequences
+     *
+     * @since 10
+     */
+    @SuppressWarnings("unchecked")
+    public static <T extends CharSequence> Comparator<T> comparingNumerically() {
+        return (Comparator<T>)Comparators.NumericComparator.INSTANCE_LEADING_ZEROS_BEHIND_NATURAL;
+    }
+
+    /**
+     * Returns a comparator that compares {@link CharSequence} objects,
+     * paying special attention to the decimal digit characters.
+     *
+     * <p>The returned comparator follows the procedure to compare two char
+     * sequences:  first, the common prefix of the sequences is skipped;
+     * then, if the sequences are different at the point lying inside or
+     * at the boundary of a subsequence, consisting of decimal digits, the
+     * corresponding numerical values are compared;  otherwise, the char
+     * sequences are compared literally.
+     *
+     * <p>In the case the numeric values of two compared char sequences
+     * are equal, but their string representations have different number
+     * of leading zeroes, the comparator treats the number with more 
+     * leading zeros as smaller.
+     * E.g. {@code "abc 001" < "abc 01" < "abc 1"}.
+     *
+     * @implSpec The returned comparator uses
+     * {@link java.lang.Character#compare(char,char)} to compare pairs of
+     * characters of its arguments.  The comparator uses
+     * {@link java.lang.Character#isDigit(char)} to test if the character
+     * represets a decimal digit.  The comparator uses
+     * {@link java.lang.Character#digit(char, int)} with the second 
+     * argument set to {@code 10} to determine the decimal numeric value
+     * of the character.
+     *
+     * @param  <T> the type of elements to be compared
+     * @return a comparator that is to compare character sequences
+     *
+     * @since 10
+     */
+    @SuppressWarnings("unchecked")
+    public static <T extends CharSequence> Comparator<T> comparingNumericallyLeadingZerosAhead() {
+        return (Comparator<T>)Comparators.NumericComparator.INSTANCE_LEADING_ZEROS_AHEAD_NATURAL;
+    }
 }