[LANG-1171] Add compare methods in StringUtils

• Type: New Feature
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Fix Version/s: 3.5
• Component/s: lang.*
• Assignee: Loic Guibert
• Reporter: Loic Guibert
• Created: 05/Oct/15 12:52
• Updated: 19/Oct/16 07:01
• Resolved: 23/Oct/15 17:58

Description

Add null safe methods in StringUtils to compare 2 Strings :

public static int compare(final String str1, final String str2);
public static int compare(final String str1, final String str2, final boolean nullIsLess);
public static int compareIgnoreCase(final String str1, final String str2);
public static int compareIgnoreCase(final String str1, final String str2, final boolean nullIsLess);

Those methods are null safe equivalent to :

String.compareTo(String);
String.compareToIgnoreCase(String);

More details :

/**
 * <p>Compare two Strings lexicographically, as per {@link String#compareTo(String)}, returning :</p>
 * <ul>
 *  <li>{@code int = 0}, if {@code str1} is equal to {@code str2} (or both {@code null})</li>
 *  <li>{@code int < 0}, if {@code str1} is less than {@code str2}</li>
 *  <li>{@code int > 0}, if {@code str1} is greater than {@code str2}</li>
 * </ul>
 * 
 * <p>This is a {@code null} safe version of :</p>
 * <blockquote><pre>str1.compareTo(str2)</pre></blockquote>
 * 
 * <p>{@code null} value is considered less than non-{@code null} value.
 * Two {@code null} references are considered equal.</p>
 *
 * <pre>
 * StringUtils.compare(null, null)   = 0
 * StringUtils.compare(null , "a")   &lt; 0
 * StringUtils.compare("a", null)    &gt; 0
 * StringUtils.compare("abc", "abc") = 0
 * StringUtils.compare("a", "b")     &lt; 0
 * StringUtils.compare("b", "a")     &gt; 0
 * StringUtils.compare("a", "B")     &gt; 0
 * StringUtils.compare("ab", "abc")  &lt; 0
 * </pre>
 *
 * @see #compare(String, String, boolean)
 * @see String#compareTo(String)
 * @param str1  the String to compare from
 * @param str2  the String to compare to
 * @return &lt; 0, 0, &gt; 0, if {@code str1} is respectively less, equal ou greater than {@code str2}
 */
public static int compare(final String str1, final String str2);

/**
 * <p>Compare two Strings lexicographically, as per {@link String#compareTo(String)}, returning :</p>
 * <ul>
 *  <li>{@code int = 0}, if {@code str1} is equal to {@code str2} (or both {@code null})</li>
 *  <li>{@code int < 0}, if {@code str1} is less than {@code str2}</li>
 *  <li>{@code int > 0}, if {@code str1} is greater than {@code str2}</li>
 * </ul>
 * 
 * <p>This is a {@code null} safe version of :</p>
 * <blockquote><pre>str1.compareTo(str2)</pre></blockquote>
 * 
 * <p>{@code null} inputs are handled according to the {@code nullIsLess} parameter.
 * Two {@code null} references are considered equal.</p>
 *
 * <pre>
 * StringUtils.compare(null, null, *)     = 0
 * StringUtils.compare(null , "a", true)  &lt; 0
 * StringUtils.compare(null , "a", false) &gt; 0
 * StringUtils.compare("a", null, true)   &gt; 0
 * StringUtils.compare("a", null, false)  &lt; 0
 * StringUtils.compare("abc", "abc", *)   = 0
 * StringUtils.compare("a", "b", *)       &lt; 0
 * StringUtils.compare("b", "a", *)       &gt; 0
 * StringUtils.compare("a", "B", *)       &gt; 0
 * StringUtils.compare("ab", "abc", *)    &lt; 0
 * </pre>
 *
 * @see String#compareTo(String)
 * @param str1  the String to compare from
 * @param str2  the String to compare to
 * @param nullIsLess  whether consider {@code null} value less than non-{@code null} value
 * @return &lt; 0, 0, &gt; 0, if {@code str1} is respectively less, equal ou greater than {@code str2}
 */
public static int compare(final String str1, final String str2, final boolean nullIsLess);

