Consolidate the StringUtils.equals and equalsIgnoreCase methods. (#409)

* Consolidate the StringUtils.equals and equalsIgnoreCase methods.

Implement the same edge case logic for null. Use the same parameter
names. Use the same Javadoc wording. Change the equals method to use a
step-wise charAt comparison.

* LANG-1436: Added Jira to changes.xml.

src/changes/changes.xml

@@ -53,6 +53,7 @@ The <action> type attribute can be add,update,fix,remove.
     <action issue="LANG-1411" type="add" dev="britter" due-to="Alexander Tsvetkov">Add isEmpty method to ObjectUtils</action>
     <action issue="LANG-1422" type="add" dev="ggregory">Add null-safe StringUtils.valueOf(char[]) to delegate to String.valueOf(char[])</action>
     <action issue="LANG-1427" type="add" dev="ggregory">Add API org.apache.commons.lang3.SystemUtils.isJavaVersionAtMost(JavaVersion)</action>
+    <action issue="LANG-1436" type="update" dev="aherbert">Consolidate the StringUtils equals and equalsIgnoreCase Javadoc and implementation</action>
   </release>
 
   <release version="3.8.1" date="2018-09-19" description="This release is a bugfix for Restoring Bundle-SymbolicName in the MANIFEST.mf file.">

src/main/java/org/apache/commons/lang3/StringUtils.java

@@ -981,7 +981,7 @@ public class StringUtils {
      * equal sequences of characters.</p>
      *
      * <p>{@code null}s are handled without exceptions. Two {@code null}
-     * references are considered to be equal. The comparison is case sensitive.</p>
+     * references are considered to be equal. The comparison is <strong>case sensitive</strong>.</p>
      *
      * <pre>
      * StringUtils.equals(null, null)   = true
@@ -991,11 +991,12 @@ public class StringUtils {
      * StringUtils.equals("abc", "ABC") = false
      * </pre>
      *
-     * @see Object#equals(Object)
      * @param cs1  the first CharSequence, may be {@code null}
      * @param cs2  the second CharSequence, may be {@code null}
      * @return {@code true} if the CharSequences are equal (case-sensitive), or both {@code null}
      * @since 3.0 Changed signature from equals(String, String) to equals(CharSequence, CharSequence)
+     * @see Object#equals(Object)
+     * @see #equalsIgnoreCase(CharSequence, CharSequence)
      */
     public static boolean equals(final CharSequence cs1, final CharSequence cs2) {
         if (cs1 == cs2) {
@@ -1010,7 +1011,14 @@ public class StringUtils {
         if (cs1 instanceof String && cs2 instanceof String) {
             return cs1.equals(cs2);
         }
-        return CharSequenceUtils.regionMatches(cs1, false, 0, cs2, 0, cs1.length());
+        // Step-wise comparison
+        final int length = cs1.length();
+        for (int i = 0; i < length; i++) {
+            if (cs1.charAt(i) != cs2.charAt(i)) {
+                return false;
+            }
+        }
+        return true;
     }
 
     /**
@@ -1018,7 +1026,7 @@ public class StringUtils {
      * equal sequences of characters, ignoring case.</p>
      *
      * <p>{@code null}s are handled without exceptions. Two {@code null}
-     * references are considered equal. Comparison is case insensitive.</p>
+     * references are considered equal. The comparison is <strong>case insensitive</strong>.</p>
      *
      * <pre>
      * StringUtils.equalsIgnoreCase(null, null)   = true
@@ -1028,22 +1036,23 @@ public class StringUtils {
      * StringUtils.equalsIgnoreCase("abc", "ABC") = true
      * </pre>
      *
-     * @param str1  the first CharSequence, may be null
-     * @param str2  the second CharSequence, may be null
-     * @return {@code true} if the CharSequence are equal, case insensitive, or
-     *  both {@code null}
+     * @param cs1  the first CharSequence, may be {@code null}
+     * @param cs2  the second CharSequence, may be {@code null}
+     * @return {@code true} if the CharSequences are equal (case-insensitive), or both {@code null}
      * @since 3.0 Changed signature from equalsIgnoreCase(String, String) to equalsIgnoreCase(CharSequence, CharSequence)
+     * @see #equals(CharSequence, CharSequence)
      */
-    public static boolean equalsIgnoreCase(final CharSequence str1, final CharSequence str2) {
-        if (str1 == null || str2 == null) {
-            return str1 == str2;
-        } else if (str1 == str2) {
+    public static boolean equalsIgnoreCase(final CharSequence cs1, final CharSequence cs2) {
+        if (cs1 == cs2) {
             return true;
-        } else if (str1.length() != str2.length()) {
-            return false;
-        } else {
-            return CharSequenceUtils.regionMatches(str1, true, 0, str2, 0, str1.length());
         }
+        if (cs1 == null || cs2 == null) {
+            return false;
+        }
+        if (cs1.length() != cs2.length()) {
+            return false;
+        }
+        return CharSequenceUtils.regionMatches(cs1, true, 0, cs2, 0, cs1.length());
     }
 
     // Compare