/**
 * <p>Compare two Strings lexicographically, ignoring case differences,
 * as per {@link String#compareToIgnoreCase(String)}, returning :</p>
 * <ul>
 *  <li>{@code int = 0}, if {@code str1} is equal to {@code str2} (or both {@code null})</li>
 *  <li>{@code int < 0}, if {@code str1} is less than {@code str2}</li>
 *  <li>{@code int > 0}, if {@code str1} is greater than {@code str2}</li>
 * </ul>
 * 
 * <p>This is a {@code null} safe version of :</p>
 * <blockquote><pre>str1.compareToIgnoreCase(str2)</pre></blockquote>
 * 
 * <p>{@code null} value is considered less than non-{@code null} value.
 * Two {@code null} references are considered equal.
 * Comparison is case insensitive.</p>
 *
 * <pre>
 * StringUtils.compareIgnoreCase(null, null)   = 0
 * StringUtils.compareIgnoreCase(null , "a")   &lt; 0
 * StringUtils.compareIgnoreCase("a", null)    &gt; 0
 * StringUtils.compareIgnoreCase("abc", "abc") = 0
 * StringUtils.compareIgnoreCase("abc", "ABC") = 0
 * StringUtils.compareIgnoreCase("a", "b")     &lt; 0
 * StringUtils.compareIgnoreCase("b", "a")     &gt; 0
 * StringUtils.compareIgnoreCase("a", "B")     &lt; 0
 * StringUtils.compareIgnoreCase("A", "b")     &lt; 0
 * StringUtils.compareIgnoreCase("ab", "ABC")  &lt; 0
 * </pre>
 *
 * @see #compareIgnoreCase(String, String, boolean)
 * @see String#compareToIgnoreCase(String)
 * @param str1  the String to compare from
 * @param str2  the String to compare to
 * @return &lt; 0, 0, &gt; 0, if {@code str1} is respectively less, equal ou greater than {@code str2},
 *          ignoring case differences.
 */
public static int compareIgnoreCase(final String str1, final String str2);

/**
 * <p>Compare two Strings lexicographically, ignoring case differences,
 * as per {@link String#compareToIgnoreCase(String)}, returning :</p>
 * <ul>
 *  <li>{@code int = 0}, if {@code str1} is equal to {@code str2} (or both {@code null})</li>
 *  <li>{@code int < 0}, if {@code str1} is less than {@code str2}</li>
 *  <li>{@code int > 0}, if {@code str1} is greater than {@code str2}</li>
 * </ul>
 * 
 * <p>This is a {@code null} safe version of :</p>
 * <blockquote><pre>str1.compareToIgnoreCase(str2)</pre></blockquote>
 * 
 * <p>{@code null} inputs are handled according to the {@code nullIsLess} parameter.
 * Two {@code null} references are considered equal.
 * Comparison is case insensitive.</p>
 *
 * <pre>
 * StringUtils.compareIgnoreCase(null, null, *)     = 0
 * StringUtils.compareIgnoreCase(null , "a", true)  &lt; 0
 * StringUtils.compareIgnoreCase(null , "a", false) &gt; 0
 * StringUtils.compareIgnoreCase("a", null, true)   &gt; 0
 * StringUtils.compareIgnoreCase("a", null, false)  &lt; 0
 * StringUtils.compareIgnoreCase("abc", "abc", *)   = 0
 * StringUtils.compareIgnoreCase("abc", "ABC", *)   = 0
 * StringUtils.compareIgnoreCase("a", "b", *)       &lt; 0
 * StringUtils.compareIgnoreCase("b", "a", *)       &gt; 0
 * StringUtils.compareIgnoreCase("a", "B", *)       &lt; 0
 * StringUtils.compareIgnoreCase("A", "b", *)       &lt; 0
 * StringUtils.compareIgnoreCase("ab", "abc", *)    &lt; 0
 * </pre>
 *
 * @see String#compareToIgnoreCase(String)
 * @param str1  the String to compare from
 * @param str2  the String to compare to
 * @param nullIsLess  whether consider {@code null} value less than non-{@code null} value
 * @return &lt; 0, 0, &gt; 0, if {@code str1} is respectively less, equal ou greater than {@code str2},
 *          ignoring case differences.
 */
public static int compareIgnoreCase(final String str1, final String str2, final boolean nullIsLess);

See PR#110 : https://github.com/apache/commons-lang/pull/110