Source code
Description: source: package: org.apache.commons.lang3, class: StringUtils

    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.lang3;
    018
    019import java.io.UnsupportedEncodingException;
    020import java.nio.charset.Charset;
    021import java.text.Normalizer;
    022import java.util.ArrayList;
    023import java.util.Arrays;
    024import java.util.HashSet;
    025import java.util.Iterator;
    026import java.util.List;
    027import java.util.Locale;
    028import java.util.Objects;
    029import java.util.Set;
    030import java.util.function.Supplier;
    031import java.util.regex.Pattern;
    032
    033import org.apache.commons.lang3.function.Suppliers;
    034import org.apache.commons.lang3.function.ToBooleanBiFunction;
    035import org.apache.commons.lang3.stream.LangCollectors;
    036import org.apache.commons.lang3.stream.Streams;
    037
    038/**
    039 * Operations on {@link String} that are
    040 * {@code null} safe.
    041 *
    042 * <ul>
    043 *  <li><b>IsEmpty/IsBlank</b>
    044 *      - checks if a String contains text</li>
    045 *  <li><b>Trim/Strip</b>
    046 *      - removes leading and trailing whitespace</li>
    047 *  <li><b>Equals/Compare</b>
    048 *      - compares two strings in a null-safe manner</li>
    049 *  <li><b>startsWith</b>
    050 *      - check if a String starts with a prefix in a null-safe manner</li>
    051 *  <li><b>endsWith</b>
    052 *      - check if a String ends with a suffix in a null-safe manner</li>
    053 *  <li><b>IndexOf/LastIndexOf/Contains</b>
    054 *      - null-safe index-of checks
    055 *  <li><b>IndexOfAny/LastIndexOfAny/IndexOfAnyBut/LastIndexOfAnyBut</b>
    056 *      - index-of any of a set of Strings</li>
    057 *  <li><b>ContainsOnly/ContainsNone/ContainsAny</b>
    058 *      - checks if String contains only/none/any of these characters</li>
    059 *  <li><b>Substring/Left/Right/Mid</b>
    060 *      - null-safe substring extractions</li>
    061 *  <li><b>SubstringBefore/SubstringAfter/SubstringBetween</b>
    062 *      - substring extraction relative to other strings</li>
    063 *  <li><b>Split/Join</b>
    064 *      - splits a String into an array of substrings and vice versa</li>
    065 *  <li><b>Remove/Delete</b>
    066 *      - removes part of a String</li>
    067 *  <li><b>Replace/Overlay</b>
    068 *      - Searches a String and replaces one String with another</li>
    069 *  <li><b>Chomp/Chop</b>
    070 *      - removes the last part of a String</li>
    071 *  <li><b>AppendIfMissing</b>
    072 *      - appends a suffix to the end of the String if not present</li>
    073 *  <li><b>PrependIfMissing</b>
    074 *      - prepends a prefix to the start of the String if not present</li>
    075 *  <li><b>LeftPad/RightPad/Center/Repeat</b>
    076 *      - pads a String</li>
    077 *  <li><b>UpperCase/LowerCase/SwapCase/Capitalize/Uncapitalize</b>
    078 *      - changes the case of a String</li>
    079 *  <li><b>CountMatches</b>
    080 *      - counts the number of occurrences of one String in another</li>
    081 *  <li><b>IsAlpha/IsNumeric/IsWhitespace/IsAsciiPrintable</b>
    082 *      - checks the characters in a String</li>
    083 *  <li><b>DefaultString</b>
    084 *      - protects against a null input String</li>
    085 *  <li><b>Rotate</b>
    086 *      - rotate (circular shift) a String</li>
    087 *  <li><b>Reverse/ReverseDelimited</b>
    088 *      - reverses a String</li>
    089 *  <li><b>Abbreviate</b>
    090 *      - abbreviates a string using ellipses or another given String</li>
    091 *  <li><b>Difference</b>
    092 *      - compares Strings and reports on their differences</li>
    093 *  <li><b>LevenshteinDistance</b>
    094 *      - the number of changes needed to change one String into another</li>
    095 * </ul>
    096 *
    097 * <p>The {@link StringUtils} class defines certain words related to
    098 * String handling.</p>
    099 *
    100 * <ul>
    101 *  <li>null - {@code null}</li>
    102 *  <li>empty - a zero-length string ({@code ""})</li>
    103 *  <li>space - the space character ({@code ' '}, char 32)</li>
    104 *  <li>whitespace - the characters defined by {@link Character#isWhitespace(char)}</li>
    105 *  <li>trim - the characters &lt;= 32 as in {@link String#trim()}</li>
    106 * </ul>
    107 *
    108 * <p>{@link StringUtils} handles {@code null} input Strings quietly.
    109 * That is to say that a {@code null} input will return {@code null}.
    110 * Where a {@code boolean} or {@code int} is being returned
    111 * details vary by method.</p>
    112 *
    113 * <p>A side effect of the {@code null} handling is that a
    114 * {@link NullPointerException} should be considered a bug in
    115 * {@link StringUtils}.</p>
    116 *
    117 * <p>Methods in this class include sample code in their Javadoc comments to explain their operation.
    118 * The symbol {@code *} is used to indicate any input including {@code null}.</p>
    119 *
    120 * <p>#ThreadSafe#</p>
    121 * @see String
    122 * @since 1.0
    123 */
    124//@Immutable
    125public class StringUtils {
    126
    127    // Performance testing notes (JDK 1.4, Jul03, scolebourne)
    128    // Whitespace:
    129    // Character.isWhitespace() is faster than WHITESPACE.indexOf()
    130    // where WHITESPACE is a string of all whitespace characters
    131    //
    132    // Character access:
    133    // String.charAt(n) versus toCharArray(), then array[n]
    134    // String.charAt(n) is about 15% worse for a 10K string
    135    // They are about equal for a length 50 string
    136    // String.charAt(n) is about 4 times better for a length 3 string
    137    // String.charAt(n) is best bet overall
    138    //
    139    // Append:
    140    // String.concat about twice as fast as StringBuffer.append
    141    // (not sure who tested this)
    142
    143    /**
    144     * A String for a space character.
    145     *
    146     * @since 3.2
    147     */
    148    public static final String SPACE = " ";
    149
    150    /**
    151     * The empty String {@code ""}.
    152     * @since 2.0
    153     */
    154    public static final String EMPTY = "";
    155
    156    /**
    157     * A String for linefeed LF ("\n").
    158     *
    159     * @see <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-3.html#jls-3.10.6">JLF: Escape Sequences
    160     *      for Character and String Literals</a>
    161     * @since 3.2
    162     */
    163    public static final String LF = "\n";
    164
    165    /**
    166     * A String for carriage return CR ("\r").
    167     *
    168     * @see <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-3.html#jls-3.10.6">JLF: Escape Sequences
    169     *      for Character and String Literals</a>
    170     * @since 3.2
    171     */
    172    public static final String CR = "\r";
    173
    174    /**
    175     * Represents a failed index search.
    176     * @since 2.1
    177     */
    178    public static final int INDEX_NOT_FOUND = -1;
    179
    180    /**
    181     * The maximum size to which the padding constant(s) can expand.
    182     */
    183    private static final int PAD_LIMIT = 8192;
    184
    185    /**
    186     * Pattern used in {@link #stripAccents(String)}.
    187     */
    188    private static final Pattern STRIP_ACCENTS_PATTERN = Pattern.compile("\\p{InCombiningDiacriticalMarks}+"); //$NON-NLS-1$
    189
    190    /**
    191     * Abbreviates a String using ellipses. This will turn
    192     * "Now is the time for all good men" into "Now is the time for..."
    193     *
    194     * <p>Specifically:</p>
    195     * <ul>
    196     *   <li>If the number of characters in {@code str} is less than or equal to
    197     *       {@code maxWidth}, return {@code str}.</li>
    198     *   <li>Else abbreviate it to {@code (substring(str, 0, max-3) + "...")}.</li>
    199     *   <li>If {@code maxWidth} is less than {@code 4}, throw an
    200     *       {@link IllegalArgumentException}.</li>
    201     *   <li>In no case will it return a String of length greater than
    202     *       {@code maxWidth}.</li>
    203     * </ul>
    204     *
    205     * <pre>
    206     * StringUtils.abbreviate(null, *)      = null
    207     * StringUtils.abbreviate("", 4)        = ""
    208     * StringUtils.abbreviate("abcdefg", 6) = "abc..."
    209     * StringUtils.abbreviate("abcdefg", 7) = "abcdefg"
    210     * StringUtils.abbreviate("abcdefg", 8) = "abcdefg"
    211     * StringUtils.abbreviate("abcdefg", 4) = "a..."
    212     * StringUtils.abbreviate("abcdefg", 3) = IllegalArgumentException
    213     * </pre>
    214     *
    215     * @param str  the String to check, may be null
    216     * @param maxWidth  maximum length of result String, must be at least 4
    217     * @return abbreviated String, {@code null} if null String input
    218     * @throws IllegalArgumentException if the width is too small
    219     * @since 2.0
    220     */
    221    public static String abbreviate(final String str, final int maxWidth) {
    222        return abbreviate(str, "...", 0, maxWidth);
    223    }
    224
    225    /**
    226     * Abbreviates a String using ellipses. This will turn
    227     * "Now is the time for all good men" into "...is the time for..."
    228     *
    229     * <p>Works like {@code abbreviate(String, int)}, but allows you to specify
    230     * a "left edge" offset.  Note that this left edge is not necessarily going to
    231     * be the leftmost character in the result, or the first character following the
    232     * ellipses, but it will appear somewhere in the result.
    233     *
    234     * <p>In no case will it return a String of length greater than
    235     * {@code maxWidth}.</p>
    236     *
    237     * <pre>
    238     * StringUtils.abbreviate(null, *, *)                = null
    239     * StringUtils.abbreviate("", 0, 4)                  = ""
    240     * StringUtils.abbreviate("abcdefghijklmno", -1, 10) = "abcdefg..."
    241     * StringUtils.abbreviate("abcdefghijklmno", 0, 10)  = "abcdefg..."
    242     * StringUtils.abbreviate("abcdefghijklmno", 1, 10)  = "abcdefg..."
    243     * StringUtils.abbreviate("abcdefghijklmno", 4, 10)  = "abcdefg..."
    244     * StringUtils.abbreviate("abcdefghijklmno", 5, 10)  = "...fghi..."
    245     * StringUtils.abbreviate("abcdefghijklmno", 6, 10)  = "...ghij..."
    246     * StringUtils.abbreviate("abcdefghijklmno", 8, 10)  = "...ijklmno"
    247     * StringUtils.abbreviate("abcdefghijklmno", 10, 10) = "...ijklmno"
    248     * StringUtils.abbreviate("abcdefghijklmno", 12, 10) = "...ijklmno"
    249     * StringUtils.abbreviate("abcdefghij", 0, 3)        = IllegalArgumentException
    250     * StringUtils.abbreviate("abcdefghij", 5, 6)        = IllegalArgumentException
    251     * </pre>
    252     *
    253     * @param str  the String to check, may be null
    254     * @param offset  left edge of source String
    255     * @param maxWidth  maximum length of result String, must be at least 4
    256     * @return abbreviated String, {@code null} if null String input
    257     * @throws IllegalArgumentException if the width is too small
    258     * @since 2.0
    259     */
    260    public static String abbreviate(final String str, final int offset, final int maxWidth) {
    261        return abbreviate(str, "...", offset, maxWidth);
    262    }
    263
    264    /**
    265     * Abbreviates a String using another given String as replacement marker. This will turn
    266     * "Now is the time for all good men" into "Now is the time for..." if "..." was defined
    267     * as the replacement marker.
    268     *
    269     * <p>Specifically:</p>
    270     * <ul>
    271     *   <li>If the number of characters in {@code str} is less than or equal to
    272     *       {@code maxWidth}, return {@code str}.</li>
    273     *   <li>Else abbreviate it to {@code (substring(str, 0, max-abbrevMarker.length) + abbrevMarker)}.</li>
    274     *   <li>If {@code maxWidth} is less than {@code abbrevMarker.length + 1}, throw an
    275     *       {@link IllegalArgumentException}.</li>
    276     *   <li>In no case will it return a String of length greater than
    277     *       {@code maxWidth}.</li>
    278     * </ul>
    279     *
    280     * <pre>
    281     * StringUtils.abbreviate(null, "...", *)      = null
    282     * StringUtils.abbreviate("abcdefg", null, *)  = "abcdefg"
    283     * StringUtils.abbreviate("", "...", 4)        = ""
    284     * StringUtils.abbreviate("abcdefg", ".", 5)   = "abcd."
    285     * StringUtils.abbreviate("abcdefg", ".", 7)   = "abcdefg"
    286     * StringUtils.abbreviate("abcdefg", ".", 8)   = "abcdefg"
    287     * StringUtils.abbreviate("abcdefg", "..", 4)  = "ab.."
    288     * StringUtils.abbreviate("abcdefg", "..", 3)  = "a.."
    289     * StringUtils.abbreviate("abcdefg", "..", 2)  = IllegalArgumentException
    290     * StringUtils.abbreviate("abcdefg", "...", 3) = IllegalArgumentException
    291     * </pre>
    292     *
    293     * @param str  the String to check, may be null
    294     * @param abbrevMarker  the String used as replacement marker
    295     * @param maxWidth  maximum length of result String, must be at least {@code abbrevMarker.length + 1}
    296     * @return abbreviated String, {@code null} if null String input
    297     * @throws IllegalArgumentException if the width is too small
    298     * @since 3.6
    299     */
    300    public static String abbreviate(final String str, final String abbrevMarker, final int maxWidth) {
    301        return abbreviate(str, abbrevMarker, 0, maxWidth);
    302    }
    303    /**
    304     * Abbreviates a String using a given replacement marker. This will turn
    305     * "Now is the time for all good men" into "...is the time for..." if "..." was defined
    306     * as the replacement marker.
    307     *
    308     * <p>Works like {@code abbreviate(String, String, int)}, but allows you to specify
    309     * a "left edge" offset.  Note that this left edge is not necessarily going to
    310     * be the leftmost character in the result, or the first character following the
    311     * replacement marker, but it will appear somewhere in the result.
    312     *
    313     * <p>In no case will it return a String of length greater than {@code maxWidth}.</p>
    314     *
    315     * <pre>
    316     * StringUtils.abbreviate(null, null, *, *)                 = null
    317     * StringUtils.abbreviate("abcdefghijklmno", null, *, *)    = "abcdefghijklmno"
    318     * StringUtils.abbreviate("", "...", 0, 4)                  = ""
    319     * StringUtils.abbreviate("abcdefghijklmno", "---", -1, 10) = "abcdefg---"
    320     * StringUtils.abbreviate("abcdefghijklmno", ",", 0, 10)    = "abcdefghi,"
    321     * StringUtils.abbreviate("abcdefghijklmno", ",", 1, 10)    = "abcdefghi,"
    322     * StringUtils.abbreviate("abcdefghijklmno", ",", 2, 10)    = "abcdefghi,"
    323     * StringUtils.abbreviate("abcdefghijklmno", "::", 4, 10)   = "::efghij::"
    324     * StringUtils.abbreviate("abcdefghijklmno", "...", 6, 10)  = "...ghij..."
    325     * StringUtils.abbreviate("abcdefghijklmno", "*", 9, 10)    = "*ghijklmno"
    326     * StringUtils.abbreviate("abcdefghijklmno", "'", 10, 10)   = "'ghijklmno"
    327     * StringUtils.abbreviate("abcdefghijklmno", "!", 12, 10)   = "!ghijklmno"
    328     * StringUtils.abbreviate("abcdefghij", "abra", 0, 4)       = IllegalArgumentException
    329     * StringUtils.abbreviate("abcdefghij", "...", 5, 6)        = IllegalArgumentException
    330     * </pre>
    331     *
    332     * @param str  the String to check, may be null
    333     * @param abbrevMarker  the String used as replacement marker
    334     * @param offset  left edge of source String
    335     * @param maxWidth  maximum length of result String, must be at least 4
    336     * @return abbreviated String, {@code null} if null String input
    337     * @throws IllegalArgumentException if the width is too small
    338     * @since 3.6
    339     */
    340    public static String abbreviate(final String str, final String abbrevMarker, int offset, final int maxWidth) {
    341        if (isNotEmpty(str) && EMPTY.equals(abbrevMarker) && maxWidth > 0) {
    342            return substring(str, 0, maxWidth);
    343        }
    344        if (isAnyEmpty(str, abbrevMarker)) {
    345            return str;
    346        }
    347        final int abbrevMarkerLength = abbrevMarker.length();
    348        final int minAbbrevWidth = abbrevMarkerLength + 1;
    349        final int minAbbrevWidthOffset = abbrevMarkerLength + abbrevMarkerLength + 1;
    350
    351        if (maxWidth < minAbbrevWidth) {
    352            throw new IllegalArgumentException(String.format("Minimum abbreviation width is %d", minAbbrevWidth));
    353        }
    354        final int strLen = str.length();
    355        if (strLen <= maxWidth) {
    356            return str;
    357        }
    358        if (offset > strLen) {
    359            offset = strLen;
    360        }
    361        if (strLen - offset < maxWidth - abbrevMarkerLength) {
    362            offset = strLen - (maxWidth - abbrevMarkerLength);
    363        }
    364        if (offset <= abbrevMarkerLength + 1) {
    365            return str.substring(0, maxWidth - abbrevMarkerLength) + abbrevMarker;
    366        }
    367        if (maxWidth < minAbbrevWidthOffset) {
    368            throw new IllegalArgumentException(String.format("Minimum abbreviation width with offset is %d", minAbbrevWidthOffset));
    369        }
    370        if (offset + maxWidth - abbrevMarkerLength < strLen) {
    371            return abbrevMarker + abbreviate(str.substring(offset), abbrevMarker, maxWidth - abbrevMarkerLength);
    372        }
    373        return abbrevMarker + str.substring(strLen - (maxWidth - abbrevMarkerLength));
    374    }
    375
    376    /**
    377     * Abbreviates a String to the length passed, replacing the middle characters with the supplied
    378     * replacement String.
    379     *
    380     * <p>This abbreviation only occurs if the following criteria is met:</p>
    381     * <ul>
    382     * <li>Neither the String for abbreviation nor the replacement String are null or empty </li>
    383     * <li>The length to truncate to is less than the length of the supplied String</li>
    384     * <li>The length to truncate to is greater than 0</li>
    385     * <li>The abbreviated String will have enough room for the length supplied replacement String
    386     * and the first and last characters of the supplied String for abbreviation</li>
    387     * </ul>
    388     * <p>Otherwise, the returned String will be the same as the supplied String for abbreviation.
    389     * </p>
    390     *
    391     * <pre>
    392     * StringUtils.abbreviateMiddle(null, null, 0)    = null
    393     * StringUtils.abbreviateMiddle("abc", null, 0)   = "abc"
    394     * StringUtils.abbreviateMiddle("abc", ".", 0)    = "abc"
    395     * StringUtils.abbreviateMiddle("abc", ".", 3)    = "abc"
    396     * StringUtils.abbreviateMiddle("abcdef", ".", 4) = "ab.f"
    397     * </pre>
    398     *
    399     * @param str  the String to abbreviate, may be null
    400     * @param middle the String to replace the middle characters with, may be null
    401     * @param length the length to abbreviate {@code str} to.
    402     * @return the abbreviated String if the above criteria is met, or the original String supplied for abbreviation.
    403     * @since 2.5
    404     */
    405    public static String abbreviateMiddle(final String str, final String middle, final int length) {
    406        if (isAnyEmpty(str, middle) || length >= str.length() || length < middle.length() + 2) {
    407            return str;
    408        }
    409        final int targetSting = length - middle.length();
    410        final int startOffset = targetSting / 2 + targetSting % 2;
    411        final int endOffset = str.length() - targetSting / 2;
    412        return str.substring(0, startOffset) + middle + str.substring(endOffset);
    413    }
    414
    415    /**
    416     * Appends the suffix to the end of the string if the string does not
    417     * already end with the suffix.
    418     *
    419     * @param str The string.
    420     * @param suffix The suffix to append to the end of the string.
    421     * @param ignoreCase Indicates whether the compare should ignore case.
    422     * @param suffixes Additional suffixes that are valid terminators (optional).
    423     *
    424     * @return A new String if suffix was appended, the same string otherwise.
    425     */
    426    private static String appendIfMissing(final String str, final CharSequence suffix, final boolean ignoreCase, final CharSequence... suffixes) {
    427        if (str == null || isEmpty(suffix) || endsWith(str, suffix, ignoreCase)) {
    428            return str;
    429        }
    430        if (ArrayUtils.isNotEmpty(suffixes)) {
    431            for (final CharSequence s : suffixes) {
    432                if (endsWith(str, s, ignoreCase)) {
    433                    return str;
    434                }
    435            }
    436        }
    437        return str + suffix;
    438    }
    439
    440    /**
    441     * Appends the suffix to the end of the string if the string does not
    442     * already end with any of the suffixes.
    443     *
    444     * <pre>
    445     * StringUtils.appendIfMissing(null, null)      = null
    446     * StringUtils.appendIfMissing("abc", null)     = "abc"
    447     * StringUtils.appendIfMissing("", "xyz"        = "xyz"
    448     * StringUtils.appendIfMissing("abc", "xyz")    = "abcxyz"
    449     * StringUtils.appendIfMissing("abcxyz", "xyz") = "abcxyz"
    450     * StringUtils.appendIfMissing("abcXYZ", "xyz") = "abcXYZxyz"
    451     * </pre>
    452     * <p>With additional suffixes,</p>
    453     * <pre>
    454     * StringUtils.appendIfMissing(null, null, null)       = null
    455     * StringUtils.appendIfMissing("abc", null, null)      = "abc"
    456     * StringUtils.appendIfMissing("", "xyz", null)        = "xyz"
    457     * StringUtils.appendIfMissing("abc", "xyz", new CharSequence[]{null}) = "abcxyz"
    458     * StringUtils.appendIfMissing("abc", "xyz", "")       = "abc"
    459     * StringUtils.appendIfMissing("abc", "xyz", "mno")    = "abcxyz"
    460     * StringUtils.appendIfMissing("abcxyz", "xyz", "mno") = "abcxyz"
    461     * StringUtils.appendIfMissing("abcmno", "xyz", "mno") = "abcmno"
    462     * StringUtils.appendIfMissing("abcXYZ", "xyz", "mno") = "abcXYZxyz"
    463     * StringUtils.appendIfMissing("abcMNO", "xyz", "mno") = "abcMNOxyz"
    464     * </pre>
    465     *
    466     * @param str The string.
    467     * @param suffix The suffix to append to the end of the string.
    468     * @param suffixes Additional suffixes that are valid terminators.
    469     *
    470     * @return A new String if suffix was appended, the same string otherwise.
    471     *
    472     * @since 3.2
    473     */
    474    public static String appendIfMissing(final String str, final CharSequence suffix, final CharSequence... suffixes) {
    475        return appendIfMissing(str, suffix, false, suffixes);
    476    }
    477
    478    /**
    479     * Appends the suffix to the end of the string if the string does not
    480     * already end, case-insensitive, with any of the suffixes.
    481     *
    482     * <pre>
    483     * StringUtils.appendIfMissingIgnoreCase(null, null)      = null
    484     * StringUtils.appendIfMissingIgnoreCase("abc", null)     = "abc"
    485     * StringUtils.appendIfMissingIgnoreCase("", "xyz")       = "xyz"
    486     * StringUtils.appendIfMissingIgnoreCase("abc", "xyz")    = "abcxyz"
    487     * StringUtils.appendIfMissingIgnoreCase("abcxyz", "xyz") = "abcxyz"
    488     * StringUtils.appendIfMissingIgnoreCase("abcXYZ", "xyz") = "abcXYZ"
    489     * </pre>
    490     * <p>With additional suffixes,</p>
    491     * <pre>
    492     * StringUtils.appendIfMissingIgnoreCase(null, null, null)       = null
    493     * StringUtils.appendIfMissingIgnoreCase("abc", null, null)      = "abc"
    494     * StringUtils.appendIfMissingIgnoreCase("", "xyz", null)        = "xyz"
    495     * StringUtils.appendIfMissingIgnoreCase("abc", "xyz", new CharSequence[]{null}) = "abcxyz"
    496     * StringUtils.appendIfMissingIgnoreCase("abc", "xyz", "")       = "abc"
    497     * StringUtils.appendIfMissingIgnoreCase("abc", "xyz", "mno")    = "abcxyz"
    498     * StringUtils.appendIfMissingIgnoreCase("abcxyz", "xyz", "mno") = "abcxyz"
    499     * StringUtils.appendIfMissingIgnoreCase("abcmno", "xyz", "mno") = "abcmno"
    500     * StringUtils.appendIfMissingIgnoreCase("abcXYZ", "xyz", "mno") = "abcXYZ"
    501     * StringUtils.appendIfMissingIgnoreCase("abcMNO", "xyz", "mno") = "abcMNO"
    502     * </pre>
    503     *
    504     * @param str The string.
    505     * @param suffix The suffix to append to the end of the string.
    506     * @param suffixes Additional suffixes that are valid terminators.
    507     *
    508     * @return A new String if suffix was appended, the same string otherwise.
    509     *
    510     * @since 3.2
    511     */
    512    public static String appendIfMissingIgnoreCase(final String str, final CharSequence suffix, final CharSequence... suffixes) {
    513        return appendIfMissing(str, suffix, true, suffixes);
    514    }
    515
    516    /**
    517     * Capitalizes a String changing the first character to title case as
    518     * per {@link Character#toTitleCase(int)}. No other characters are changed.
    519     *
    520     * <p>For a word based algorithm, see {@link org.apache.commons.text.WordUtils#capitalize(String)}.
    521     * A {@code null} input String returns {@code null}.</p>
    522     *
    523     * <pre>
    524     * StringUtils.capitalize(null)    = null
    525     * StringUtils.capitalize("")      = ""
    526     * StringUtils.capitalize("cat")   = "Cat"
    527     * StringUtils.capitalize("cAt")   = "CAt"
    528     * StringUtils.capitalize("'cat'") = "'cat'"
    529     * </pre>
    530     *
    531     * @param str the String to capitalize, may be null
    532     * @return the capitalized String, {@code null} if null String input
    533     * @see org.apache.commons.text.WordUtils#capitalize(String)
    534     * @see #uncapitalize(String)
    535     * @since 2.0
    536     */
    537    public static String capitalize(final String str) {
    538        final int strLen = length(str);
    539        if (strLen == 0) {
    540            return str;
    541        }
    542
    543        final int firstCodepoint = str.codePointAt(0);
    544        final int newCodePoint = Character.toTitleCase(firstCodepoint);
    545        if (firstCodepoint == newCodePoint) {
    546            // already capitalized
    547            return str;
    548        }
    549
    550        final int[] newCodePoints = new int[strLen]; // cannot be longer than the char array
    551        int outOffset = 0;
    552        newCodePoints[outOffset++] = newCodePoint; // copy the first code point
    553        for (int inOffset = Character.charCount(firstCodepoint); inOffset < strLen; ) {
    554            final int codePoint = str.codePointAt(inOffset);
    555            newCodePoints[outOffset++] = codePoint; // copy the remaining ones
    556            inOffset += Character.charCount(codePoint);
    557         }
    558        return new String(newCodePoints, 0, outOffset);
    559    }
    560
    561    /**
    562     * Centers a String in a larger String of size {@code size}
    563     * using the space character (' ').
    564     *
    565     * <p>If the size is less than the String length, the original String is returned.
    566     * A {@code null} String returns {@code null}.
    567     * A negative size is treated as zero.</p>
    568     *
    569     * <p>Equivalent to {@code center(str, size, " ")}.</p>
    570     *
    571     * <pre>
    572     * StringUtils.center(null, *)   = null
    573     * StringUtils.center("", 4)     = "    "
    574     * StringUtils.center("ab", -1)  = "ab"
    575     * StringUtils.center("ab", 4)   = " ab "
    576     * StringUtils.center("abcd", 2) = "abcd"
    577     * StringUtils.center("a", 4)    = " a  "
    578     * </pre>
    579     *
    580     * @param str  the String to center, may be null
    581     * @param size  the int size of new String, negative treated as zero
    582     * @return centered String, {@code null} if null String input
    583     */
    584    public static String center(final String str, final int size) {
    585        return center(str, size, ' ');
    586    }
    587
    588    /**
    589     * Centers a String in a larger String of size {@code size}.
    590     * Uses a supplied character as the value to pad the String with.
    591     *
    592     * <p>If the size is less than the String length, the String is returned.
    593     * A {@code null} String returns {@code null}.
    594     * A negative size is treated as zero.</p>
    595     *
    596     * <pre>
    597     * StringUtils.center(null, *, *)     = null
    598     * StringUtils.center("", 4, ' ')     = "    "
    599     * StringUtils.center("ab", -1, ' ')  = "ab"
    600     * StringUtils.center("ab", 4, ' ')   = " ab "
    601     * StringUtils.center("abcd", 2, ' ') = "abcd"
    602     * StringUtils.center("a", 4, ' ')    = " a  "
    603     * StringUtils.center("a", 4, 'y')    = "yayy"
    604     * </pre>
    605     *
    606     * @param str  the String to center, may be null
    607     * @param size  the int size of new String, negative treated as zero
    608     * @param padChar  the character to pad the new String with
    609     * @return centered String, {@code null} if null String input
    610     * @since 2.0
    611     */
    612    public static String center(String str, final int size, final char padChar) {
    613        if (str == null || size <= 0) {
    614            return str;
    615        }
    616        final int strLen = str.length();
    617        final int pads = size - strLen;
    618        if (pads <= 0) {
    619            return str;
    620        }
    621        str = leftPad(str, strLen + pads / 2, padChar);
    622        return rightPad(str, size, padChar);
    623    }
    624
    625    /**
    626     * Centers a String in a larger String of size {@code size}.
    627     * Uses a supplied String as the value to pad the String with.
    628     *
    629     * <p>If the size is less than the String length, the String is returned.
    630     * A {@code null} String returns {@code null}.
    631     * A negative size is treated as zero.</p>
    632     *
    633     * <pre>
    634     * StringUtils.center(null, *, *)     = null
    635     * StringUtils.center("", 4, " ")     = "    "
    636     * StringUtils.center("ab", -1, " ")  = "ab"
    637     * StringUtils.center("ab", 4, " ")   = " ab "
    638     * StringUtils.center("abcd", 2, " ") = "abcd"
    639     * StringUtils.center("a", 4, " ")    = " a  "
    640     * StringUtils.center("a", 4, "yz")   = "yayz"
    641     * StringUtils.center("abc", 7, null) = "  abc  "
    642     * StringUtils.center("abc", 7, "")   = "  abc  "
    643     * </pre>
    644     *
    645     * @param str  the String to center, may be null
    646     * @param size  the int size of new String, negative treated as zero
    647     * @param padStr  the String to pad the new String with, must not be null or empty
    648     * @return centered String, {@code null} if null String input
    649     * @throws IllegalArgumentException if padStr is {@code null} or empty
    650     */
    651    public static String center(String str, final int size, String padStr) {
    652        if (str == null || size <= 0) {
    653            return str;
    654        }
    655        if (isEmpty(padStr)) {
    656            padStr = SPACE;
    657        }
    658        final int strLen = str.length();
    659        final int pads = size - strLen;
    660        if (pads <= 0) {
    661            return str;
    662        }
    663        str = leftPad(str, strLen + pads / 2, padStr);
    664        return rightPad(str, size, padStr);
    665    }
    666
    667    /**
    668     * Removes one newline from end of a String if it's there,
    669     * otherwise leave it alone.  A newline is &quot;{@code \n}&quot;,
    670     * &quot;{@code \r}&quot;, or &quot;{@code \r\n}&quot;.
    671     *
    672     * <p>NOTE: This method changed in 2.0.
    673     * It now more closely matches Perl chomp.</p>
    674     *
    675     * <pre>
    676     * StringUtils.chomp(null)          = null
    677     * StringUtils.chomp("")            = ""
    678     * StringUtils.chomp("abc \r")      = "abc "
    679     * StringUtils.chomp("abc\n")       = "abc"
    680     * StringUtils.chomp("abc\r\n")     = "abc"
    681     * StringUtils.chomp("abc\r\n\r\n") = "abc\r\n"
    682     * StringUtils.chomp("abc\n\r")     = "abc\n"
    683     * StringUtils.chomp("abc\n\rabc")  = "abc\n\rabc"
    684     * StringUtils.chomp("\r")          = ""
    685     * StringUtils.chomp("\n")          = ""
    686     * StringUtils.chomp("\r\n")        = ""
    687     * </pre>
    688     *
    689     * @param str  the String to chomp a newline from, may be null
    690     * @return String without newline, {@code null} if null String input
    691     */
    692    public static String chomp(final String str) {
    693        if (isEmpty(str)) {
    694            return str;
    695        }
    696
    697        if (str.length() == 1) {
    698            final char ch = str.charAt(0);
    699            if (ch == CharUtils.CR || ch == CharUtils.LF) {
    700                return EMPTY;
    701            }
    702            return str;
    703        }
    704
    705        int lastIdx = str.length() - 1;
    706        final char last = str.charAt(lastIdx);
    707
    708        if (last == CharUtils.LF) {
    709            if (str.charAt(lastIdx - 1) == CharUtils.CR) {
    710                lastIdx--;
    711            }
    712        } else if (last != CharUtils.CR) {
    713            lastIdx++;
    714        }
    715        return str.substring(0, lastIdx);
    716    }
    717
    718    /**
    719     * Removes {@code separator} from the end of
    720     * {@code str} if it's there, otherwise leave it alone.
    721     *
    722     * <p>NOTE: This method changed in version 2.0.
    723     * It now more closely matches Perl chomp.
    724     * For the previous behavior, use {@link #substringBeforeLast(String, String)}.
    725     * This method uses {@link String#endsWith(String)}.</p>
    726     *
    727     * <pre>
    728     * StringUtils.chomp(null, *)         = null
    729     * StringUtils.chomp("", *)           = ""
    730     * StringUtils.chomp("foobar", "bar") = "foo"
    731     * StringUtils.chomp("foobar", "baz") = "foobar"
    732     * StringUtils.chomp("foo", "foo")    = ""
    733     * StringUtils.chomp("foo ", "foo")   = "foo "
    734     * StringUtils.chomp(" foo", "foo")   = " "
    735     * StringUtils.chomp("foo", "foooo")  = "foo"
    736     * StringUtils.chomp("foo", "")       = "foo"
    737     * StringUtils.chomp("foo", null)     = "foo"
    738     * </pre>
    739     *
    740     * @param str  the String to chomp from, may be null
    741     * @param separator  separator String, may be null
    742     * @return String without trailing separator, {@code null} if null String input
    743     * @deprecated This feature will be removed in Lang 4, use {@link StringUtils#removeEnd(String, String)} instead
    744     */
    745    @Deprecated
    746    public static String chomp(final String str, final String separator) {
    747        return removeEnd(str, separator);
    748    }
    749
    750    /**
    751     * Remove the last character from a String.
    752     *
    753     * <p>If the String ends in {@code \r\n}, then remove both
    754     * of them.</p>
    755     *
    756     * <pre>
    757     * StringUtils.chop(null)          = null
    758     * StringUtils.chop("")            = ""
    759     * StringUtils.chop("abc \r")      = "abc "
    760     * StringUtils.chop("abc\n")       = "abc"
    761     * StringUtils.chop("abc\r\n")     = "abc"
    762     * StringUtils.chop("abc")         = "ab"
    763     * StringUtils.chop("abc\nabc")    = "abc\nab"
    764     * StringUtils.chop("a")           = ""
    765     * StringUtils.chop("\r")          = ""
    766     * StringUtils.chop("\n")          = ""
    767     * StringUtils.chop("\r\n")        = ""
    768     * </pre>
    769     *
    770     * @param str  the String to chop last character from, may be null
    771     * @return String without last character, {@code null} if null String input
    772     */
    773    public static String chop(final String str) {
    774        if (str == null) {
    775            return null;
    776        }
    777        final int strLen = str.length();
    778        if (strLen < 2) {
    779            return EMPTY;
    780        }
    781        final int lastIdx = strLen - 1;
    782        final String ret = str.substring(0, lastIdx);
    783        final char last = str.charAt(lastIdx);
    784        if (last == CharUtils.LF && ret.charAt(lastIdx - 1) == CharUtils.CR) {
    785            return ret.substring(0, lastIdx - 1);
    786        }
    787        return ret;
    788    }
    789
    790    /**
    791     * Compare two Strings lexicographically, as per {@link String#compareTo(String)}, returning :
    792     * <ul>
    793     *  <li>{@code int = 0}, if {@code str1} is equal to {@code str2} (or both {@code null})</li>
    794     *  <li>{@code int < 0}, if {@code str1} is less than {@code str2}</li>
    795     *  <li>{@code int > 0}, if {@code str1} is greater than {@code str2}</li>
    796     * </ul>
    797     *
    798     * <p>This is a {@code null} safe version of :</p>
    799     * <blockquote><pre>str1.compareTo(str2)</pre></blockquote>
    800     *
    801     * <p>{@code null} value is considered less than non-{@code null} value.
    802     * Two {@code null} references are considered equal.</p>
    803     *
    804     * <pre>{@code
    805     * StringUtils.compare(null, null)   = 0
    806     * StringUtils.compare(null , "a")   < 0
    807     * StringUtils.compare("a", null)   > 0
    808     * StringUtils.compare("abc", "abc") = 0
    809     * StringUtils.compare("a", "b")     < 0
    810     * StringUtils.compare("b", "a")     > 0
    811     * StringUtils.compare("a", "B")     > 0
    812     * StringUtils.compare("ab", "abc")  < 0
    813     * }</pre>
    814     *
    815     * @see #compare(String, String, boolean)
    816     * @see String#compareTo(String)
    817     * @param str1  the String to compare from
    818     * @param str2  the String to compare to
    819     * @return &lt; 0, 0, &gt; 0, if {@code str1} is respectively less, equal or greater than {@code str2}
    820     * @since 3.5
    821     */
    822    public static int compare(final String str1, final String str2) {
    823        return compare(str1, str2, true);
    824    }
    825
    826    /**
    827     * Compare two Strings lexicographically, as per {@link String#compareTo(String)}, returning :
    828     * <ul>
    829     *  <li>{@code int = 0}, if {@code str1} is equal to {@code str2} (or both {@code null})</li>
    830     *  <li>{@code int < 0}, if {@code str1} is less than {@code str2}</li>
    831     *  <li>{@code int > 0}, if {@code str1} is greater than {@code str2}</li>
    832     * </ul>
    833     *
    834     * <p>This is a {@code null} safe version of :</p>
    835     * <blockquote><pre>str1.compareTo(str2)</pre></blockquote>
    836     *
    837     * <p>{@code null} inputs are handled according to the {@code nullIsLess} parameter.
    838     * Two {@code null} references are considered equal.</p>
    839     *
    840     * <pre>{@code
    841     * StringUtils.compare(null, null, *)     = 0
    842     * StringUtils.compare(null , "a", true)  < 0
    843     * StringUtils.compare(null , "a", false) > 0
    844     * StringUtils.compare("a", null, true)   > 0
    845     * StringUtils.compare("a", null, false)  < 0
    846     * StringUtils.compare("abc", "abc", *)   = 0
    847     * StringUtils.compare("a", "b", *)       < 0
    848     * StringUtils.compare("b", "a", *)       > 0
    849     * StringUtils.compare("a", "B", *)       > 0
    850     * StringUtils.compare("ab", "abc", *)    < 0
    851     * }</pre>
    852     *
    853     * @see String#compareTo(String)
    854     * @param str1  the String to compare from
    855     * @param str2  the String to compare to
    856     * @param nullIsLess  whether consider {@code null} value less than non-{@code null} value
    857     * @return &lt; 0, 0, &gt; 0, if {@code str1} is respectively less, equal ou greater than {@code str2}
    858     * @since 3.5
    859     */
    860    public static int compare(final String str1, final String str2, final boolean nullIsLess) {
    861        if (str1 == str2) { // NOSONARLINT this intentionally uses == to allow for both null
    862            return 0;
    863        }
    864        if (str1 == null) {
    865            return nullIsLess ? -1 : 1;
    866        }
    867        if (str2 == null) {
    868            return nullIsLess ? 1 : - 1;
    869        }
    870        return str1.compareTo(str2);
    871    }
    872
    873    /**
    874     * Compare two Strings lexicographically, ignoring case differences,
    875     * as per {@link String#compareToIgnoreCase(String)}, returning :
    876     * <ul>
    877     *  <li>{@code int = 0}, if {@code str1} is equal to {@code str2} (or both {@code null})</li>
    878     *  <li>{@code int < 0}, if {@code str1} is less than {@code str2}</li>
    879     *  <li>{@code int > 0}, if {@code str1} is greater than {@code str2}</li>
    880     * </ul>
    881     *
    882     * <p>This is a {@code null} safe version of :</p>
    883     * <blockquote><pre>str1.compareToIgnoreCase(str2)</pre></blockquote>
    884     *
    885     * <p>{@code null} value is considered less than non-{@code null} value.
    886     * Two {@code null} references are considered equal.
    887     * Comparison is case insensitive.</p>
    888     *
    889     * <pre>{@code
    890     * StringUtils.compareIgnoreCase(null, null)   = 0
    891     * StringUtils.compareIgnoreCase(null , "a")   < 0
    892     * StringUtils.compareIgnoreCase("a", null)    > 0
    893     * StringUtils.compareIgnoreCase("abc", "abc") = 0
    894     * StringUtils.compareIgnoreCase("abc", "ABC") = 0
    895     * StringUtils.compareIgnoreCase("a", "b")     < 0
    896     * StringUtils.compareIgnoreCase("b", "a")     > 0
    897     * StringUtils.compareIgnoreCase("a", "B")     < 0
    898     * StringUtils.compareIgnoreCase("A", "b")     < 0
    899     * StringUtils.compareIgnoreCase("ab", "ABC")  < 0
    900     * }</pre>
    901     *
    902     * @see #compareIgnoreCase(String, String, boolean)
    903     * @see String#compareToIgnoreCase(String)
    904     * @param str1  the String to compare from
    905     * @param str2  the String to compare to
    906     * @return &lt; 0, 0, &gt; 0, if {@code str1} is respectively less, equal ou greater than {@code str2},
    907     *          ignoring case differences.
    908     * @since 3.5
    909     */
    910    public static int compareIgnoreCase(final String str1, final String str2) {
    911        return compareIgnoreCase(str1, str2, true);
    912    }
    913
    914    /**
    915     * Compare two Strings lexicographically, ignoring case differences,
    916     * as per {@link String#compareToIgnoreCase(String)}, returning :
    917     * <ul>
    918     *  <li>{@code int = 0}, if {@code str1} is equal to {@code str2} (or both {@code null})</li>
    919     *  <li>{@code int < 0}, if {@code str1} is less than {@code str2}</li>
    920     *  <li>{@code int > 0}, if {@code str1} is greater than {@code str2}</li>
    921     * </ul>
    922     *
    923     * <p>This is a {@code null} safe version of :</p>
    924     * <blockquote><pre>str1.compareToIgnoreCase(str2)</pre></blockquote>
    925     *
    926     * <p>{@code null} inputs are handled according to the {@code nullIsLess} parameter.
    927     * Two {@code null} references are considered equal.
    928     * Comparison is case insensitive.</p>
    929     *
    930     * <pre>{@code
    931     * StringUtils.compareIgnoreCase(null, null, *)     = 0
    932     * StringUtils.compareIgnoreCase(null , "a", true)  < 0
    933     * StringUtils.compareIgnoreCase(null , "a", false) > 0
    934     * StringUtils.compareIgnoreCase("a", null, true)   > 0
    935     * StringUtils.compareIgnoreCase("a", null, false)  < 0
    936     * StringUtils.compareIgnoreCase("abc", "abc", *)   = 0
    937     * StringUtils.compareIgnoreCase("abc", "ABC", *)   = 0
    938     * StringUtils.compareIgnoreCase("a", "b", *)       < 0
    939     * StringUtils.compareIgnoreCase("b", "a", *)       > 0
    940     * StringUtils.compareIgnoreCase("a", "B", *)       < 0
    941     * StringUtils.compareIgnoreCase("A", "b", *)       < 0
    942     * StringUtils.compareIgnoreCase("ab", "abc", *)    < 0
    943     * }</pre>
    944     *
    945     * @see String#compareToIgnoreCase(String)
    946     * @param str1  the String to compare from
    947     * @param str2  the String to compare to
    948     * @param nullIsLess  whether consider {@code null} value less than non-{@code null} value
    949     * @return &lt; 0, 0, &gt; 0, if {@code str1} is respectively less, equal ou greater than {@code str2},
    950     *          ignoring case differences.
    951     * @since 3.5
    952     */
    953    public static int compareIgnoreCase(final String str1, final String str2, final boolean nullIsLess) {
    954        if (str1 == str2) { // NOSONARLINT this intentionally uses == to allow for both null
    955            return 0;
    956        }
    957        if (str1 == null) {
    958            return nullIsLess ? -1 : 1;
    959        }
    960        if (str2 == null) {
    961            return nullIsLess ? 1 : - 1;
    962        }
    963        return str1.compareToIgnoreCase(str2);
    964    }
    965
    966    /**
    967     * Checks if CharSequence contains a search CharSequence, handling {@code null}.
    968     * This method uses {@link String#indexOf(String)} if possible.
    969     *
    970     * <p>A {@code null} CharSequence will return {@code false}.</p>
    971     *
    972     * <pre>
    973     * StringUtils.contains(null, *)     = false
    974     * StringUtils.contains(*, null)     = false
    975     * StringUtils.contains("", "")      = true
    976     * StringUtils.contains("abc", "")   = true
    977     * StringUtils.contains("abc", "a")  = true
    978     * StringUtils.contains("abc", "z")  = false
    979     * </pre>
    980     *
    981     * @param seq  the CharSequence to check, may be null
    982     * @param searchSeq  the CharSequence to find, may be null
    983     * @return true if the CharSequence contains the search CharSequence,
    984     *  false if not or {@code null} string input
    985     * @since 2.0
    986     * @since 3.0 Changed signature from contains(String, String) to contains(CharSequence, CharSequence)
    987     */
    988    public static boolean contains(final CharSequence seq, final CharSequence searchSeq) {
    989        if (seq == null || searchSeq == null) {
    990            return false;
    991        }
    992        return CharSequenceUtils.indexOf(seq, searchSeq, 0) >= 0;
    993    }
    994
    995    /**
    996     * Checks if CharSequence contains a search character, handling {@code null}.
    997     * This method uses {@link String#indexOf(int)} if possible.
    998     *
    999     * <p>A {@code null} or empty ("") CharSequence will return {@code false}.</p>
    1000     *
    1001     * <pre>
    1002     * StringUtils.contains(null, *)    = false
    1003     * StringUtils.contains("", *)      = false
    1004     * StringUtils.contains("abc", 'a') = true
    1005     * StringUtils.contains("abc", 'z') = false
    1006     * </pre>
    1007     *
    1008     * @param seq  the CharSequence to check, may be null
    1009     * @param searchChar  the character to find
    1010     * @return true if the CharSequence contains the search character,
    1011     *  false if not or {@code null} string input
    1012     * @since 2.0
    1013     * @since 3.0 Changed signature from contains(String, int) to contains(CharSequence, int)
    1014     */
    1015    public static boolean contains(final CharSequence seq, final int searchChar) {
    1016        if (isEmpty(seq)) {
    1017            return false;
    1018        }
    1019        return CharSequenceUtils.indexOf(seq, searchChar, 0) >= 0;
    1020    }
    1021
    1022    /**
    1023     * Checks if the CharSequence contains any character in the given
    1024     * set of characters.
    1025     *
    1026     * <p>A {@code null} CharSequence will return {@code false}.
    1027     * A {@code null} or zero length search array will return {@code false}.</p>
    1028     *
    1029     * <pre>
    1030     * StringUtils.containsAny(null, *)                  = false
    1031     * StringUtils.containsAny("", *)                    = false
    1032     * StringUtils.containsAny(*, null)                  = false
    1033     * StringUtils.containsAny(*, [])                    = false
    1034     * StringUtils.containsAny("zzabyycdxx", ['z', 'a']) = true
    1035     * StringUtils.containsAny("zzabyycdxx", ['b', 'y']) = true
    1036     * StringUtils.containsAny("zzabyycdxx", ['z', 'y']) = true
    1037     * StringUtils.containsAny("aba", ['z'])             = false
    1038     * </pre>
    1039     *
    1040     * @param cs  the CharSequence to check, may be null
    1041     * @param searchChars  the chars to search for, may be null
    1042     * @return the {@code true} if any of the chars are found,
    1043     * {@code false} if no match or null input
    1044     * @since 2.4
    1045     * @since 3.0 Changed signature from containsAny(String, char[]) to containsAny(CharSequence, char...)
    1046     */
    1047    public static boolean containsAny(final CharSequence cs, final char... searchChars) {
    1048        if (isEmpty(cs) || ArrayUtils.isEmpty(searchChars)) {
    1049            return false;
    1050        }
    1051        final int csLength = cs.length();
    1052        final int searchLength = searchChars.length;
    1053        final int csLast = csLength - 1;
    1054        final int searchLast = searchLength - 1;
    1055        for (int i = 0; i < csLength; i++) {
    1056            final char ch = cs.charAt(i);
    1057            for (int j = 0; j < searchLength; j++) {
    1058                if (searchChars[j] == ch) {
    1059                    if (!Character.isHighSurrogate(ch)) {
    1060                        // ch is in the Basic Multilingual Plane
    1061                        return true;
    1062                    }
    1063                    if (j == searchLast) {
    1064                        // missing low surrogate, fine, like String.indexOf(String)
    1065                        return true;
    1066                    }
    1067                    if (i < csLast && searchChars[j + 1] == cs.charAt(i + 1)) {
    1068                        return true;
    1069                    }
    1070                }
    1071            }
    1072        }
    1073        return false;
    1074    }
    1075
    1076    /**
    1077     * Checks if the CharSequence contains any character in the given set of characters.
    1078     *
    1079     * <p>
    1080     * A {@code null} CharSequence will return {@code false}. A {@code null} search CharSequence will return
    1081     * {@code false}.
    1082     * </p>
    1083     *
    1084     * <pre>
    1085     * StringUtils.containsAny(null, *)               = false
    1086     * StringUtils.containsAny("", *)                 = false
    1087     * StringUtils.containsAny(*, null)               = false
    1088     * StringUtils.containsAny(*, "")                 = false
    1089     * StringUtils.containsAny("zzabyycdxx", "za")    = true
    1090     * StringUtils.containsAny("zzabyycdxx", "by")    = true
    1091     * StringUtils.containsAny("zzabyycdxx", "zy")    = true
    1092     * StringUtils.containsAny("zzabyycdxx", "\tx")   = true
    1093     * StringUtils.containsAny("zzabyycdxx", "$.#yF") = true
    1094     * StringUtils.containsAny("aba", "z")            = false
    1095     * </pre>
    1096     *
    1097     * @param cs
    1098     *            the CharSequence to check, may be null
    1099     * @param searchChars
    1100     *            the chars to search for, may be null
    1101     * @return the {@code true} if any of the chars are found, {@code false} if no match or null input
    1102     * @since 2.4
    1103     * @since 3.0 Changed signature from containsAny(String, String) to containsAny(CharSequence, CharSequence)
    1104     */
    1105    public static boolean containsAny(final CharSequence cs, final CharSequence searchChars) {
    1106        if (searchChars == null) {
    1107            return false;
    1108        }
    1109        return containsAny(cs, CharSequenceUtils.toCharArray(searchChars));
    1110    }
    1111
    1112    /**
    1113     * Checks if the CharSequence contains any of the CharSequences in the given array.
    1114     *
    1115     * <p>
    1116     * A {@code null} {@code cs} CharSequence will return {@code false}. A {@code null} or zero length search array will
    1117     * return {@code false}.
    1118     * </p>
    1119     *
    1120     * <pre>
    1121     * StringUtils.containsAny(null, *)            = false
    1122     * StringUtils.containsAny("", *)              = false
    1123     * StringUtils.containsAny(*, null)            = false
    1124     * StringUtils.containsAny(*, [])              = false
    1125     * StringUtils.containsAny("abcd", "ab", null) = true
    1126     * StringUtils.containsAny("abcd", "ab", "cd") = true
    1127     * StringUtils.containsAny("abc", "d", "abc")  = true
    1128     * </pre>
    1129     *
    1130     * @param cs The CharSequence to check, may be null
    1131     * @param searchCharSequences The array of CharSequences to search for, may be null. Individual CharSequences may be
    1132     *        null as well.
    1133     * @return {@code true} if any of the search CharSequences are found, {@code false} otherwise
    1134     * @since 3.4
    1135     */
    1136    public static boolean containsAny(final CharSequence cs, final CharSequence... searchCharSequences) {
    1137        return containsAny(StringUtils::contains, cs, searchCharSequences);
    1138    }
    1139
    1140    /**
    1141     * Checks if the CharSequence contains any of the CharSequences in the given array.
    1142     *
    1143     * <p>
    1144     * A {@code null} {@code cs} CharSequence will return {@code false}. A {@code null} or zero length search array will
    1145     * return {@code false}.
    1146     * </p>
    1147     *
    1148     * @param cs The CharSequence to check, may be null
    1149     * @param searchCharSequences The array of CharSequences to search for, may be null. Individual CharSequences may be
    1150     *        null as well.
    1151     * @return {@code true} if any of the search CharSequences are found, {@code false} otherwise
    1152     * @since 3.12.0
    1153     */
    1154    private static boolean containsAny(final ToBooleanBiFunction<CharSequence, CharSequence> test,
    1155        final CharSequence cs, final CharSequence... searchCharSequences) {
    1156        if (isEmpty(cs) || ArrayUtils.isEmpty(searchCharSequences)) {
    1157            return false;
    1158        }
    1159        for (final CharSequence searchCharSequence : searchCharSequences) {
    1160            if (test.applyAsBoolean(cs, searchCharSequence)) {
    1161                return true;
    1162            }
    1163        }
    1164        return false;
    1165    }
    1166
    1167    /**
    1168     * Checks if the CharSequence contains any of the CharSequences in the given array, ignoring case.
    1169     *
    1170     * <p>
    1171     * A {@code null} {@code cs} CharSequence will return {@code false}. A {@code null} or zero length search array will
    1172     * return {@code false}.
    1173     * </p>
    1174     *
    1175     * <pre>
    1176     * StringUtils.containsAny(null, *)            = false
    1177     * StringUtils.containsAny("", *)              = false
    1178     * StringUtils.containsAny(*, null)            = false
    1179     * StringUtils.containsAny(*, [])              = false
    1180     * StringUtils.containsAny("abcd", "ab", null) = true
    1181     * StringUtils.containsAny("abcd", "ab", "cd") = true
    1182     * StringUtils.containsAny("abc", "d", "abc")  = true
    1183     * StringUtils.containsAny("abc", "D", "ABC")  = true
    1184     * StringUtils.containsAny("ABC", "d", "abc")  = true
    1185     * </pre>
    1186     *
    1187     * @param cs The CharSequence to check, may be null
    1188     * @param searchCharSequences The array of CharSequences to search for, may be null. Individual CharSequences may be
    1189     *        null as well.
    1190     * @return {@code true} if any of the search CharSequences are found, {@code false} otherwise
    1191     * @since 3.12.0
    1192     */
    1193    public static boolean containsAnyIgnoreCase(final CharSequence cs, final CharSequence... searchCharSequences) {
    1194        return containsAny(StringUtils::containsIgnoreCase, cs, searchCharSequences);
    1195    }
    1196
    1197    /**
    1198     * Checks if CharSequence contains a search CharSequence irrespective of case,
    1199     * handling {@code null}. Case-insensitivity is defined as by
    1200     * {@link String#equalsIgnoreCase(String)}.
    1201     *
    1202     * <p>A {@code null} CharSequence will return {@code false}.
    1203     *
    1204     * <pre>
    1205     * StringUtils.containsIgnoreCase(null, *)    = false
    1206     * StringUtils.containsIgnoreCase(*, null)    = false
    1207     * StringUtils.containsIgnoreCase("", "")     = true
    1208     * StringUtils.containsIgnoreCase("abc", "")  = true
    1209     * StringUtils.containsIgnoreCase("abc", "a") = true
    1210     * StringUtils.containsIgnoreCase("abc", "z") = false
    1211     * StringUtils.containsIgnoreCase("abc", "A") = true
    1212     * StringUtils.containsIgnoreCase("abc", "Z") = false
    1213     * </pre>
    1214     *
    1215     * @param str  the CharSequence to check, may be null
    1216     * @param searchStr  the CharSequence to find, may be null
    1217     * @return true if the CharSequence contains the search CharSequence irrespective of
    1218     * case or false if not or {@code null} string input
    1219     * @since 3.0 Changed signature from containsIgnoreCase(String, String) to containsIgnoreCase(CharSequence, CharSequence)
    1220     */
    1221    public static boolean containsIgnoreCase(final CharSequence str, final CharSequence searchStr) {
    1222        if (str == null || searchStr == null) {
    1223            return false;
    1224        }
    1225        final int len = searchStr.length();
    1226        final int max = str.length() - len;
    1227        for (int i = 0; i <= max; i++) {
    1228            if (CharSequenceUtils.regionMatches(str, true, i, searchStr, 0, len)) {
    1229                return true;
    1230            }
    1231        }
    1232        return false;
    1233    }
    1234
    1235    /**
    1236     * Checks that the CharSequence does not contain certain characters.
    1237     *
    1238     * <p>A {@code null} CharSequence will return {@code true}.
    1239     * A {@code null} invalid character array will return {@code true}.
    1240     * An empty CharSequence (length()=0) always returns true.</p>
    1241     *
    1242     * <pre>
    1243     * StringUtils.containsNone(null, *)       = true
    1244     * StringUtils.containsNone(*, null)       = true
    1245     * StringUtils.containsNone("", *)         = true
    1246     * StringUtils.containsNone("ab", '')      = true
    1247     * StringUtils.containsNone("abab", 'xyz') = true
    1248     * StringUtils.containsNone("ab1", 'xyz')  = true
    1249     * StringUtils.containsNone("abz", 'xyz')  = false
    1250     * </pre>
    1251     *
    1252     * @param cs  the CharSequence to check, may be null
    1253     * @param searchChars  an array of invalid chars, may be null
    1254     * @return true if it contains none of the invalid chars, or is null
    1255     * @since 2.0
    1256     * @since 3.0 Changed signature from containsNone(String, char[]) to containsNone(CharSequence, char...)
    1257     */
    1258    public static boolean containsNone(final CharSequence cs, final char... searchChars) {
    1259        if (cs == null || searchChars == null) {
    1260            return true;
    1261        }
    1262        final int csLen = cs.length();
    1263        final int csLast = csLen - 1;
    1264        final int searchLen = searchChars.length;
    1265        final int searchLast = searchLen - 1;
    1266        for (int i = 0; i < csLen; i++) {
    1267            final char ch = cs.charAt(i);
    1268            for (int j = 0; j < searchLen; j++) {
    1269                if (searchChars[j] == ch) {
    1270                    if (!Character.isHighSurrogate(ch)) {
    1271                        // ch is in the Basic Multilingual Plane
    1272                        return false;
    1273                    }
    1274                    if (j == searchLast) {
    1275                        // missing low surrogate, fine, like String.indexOf(String)
    1276                        return false;
    1277                    }
    1278                    if (i < csLast && searchChars[j + 1] == cs.charAt(i + 1)) {
    1279                        return false;
    1280                    }
    1281                }
    1282            }
    1283        }
    1284        return true;
    1285    }
    1286
    1287    /**
    1288     * Checks that the CharSequence does not contain certain characters.
    1289     *
    1290     * <p>A {@code null} CharSequence will return {@code true}.
    1291     * A {@code null} invalid character array will return {@code true}.
    1292     * An empty String ("") always returns true.</p>
    1293     *
    1294     * <pre>
    1295     * StringUtils.containsNone(null, *)       = true
    1296     * StringUtils.containsNone(*, null)       = true
    1297     * StringUtils.containsNone("", *)         = true
    1298     * StringUtils.containsNone("ab", "")      = true
    1299     * StringUtils.containsNone("abab", "xyz") = true
    1300     * StringUtils.containsNone("ab1", "xyz")  = true
    1301     * StringUtils.containsNone("abz", "xyz")  = false
    1302     * </pre>
    1303     *
    1304     * @param cs  the CharSequence to check, may be null
    1305     * @param invalidChars  a String of invalid chars, may be null
    1306     * @return true if it contains none of the invalid chars, or is null
    1307     * @since 2.0
    1308     * @since 3.0 Changed signature from containsNone(String, String) to containsNone(CharSequence, String)
    1309     */
    1310    public static boolean containsNone(final CharSequence cs, final String invalidChars) {
    1311        if (invalidChars == null) {
    1312            return true;
    1313        }
    1314        return containsNone(cs, invalidChars.toCharArray());
    1315    }
    1316
    1317    /**
    1318     * Checks if the CharSequence contains only certain characters.
    1319     *
    1320     * <p>A {@code null} CharSequence will return {@code false}.
    1321     * A {@code null} valid character array will return {@code false}.
    1322     * An empty CharSequence (length()=0) always returns {@code true}.</p>
    1323     *
    1324     * <pre>
    1325     * StringUtils.containsOnly(null, *)       = false
    1326     * StringUtils.containsOnly(*, null)       = false
    1327     * StringUtils.containsOnly("", *)         = true
    1328     * StringUtils.containsOnly("ab", '')      = false
    1329     * StringUtils.containsOnly("abab", 'abc') = true
    1330     * StringUtils.containsOnly("ab1", 'abc')  = false
    1331     * StringUtils.containsOnly("abz", 'abc')  = false
    1332     * </pre>
    1333     *
    1334     * @param cs  the String to check, may be null
    1335     * @param valid  an array of valid chars, may be null
    1336     * @return true if it only contains valid chars and is non-null
    1337     * @since 3.0 Changed signature from containsOnly(String, char[]) to containsOnly(CharSequence, char...)
    1338     */
    1339    public static boolean containsOnly(final CharSequence cs, final char... valid) {
    1340        // All these pre-checks are to maintain API with an older version
    1341        if (valid == null || cs == null) {
    1342            return false;
    1343        }
    1344        if (cs.length() == 0) {
    1345            return true;
    1346        }
    1347        if (valid.length == 0) {
    1348            return false;
    1349        }
    1350        return indexOfAnyBut(cs, valid) == INDEX_NOT_FOUND;
    1351    }
    1352
    1353    /**
    1354     * Checks if the CharSequence contains only certain characters.
    1355     *
    1356     * <p>A {@code null} CharSequence will return {@code false}.
    1357     * A {@code null} valid character String will return {@code false}.
    1358     * An empty String (length()=0) always returns {@code true}.</p>
    1359     *
    1360     * <pre>
    1361     * StringUtils.containsOnly(null, *)       = false
    1362     * StringUtils.containsOnly(*, null)       = false
    1363     * StringUtils.containsOnly("", *)         = true
    1364     * StringUtils.containsOnly("ab", "")      = false
    1365     * StringUtils.containsOnly("abab", "abc") = true
    1366     * StringUtils.containsOnly("ab1", "abc")  = false
    1367     * StringUtils.containsOnly("abz", "abc")  = false
    1368     * </pre>
    1369     *
    1370     * @param cs  the CharSequence to check, may be null
    1371     * @param validChars  a String of valid chars, may be null
    1372     * @return true if it only contains valid chars and is non-null
    1373     * @since 2.0
    1374     * @since 3.0 Changed signature from containsOnly(String, String) to containsOnly(CharSequence, String)
    1375     */
    1376    public static boolean containsOnly(final CharSequence cs, final String validChars) {
    1377        if (cs == null || validChars == null) {
    1378            return false;
    1379        }
    1380        return containsOnly(cs, validChars.toCharArray());
    1381    }
    1382
    1383    /**
    1384     * Check whether the given CharSequence contains any whitespace characters.
    1385     *
    1386     * <p>Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
    1387     *
    1388     * @param seq the CharSequence to check (may be {@code null})
    1389     * @return {@code true} if the CharSequence is not empty and
    1390     * contains at least 1 (breaking) whitespace character
    1391     * @since 3.0
    1392     */
    1393    // From org.springframework.util.StringUtils, under Apache License 2.0
    1394    public static boolean containsWhitespace(final CharSequence seq) {
    1395        if (isEmpty(seq)) {
    1396            return false;
    1397        }
    1398        final int strLen = seq.length();
    1399        for (int i = 0; i < strLen; i++) {
    1400            if (Character.isWhitespace(seq.charAt(i))) {
    1401                return true;
    1402            }
    1403        }
    1404        return false;
    1405    }
    1406
    1407    private static void convertRemainingAccentCharacters(final StringBuilder decomposed) {
    1408        for (int i = 0; i < decomposed.length(); i++) {
    1409            final char charAt = decomposed.charAt(i);
    1410            switch (charAt) {
    1411            case '\u0141':
    1412                decomposed.setCharAt(i, 'L');
    1413                break;
    1414            case '\u0142':
    1415                decomposed.setCharAt(i, 'l');
    1416                break;
    1417            // D with stroke
    1418            case '\u0110':
    1419                // LATIN CAPITAL LETTER D WITH STROKE
    1420                decomposed.setCharAt(i, 'D');
    1421                break;
    1422            case '\u0111':
    1423                // LATIN SMALL LETTER D WITH STROKE
    1424                decomposed.setCharAt(i, 'd');
    1425                break;
    1426            // I with bar
    1427            case '\u0197':
    1428                decomposed.setCharAt(i, 'I');
    1429                break;
    1430            case '\u0268':
    1431                decomposed.setCharAt(i, 'i');
    1432                break;
    1433            case '\u1D7B':
    1434                decomposed.setCharAt(i, 'I');
    1435                break;
    1436            case '\u1DA4':
    1437                decomposed.setCharAt(i, 'i');
    1438                break;
    1439            case '\u1DA7':
    1440                decomposed.setCharAt(i, 'I');
    1441                break;
    1442            // U with bar
    1443            case '\u0244':
    1444                // LATIN CAPITAL LETTER U BAR
    1445                decomposed.setCharAt(i, 'U');
    1446                break;
    1447            case '\u0289':
    1448                // LATIN SMALL LETTER U BAR
    1449                decomposed.setCharAt(i, 'u');
    1450                break;
    1451            case '\u1D7E':
    1452                // LATIN SMALL CAPITAL LETTER U WITH STROKE
    1453                decomposed.setCharAt(i, 'U');
    1454                break;
    1455            case '\u1DB6':
    1456                // MODIFIER LETTER SMALL U BAR
    1457                decomposed.setCharAt(i, 'u');
    1458                break;
    1459            // T with stroke
    1460            case '\u0166':
    1461                // LATIN CAPITAL LETTER T WITH STROKE
    1462                decomposed.setCharAt(i, 'T');
    1463                break;
    1464            case '\u0167':
    1465                // LATIN SMALL LETTER T WITH STROKE
    1466                decomposed.setCharAt(i, 't');
    1467                break;
    1468            default:
    1469                break;
    1470            }
    1471        }
    1472    }
    1473
    1474    /**
    1475     * Counts how many times the char appears in the given string.
    1476     *
    1477     * <p>A {@code null} or empty ("") String input returns {@code 0}.</p>
    1478     *
    1479     * <pre>
    1480     * StringUtils.countMatches(null, *)     = 0
    1481     * StringUtils.countMatches("", *)       = 0
    1482     * StringUtils.countMatches("abba", 0)   = 0
    1483     * StringUtils.countMatches("abba", 'a') = 2
    1484     * StringUtils.countMatches("abba", 'b') = 2
    1485     * StringUtils.countMatches("abba", 'x') = 0
    1486     * </pre>
    1487     *
    1488     * @param str  the CharSequence to check, may be null
    1489     * @param ch  the char to count
    1490     * @return the number of occurrences, 0 if the CharSequence is {@code null}
    1491     * @since 3.4
    1492     */
    1493    public static int countMatches(final CharSequence str, final char ch) {
    1494        if (isEmpty(str)) {
    1495            return 0;
    1496        }
    1497        int count = 0;
    1498        // We could also call str.toCharArray() for faster lookups but that would generate more garbage.
    1499        for (int i = 0; i < str.length(); i++) {
    1500            if (ch == str.charAt(i)) {
    1501                count++;
    1502            }
    1503        }
    1504        return count;
    1505    }
    1506
    1507    /**
    1508     * Counts how many times the substring appears in the larger string.
    1509     * Note that the code only counts non-overlapping matches.
    1510     *
    1511     * <p>A {@code null} or empty ("") String input returns {@code 0}.</p>
    1512     *
    1513     * <pre>
    1514     * StringUtils.countMatches(null, *)        = 0
    1515     * StringUtils.countMatches("", *)          = 0
    1516     * StringUtils.countMatches("abba", null)   = 0
    1517     * StringUtils.countMatches("abba", "")     = 0
    1518     * StringUtils.countMatches("abba", "a")    = 2
    1519     * StringUtils.countMatches("abba", "ab")   = 1
    1520     * StringUtils.countMatches("abba", "xxx")  = 0
    1521     * StringUtils.countMatches("ababa", "aba") = 1
    1522     * </pre>
    1523     *
    1524     * @param str  the CharSequence to check, may be null
    1525     * @param sub  the substring to count, may be null
    1526     * @return the number of occurrences, 0 if either CharSequence is {@code null}
    1527     * @since 3.0 Changed signature from countMatches(String, String) to countMatches(CharSequence, CharSequence)
    1528     */
    1529    public static int countMatches(final CharSequence str, final CharSequence sub) {
    1530        if (isEmpty(str) || isEmpty(sub)) {
    1531            return 0;
    1532        }
    1533        int count = 0;
    1534        int idx = 0;
    1535        while ((idx = CharSequenceUtils.indexOf(str, sub, idx)) != INDEX_NOT_FOUND) {
    1536            count++;
    1537            idx += sub.length();
    1538        }
    1539        return count;
    1540    }
    1541
    1542    /**
    1543     * Returns either the passed in CharSequence, or if the CharSequence is
    1544     * whitespace, empty ("") or {@code null}, the value of {@code defaultStr}.
    1545     *
    1546     * <p>Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
    1547     *
    1548     * <pre>
    1549     * StringUtils.defaultIfBlank(null, "NULL")  = "NULL"
    1550     * StringUtils.defaultIfBlank("", "NULL")    = "NULL"
    1551     * StringUtils.defaultIfBlank(" ", "NULL")   = "NULL"
    1552     * StringUtils.defaultIfBlank("bat", "NULL") = "bat"
    1553     * StringUtils.defaultIfBlank("", null)      = null
    1554     * </pre>
    1555     * @param <T> the specific kind of CharSequence
    1556     * @param str the CharSequence to check, may be null
    1557     * @param defaultStr  the default CharSequence to return
    1558     *  if the input is whitespace, empty ("") or {@code null}, may be null
    1559     * @return the passed in CharSequence, or the default
    1560     * @see StringUtils#defaultString(String, String)
    1561     */
    1562    public static <T extends CharSequence> T defaultIfBlank(final T str, final T defaultStr) {
    1563        return isBlank(str) ? defaultStr : str;
    1564    }
    1565
    1566    /**
    1567     * Returns either the passed in CharSequence, or if the CharSequence is
    1568     * empty or {@code null}, the value of {@code defaultStr}.
    1569     *
    1570     * <pre>
    1571     * StringUtils.defaultIfEmpty(null, "NULL")  = "NULL"
    1572     * StringUtils.defaultIfEmpty("", "NULL")    = "NULL"
    1573     * StringUtils.defaultIfEmpty(" ", "NULL")   = " "
    1574     * StringUtils.defaultIfEmpty("bat", "NULL") = "bat"
    1575     * StringUtils.defaultIfEmpty("", null)      = null
    1576     * </pre>
    1577     * @param <T> the specific kind of CharSequence
    1578     * @param str  the CharSequence to check, may be null
    1579     * @param defaultStr  the default CharSequence to return
    1580     *  if the input is empty ("") or {@code null}, may be null
    1581     * @return the passed in CharSequence, or the default
    1582     * @see StringUtils#defaultString(String, String)
    1583     */
    1584    public static <T extends CharSequence> T defaultIfEmpty(final T str, final T defaultStr) {
    1585        return isEmpty(str) ? defaultStr : str;
    1586    }
    1587
    1588    /**
    1589     * Returns either the passed in String,
    1590     * or if the String is {@code null}, an empty String ("").
    1591     *
    1592     * <pre>
    1593     * StringUtils.defaultString(null)  = ""
    1594     * StringUtils.defaultString("")    = ""
    1595     * StringUtils.defaultString("bat") = "bat"
    1596     * </pre>
    1597     *
    1598     * @see Objects#toString(Object, String)
    1599     * @see String#valueOf(Object)
    1600     * @param str  the String to check, may be null
    1601     * @return the passed in String, or the empty String if it
    1602     *  was {@code null}
    1603     */
    1604    public static String defaultString(final String str) {
    1605        return Objects.toString(str, EMPTY);
    1606    }
    1607
    1608    /**
    1609     * Returns either the given String, or if the String is
    1610     * {@code null}, {@code nullDefault}.
    1611     *
    1612     * <pre>
    1613     * StringUtils.defaultString(null, "NULL")  = "NULL"
    1614     * StringUtils.defaultString("", "NULL")    = ""
    1615     * StringUtils.defaultString("bat", "NULL") = "bat"
    1616     * </pre>
    1617     * <p>
    1618     * Since this is now provided by Java, instead call {@link Objects#toString(Object, String)}:
    1619     * </p>
    1620     * <pre>
    1621     * Objects.toString(null, "NULL")  = "NULL"
    1622     * Objects.toString("", "NULL")    = ""
    1623     * Objects.toString("bat", "NULL") = "bat"
    1624     * </pre>
    1625     *
    1626     * @see Objects#toString(Object, String)
    1627     * @see String#valueOf(Object)
    1628     * @param str  the String to check, may be null
    1629     * @param nullDefault  the default String to return
    1630     *  if the input is {@code null}, may be null
    1631     * @return the passed in String, or the default if it was {@code null}
    1632     * @deprecated Use {@link Objects#toString(Object, String)}
    1633     */
    1634    @Deprecated
    1635    public static String defaultString(final String str, final String nullDefault) {
    1636        return Objects.toString(str, nullDefault);
    1637    }
    1638
    1639    /**
    1640     * Deletes all whitespaces from a String as defined by
    1641     * {@link Character#isWhitespace(char)}.
    1642     *
    1643     * <pre>
    1644     * StringUtils.deleteWhitespace(null)         = null
    1645     * StringUtils.deleteWhitespace("")           = ""
    1646     * StringUtils.deleteWhitespace("abc")        = "abc"
    1647     * StringUtils.deleteWhitespace("   ab  c  ") = "abc"
    1648     * </pre>
    1649     *
    1650     * @param str  the String to delete whitespace from, may be null
    1651     * @return the String without whitespaces, {@code null} if null String input
    1652     */
    1653    public static String deleteWhitespace(final String str) {
    1654        if (isEmpty(str)) {
    1655            return str;
    1656        }
    1657        final int sz = str.length();
    1658        final char[] chs = new char[sz];
    1659        int count = 0;
    1660        for (int i = 0; i < sz; i++) {
    1661            if (!Character.isWhitespace(str.charAt(i))) {
    1662                chs[count++] = str.charAt(i);
    1663            }
    1664        }
    1665        if (count == sz) {
    1666            return str;
    1667        }
    1668        if (count == 0) {
    1669            return EMPTY;
    1670        }
    1671        return new String(chs, 0, count);
    1672    }
    1673
    1674    /**
    1675     * Compares two Strings, and returns the portion where they differ.
    1676     * More precisely, return the remainder of the second String,
    1677     * starting from where it's different from the first. This means that
    1678     * the difference between "abc" and "ab" is the empty String and not "c".
    1679     *
    1680     * <p>For example,
    1681     * {@code difference("i am a machine", "i am a robot") -> "robot"}.</p>
    1682     *
    1683     * <pre>
    1684     * StringUtils.difference(null, null)       = null
    1685     * StringUtils.difference("", "")           = ""
    1686     * StringUtils.difference("", "abc")        = "abc"
    1687     * StringUtils.difference("abc", "")        = ""
    1688     * StringUtils.difference("abc", "abc")     = ""
    1689     * StringUtils.difference("abc", "ab")      = ""
    1690     * StringUtils.difference("ab", "abxyz")    = "xyz"
    1691     * StringUtils.difference("abcde", "abxyz") = "xyz"
    1692     * StringUtils.difference("abcde", "xyz")   = "xyz"
    1693     * </pre>
    1694     *
    1695     * @param str1  the first String, may be null
    1696     * @param str2  the second String, may be null
    1697     * @return the portion of str2 where it differs from str1; returns the
    1698     * empty String if they are equal
    1699     * @see #indexOfDifference(CharSequence,CharSequence)
    1700     * @since 2.0
    1701     */
    1702    public static String difference(final String str1, final String str2) {
    1703        if (str1 == null) {
    1704            return str2;
    1705        }
    1706        if (str2 == null) {
    1707            return str1;
    1708        }
    1709        final int at = indexOfDifference(str1, str2);
    1710        if (at == INDEX_NOT_FOUND) {
    1711            return EMPTY;
    1712        }
    1713        return str2.substring(at);
    1714    }
    1715
    1716    /**
    1717     * Check if a CharSequence ends with a specified suffix.
    1718     *
    1719     * <p>{@code null}s are handled without exceptions. Two {@code null}
    1720     * references are considered to be equal. The comparison is case-sensitive.</p>
    1721     *
    1722     * <pre>
    1723     * StringUtils.endsWith(null, null)      = true
    1724     * StringUtils.endsWith(null, "def")     = false
    1725     * StringUtils.endsWith("abcdef", null)  = false
    1726     * StringUtils.endsWith("abcdef", "def") = true
    1727     * StringUtils.endsWith("ABCDEF", "def") = false
    1728     * StringUtils.endsWith("ABCDEF", "cde") = false
    1729     * StringUtils.endsWith("ABCDEF", "")    = true
    1730     * </pre>
    1731     *
    1732     * @see String#endsWith(String)
    1733     * @param str  the CharSequence to check, may be null
    1734     * @param suffix the suffix to find, may be null
    1735     * @return {@code true} if the CharSequence ends with the suffix, case-sensitive, or
    1736     *  both {@code null}
    1737     * @since 2.4
    1738     * @since 3.0 Changed signature from endsWith(String, String) to endsWith(CharSequence, CharSequence)
    1739     */
    1740    public static boolean endsWith(final CharSequence str, final CharSequence suffix) {
    1741        return endsWith(str, suffix, false);
    1742    }
    1743
    1744    /**
    1745     * Check if a CharSequence ends with a specified suffix (optionally case-insensitive).
    1746     *
    1747     * @see String#endsWith(String)
    1748     * @param str  the CharSequence to check, may be null
    1749     * @param suffix the suffix to find, may be null
    1750     * @param ignoreCase indicates whether the compare should ignore case
    1751     *  (case-insensitive) or not.
    1752     * @return {@code true} if the CharSequence starts with the prefix or
    1753     *  both {@code null}
    1754     */
    1755    private static boolean endsWith(final CharSequence str, final CharSequence suffix, final boolean ignoreCase) {
    1756        if (str == null || suffix == null) {
    1757            return str == suffix;
    1758        }
    1759        if (suffix.length() > str.length()) {
    1760            return false;
    1761        }
    1762        final int strOffset = str.length() - suffix.length();
    1763        return CharSequenceUtils.regionMatches(str, ignoreCase, strOffset, suffix, 0, suffix.length());
    1764    }
    1765
    1766    /**
    1767     * Check if a CharSequence ends with any of the provided case-sensitive suffixes.
    1768     *
    1769     * <pre>
    1770     * StringUtils.endsWithAny(null, null)                  = false
    1771     * StringUtils.endsWithAny(null, new String[] {"abc"})  = false
    1772     * StringUtils.endsWithAny("abcxyz", null)              = false
    1773     * StringUtils.endsWithAny("abcxyz", new String[] {""}) = true
    1774     * StringUtils.endsWithAny("abcxyz", new String[] {"xyz"}) = true
    1775     * StringUtils.endsWithAny("abcxyz", new String[] {null, "xyz", "abc"}) = true
    1776     * StringUtils.endsWithAny("abcXYZ", "def", "XYZ")      = true
    1777     * StringUtils.endsWithAny("abcXYZ", "def", "xyz")      = false
    1778     * </pre>
    1779     *
    1780     * @param sequence  the CharSequence to check, may be null
    1781     * @param searchStrings the case-sensitive CharSequences to find, may be empty or contain {@code null}
    1782     * @see StringUtils#endsWith(CharSequence, CharSequence)
    1783     * @return {@code true} if the input {@code sequence} is {@code null} AND no {@code searchStrings} are provided, or
    1784     *   the input {@code sequence} ends in any of the provided case-sensitive {@code searchStrings}.
    1785     * @since 3.0
    1786     */
    1787    public static boolean endsWithAny(final CharSequence sequence, final CharSequence... searchStrings) {
    1788        if (isEmpty(sequence) || ArrayUtils.isEmpty(searchStrings)) {
    1789            return false;
    1790        }
    1791        for (final CharSequence searchString : searchStrings) {
    1792            if (endsWith(sequence, searchString)) {
    1793                return true;
    1794            }
    1795        }
    1796        return false;
    1797    }
    1798
    1799    /**
    1800     * Case-insensitive check if a CharSequence ends with a specified suffix.
    1801     *
    1802     * <p>{@code null}s are handled without exceptions. Two {@code null}
    1803     * references are considered to be equal. The comparison is case insensitive.</p>
    1804     *
    1805     * <pre>
    1806     * StringUtils.endsWithIgnoreCase(null, null)      = true
    1807     * StringUtils.endsWithIgnoreCase(null, "def")     = false
    1808     * StringUtils.endsWithIgnoreCase("abcdef", null)  = false
    1809     * StringUtils.endsWithIgnoreCase("abcdef", "def") = true
    1810     * StringUtils.endsWithIgnoreCase("ABCDEF", "def") = true
    1811     * StringUtils.endsWithIgnoreCase("ABCDEF", "cde") = false
    1812     * </pre>
    1813     *
    1814     * @see String#endsWith(String)
    1815     * @param str  the CharSequence to check, may be null
    1816     * @param suffix the suffix to find, may be null
    1817     * @return {@code true} if the CharSequence ends with the suffix, case-insensitive, or
    1818     *  both {@code null}
    1819     * @since 2.4
    1820     * @since 3.0 Changed signature from endsWithIgnoreCase(String, String) to endsWithIgnoreCase(CharSequence, CharSequence)
    1821     */
    1822    public static boolean endsWithIgnoreCase(final CharSequence str, final CharSequence suffix) {
    1823        return endsWith(str, suffix, true);
    1824    }
    1825
    1826    /**
    1827     * Compares two CharSequences, returning {@code true} if they represent
    1828     * equal sequences of characters.
    1829     *
    1830     * <p>{@code null}s are handled without exceptions. Two {@code null}
    1831     * references are considered to be equal. The comparison is <strong>case-sensitive</strong>.</p>
    1832     *
    1833     * <pre>
    1834     * StringUtils.equals(null, null)   = true
    1835     * StringUtils.equals(null, "abc")  = false
    1836     * StringUtils.equals("abc", null)  = false
    1837     * StringUtils.equals("abc", "abc") = true
    1838     * StringUtils.equals("abc", "ABC") = false
    1839     * </pre>
    1840     *
    1841     * @param cs1  the first CharSequence, may be {@code null}
    1842     * @param cs2  the second CharSequence, may be {@code null}
    1843     * @return {@code true} if the CharSequences are equal (case-sensitive), or both {@code null}
    1844     * @since 3.0 Changed signature from equals(String, String) to equals(CharSequence, CharSequence)
    1845     * @see Object#equals(Object)
    1846     * @see #equalsIgnoreCase(CharSequence, CharSequence)
    1847     */
    1848    public static boolean equals(final CharSequence cs1, final CharSequence cs2) {
    1849        if (cs1 == cs2) {
    1850            return true;
    1851        }
    1852        if (cs1 == null || cs2 == null) {
    1853            return false;
    1854        }
    1855        if (cs1.length() != cs2.length()) {
    1856            return false;
    1857        }
    1858        if (cs1 instanceof String && cs2 instanceof String) {
    1859            return cs1.equals(cs2);
    1860        }
    1861        // Step-wise comparison
    1862        final int length = cs1.length();
    1863        for (int i = 0; i < length; i++) {
    1864            if (cs1.charAt(i) != cs2.charAt(i)) {
    1865                return false;
    1866            }
    1867        }
    1868        return true;
    1869    }
    1870
    1871    /**
    1872     * Compares given {@code string} to a CharSequences vararg of {@code searchStrings},
    1873     * returning {@code true} if the {@code string} is equal to any of the {@code searchStrings}.
    1874     *
    1875     * <pre>
    1876     * StringUtils.equalsAny(null, (CharSequence[]) null) = false
    1877     * StringUtils.equalsAny(null, null, null)    = true
    1878     * StringUtils.equalsAny(null, "abc", "def")  = false
    1879     * StringUtils.equalsAny("abc", null, "def")  = false
    1880     * StringUtils.equalsAny("abc", "abc", "def") = true
    1881     * StringUtils.equalsAny("abc", "ABC", "DEF") = false
    1882     * </pre>
    1883     *
    1884     * @param string to compare, may be {@code null}.
    1885     * @param searchStrings a vararg of strings, may be {@code null}.
    1886     * @return {@code true} if the string is equal (case-sensitive) to any other element of {@code searchStrings};
    1887     * {@code false} if {@code searchStrings} is null or contains no matches.
    1888     * @since 3.5
    1889     */
    1890    public static boolean equalsAny(final CharSequence string, final CharSequence... searchStrings) {
    1891        if (ArrayUtils.isNotEmpty(searchStrings)) {
    1892            for (final CharSequence next : searchStrings) {
    1893                if (equals(string, next)) {
    1894                    return true;
    1895                }
    1896            }
    1897        }
    1898        return false;
    1899    }
    1900
    1901    /**
    1902     * Compares given {@code string} to a CharSequences vararg of {@code searchStrings},
    1903     * returning {@code true} if the {@code string} is equal to any of the {@code searchStrings}, ignoring case.
    1904     *
    1905     * <pre>
    1906     * StringUtils.equalsAnyIgnoreCase(null, (CharSequence[]) null) = false
    1907     * StringUtils.equalsAnyIgnoreCase(null, null, null)    = true
    1908     * StringUtils.equalsAnyIgnoreCase(null, "abc", "def")  = false
    1909     * StringUtils.equalsAnyIgnoreCase("abc", null, "def")  = false
    1910     * StringUtils.equalsAnyIgnoreCase("abc", "abc", "def") = true
    1911     * StringUtils.equalsAnyIgnoreCase("abc", "ABC", "DEF") = true
    1912     * </pre>
    1913     *
    1914     * @param string to compare, may be {@code null}.
    1915     * @param searchStrings a vararg of strings, may be {@code null}.
    1916     * @return {@code true} if the string is equal (case-insensitive) to any other element of {@code searchStrings};
    1917     * {@code false} if {@code searchStrings} is null or contains no matches.
    1918     * @since 3.5
    1919     */
    1920    public static boolean equalsAnyIgnoreCase(final CharSequence string, final CharSequence... searchStrings) {
    1921        if (ArrayUtils.isNotEmpty(searchStrings)) {
    1922            for (final CharSequence next : searchStrings) {
    1923                if (equalsIgnoreCase(string, next)) {
    1924                    return true;
    1925                }
    1926            }
    1927        }
    1928        return false;
    1929    }
    1930
    1931    /**
    1932     * Compares two CharSequences, returning {@code true} if they represent
    1933     * equal sequences of characters, ignoring case.
    1934     *
    1935     * <p>{@code null}s are handled without exceptions. Two {@code null}
    1936     * references are considered equal. The comparison is <strong>case insensitive</strong>.</p>
    1937     *
    1938     * <pre>
    1939     * StringUtils.equalsIgnoreCase(null, null)   = true
    1940     * StringUtils.equalsIgnoreCase(null, "abc")  = false
    1941     * StringUtils.equalsIgnoreCase("abc", null)  = false
    1942     * StringUtils.equalsIgnoreCase("abc", "abc") = true
    1943     * StringUtils.equalsIgnoreCase("abc", "ABC") = true
    1944     * </pre>
    1945     *
    1946     * @param cs1  the first CharSequence, may be {@code null}
    1947     * @param cs2  the second CharSequence, may be {@code null}
    1948     * @return {@code true} if the CharSequences are equal (case-insensitive), or both {@code null}
    1949     * @since 3.0 Changed signature from equalsIgnoreCase(String, String) to equalsIgnoreCase(CharSequence, CharSequence)
    1950     * @see #equals(CharSequence, CharSequence)
    1951     */
    1952    public static boolean equalsIgnoreCase(final CharSequence cs1, final CharSequence cs2) {
    1953        if (cs1 == cs2) {
    1954            return true;
    1955        }
    1956        if (cs1 == null || cs2 == null) {
    1957            return false;
    1958        }
    1959        if (cs1.length() != cs2.length()) {
    1960            return false;
    1961        }
    1962        return CharSequenceUtils.regionMatches(cs1, true, 0, cs2, 0, cs1.length());
    1963    }
    1964
    1965    /**
    1966     * Returns the first value in the array which is not empty (""),
    1967     * {@code null} or whitespace only.
    1968     *
    1969     * <p>Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
    1970     *
    1971     * <p>If all values are blank or the array is {@code null}
    1972     * or empty then {@code null} is returned.</p>
    1973     *
    1974     * <pre>
    1975     * StringUtils.firstNonBlank(null, null, null)     = null
    1976     * StringUtils.firstNonBlank(null, "", " ")        = null
    1977     * StringUtils.firstNonBlank("abc")                = "abc"
    1978     * StringUtils.firstNonBlank(null, "xyz")          = "xyz"
    1979     * StringUtils.firstNonBlank(null, "", " ", "xyz") = "xyz"
    1980     * StringUtils.firstNonBlank(null, "xyz", "abc")   = "xyz"
    1981     * StringUtils.firstNonBlank()                     = null
    1982     * </pre>
    1983     *
    1984     * @param <T> the specific kind of CharSequence
    1985     * @param values  the values to test, may be {@code null} or empty
    1986     * @return the first value from {@code values} which is not blank,
    1987     *  or {@code null} if there are no non-blank values
    1988     * @since 3.8
    1989     */
    1990    @SafeVarargs
    1991    public static <T extends CharSequence> T firstNonBlank(final T... values) {
    1992        if (values != null) {
    1993            for (final T val : values) {
    1994                if (isNotBlank(val)) {
    1995                    return val;
    1996                }
    1997            }
    1998        }
    1999        return null;
    2000    }
    2001
    2002    /**
    2003     * Returns the first value in the array which is not empty.
    2004     *
    2005     * <p>If all values are empty or the array is {@code null}
    2006     * or empty then {@code null} is returned.</p>
    2007     *
    2008     * <pre>
    2009     * StringUtils.firstNonEmpty(null, null, null)   = null
    2010     * StringUtils.firstNonEmpty(null, null, "")     = null
    2011     * StringUtils.firstNonEmpty(null, "", " ")      = " "
    2012     * StringUtils.firstNonEmpty("abc")              = "abc"
    2013     * StringUtils.firstNonEmpty(null, "xyz")        = "xyz"
    2014     * StringUtils.firstNonEmpty("", "xyz")          = "xyz"
    2015     * StringUtils.firstNonEmpty(null, "xyz", "abc") = "xyz"
    2016     * StringUtils.firstNonEmpty()                   = null
    2017     * </pre>
    2018     *
    2019     * @param <T> the specific kind of CharSequence
    2020     * @param values  the values to test, may be {@code null} or empty
    2021     * @return the first value from {@code values} which is not empty,
    2022     *  or {@code null} if there are no non-empty values
    2023     * @since 3.8
    2024     */
    2025    @SafeVarargs
    2026    public static <T extends CharSequence> T firstNonEmpty(final T... values) {
    2027        if (values != null) {
    2028            for (final T val : values) {
    2029                if (isNotEmpty(val)) {
    2030                    return val;
    2031                }
    2032            }
    2033        }
    2034        return null;
    2035    }
    2036
    2037    /**
    2038     * Calls {@link String#getBytes(Charset)} in a null-safe manner.
    2039     *
    2040     * @param string input string
    2041     * @param charset The {@link Charset} to encode the {@link String}. If null, then use the default Charset.
    2042     * @return The empty byte[] if {@code string} is null, the result of {@link String#getBytes(Charset)} otherwise.
    2043     * @see String#getBytes(Charset)
    2044     * @since 3.10
    2045     */
    2046    public static byte[] getBytes(final String string, final Charset charset) {
    2047        return string == null ? ArrayUtils.EMPTY_BYTE_ARRAY : string.getBytes(Charsets.toCharset(charset));
    2048    }
    2049
    2050    /**
    2051     * Calls {@link String#getBytes(String)} in a null-safe manner.
    2052     *
    2053     * @param string input string
    2054     * @param charset The {@link Charset} name to encode the {@link String}. If null, then use the default Charset.
    2055     * @return The empty byte[] if {@code string} is null, the result of {@link String#getBytes(String)} otherwise.
    2056     * @throws UnsupportedEncodingException Thrown when the named charset is not supported.
    2057     * @see String#getBytes(String)
    2058     * @since 3.10
    2059     */
    2060    public static byte[] getBytes(final String string, final String charset) throws UnsupportedEncodingException {
    2061        return string == null ? ArrayUtils.EMPTY_BYTE_ARRAY : string.getBytes(Charsets.toCharsetName(charset));
    2062    }
    2063
    2064    /**
    2065     * Compares all Strings in an array and returns the initial sequence of
    2066     * characters that is common to all of them.
    2067     *
    2068     * <p>For example,
    2069     * {@code getCommonPrefix(new String[] {"i am a machine", "i am a robot"}) -&gt; "i am a "}</p>
    2070     *
    2071     * <pre>
    2072     * StringUtils.getCommonPrefix(null)                             = ""
    2073     * StringUtils.getCommonPrefix(new String[] {})                  = ""
    2074     * StringUtils.getCommonPrefix(new String[] {"abc"})             = "abc"
    2075     * StringUtils.getCommonPrefix(new String[] {null, null})        = ""
    2076     * StringUtils.getCommonPrefix(new String[] {"", ""})            = ""
    2077     * StringUtils.getCommonPrefix(new String[] {"", null})          = ""
    2078     * StringUtils.getCommonPrefix(new String[] {"abc", null, null}) = ""
    2079     * StringUtils.getCommonPrefix(new String[] {null, null, "abc"}) = ""
    2080     * StringUtils.getCommonPrefix(new String[] {"", "abc"})         = ""
    2081     * StringUtils.getCommonPrefix(new String[] {"abc", ""})         = ""
    2082     * StringUtils.getCommonPrefix(new String[] {"abc", "abc"})      = "abc"
    2083     * StringUtils.getCommonPrefix(new String[] {"abc", "a"})        = "a"
    2084     * StringUtils.getCommonPrefix(new String[] {"ab", "abxyz"})     = "ab"
    2085     * StringUtils.getCommonPrefix(new String[] {"abcde", "abxyz"})  = "ab"
    2086     * StringUtils.getCommonPrefix(new String[] {"abcde", "xyz"})    = ""
    2087     * StringUtils.getCommonPrefix(new String[] {"xyz", "abcde"})    = ""
    2088     * StringUtils.getCommonPrefix(new String[] {"i am a machine", "i am a robot"}) = "i am a "
    2089     * </pre>
    2090     *
    2091     * @param strs  array of String objects, entries may be null
    2092     * @return the initial sequence of characters that are common to all Strings
    2093     * in the array; empty String if the array is null, the elements are all null
    2094     * or if there is no common prefix.
    2095     * @since 2.4
    2096     */
    2097    public static String getCommonPrefix(final String... strs) {
    2098        if (ArrayUtils.isEmpty(strs)) {
    2099            return EMPTY;
    2100        }
    2101        final int smallestIndexOfDiff = indexOfDifference(strs);
    2102        if (smallestIndexOfDiff == INDEX_NOT_FOUND) {
    2103            // all strings were identical
    2104            if (strs[0] == null) {
    2105                return EMPTY;
    2106            }
    2107            return strs[0];
    2108        }
    2109        if (smallestIndexOfDiff == 0) {
    2110            // there were no common initial characters
    2111            return EMPTY;
    2112        }
    2113        // we found a common initial character sequence
    2114        return strs[0].substring(0, smallestIndexOfDiff);
    2115    }
    2116
    2117    /**
    2118     * Checks if a String {@code str} contains Unicode digits,
    2119     * if yes then concatenate all the digits in {@code str} and return it as a String.
    2120     *
    2121     * <p>An empty ("") String will be returned if no digits found in {@code str}.</p>
    2122     *
    2123     * <pre>
    2124     * StringUtils.getDigits(null)                 = null
    2125     * StringUtils.getDigits("")                   = ""
    2126     * StringUtils.getDigits("abc")                = ""
    2127     * StringUtils.getDigits("1000$")              = "1000"
    2128     * StringUtils.getDigits("1123~45")            = "112345"
    2129     * StringUtils.getDigits("(541) 754-3010")     = "5417543010"
    2130     * StringUtils.getDigits("\u0967\u0968\u0969") = "\u0967\u0968\u0969"
    2131     * </pre>
    2132     *
    2133     * @param str the String to extract digits from, may be null
    2134     * @return String with only digits,
    2135     *           or an empty ("") String if no digits found,
    2136     *           or {@code null} String if {@code str} is null
    2137     * @since 3.6
    2138     */
    2139    public static String getDigits(final String str) {
    2140        if (isEmpty(str)) {
    2141            return str;
    2142        }
    2143        final int sz = str.length();
    2144        final StringBuilder strDigits = new StringBuilder(sz);
    2145        for (int i = 0; i < sz; i++) {
    2146            final char tempChar = str.charAt(i);
    2147            if (Character.isDigit(tempChar)) {
    2148                strDigits.append(tempChar);
    2149            }
    2150        }
    2151        return strDigits.toString();
    2152    }
    2153
    2154    /**
    2155     * Find the Fuzzy Distance which indicates the similarity score between two Strings.
    2156     *
    2157     * <p>This string matching algorithm is similar to the algorithms of editors such as Sublime Text,
    2158     * TextMate, Atom and others. One point is given for every matched character. Subsequent
    2159     * matches yield two bonus points. A higher score indicates a higher similarity.</p>
    2160     *
    2161     * <pre>
    2162     * StringUtils.getFuzzyDistance(null, null, null)                                    = IllegalArgumentException
    2163     * StringUtils.getFuzzyDistance("", "", Locale.ENGLISH)                              = 0
    2164     * StringUtils.getFuzzyDistance("Workshop", "b", Locale.ENGLISH)                     = 0
    2165     * StringUtils.getFuzzyDistance("Room", "o", Locale.ENGLISH)                         = 1
    2166     * StringUtils.getFuzzyDistance("Workshop", "w", Locale.ENGLISH)                     = 1
    2167     * StringUtils.getFuzzyDistance("Workshop", "ws", Locale.ENGLISH)                    = 2
    2168     * StringUtils.getFuzzyDistance("Workshop", "wo", Locale.ENGLISH)                    = 4
    2169     * StringUtils.getFuzzyDistance("Apache Software Foundation", "asf", Locale.ENGLISH) = 3
    2170     * </pre>
    2171     *
    2172     * @param term a full term that should be matched against, must not be null
    2173     * @param query the query that will be matched against a term, must not be null
    2174     * @param locale This string matching logic is case-insensitive. A locale is necessary to normalize
    2175     *  both Strings to lower case.
    2176     * @return result score
    2177     * @throws IllegalArgumentException if either String input {@code null} or Locale input {@code null}
    2178     * @since 3.4
    2179     * @deprecated As of 3.6, use Apache Commons Text
    2180     * <a href="https://commons.apache.org/proper/commons-text/javadocs/api-release/org/apache/commons/text/similarity/FuzzyScore.html">
    2181     * FuzzyScore</a> instead
    2182     */
    2183    @Deprecated
    2184    public static int getFuzzyDistance(final CharSequence term, final CharSequence query, final Locale locale) {
    2185        if (term == null || query == null) {
    2186            throw new IllegalArgumentException("Strings must not be null");
    2187        }
    2188        if (locale == null) {
    2189            throw new IllegalArgumentException("Locale must not be null");
    2190        }
    2191
    2192        // fuzzy logic is case-insensitive. We normalize the Strings to lower
    2193        // case right from the start. Turning characters to lower case
    2194        // via Character.toLowerCase(char) is unfortunately insufficient
    2195        // as it does not accept a locale.
    2196        final String termLowerCase = term.toString().toLowerCase(locale);
    2197        final String queryLowerCase = query.toString().toLowerCase(locale);
    2198
    2199        // the resulting score
    2200        int score = 0;
    2201
    2202        // the position in the term which will be scanned next for potential
    2203        // query character matches
    2204        int termIndex = 0;
    2205
    2206        // index of the previously matched character in the term
    2207        int previousMatchingCharacterIndex = Integer.MIN_VALUE;
    2208
    2209        for (int queryIndex = 0; queryIndex < queryLowerCase.length(); queryIndex++) {
    2210            final char queryChar = queryLowerCase.charAt(queryIndex);
    2211
    2212            boolean termCharacterMatchFound = false;
    2213            for (; termIndex < termLowerCase.length() && !termCharacterMatchFound; termIndex++) {
    2214                final char termChar = termLowerCase.charAt(termIndex);
    2215
    2216                if (queryChar == termChar) {
    2217                    // simple character matches result in one point
    2218                    score++;
    2219
    2220                    // subsequent character matches further improve
    2221                    // the score.
    2222                    if (previousMatchingCharacterIndex + 1 == termIndex) {
    2223                        score += 2;
    2224                    }
    2225
    2226                    previousMatchingCharacterIndex = termIndex;
    2227
    2228                    // we can leave the nested loop. Every character in the
    2229                    // query can match at most one character in the term.
    2230                    termCharacterMatchFound = true;
    2231                }
    2232            }
    2233        }
    2234
    2235        return score;
    2236    }
    2237
    2238    /**
    2239     * Returns either the passed in CharSequence, or if the CharSequence is
    2240     * whitespace, empty ("") or {@code null}, the value supplied by {@code defaultStrSupplier}.
    2241     *
    2242     * <p>Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
    2243     *
    2244     * <p>Caller responsible for thread-safety and exception handling of default value supplier</p>
    2245     *
    2246     * <pre>
    2247     * {@code
    2248     * StringUtils.getIfBlank(null, () -> "NULL")   = "NULL"
    2249     * StringUtils.getIfBlank("", () -> "NULL")     = "NULL"
    2250     * StringUtils.getIfBlank(" ", () -> "NULL")    = "NULL"
    2251     * StringUtils.getIfBlank("bat", () -> "NULL")  = "bat"
    2252     * StringUtils.getIfBlank("", () -> null)       = null
    2253     * StringUtils.getIfBlank("", null)             = null
    2254     * }</pre>
    2255     * @param <T> the specific kind of CharSequence
    2256     * @param str the CharSequence to check, may be null
    2257     * @param defaultSupplier the supplier of default CharSequence to return
    2258     *  if the input is whitespace, empty ("") or {@code null}, may be null
    2259     * @return the passed in CharSequence, or the default
    2260     * @see StringUtils#defaultString(String, String)
    2261     * @since 3.10
    2262     */
    2263    public static <T extends CharSequence> T getIfBlank(final T str, final Supplier<T> defaultSupplier) {
    2264        return isBlank(str) ? Suppliers.get(defaultSupplier) : str;
    2265    }
    2266
    2267    /**
    2268     * Returns either the passed in CharSequence, or if the CharSequence is
    2269     * empty or {@code null}, the value supplied by {@code defaultStrSupplier}.
    2270     *
    2271     * <p>Caller responsible for thread-safety and exception handling of default value supplier</p>
    2272     *
    2273     * <pre>
    2274     * {@code
    2275     * StringUtils.getIfEmpty(null, () -> "NULL")    = "NULL"
    2276     * StringUtils.getIfEmpty("", () -> "NULL")      = "NULL"
    2277     * StringUtils.getIfEmpty(" ", () -> "NULL")     = " "
    2278     * StringUtils.getIfEmpty("bat", () -> "NULL")   = "bat"
    2279     * StringUtils.getIfEmpty("", () -> null)        = null
    2280     * StringUtils.getIfEmpty("", null)              = null
    2281     * }
    2282     * </pre>
    2283     * @param <T> the specific kind of CharSequence
    2284     * @param str  the CharSequence to check, may be null
    2285     * @param defaultSupplier  the supplier of default CharSequence to return
    2286     *  if the input is empty ("") or {@code null}, may be null
    2287     * @return the passed in CharSequence, or the default
    2288     * @see StringUtils#defaultString(String, String)
    2289     * @since 3.10
    2290     */
    2291    public static <T extends CharSequence> T getIfEmpty(final T str, final Supplier<T> defaultSupplier) {
    2292        return isEmpty(str) ? Suppliers.get(defaultSupplier) : str;
    2293    }
    2294
    2295    /**
    2296     * Find the Jaro Winkler Distance which indicates the similarity score between two Strings.
    2297     *
    2298     * <p>The Jaro measure is the weighted sum of percentage of matched characters from each file and transposed characters.
    2299     * Winkler increased this measure for matching initial characters.</p>
    2300     *
    2301     * <p>This implementation is based on the Jaro Winkler similarity algorithm
    2302     * from <a href="https://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance">https://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance</a>.</p>
    2303     *
    2304     * <pre>
    2305     * StringUtils.getJaroWinklerDistance(null, null)          = IllegalArgumentException
    2306     * StringUtils.getJaroWinklerDistance("", "")              = 0.0
    2307     * StringUtils.getJaroWinklerDistance("", "a")             = 0.0
    2308     * StringUtils.getJaroWinklerDistance("aaapppp", "")       = 0.0
    2309     * StringUtils.getJaroWinklerDistance("frog", "fog")       = 0.93
    2310     * StringUtils.getJaroWinklerDistance("fly", "ant")        = 0.0
    2311     * StringUtils.getJaroWinklerDistance("elephant", "hippo") = 0.44
    2312     * StringUtils.getJaroWinklerDistance("hippo", "elephant") = 0.44
    2313     * StringUtils.getJaroWinklerDistance("hippo", "zzzzzzzz") = 0.0
    2314     * StringUtils.getJaroWinklerDistance("hello", "hallo")    = 0.88
    2315     * StringUtils.getJaroWinklerDistance("ABC Corporation", "ABC Corp") = 0.93
    2316     * StringUtils.getJaroWinklerDistance("D N H Enterprises Inc", "D &amp; H Enterprises, Inc.") = 0.95
    2317     * StringUtils.getJaroWinklerDistance("My Gym Children's Fitness Center", "My Gym. Childrens Fitness") = 0.92
    2318     * StringUtils.getJaroWinklerDistance("PENNSYLVANIA", "PENNCISYLVNIA") = 0.88
    2319     * </pre>
    2320     *
    2321     * @param first the first String, must not be null
    2322     * @param second the second String, must not be null
    2323     * @return result distance
    2324     * @throws IllegalArgumentException if either String input {@code null}
    2325     * @since 3.3
    2326     * @deprecated As of 3.6, use Apache Commons Text
    2327     * <a href="https://commons.apache.org/proper/commons-text/javadocs/api-release/org/apache/commons/text/similarity/JaroWinklerDistance.html">
    2328     * JaroWinklerDistance</a> instead
    2329     */
    2330    @Deprecated
    2331    public static double getJaroWinklerDistance(final CharSequence first, final CharSequence second) {
    2332        final double DEFAULT_SCALING_FACTOR = 0.1;
    2333
    2334        if (first == null || second == null) {
    2335            throw new IllegalArgumentException("Strings must not be null");
    2336        }
    2337
    2338        final int[] mtp = matches(first, second);
    2339        final double m = mtp[0];
    2340        if (m == 0) {
    2341            return 0D;
    2342        }
    2343        final double j = (m / first.length() + m / second.length() + (m - mtp[1]) / m) / 3;
    2344        final double jw = j < 0.7D ? j : j + Math.min(DEFAULT_SCALING_FACTOR, 1D / mtp[3]) * mtp[2] * (1D - j);
    2345        return Math.round(jw * 100.0D) / 100.0D;
    2346    }
    2347
    2348    /**
    2349     * Find the Levenshtein distance between two Strings.
    2350     *
    2351     * <p>This is the number of changes needed to change one String into
    2352     * another, where each change is a single character modification (deletion,
    2353     * insertion or substitution).</p>
    2354     *
    2355     * <p>The implementation uses a single-dimensional array of length s.length() + 1. See
    2356     * <a href="https://blog.softwx.net/2014/12/optimizing-levenshtein-algorithm-in-c.html">
    2357     * https://blog.softwx.net/2014/12/optimizing-levenshtein-algorithm-in-c.html</a> for details.</p>
    2358     *
    2359     * <pre>
    2360     * StringUtils.getLevenshteinDistance(null, *)             = IllegalArgumentException
    2361     * StringUtils.getLevenshteinDistance(*, null)             = IllegalArgumentException
    2362     * StringUtils.getLevenshteinDistance("", "")              = 0
    2363     * StringUtils.getLevenshteinDistance("", "a")             = 1
    2364     * StringUtils.getLevenshteinDistance("aaapppp", "")       = 7
    2365     * StringUtils.getLevenshteinDistance("frog", "fog")       = 1
    2366     * StringUtils.getLevenshteinDistance("fly", "ant")        = 3
    2367     * StringUtils.getLevenshteinDistance("elephant", "hippo") = 7
    2368     * StringUtils.getLevenshteinDistance("hippo", "elephant") = 7
    2369     * StringUtils.getLevenshteinDistance("hippo", "zzzzzzzz") = 8
    2370     * StringUtils.getLevenshteinDistance("hello", "hallo")    = 1
    2371     * </pre>
    2372     *
    2373     * @param s  the first String, must not be null
    2374     * @param t  the second String, must not be null
    2375     * @return result distance
    2376     * @throws IllegalArgumentException if either String input {@code null}
    2377     * @since 3.0 Changed signature from getLevenshteinDistance(String, String) to
    2378     * getLevenshteinDistance(CharSequence, CharSequence)
    2379     * @deprecated As of 3.6, use Apache Commons Text
    2380     * <a href="https://commons.apache.org/proper/commons-text/javadocs/api-release/org/apache/commons/text/similarity/LevenshteinDistance.html">
    2381     * LevenshteinDistance</a> instead
    2382     */
    2383    @Deprecated
    2384    public static int getLevenshteinDistance(CharSequence s, CharSequence t) {
    2385        if (s == null || t == null) {
    2386            throw new IllegalArgumentException("Strings must not be null");
    2387        }
    2388
    2389        int n = s.length();
    2390        int m = t.length();
    2391
    2392        if (n == 0) {
    2393            return m;
    2394        }
    2395        if (m == 0) {
    2396            return n;
    2397        }
    2398
    2399        if (n > m) {
    2400            // swap the input strings to consume less memory
    2401            final CharSequence tmp = s;
    2402            s = t;
    2403            t = tmp;
    2404            n = m;
    2405            m = t.length();
    2406        }
    2407
    2408        final int[] p = new int[n + 1];
    2409        // indexes into strings s and t
    2410        int i; // iterates through s
    2411        int j; // iterates through t
    2412        int upperleft;
    2413        int upper;
    2414
    2415        char jOfT; // jth character of t
    2416        int cost;
    2417
    2418        for (i = 0; i <= n; i++) {
    2419            p[i] = i;
    2420        }
    2421
    2422        for (j = 1; j <= m; j++) {
    2423            upperleft = p[0];
    2424            jOfT = t.charAt(j - 1);
    2425            p[0] = j;
    2426
    2427            for (i = 1; i <= n; i++) {
    2428                upper = p[i];
    2429                cost = s.charAt(i - 1) == jOfT ? 0 : 1;
    2430                // minimum of cell to the left+1, to the top+1, diagonally left and up +cost
    2431                p[i] = Math.min(Math.min(p[i - 1] + 1, p[i] + 1), upperleft + cost);
    2432                upperleft = upper;
    2433            }
    2434        }
    2435
    2436        return p[n];
    2437    }
    2438
    2439    /**
    2440     * Find the Levenshtein distance between two Strings if it's less than or equal to a given
    2441     * threshold.
    2442     *
    2443     * <p>This is the number of changes needed to change one String into
    2444     * another, where each change is a single character modification (deletion,
    2445     * insertion or substitution).</p>
    2446     *
    2447     * <p>This implementation follows from Algorithms on Strings, Trees and Sequences by Dan Gusfield
    2448     * and Chas Emerick's implementation of the Levenshtein distance algorithm from
    2449     * <a href="https://web.archive.org/web/20120212021906/http%3A//www.merriampark.com/ld.htm">http://www.merriampark.com/ld.htm</a></p>
    2450     *
    2451     * <pre>
    2452     * StringUtils.getLevenshteinDistance(null, *, *)             = IllegalArgumentException
    2453     * StringUtils.getLevenshteinDistance(*, null, *)             = IllegalArgumentException
    2454     * StringUtils.getLevenshteinDistance(*, *, -1)               = IllegalArgumentException
    2455     * StringUtils.getLevenshteinDistance("", "", 0)              = 0
    2456     * StringUtils.getLevenshteinDistance("aaapppp", "", 8)       = 7
    2457     * StringUtils.getLevenshteinDistance("aaapppp", "", 7)       = 7
    2458     * StringUtils.getLevenshteinDistance("aaapppp", "", 6))      = -1
    2459     * StringUtils.getLevenshteinDistance("elephant", "hippo", 7) = 7
    2460     * StringUtils.getLevenshteinDistance("elephant", "hippo", 6) = -1
    2461     * StringUtils.getLevenshteinDistance("hippo", "elephant", 7) = 7
    2462     * StringUtils.getLevenshteinDistance("hippo", "elephant", 6) = -1
    2463     * </pre>
    2464     *
    2465     * @param s  the first String, must not be null
    2466     * @param t  the second String, must not be null
    2467     * @param threshold the target threshold, must not be negative
    2468     * @return result distance, or {@code -1} if the distance would be greater than the threshold
    2469     * @throws IllegalArgumentException if either String input {@code null} or negative threshold
    2470     * @deprecated As of 3.6, use Apache Commons Text
    2471     * <a href="https://commons.apache.org/proper/commons-text/javadocs/api-release/org/apache/commons/text/similarity/LevenshteinDistance.html">
    2472     * LevenshteinDistance</a> instead
    2473     */
    2474    @Deprecated
    2475    public static int getLevenshteinDistance(CharSequence s, CharSequence t, final int threshold) {
    2476        if (s == null || t == null) {
    2477            throw new IllegalArgumentException("Strings must not be null");
    2478        }
    2479        if (threshold < 0) {
    2480            throw new IllegalArgumentException("Threshold must not be negative");
    2481        }
    2482
    2483        /*
    2484        This implementation only computes the distance if it's less than or equal to the
    2485        threshold value, returning -1 if it's greater.  The advantage is performance: unbounded
    2486        distance is O(nm), but a bound of k allows us to reduce it to O(km) time by only
    2487        computing a diagonal stripe of width 2k + 1 of the cost table.
    2488        It is also possible to use this to compute the unbounded Levenshtein distance by starting
    2489        the threshold at 1 and doubling each time until the distance is found; this is O(dm), where
    2490        d is the distance.
    2491
    2492        One subtlety comes from needing to ignore entries on the border of our stripe
    2493        eg.
    2494        p[] = |#|#|#|*
    2495        d[] =  *|#|#|#|
    2496        We must ignore the entry to the left of the leftmost member
    2497        We must ignore the entry above the rightmost member
    2498
    2499        Another subtlety comes from our stripe running off the matrix if the strings aren't
    2500        of the same size.  Since string s is always swapped to be the shorter of the two,
    2501        the stripe will always run off to the upper right instead of the lower left of the matrix.
    2502
    2503        As a concrete example, suppose s is of length 5, t is of length 7, and our threshold is 1.
    2504        In this case we're going to walk a stripe of length 3.  The matrix would look like so:
    2505
    2506           1 2 3 4 5
    2507        1 |#|#| | | |
    2508        2 |#|#|#| | |
    2509        3 | |#|#|#| |
    2510        4 | | |#|#|#|
    2511        5 | | | |#|#|
    2512        6 | | | | |#|
    2513        7 | | | | | |
    2514
    2515        Note how the stripe leads off the table as there is no possible way to turn a string of length 5
    2516        into one of length 7 in edit distance of 1.
    2517
    2518        Additionally, this implementation decreases memory usage by using two
    2519        single-dimensional arrays and swapping them back and forth instead of allocating
    2520        an entire n by m matrix.  This requires a few minor changes, such as immediately returning
    2521        when it's detected that the stripe has run off the matrix and initially filling the arrays with
    2522        large values so that entries we don't compute are ignored.
    2523
    2524        See Algorithms on Strings, Trees and Sequences by Dan Gusfield for some discussion.
    2525         */
    2526
    2527        int n = s.length(); // length of s
    2528        int m = t.length(); // length of t
    2529
    2530        // if one string is empty, the edit distance is necessarily the length of the other
    2531        if (n == 0) {
    2532            return m <= threshold ? m : -1;
    2533        }
    2534        if (m == 0) {
    2535            return n <= threshold ? n : -1;
    2536        }
    2537        if (Math.abs(n - m) > threshold) {
    2538            // no need to calculate the distance if the length difference is greater than the threshold
    2539            return -1;
    2540        }
    2541
    2542        if (n > m) {
    2543            // swap the two strings to consume less memory
    2544            final CharSequence tmp = s;
    2545            s = t;
    2546            t = tmp;
    2547            n = m;
    2548            m = t.length();
    2549        }
    2550
    2551        int[] p = new int[n + 1]; // 'previous' cost array, horizontally
    2552        int[] d = new int[n + 1]; // cost array, horizontally
    2553        int[] tmp; // placeholder to assist in swapping p and d
    2554
    2555        // fill in starting table values
    2556        final int boundary = Math.min(n, threshold) + 1;
    2557        for (int i = 0; i < boundary; i++) {
    2558            p[i] = i;
    2559        }
    2560        // these fills ensure that the value above the rightmost entry of our
    2561        // stripe will be ignored in following loop iterations
    2562        Arrays.fill(p, boundary, p.length, Integer.MAX_VALUE);
    2563        Arrays.fill(d, Integer.MAX_VALUE);
    2564
    2565        // iterates through t
    2566        for (int j = 1; j <= m; j++) {
    2567            final char jOfT = t.charAt(j - 1); // jth character of t
    2568            d[0] = j;
    2569
    2570            // compute stripe indices, constrain to array size
    2571            final int min = Math.max(1, j - threshold);
    2572            final int max = j > Integer.MAX_VALUE - threshold ? n : Math.min(n, j + threshold);
    2573
    2574            // the stripe may lead off of the table if s and t are of different sizes
    2575            if (min > max) {
    2576                return -1;
    2577            }
    2578
    2579            // ignore entry left of leftmost
    2580            if (min > 1) {
    2581                d[min - 1] = Integer.MAX_VALUE;
    2582            }
    2583
    2584            // iterates through [min, max] in s
    2585            for (int i = min; i <= max; i++) {
    2586                if (s.charAt(i - 1) == jOfT) {
    2587                    // diagonally left and up
    2588                    d[i] = p[i - 1];
    2589                } else {
    2590                    // 1 + minimum of cell to the left, to the top, diagonally left and up
    2591                    d[i] = 1 + Math.min(Math.min(d[i - 1], p[i]), p[i - 1]);
    2592                }
    2593            }
    2594
    2595            // copy current distance counts to 'previous row' distance counts
    2596            tmp = p;
    2597            p = d;
    2598            d = tmp;
    2599        }
    2600
    2601        // if p[n] is greater than the threshold, there's no guarantee on it being the correct
    2602        // distance
    2603        if (p[n] <= threshold) {
    2604            return p[n];
    2605        }
    2606        return -1;
    2607    }
    2608
    2609    /**
    2610     * Finds the first index within a CharSequence, handling {@code null}.
    2611     * This method uses {@link String#indexOf(String, int)} if possible.
    2612     *
    2613     * <p>A {@code null} CharSequence will return {@code -1}.</p>
    2614     *
    2615     * <pre>
    2616     * StringUtils.indexOf(null, *)          = -1
    2617     * StringUtils.indexOf(*, null)          = -1
    2618     * StringUtils.indexOf("", "")           = 0
    2619     * StringUtils.indexOf("", *)            = -1 (except when * = "")
    2620     * StringUtils.indexOf("aabaabaa", "a")  = 0
    2621     * StringUtils.indexOf("aabaabaa", "b")  = 2
    2622     * StringUtils.indexOf("aabaabaa", "ab") = 1
    2623     * StringUtils.indexOf("aabaabaa", "")   = 0
    2624     * </pre>
    2625     *
    2626     * @param seq  the CharSequence to check, may be null
    2627     * @param searchSeq  the CharSequence to find, may be null
    2628     * @return the first index of the search CharSequence,
    2629     *  -1 if no match or {@code null} string input
    2630     * @since 2.0
    2631     * @since 3.0 Changed signature from indexOf(String, String) to indexOf(CharSequence, CharSequence)
    2632     */
    2633    public static int indexOf(final CharSequence seq, final CharSequence searchSeq) {
    2634        if (seq == null || searchSeq == null) {
    2635            return INDEX_NOT_FOUND;
    2636        }
    2637        return CharSequenceUtils.indexOf(seq, searchSeq, 0);
    2638    }
    2639
    2640    /**
    2641     * Finds the first index within a CharSequence, handling {@code null}.
    2642     * This method uses {@link String#indexOf(String, int)} if possible.
    2643     *
    2644     * <p>A {@code null} CharSequence will return {@code -1}.
    2645     * A negative start position is treated as zero.
    2646     * An empty ("") search CharSequence always matches.
    2647     * A start position greater than the string length only matches
    2648     * an empty search CharSequence.</p>
    2649     *
    2650     * <pre>
    2651     * StringUtils.indexOf(null, *, *)          = -1
    2652     * StringUtils.indexOf(*, null, *)          = -1
    2653     * StringUtils.indexOf("", "", 0)           = 0
    2654     * StringUtils.indexOf("", *, 0)            = -1 (except when * = "")
    2655     * StringUtils.indexOf("aabaabaa", "a", 0)  = 0
    2656     * StringUtils.indexOf("aabaabaa", "b", 0)  = 2
    2657     * StringUtils.indexOf("aabaabaa", "ab", 0) = 1
    2658     * StringUtils.indexOf("aabaabaa", "b", 3)  = 5
    2659     * StringUtils.indexOf("aabaabaa", "b", 9)  = -1
    2660     * StringUtils.indexOf("aabaabaa", "b", -1) = 2
    2661     * StringUtils.indexOf("aabaabaa", "", 2)   = 2
    2662     * StringUtils.indexOf("abc", "", 9)        = 3
    2663     * </pre>
    2664     *
    2665     * @param seq  the CharSequence to check, may be null
    2666     * @param searchSeq  the CharSequence to find, may be null
    2667     * @param startPos  the start position, negative treated as zero
    2668     * @return the first index of the search CharSequence (always &ge; startPos),
    2669     *  -1 if no match or {@code null} string input
    2670     * @since 2.0
    2671     * @since 3.0 Changed signature from indexOf(String, String, int) to indexOf(CharSequence, CharSequence, int)
    2672     */
    2673    public static int indexOf(final CharSequence seq, final CharSequence searchSeq, final int startPos) {
    2674        if (seq == null || searchSeq == null) {
    2675            return INDEX_NOT_FOUND;
    2676        }
    2677        return CharSequenceUtils.indexOf(seq, searchSeq, startPos);
    2678    }
    2679
    2680    /**
    2681     * Returns the index within {@code seq} of the first occurrence of
    2682     * the specified character. If a character with value
    2683     * {@code searchChar} occurs in the character sequence represented by
    2684     * {@code seq} {@link CharSequence} object, then the index (in Unicode
    2685     * code units) of the first such occurrence is returned. For
    2686     * values of {@code searchChar} in the range from 0 to 0xFFFF
    2687     * (inclusive), this is the smallest value <em>k</em> such that:
    2688     * <blockquote><pre>
    2689     * this.charAt(<em>k</em>) == searchChar
    2690     * </pre></blockquote>
    2691     * is true. For other values of {@code searchChar}, it is the
    2692     * smallest value <em>k</em> such that:
    2693     * <blockquote><pre>
    2694     * this.codePointAt(<em>k</em>) == searchChar
    2695     * </pre></blockquote>
    2696     * is true. In either case, if no such character occurs in {@code seq},
    2697     * then {@code INDEX_NOT_FOUND (-1)} is returned.
    2698     *
    2699     * <p>Furthermore, a {@code null} or empty ("") CharSequence will
    2700     * return {@code INDEX_NOT_FOUND (-1)}.</p>
    2701     *
    2702     * <pre>
    2703     * StringUtils.indexOf(null, *)         = -1
    2704     * StringUtils.indexOf("", *)           = -1
    2705     * StringUtils.indexOf("aabaabaa", 'a') = 0
    2706     * StringUtils.indexOf("aabaabaa", 'b') = 2
    2707     * </pre>
    2708     *
    2709     * @param seq  the CharSequence to check, may be null
    2710     * @param searchChar  the character to find
    2711     * @return the first index of the search character,
    2712     *  -1 if no match or {@code null} string input
    2713     * @since 2.0
    2714     * @since 3.0 Changed signature from indexOf(String, int) to indexOf(CharSequence, int)
    2715     * @since 3.6 Updated {@link CharSequenceUtils} call to behave more like {@link String}
    2716     */
    2717    public static int indexOf(final CharSequence seq, final int searchChar) {
    2718        if (isEmpty(seq)) {
    2719            return INDEX_NOT_FOUND;
    2720        }
    2721        return CharSequenceUtils.indexOf(seq, searchChar, 0);
    2722    }
    2723
    2724    /**
    2725     * Returns the index within {@code seq} of the first occurrence of the
    2726     * specified character, starting the search at the specified index.
    2727     * <p>
    2728     * If a character with value {@code searchChar} occurs in the
    2729     * character sequence represented by the {@code seq} {@link CharSequence}
    2730     * object at an index no smaller than {@code startPos}, then
    2731     * the index of the first such occurrence is returned. For values
    2732     * of {@code searchChar} in the range from 0 to 0xFFFF (inclusive),
    2733     * this is the smallest value <em>k</em> such that:
    2734     * <blockquote><pre>
    2735     * (this.charAt(<em>k</em>) == searchChar) &amp;&amp; (<em>k</em> &gt;= startPos)
    2736     * </pre></blockquote>
    2737     * is true. For other values of {@code searchChar}, it is the
    2738     * smallest value <em>k</em> such that:
    2739     * <blockquote><pre>
    2740     * (this.codePointAt(<em>k</em>) == searchChar) &amp;&amp; (<em>k</em> &gt;= startPos)
    2741     * </pre></blockquote>
    2742     * is true. In either case, if no such character occurs in {@code seq}
    2743     * at or after position {@code startPos}, then
    2744     * {@code -1} is returned.
    2745     *
    2746     * <p>
    2747     * There is no restriction on the value of {@code startPos}. If it
    2748     * is negative, it has the same effect as if it were zero: this entire
    2749     * string may be searched. If it is greater than the length of this
    2750     * string, it has the same effect as if it were equal to the length of
    2751     * this string: {@code (INDEX_NOT_FOUND) -1} is returned. Furthermore, a
    2752     * {@code null} or empty ("") CharSequence will
    2753     * return {@code (INDEX_NOT_FOUND) -1}.
    2754     *
    2755     * <p>All indices are specified in {@code char} values
    2756     * (Unicode code units).
    2757     *
    2758     * <pre>
    2759     * StringUtils.indexOf(null, *, *)          = -1
    2760     * StringUtils.indexOf("", *, *)            = -1
    2761     * StringUtils.indexOf("aabaabaa", 'b', 0)  = 2
    2762     * StringUtils.indexOf("aabaabaa", 'b', 3)  = 5
    2763     * StringUtils.indexOf("aabaabaa", 'b', 9)  = -1
    2764     * StringUtils.indexOf("aabaabaa", 'b', -1) = 2
    2765     * </pre>
    2766     *
    2767     * @param seq  the CharSequence to check, may be null
    2768     * @param searchChar  the character to find
    2769     * @param startPos  the start position, negative treated as zero
    2770     * @return the first index of the search character (always &ge; startPos),
    2771     *  -1 if no match or {@code null} string input
    2772     * @since 2.0
    2773     * @since 3.0 Changed signature from indexOf(String, int, int) to indexOf(CharSequence, int, int)
    2774     * @since 3.6 Updated {@link CharSequenceUtils} call to behave more like {@link String}
    2775     */
    2776    public static int indexOf(final CharSequence seq, final int searchChar, final int startPos) {
    2777        if (isEmpty(seq)) {
    2778            return INDEX_NOT_FOUND;
    2779        }
    2780        return CharSequenceUtils.indexOf(seq, searchChar, startPos);
    2781    }
    2782
    2783    /**
    2784     * Search a CharSequence to find the first index of any
    2785     * character in the given set of characters.
    2786     *
    2787     * <p>A {@code null} String will return {@code -1}.
    2788     * A {@code null} or zero length search array will return {@code -1}.</p>
    2789     *
    2790     * <pre>
    2791     * StringUtils.indexOfAny(null, *)                  = -1
    2792     * StringUtils.indexOfAny("", *)                    = -1
    2793     * StringUtils.indexOfAny(*, null)                  = -1
    2794     * StringUtils.indexOfAny(*, [])                    = -1
    2795     * StringUtils.indexOfAny("zzabyycdxx", ['z', 'a']) = 0
    2796     * StringUtils.indexOfAny("zzabyycdxx", ['b', 'y']) = 3
    2797     * StringUtils.indexOfAny("aba", ['z'])             = -1
    2798     * </pre>
    2799     *
    2800     * @param cs  the CharSequence to check, may be null
    2801     * @param searchChars  the chars to search for, may be null
    2802     * @return the index of any of the chars, -1 if no match or null input
    2803     * @since 2.0
    2804     * @since 3.0 Changed signature from indexOfAny(String, char[]) to indexOfAny(CharSequence, char...)
    2805     */
    2806    public static int indexOfAny(final CharSequence cs, final char... searchChars) {
    2807        if (isEmpty(cs) || ArrayUtils.isEmpty(searchChars)) {
    2808            return INDEX_NOT_FOUND;
    2809        }
    2810        final int csLen = cs.length();
    2811        final int csLast = csLen - 1;
    2812        final int searchLen = searchChars.length;
    2813        final int searchLast = searchLen - 1;
    2814        for (int i = 0; i < csLen; i++) {
    2815            final char ch = cs.charAt(i);
    2816            for (int j = 0; j < searchLen; j++) {
    2817                if (searchChars[j] == ch) {
    2818                    if (i >= csLast || j >= searchLast || !Character.isHighSurrogate(ch)) {
    2819                        return i;
    2820                    }
    2821                    // ch is a supplementary character
    2822                    if (searchChars[j + 1] == cs.charAt(i + 1)) {
    2823                        return i;
    2824                    }
    2825                }
    2826            }
    2827        }
    2828        return INDEX_NOT_FOUND;
    2829    }
    2830
    2831    /**
    2832     * Find the first index of any of a set of potential substrings.
    2833     *
    2834     * <p>A {@code null} CharSequence will return {@code -1}.
    2835     * A {@code null} or zero length search array will return {@code -1}.
    2836     * A {@code null} search array entry will be ignored, but a search
    2837     * array containing "" will return {@code 0} if {@code str} is not
    2838     * null. This method uses {@link String#indexOf(String)} if possible.</p>
    2839     *
    2840     * <pre>
    2841     * StringUtils.indexOfAny(null, *)                      = -1
    2842     * StringUtils.indexOfAny(*, null)                      = -1
    2843     * StringUtils.indexOfAny(*, [])                        = -1
    2844     * StringUtils.indexOfAny("zzabyycdxx", ["ab", "cd"])   = 2
    2845     * StringUtils.indexOfAny("zzabyycdxx", ["cd", "ab"])   = 2
    2846     * StringUtils.indexOfAny("zzabyycdxx", ["mn", "op"])   = -1
    2847     * StringUtils.indexOfAny("zzabyycdxx", ["zab", "aby"]) = 1
    2848     * StringUtils.indexOfAny("zzabyycdxx", [""])           = 0
    2849     * StringUtils.indexOfAny("", [""])                     = 0
    2850     * StringUtils.indexOfAny("", ["a"])                    = -1
    2851     * </pre>
    2852     *
    2853     * @param str  the CharSequence to check, may be null
    2854     * @param searchStrs  the CharSequences to search for, may be null
    2855     * @return the first index of any of the searchStrs in str, -1 if no match
    2856     * @since 3.0 Changed signature from indexOfAny(String, String[]) to indexOfAny(CharSequence, CharSequence...)
    2857     */
    2858    public static int indexOfAny(final CharSequence str, final CharSequence... searchStrs) {
    2859        if (str == null || searchStrs == null) {
    2860            return INDEX_NOT_FOUND;
    2861        }
    2862
    2863        // String's can't have a MAX_VALUEth index.
    2864        int ret = Integer.MAX_VALUE;
    2865
    2866        int tmp;
    2867        for (final CharSequence search : searchStrs) {
    2868            if (search == null) {
    2869                continue;
    2870            }
    2871            tmp = CharSequenceUtils.indexOf(str, search, 0);
    2872            if (tmp == INDEX_NOT_FOUND) {
    2873                continue;
    2874            }
    2875
    2876            if (tmp < ret) {
    2877                ret = tmp;
    2878            }
    2879        }
    2880
    2881        return ret == Integer.MAX_VALUE ? INDEX_NOT_FOUND : ret;
    2882    }
    2883
    2884    /**
    2885     * Search a CharSequence to find the first index of any
    2886     * character in the given set of characters.
    2887     *
    2888     * <p>A {@code null} String will return {@code -1}.
    2889     * A {@code null} search string will return {@code -1}.</p>
    2890     *
    2891     * <pre>
    2892     * StringUtils.indexOfAny(null, *)            = -1
    2893     * StringUtils.indexOfAny("", *)              = -1
    2894     * StringUtils.indexOfAny(*, null)            = -1
    2895     * StringUtils.indexOfAny(*, "")              = -1
    2896     * StringUtils.indexOfAny("zzabyycdxx", "za") = 0
    2897     * StringUtils.indexOfAny("zzabyycdxx", "by") = 3
    2898     * StringUtils.indexOfAny("aba", "z")         = -1
    2899     * </pre>
    2900     *
    2901     * @param cs  the CharSequence to check, may be null
    2902     * @param searchChars  the chars to search for, may be null
    2903     * @return the index of any of the chars, -1 if no match or null input
    2904     * @since 2.0
    2905     * @since 3.0 Changed signature from indexOfAny(String, String) to indexOfAny(CharSequence, String)
    2906     */
    2907    public static int indexOfAny(final CharSequence cs, final String searchChars) {
    2908        if (isEmpty(cs) || isEmpty(searchChars)) {
    2909            return INDEX_NOT_FOUND;
    2910        }
    2911        return indexOfAny(cs, searchChars.toCharArray());
    2912    }
    2913
    2914    /**
    2915     * Searches a CharSequence to find the first index of any
    2916     * character not in the given set of characters.
    2917     *
    2918     * <p>A {@code null} CharSequence will return {@code -1}.
    2919     * A {@code null} or zero length search array will return {@code -1}.</p>
    2920     *
    2921     * <pre>
    2922     * StringUtils.indexOfAnyBut(null, *)                              = -1
    2923     * StringUtils.indexOfAnyBut("", *)                                = -1
    2924     * StringUtils.indexOfAnyBut(*, null)                              = -1
    2925     * StringUtils.indexOfAnyBut(*, [])                                = -1
    2926     * StringUtils.indexOfAnyBut("zzabyycdxx", new char[] {'z', 'a'} ) = 3
    2927     * StringUtils.indexOfAnyBut("aba", new char[] {'z'} )             = 0
    2928     * StringUtils.indexOfAnyBut("aba", new char[] {'a', 'b'} )        = -1
    2929
    2930     * </pre>
    2931     *
    2932     * @param cs  the CharSequence to check, may be null
    2933     * @param searchChars  the chars to search for, may be null
    2934     * @return the index of any of the chars, -1 if no match or null input
    2935     * @since 2.0
    2936     * @since 3.0 Changed signature from indexOfAnyBut(String, char[]) to indexOfAnyBut(CharSequence, char...)
    2937     */
    2938    public static int indexOfAnyBut(final CharSequence cs, final char... searchChars) {
    2939        if (isEmpty(cs) || ArrayUtils.isEmpty(searchChars)) {
    2940            return INDEX_NOT_FOUND;
    2941        }
    2942        final int csLen = cs.length();
    2943        final int csLast = csLen - 1;
    2944        final int searchLen = searchChars.length;
    2945        final int searchLast = searchLen - 1;
    2946        outer:
    2947        for (int i = 0; i < csLen; i++) {
    2948            final char ch = cs.charAt(i);
    2949            for (int j = 0; j < searchLen; j++) {
    2950                if (searchChars[j] == ch) {
    2951                    if (i >= csLast || j >= searchLast || !Character.isHighSurrogate(ch)) {
    2952                        continue outer;
    2953                    }
    2954                    if (searchChars[j + 1] == cs.charAt(i + 1)) {
    2955                        continue outer;
    2956                    }
    2957                }
    2958            }
    2959            return i;
    2960        }
    2961        return INDEX_NOT_FOUND;
    2962    }
    2963
    2964    /**
    2965     * Search a CharSequence to find the first index of any
    2966     * character not in the given set of characters.
    2967     *
    2968     * <p>A {@code null} CharSequence will return {@code -1}.
    2969     * A {@code null} or empty search string will return {@code -1}.</p>
    2970     *
    2971     * <pre>
    2972     * StringUtils.indexOfAnyBut(null, *)            = -1
    2973     * StringUtils.indexOfAnyBut("", *)              = -1
    2974     * StringUtils.indexOfAnyBut(*, null)            = -1
    2975     * StringUtils.indexOfAnyBut(*, "")              = -1
    2976     * StringUtils.indexOfAnyBut("zzabyycdxx", "za") = 3
    2977     * StringUtils.indexOfAnyBut("zzabyycdxx", "")   = -1
    2978     * StringUtils.indexOfAnyBut("aba", "ab")        = -1
    2979     * </pre>
    2980     *
    2981     * @param seq  the CharSequence to check, may be null
    2982     * @param searchChars  the chars to search for, may be null
    2983     * @return the index of any of the chars, -1 if no match or null input
    2984     * @since 2.0
    2985     * @since 3.0 Changed signature from indexOfAnyBut(String, String) to indexOfAnyBut(CharSequence, CharSequence)
    2986     */
    2987    public static int indexOfAnyBut(final CharSequence seq, final CharSequence searchChars) {
    2988        if (isEmpty(seq) || isEmpty(searchChars)) {
    2989            return INDEX_NOT_FOUND;
    2990        }
    2991        final int strLen = seq.length();
    2992        for (int i = 0; i < strLen; i++) {
    2993            final char ch = seq.charAt(i);
    2994            final boolean chFound = CharSequenceUtils.indexOf(searchChars, ch, 0) >= 0;
    2995            if (i + 1 < strLen && Character.isHighSurrogate(ch)) {
    2996                final char ch2 = seq.charAt(i + 1);
    2997                if (chFound && CharSequenceUtils.indexOf(searchChars, ch2, 0) < 0) {
    2998                    return i;
    2999                }
    3000            } else if (!chFound) {
    3001                return i;
    3002            }
    3003        }
    3004        return INDEX_NOT_FOUND;
    3005    }
    3006
    3007    /**
    3008     * Compares all CharSequences in an array and returns the index at which the
    3009     * CharSequences begin to differ.
    3010     *
    3011     * <p>For example,
    3012     * {@code indexOfDifference(new String[] {"i am a machine", "i am a robot"}) -> 7}</p>
    3013     *
    3014     * <pre>
    3015     * StringUtils.indexOfDifference(null)                             = -1
    3016     * StringUtils.indexOfDifference(new String[] {})                  = -1
    3017     * StringUtils.indexOfDifference(new String[] {"abc"})             = -1
    3018     * StringUtils.indexOfDifference(new String[] {null, null})        = -1
    3019     * StringUtils.indexOfDifference(new String[] {"", ""})            = -1
    3020     * StringUtils.indexOfDifference(new String[] {"", null})          = 0
    3021     * StringUtils.indexOfDifference(new String[] {"abc", null, null}) = 0
    3022     * StringUtils.indexOfDifference(new String[] {null, null, "abc"}) = 0
    3023     * StringUtils.indexOfDifference(new String[] {"", "abc"})         = 0
    3024     * StringUtils.indexOfDifference(new String[] {"abc", ""})         = 0
    3025     * StringUtils.indexOfDifference(new String[] {"abc", "abc"})      = -1
    3026     * StringUtils.indexOfDifference(new String[] {"abc", "a"})        = 1
    3027     * StringUtils.indexOfDifference(new String[] {"ab", "abxyz"})     = 2
    3028     * StringUtils.indexOfDifference(new String[] {"abcde", "abxyz"})  = 2
    3029     * StringUtils.indexOfDifference(new String[] {"abcde", "xyz"})    = 0
    3030     * StringUtils.indexOfDifference(new String[] {"xyz", "abcde"})    = 0
    3031     * StringUtils.indexOfDifference(new String[] {"i am a machine", "i am a robot"}) = 7
    3032     * </pre>
    3033     *
    3034     * @param css  array of CharSequences, entries may be null
    3035     * @return the index where the strings begin to differ; -1 if they are all equal
    3036     * @since 2.4
    3037     * @since 3.0 Changed signature from indexOfDifference(String...) to indexOfDifference(CharSequence...)
    3038     */
    3039    public static int indexOfDifference(final CharSequence... css) {
    3040        if (ArrayUtils.getLength(css) <= 1) {
    3041            return INDEX_NOT_FOUND;
    3042        }
    3043        boolean anyStringNull = false;
    3044        boolean allStringsNull = true;
    3045        final int arrayLen = css.length;
    3046        int shortestStrLen = Integer.MAX_VALUE;
    3047        int longestStrLen = 0;
    3048
    3049        // find the min and max string lengths; this avoids checking to make
    3050        // sure we are not exceeding the length of the string each time through
    3051        // the bottom loop.
    3052        for (final CharSequence cs : css) {
    3053            if (cs == null) {
    3054                anyStringNull = true;
    3055                shortestStrLen = 0;
    3056            } else {
    3057                allStringsNull = false;
    3058                shortestStrLen = Math.min(cs.length(), shortestStrLen);
    3059                longestStrLen = Math.max(cs.length(), longestStrLen);
    3060            }
    3061        }
    3062
    3063        // handle lists containing all nulls or all empty strings
    3064        if (allStringsNull || longestStrLen == 0 && !anyStringNull) {
    3065            return INDEX_NOT_FOUND;
    3066        }
    3067
    3068        // handle lists containing some nulls or some empty strings
    3069        if (shortestStrLen == 0) {
    3070            return 0;
    3071        }
    3072
    3073        // find the position with the first difference across all strings
    3074        int firstDiff = -1;
    3075        for (int stringPos = 0; stringPos < shortestStrLen; stringPos++) {
    3076            final char comparisonChar = css[0].charAt(stringPos);
    3077            for (int arrayPos = 1; arrayPos < arrayLen; arrayPos++) {
    3078                if (css[arrayPos].charAt(stringPos) != comparisonChar) {
    3079                    firstDiff = stringPos;
    3080                    break;
    3081                }
    3082            }
    3083            if (firstDiff != -1) {
    3084                break;
    3085            }
    3086        }
    3087
    3088        if (firstDiff == -1 && shortestStrLen != longestStrLen) {
    3089            // we compared all of the characters up to the length of the
    3090            // shortest string and didn't find a match, but the string lengths
    3091            // vary, so return the length of the shortest string.
    3092            return shortestStrLen;
    3093        }
    3094        return firstDiff;
    3095    }
    3096
    3097    /**
    3098     * Compares two CharSequences, and returns the index at which the
    3099     * CharSequences begin to differ.
    3100     *
    3101     * <p>For example,
    3102     * {@code indexOfDifference("i am a machine", "i am a robot") -> 7}</p>
    3103     *
    3104     * <pre>
    3105     * StringUtils.indexOfDifference(null, null)       = -1
    3106     * StringUtils.indexOfDifference("", "")           = -1
    3107     * StringUtils.indexOfDifference("", "abc")        = 0
    3108     * StringUtils.indexOfDifference("abc", "")        = 0
    3109     * StringUtils.indexOfDifference("abc", "abc")     = -1
    3110     * StringUtils.indexOfDifference("ab", "abxyz")    = 2
    3111     * StringUtils.indexOfDifference("abcde", "abxyz") = 2
    3112     * StringUtils.indexOfDifference("abcde", "xyz")   = 0
    3113     * </pre>
    3114     *
    3115     * @param cs1  the first CharSequence, may be null
    3116     * @param cs2  the second CharSequence, may be null
    3117     * @return the index where cs1 and cs2 begin to differ; -1 if they are equal
    3118     * @since 2.0
    3119     * @since 3.0 Changed signature from indexOfDifference(String, String) to
    3120     * indexOfDifference(CharSequence, CharSequence)
    3121     */
    3122    public static int indexOfDifference(final CharSequence cs1, final CharSequence cs2) {
    3123        if (cs1 == cs2) {
    3124            return INDEX_NOT_FOUND;
    3125        }
    3126        if (cs1 == null || cs2 == null) {
    3127            return 0;
    3128        }
    3129        int i;
    3130        for (i = 0; i < cs1.length() && i < cs2.length(); ++i) {
    3131            if (cs1.charAt(i) != cs2.charAt(i)) {
    3132                break;
    3133            }
    3134        }
    3135        if (i < cs2.length() || i < cs1.length()) {
    3136            return i;
    3137        }
    3138        return INDEX_NOT_FOUND;
    3139    }
    3140
    3141    /**
    3142     * Case in-sensitive find of the first index within a CharSequence.
    3143     *
    3144     * <p>A {@code null} CharSequence will return {@code -1}.
    3145     * A negative start position is treated as zero.
    3146     * An empty ("") search CharSequence always matches.
    3147     * A start position greater than the string length only matches
    3148     * an empty search CharSequence.</p>
    3149     *
    3150     * <pre>
    3151     * StringUtils.indexOfIgnoreCase(null, *)          = -1
    3152     * StringUtils.indexOfIgnoreCase(*, null)          = -1
    3153     * StringUtils.indexOfIgnoreCase("", "")           = 0
    3154     * StringUtils.indexOfIgnoreCase(" ", " ")         = 0
    3155     * StringUtils.indexOfIgnoreCase("aabaabaa", "a")  = 0
    3156     * StringUtils.indexOfIgnoreCase("aabaabaa", "b")  = 2
    3157     * StringUtils.indexOfIgnoreCase("aabaabaa", "ab") = 1
    3158     * </pre>
    3159     *
    3160     * @param str  the CharSequence to check, may be null
    3161     * @param searchStr  the CharSequence to find, may be null
    3162     * @return the first index of the search CharSequence,
    3163     *  -1 if no match or {@code null} string input
    3164     * @since 2.5
    3165     * @since 3.0 Changed signature from indexOfIgnoreCase(String, String) to indexOfIgnoreCase(CharSequence, CharSequence)
    3166     */
    3167    public static int indexOfIgnoreCase(final CharSequence str, final CharSequence searchStr) {
    3168        return indexOfIgnoreCase(str, searchStr, 0);
    3169    }
    3170
    3171    /**
    3172     * Case in-sensitive find of the first index within a CharSequence
    3173     * from the specified position.
    3174     *
    3175     * <p>A {@code null} CharSequence will return {@code -1}.
    3176     * A negative start position is treated as zero.
    3177     * An empty ("") search CharSequence always matches.
    3178     * A start position greater than the string length only matches
    3179     * an empty search CharSequence.</p>
    3180     *
    3181     * <pre>
    3182     * StringUtils.indexOfIgnoreCase(null, *, *)          = -1
    3183     * StringUtils.indexOfIgnoreCase(*, null, *)          = -1
    3184     * StringUtils.indexOfIgnoreCase("", "", 0)           = 0
    3185     * StringUtils.indexOfIgnoreCase("aabaabaa", "A", 0)  = 0
    3186     * StringUtils.indexOfIgnoreCase("aabaabaa", "B", 0)  = 2
    3187     * StringUtils.indexOfIgnoreCase("aabaabaa", "AB", 0) = 1
    3188     * StringUtils.indexOfIgnoreCase("aabaabaa", "B", 3)  = 5
    3189     * StringUtils.indexOfIgnoreCase("aabaabaa", "B", 9)  = -1
    3190     * StringUtils.indexOfIgnoreCase("aabaabaa", "B", -1) = 2
    3191     * StringUtils.indexOfIgnoreCase("aabaabaa", "", 2)   = 2
    3192     * StringUtils.indexOfIgnoreCase("abc", "", 9)        = -1
    3193     * </pre>
    3194     *
    3195     * @param str  the CharSequence to check, may be null
    3196     * @param searchStr  the CharSequence to find, may be null
    3197     * @param startPos  the start position, negative treated as zero
    3198     * @return the first index of the search CharSequence (always &ge; startPos),
    3199     *  -1 if no match or {@code null} string input
    3200     * @since 2.5
    3201     * @since 3.0 Changed signature from indexOfIgnoreCase(String, String, int) to indexOfIgnoreCase(CharSequence, CharSequence, int)
    3202     */
    3203    public static int indexOfIgnoreCase(final CharSequence str, final CharSequence searchStr, int startPos) {
    3204        if (str == null || searchStr == null) {
    3205            return INDEX_NOT_FOUND;
    3206        }
    3207        if (startPos < 0) {
    3208            startPos = 0;
    3209        }
    3210        final int endLimit = str.length() - searchStr.length() + 1;
    3211        if (startPos > endLimit) {
    3212            return INDEX_NOT_FOUND;
    3213        }
    3214        if (searchStr.length() == 0) {
    3215            return startPos;
    3216        }
    3217        for (int i = startPos; i < endLimit; i++) {
    3218            if (CharSequenceUtils.regionMatches(str, true, i, searchStr, 0, searchStr.length())) {
    3219                return i;
    3220            }
    3221        }
    3222        return INDEX_NOT_FOUND;
    3223    }
    3224
    3225    /**
    3226     * Checks if all of the CharSequences are empty (""), null or whitespace only.
    3227     *
    3228     * <p>Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
    3229     *
    3230     * <pre>
    3231     * StringUtils.isAllBlank(null)             = true
    3232     * StringUtils.isAllBlank(null, "foo")      = false
    3233     * StringUtils.isAllBlank(null, null)       = true
    3234     * StringUtils.isAllBlank("", "bar")        = false
    3235     * StringUtils.isAllBlank("bob", "")        = false
    3236     * StringUtils.isAllBlank("  bob  ", null)  = false
    3237     * StringUtils.isAllBlank(" ", "bar")       = false
    3238     * StringUtils.isAllBlank("foo", "bar")     = false
    3239     * StringUtils.isAllBlank(new String[] {})  = true
    3240     * </pre>
    3241     *
    3242     * @param css  the CharSequences to check, may be null or empty
    3243     * @return {@code true} if all of the CharSequences are empty or null or whitespace only
    3244     * @since 3.6
    3245     */
    3246    public static boolean isAllBlank(final CharSequence... css) {
    3247        if (ArrayUtils.isEmpty(css)) {
    3248            return true;
    3249        }
    3250        for (final CharSequence cs : css) {
    3251            if (isNotBlank(cs)) {
    3252               return false;
    3253            }
    3254        }
    3255        return true;
    3256    }
    3257
    3258    /**
    3259     * Checks if all of the CharSequences are empty ("") or null.
    3260     *
    3261     * <pre>
    3262     * StringUtils.isAllEmpty(null)             = true
    3263     * StringUtils.isAllEmpty(null, "")         = true
    3264     * StringUtils.isAllEmpty(new String[] {})  = true
    3265     * StringUtils.isAllEmpty(null, "foo")      = false
    3266     * StringUtils.isAllEmpty("", "bar")        = false
    3267     * StringUtils.isAllEmpty("bob", "")        = false
    3268     * StringUtils.isAllEmpty("  bob  ", null)  = false
    3269     * StringUtils.isAllEmpty(" ", "bar")       = false
    3270     * StringUtils.isAllEmpty("foo", "bar")     = false
    3271     * </pre>
    3272     *
    3273     * @param css  the CharSequences to check, may be null or empty
    3274     * @return {@code true} if all of the CharSequences are empty or null
    3275     * @since 3.6
    3276     */
    3277    public static boolean isAllEmpty(final CharSequence... css) {
    3278        if (ArrayUtils.isEmpty(css)) {
    3279            return true;
    3280        }
    3281        for (final CharSequence cs : css) {
    3282            if (isNotEmpty(cs)) {
    3283                return false;
    3284            }
    3285        }
    3286        return true;
    3287    }
    3288
    3289    /**
    3290     * Checks if the CharSequence contains only lowercase characters.
    3291     *
    3292     * <p>{@code null} will return {@code false}.
    3293     * An empty CharSequence (length()=0) will return {@code false}.</p>
    3294     *
    3295     * <pre>
    3296     * StringUtils.isAllLowerCase(null)   = false
    3297     * StringUtils.isAllLowerCase("")     = false
    3298     * StringUtils.isAllLowerCase("  ")   = false
    3299     * StringUtils.isAllLowerCase("abc")  = true
    3300     * StringUtils.isAllLowerCase("abC")  = false
    3301     * StringUtils.isAllLowerCase("ab c") = false
    3302     * StringUtils.isAllLowerCase("ab1c") = false
    3303     * StringUtils.isAllLowerCase("ab/c") = false
    3304     * </pre>
    3305     *
    3306     * @param cs  the CharSequence to check, may be null
    3307     * @return {@code true} if only contains lowercase characters, and is non-null
    3308     * @since 2.5
    3309     * @since 3.0 Changed signature from isAllLowerCase(String) to isAllLowerCase(CharSequence)
    3310     */
    3311    public static boolean isAllLowerCase(final CharSequence cs) {
    3312        if (isEmpty(cs)) {
    3313            return false;
    3314        }
    3315        final int sz = cs.length();
    3316        for (int i = 0; i < sz; i++) {
    3317            if (!Character.isLowerCase(cs.charAt(i))) {
    3318                return false;
    3319            }
    3320        }
    3321        return true;
    3322    }
    3323
    3324    /**
    3325     * Checks if the CharSequence contains only uppercase characters.
    3326     *
    3327     * <p>{@code null} will return {@code false}.
    3328     * An empty String (length()=0) will return {@code false}.</p>
    3329     *
    3330     * <pre>
    3331     * StringUtils.isAllUpperCase(null)   = false
    3332     * StringUtils.isAllUpperCase("")     = false
    3333     * StringUtils.isAllUpperCase("  ")   = false
    3334     * StringUtils.isAllUpperCase("ABC")  = true
    3335     * StringUtils.isAllUpperCase("aBC")  = false
    3336     * StringUtils.isAllUpperCase("A C")  = false
    3337     * StringUtils.isAllUpperCase("A1C")  = false
    3338     * StringUtils.isAllUpperCase("A/C")  = false
    3339     * </pre>
    3340     *
    3341     * @param cs the CharSequence to check, may be null
    3342     * @return {@code true} if only contains uppercase characters, and is non-null
    3343     * @since 2.5
    3344     * @since 3.0 Changed signature from isAllUpperCase(String) to isAllUpperCase(CharSequence)
    3345     */
    3346    public static boolean isAllUpperCase(final CharSequence cs) {
    3347        if (isEmpty(cs)) {
    3348            return false;
    3349        }
    3350        final int sz = cs.length();
    3351        for (int i = 0; i < sz; i++) {
    3352            if (!Character.isUpperCase(cs.charAt(i))) {
    3353                return false;
    3354            }
    3355        }
    3356        return true;
    3357    }
    3358
    3359    /**
    3360     * Checks if the CharSequence contains only Unicode letters.
    3361     *
    3362     * <p>{@code null} will return {@code false}.
    3363     * An empty CharSequence (length()=0) will return {@code false}.</p>
    3364     *
    3365     * <pre>
    3366     * StringUtils.isAlpha(null)   = false
    3367     * StringUtils.isAlpha("")     = false
    3368     * StringUtils.isAlpha("  ")   = false
    3369     * StringUtils.isAlpha("abc")  = true
    3370     * StringUtils.isAlpha("ab2c") = false
    3371     * StringUtils.isAlpha("ab-c") = false
    3372     * </pre>
    3373     *
    3374     * @param cs  the CharSequence to check, may be null
    3375     * @return {@code true} if only contains letters, and is non-null
    3376     * @since 3.0 Changed signature from isAlpha(String) to isAlpha(CharSequence)
    3377     * @since 3.0 Changed "" to return false and not true
    3378     */
    3379    public static boolean isAlpha(final CharSequence cs) {
    3380        if (isEmpty(cs)) {
    3381            return false;
    3382        }
    3383        final int sz = cs.length();
    3384        for (int i = 0; i < sz; i++) {
    3385            if (!Character.isLetter(cs.charAt(i))) {
    3386                return false;
    3387            }
    3388        }
    3389        return true;
    3390    }
    3391
    3392    /**
    3393     * Checks if the CharSequence contains only Unicode letters or digits.
    3394     *
    3395     * <p>{@code null} will return {@code false}.
    3396     * An empty CharSequence (length()=0) will return {@code false}.</p>
    3397     *
    3398     * <pre>
    3399     * StringUtils.isAlphanumeric(null)   = false
    3400     * StringUtils.isAlphanumeric("")     = false
    3401     * StringUtils.isAlphanumeric("  ")   = false
    3402     * StringUtils.isAlphanumeric("abc")  = true
    3403     * StringUtils.isAlphanumeric("ab c") = false
    3404     * StringUtils.isAlphanumeric("ab2c") = true
    3405     * StringUtils.isAlphanumeric("ab-c") = false
    3406     * </pre>
    3407     *
    3408     * @param cs  the CharSequence to check, may be null
    3409     * @return {@code true} if only contains letters or digits,
    3410     *  and is non-null
    3411     * @since 3.0 Changed signature from isAlphanumeric(String) to isAlphanumeric(CharSequence)
    3412     * @since 3.0 Changed "" to return false and not true
    3413     */
    3414    public static boolean isAlphanumeric(final CharSequence cs) {
    3415        if (isEmpty(cs)) {
    3416            return false;
    3417        }
    3418        final int sz = cs.length();
    3419        for (int i = 0; i < sz; i++) {
    3420            if (!Character.isLetterOrDigit(cs.charAt(i))) {
    3421                return false;
    3422            }
    3423        }
    3424        return true;
    3425    }
    3426
    3427    /**
    3428     * Checks if the CharSequence contains only Unicode letters, digits
    3429     * or space ({@code ' '}).
    3430     *
    3431     * <p>{@code null} will return {@code false}.
    3432     * An empty CharSequence (length()=0) will return {@code true}.</p>
    3433     *
    3434     * <pre>
    3435     * StringUtils.isAlphanumericSpace(null)   = false
    3436     * StringUtils.isAlphanumericSpace("")     = true
    3437     * StringUtils.isAlphanumericSpace("  ")   = true
    3438     * StringUtils.isAlphanumericSpace("abc")  = true
    3439     * StringUtils.isAlphanumericSpace("ab c") = true
    3440     * StringUtils.isAlphanumericSpace("ab2c") = true
    3441     * StringUtils.isAlphanumericSpace("ab-c") = false
    3442     * </pre>
    3443     *
    3444     * @param cs  the CharSequence to check, may be null
    3445     * @return {@code true} if only contains letters, digits or space,
    3446     *  and is non-null
    3447     * @since 3.0 Changed signature from isAlphanumericSpace(String) to isAlphanumericSpace(CharSequence)
    3448     */
    3449    public static boolean isAlphanumericSpace(final CharSequence cs) {
    3450        if (cs == null) {
    3451            return false;
    3452        }
    3453        final int sz = cs.length();
    3454        for (int i = 0; i < sz; i++) {
    3455            final char nowChar = cs.charAt(i);
    3456            if (nowChar != ' ' && !Character.isLetterOrDigit(nowChar) ) {
    3457                return false;
    3458            }
    3459        }
    3460        return true;
    3461    }
    3462
    3463    /**
    3464     * Checks if the CharSequence contains only Unicode letters and
    3465     * space (' ').
    3466     *
    3467     * <p>{@code null} will return {@code false}
    3468     * An empty CharSequence (length()=0) will return {@code true}.</p>
    3469     *
    3470     * <pre>
    3471     * StringUtils.isAlphaSpace(null)   = false
    3472     * StringUtils.isAlphaSpace("")     = true
    3473     * StringUtils.isAlphaSpace("  ")   = true
    3474     * StringUtils.isAlphaSpace("abc")  = true
    3475     * StringUtils.isAlphaSpace("ab c") = true
    3476     * StringUtils.isAlphaSpace("ab2c") = false
    3477     * StringUtils.isAlphaSpace("ab-c") = false
    3478     * </pre>
    3479     *
    3480     * @param cs  the CharSequence to check, may be null
    3481     * @return {@code true} if only contains letters and space,
    3482     *  and is non-null
    3483     * @since 3.0 Changed signature from isAlphaSpace(String) to isAlphaSpace(CharSequence)
    3484     */
    3485    public static boolean isAlphaSpace(final CharSequence cs) {
    3486        if (cs == null) {
    3487            return false;
    3488        }
    3489        final int sz = cs.length();
    3490        for (int i = 0; i < sz; i++) {
    3491            final char nowChar = cs.charAt(i);
    3492            if (nowChar != ' ' && !Character.isLetter(nowChar)) {
    3493                return false;
    3494            }
    3495        }
    3496        return true;
    3497    }
    3498
    3499    /**
    3500     * Checks if any of the CharSequences are empty ("") or null or whitespace only.
    3501     *
    3502     * <p>Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
    3503     *
    3504     * <pre>
    3505     * StringUtils.isAnyBlank((String) null)    = true
    3506     * StringUtils.isAnyBlank((String[]) null)  = false
    3507     * StringUtils.isAnyBlank(null, "foo")      = true
    3508     * StringUtils.isAnyBlank(null, null)       = true
    3509     * StringUtils.isAnyBlank("", "bar")        = true
    3510     * StringUtils.isAnyBlank("bob", "")        = true
    3511     * StringUtils.isAnyBlank("  bob  ", null)  = true
    3512     * StringUtils.isAnyBlank(" ", "bar")       = true
    3513     * StringUtils.isAnyBlank(new String[] {})  = false
    3514     * StringUtils.isAnyBlank(new String[]{""}) = true
    3515     * StringUtils.isAnyBlank("foo", "bar")     = false
    3516     * </pre>
    3517     *
    3518     * @param css  the CharSequences to check, may be null or empty
    3519     * @return {@code true} if any of the CharSequences are empty or null or whitespace only
    3520     * @since 3.2
    3521     */
    3522    public static boolean isAnyBlank(final CharSequence... css) {
    3523        if (ArrayUtils.isEmpty(css)) {
    3524            return false;
    3525        }
    3526        for (final CharSequence cs : css) {
    3527            if (isBlank(cs)) {
    3528                return true;
    3529            }
    3530        }
    3531        return false;
    3532    }
    3533
    3534    /**
    3535     * Checks if any of the CharSequences are empty ("") or null.
    3536     *
    3537     * <pre>
    3538     * StringUtils.isAnyEmpty((String) null)    = true
    3539     * StringUtils.isAnyEmpty((String[]) null)  = false
    3540     * StringUtils.isAnyEmpty(null, "foo")      = true
    3541     * StringUtils.isAnyEmpty("", "bar")        = true
    3542     * StringUtils.isAnyEmpty("bob", "")        = true
    3543     * StringUtils.isAnyEmpty("  bob  ", null)  = true
    3544     * StringUtils.isAnyEmpty(" ", "bar")       = false
    3545     * StringUtils.isAnyEmpty("foo", "bar")     = false
    3546     * StringUtils.isAnyEmpty(new String[]{})   = false
    3547     * StringUtils.isAnyEmpty(new String[]{""}) = true
    3548     * </pre>
    3549     *
    3550     * @param css  the CharSequences to check, may be null or empty
    3551     * @return {@code true} if any of the CharSequences are empty or null
    3552     * @since 3.2
    3553     */
    3554    public static boolean isAnyEmpty(final CharSequence... css) {
    3555        if (ArrayUtils.isEmpty(css)) {
    3556            return false;
    3557        }
    3558        for (final CharSequence cs : css) {
    3559            if (isEmpty(cs)) {
    3560                return true;
    3561            }
    3562        }
    3563        return false;
    3564    }
    3565
    3566    /**
    3567     * Checks if the CharSequence contains only ASCII printable characters.
    3568     *
    3569     * <p>{@code null} will return {@code false}.
    3570     * An empty CharSequence (length()=0) will return {@code true}.</p>
    3571     *
    3572     * <pre>
    3573     * StringUtils.isAsciiPrintable(null)     = false
    3574     * StringUtils.isAsciiPrintable("")       = true
    3575     * StringUtils.isAsciiPrintable(" ")      = true
    3576     * StringUtils.isAsciiPrintable("Ceki")   = true
    3577     * StringUtils.isAsciiPrintable("ab2c")   = true
    3578     * StringUtils.isAsciiPrintable("!ab-c~") = true
    3579     * StringUtils.isAsciiPrintable("\u0020") = true
    3580     * StringUtils.isAsciiPrintable("\u0021") = true
    3581     * StringUtils.isAsciiPrintable("\u007e") = true
    3582     * StringUtils.isAsciiPrintable("\u007f") = false
    3583     * StringUtils.isAsciiPrintable("Ceki G\u00fclc\u00fc") = false
    3584     * </pre>
    3585     *
    3586     * @param cs the CharSequence to check, may be null
    3587     * @return {@code true} if every character is in the range
    3588     *  32 through 126
    3589     * @since 2.1
    3590     * @since 3.0 Changed signature from isAsciiPrintable(String) to isAsciiPrintable(CharSequence)
    3591     */
    3592    public static boolean isAsciiPrintable(final CharSequence cs) {
    3593        if (cs == null) {
    3594            return false;
    3595        }
    3596        final int sz = cs.length();
    3597        for (int i = 0; i < sz; i++) {
    3598            if (!CharUtils.isAsciiPrintable(cs.charAt(i))) {
    3599                return false;
    3600            }
    3601        }
    3602        return true;
    3603    }
    3604
    3605    /**
    3606     * Checks if a CharSequence is empty (""), null or whitespace only.
    3607     *
    3608     * <p>Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
    3609     *
    3610     * <pre>
    3611     * StringUtils.isBlank(null)      = true
    3612     * StringUtils.isBlank("")        = true
    3613     * StringUtils.isBlank(" ")       = true
    3614     * StringUtils.isBlank("bob")     = false
    3615     * StringUtils.isBlank("  bob  ") = false
    3616     * </pre>
    3617     *
    3618     * @param cs  the CharSequence to check, may be null
    3619     * @return {@code true} if the CharSequence is null, empty or whitespace only
    3620     * @since 2.0
    3621     * @since 3.0 Changed signature from isBlank(String) to isBlank(CharSequence)
    3622     */
    3623    public static boolean isBlank(final CharSequence cs) {
    3624        final int strLen = length(cs);
    3625        if (strLen == 0) {
    3626            return true;
    3627        }
    3628        for (int i = 0; i < strLen; i++) {
    3629            if (!Character.isWhitespace(cs.charAt(i))) {
    3630                return false;
    3631            }
    3632        }
    3633        return true;
    3634    }
    3635
    3636    /**
    3637     * Checks if a CharSequence is empty ("") or null.
    3638     *
    3639     * <pre>
    3640     * StringUtils.isEmpty(null)      = true
    3641     * StringUtils.isEmpty("")        = true
    3642     * StringUtils.isEmpty(" ")       = false
    3643     * StringUtils.isEmpty("bob")     = false
    3644     * StringUtils.isEmpty("  bob  ") = false
    3645     * </pre>
    3646     *
    3647     * <p>NOTE: This method changed in Lang version 2.0.
    3648     * It no longer trims the CharSequence.
    3649     * That functionality is available in isBlank().</p>
    3650     *
    3651     * @param cs  the CharSequence to check, may be null
    3652     * @return {@code true} if the CharSequence is empty or null
    3653     * @since 3.0 Changed signature from isEmpty(String) to isEmpty(CharSequence)
    3654     */
    3655    public static boolean isEmpty(final CharSequence cs) {
    3656        return cs == null || cs.length() == 0;
    3657    }
    3658
    3659    /**
    3660     * Checks if the CharSequence contains mixed casing of both uppercase and lowercase characters.
    3661     *
    3662     * <p>{@code null} will return {@code false}. An empty CharSequence ({@code length()=0}) will return
    3663     * {@code false}.</p>
    3664     *
    3665     * <pre>
    3666     * StringUtils.isMixedCase(null)    = false
    3667     * StringUtils.isMixedCase("")      = false
    3668     * StringUtils.isMixedCase(" ")     = false
    3669     * StringUtils.isMixedCase("ABC")   = false
    3670     * StringUtils.isMixedCase("abc")   = false
    3671     * StringUtils.isMixedCase("aBc")   = true
    3672     * StringUtils.isMixedCase("A c")   = true
    3673     * StringUtils.isMixedCase("A1c")   = true
    3674     * StringUtils.isMixedCase("a/C")   = true
    3675     * StringUtils.isMixedCase("aC\t")  = true
    3676     * </pre>
    3677     *
    3678     * @param cs the CharSequence to check, may be null
    3679     * @return {@code true} if the CharSequence contains both uppercase and lowercase characters
    3680     * @since 3.5
    3681     */
    3682    public static boolean isMixedCase(final CharSequence cs) {
    3683        if (isEmpty(cs) || cs.length() == 1) {
    3684            return false;
    3685        }
    3686        boolean containsUppercase = false;
    3687        boolean containsLowercase = false;
    3688        final int sz = cs.length();
    3689        for (int i = 0; i < sz; i++) {
    3690            final char nowChar = cs.charAt(i);
    3691            if (Character.isUpperCase(nowChar)) {
    3692                containsUppercase = true;
    3693            } else if (Character.isLowerCase(nowChar)) {
    3694                containsLowercase = true;
    3695            }
    3696            if (containsUppercase && containsLowercase) {
    3697                return true;
    3698            }
    3699        }
    3700        return false;
    3701    }
    3702
    3703    /**
    3704     * Checks if none of the CharSequences are empty (""), null or whitespace only.
    3705     *
    3706     * <p>Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
    3707     *
    3708     * <pre>
    3709     * StringUtils.isNoneBlank((String) null)    = false
    3710     * StringUtils.isNoneBlank((String[]) null)  = true
    3711     * StringUtils.isNoneBlank(null, "foo")      = false
    3712     * StringUtils.isNoneBlank(null, null)       = false
    3713     * StringUtils.isNoneBlank("", "bar")        = false
    3714     * StringUtils.isNoneBlank("bob", "")        = false
    3715     * StringUtils.isNoneBlank("  bob  ", null)  = false
    3716     * StringUtils.isNoneBlank(" ", "bar")       = false
    3717     * StringUtils.isNoneBlank(new String[] {})  = true
    3718     * StringUtils.isNoneBlank(new String[]{""}) = false
    3719     * StringUtils.isNoneBlank("foo", "bar")     = true
    3720     * </pre>
    3721     *
    3722     * @param css  the CharSequences to check, may be null or empty
    3723     * @return {@code true} if none of the CharSequences are empty or null or whitespace only
    3724     * @since 3.2
    3725     */
    3726    public static boolean isNoneBlank(final CharSequence... css) {
    3727      return !isAnyBlank(css);
    3728    }
    3729
    3730    /**
    3731     * Checks if none of the CharSequences are empty ("") or null.
    3732     *
    3733     * <pre>
    3734     * StringUtils.isNoneEmpty((String) null)    = false
    3735     * StringUtils.isNoneEmpty((String[]) null)  = true
    3736     * StringUtils.isNoneEmpty(null, "foo")      = false
    3737     * StringUtils.isNoneEmpty("", "bar")        = false
    3738     * StringUtils.isNoneEmpty("bob", "")        = false
    3739     * StringUtils.isNoneEmpty("  bob  ", null)  = false
    3740     * StringUtils.isNoneEmpty(new String[] {})  = true
    3741     * StringUtils.isNoneEmpty(new String[]{""}) = false
    3742     * StringUtils.isNoneEmpty(" ", "bar")       = true
    3743     * StringUtils.isNoneEmpty("foo", "bar")     = true
    3744     * </pre>
    3745     *
    3746     * @param css  the CharSequences to check, may be null or empty
    3747     * @return {@code true} if none of the CharSequences are empty or null
    3748     * @since 3.2
    3749     */
    3750    public static boolean isNoneEmpty(final CharSequence... css) {
    3751      return !isAnyEmpty(css);
    3752    }
    3753
    3754    /**
    3755     * Checks if a CharSequence is not empty (""), not null and not whitespace only.
    3756     *
    3757     * <p>Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
    3758     *
    3759     * <pre>
    3760     * StringUtils.isNotBlank(null)      = false
    3761     * StringUtils.isNotBlank("")        = false
    3762     * StringUtils.isNotBlank(" ")       = false
    3763     * StringUtils.isNotBlank("bob")     = true
    3764     * StringUtils.isNotBlank("  bob  ") = true
    3765     * </pre>
    3766     *
    3767     * @param cs  the CharSequence to check, may be null
    3768     * @return {@code true} if the CharSequence is
    3769     *  not empty and not null and not whitespace only
    3770     * @since 2.0
    3771     * @since 3.0 Changed signature from isNotBlank(String) to isNotBlank(CharSequence)
    3772     */
    3773    public static boolean isNotBlank(final CharSequence cs) {
    3774        return !isBlank(cs);
    3775    }
    3776
    3777    /**
    3778     * Checks if a CharSequence is not empty ("") and not null.
    3779     *
    3780     * <pre>
    3781     * StringUtils.isNotEmpty(null)      = false
    3782     * StringUtils.isNotEmpty("")        = false
    3783     * StringUtils.isNotEmpty(" ")       = true
    3784     * StringUtils.isNotEmpty("bob")     = true
    3785     * StringUtils.isNotEmpty("  bob  ") = true
    3786     * </pre>
    3787     *
    3788     * @param cs  the CharSequence to check, may be null
    3789     * @return {@code true} if the CharSequence is not empty and not null
    3790     * @since 3.0 Changed signature from isNotEmpty(String) to isNotEmpty(CharSequence)
    3791     */
    3792    public static boolean isNotEmpty(final CharSequence cs) {
    3793        return !isEmpty(cs);
    3794    }
    3795
    3796    /**
    3797     * Checks if the CharSequence contains only Unicode digits.
    3798     * A decimal point is not a Unicode digit and returns false.
    3799     *
    3800     * <p>{@code null} will return {@code false}.
    3801     * An empty CharSequence (length()=0) will return {@code false}.</p>
    3802     *
    3803     * <p>Note that the method does not allow for a leading sign, either positive or negative.
    3804     * Also, if a String passes the numeric test, it may still generate a NumberFormatException
    3805     * when parsed by Integer.parseInt or Long.parseLong, e.g. if the value is outside the range
    3806     * for int or long respectively.</p>
    3807     *
    3808     * <pre>
    3809     * StringUtils.isNumeric(null)   = false
    3810     * StringUtils.isNumeric("")     = false
    3811     * StringUtils.isNumeric("  ")   = false
    3812     * StringUtils.isNumeric("123")  = true
    3813     * StringUtils.isNumeric("\u0967\u0968\u0969")  = true
    3814     * StringUtils.isNumeric("12 3") = false
    3815     * StringUtils.isNumeric("ab2c") = false
    3816     * StringUtils.isNumeric("12-3") = false
    3817     * StringUtils.isNumeric("12.3") = false
    3818     * StringUtils.isNumeric("-123") = false
    3819     * StringUtils.isNumeric("+123") = false
    3820     * </pre>
    3821     *
    3822     * @param cs  the CharSequence to check, may be null
    3823     * @return {@code true} if only contains digits, and is non-null
    3824     * @since 3.0 Changed signature from isNumeric(String) to isNumeric(CharSequence)
    3825     * @since 3.0 Changed "" to return false and not true
    3826     */
    3827    public static boolean isNumeric(final CharSequence cs) {
    3828        if (isEmpty(cs)) {
    3829            return false;
    3830        }
    3831        final int sz = cs.length();
    3832        for (int i = 0; i < sz; i++) {
    3833            if (!Character.isDigit(cs.charAt(i))) {
    3834                return false;
    3835            }
    3836        }
    3837        return true;
    3838    }
    3839
    3840    /**
    3841     * Checks if the CharSequence contains only Unicode digits or space
    3842     * ({@code ' '}).
    3843     * A decimal point is not a Unicode digit and returns false.
    3844     *
    3845     * <p>{@code null} will return {@code false}.
    3846     * An empty CharSequence (length()=0) will return {@code true}.</p>
    3847     *
    3848     * <pre>
    3849     * StringUtils.isNumericSpace(null)   = false
    3850     * StringUtils.isNumericSpace("")     = true
    3851     * StringUtils.isNumericSpace("  ")   = true
    3852     * StringUtils.isNumericSpace("123")  = true
    3853     * StringUtils.isNumericSpace("12 3") = true
    3854     * StringUtils.isNumericSpace("\u0967\u0968\u0969")   = true
    3855     * StringUtils.isNumericSpace("\u0967\u0968 \u0969")  = true
    3856     * StringUtils.isNumericSpace("ab2c") = false
    3857     * StringUtils.isNumericSpace("12-3") = false
    3858     * StringUtils.isNumericSpace("12.3") = false
    3859     * </pre>
    3860     *
    3861     * @param cs  the CharSequence to check, may be null
    3862     * @return {@code true} if only contains digits or space,
    3863     *  and is non-null
    3864     * @since 3.0 Changed signature from isNumericSpace(String) to isNumericSpace(CharSequence)
    3865     */
    3866    public static boolean isNumericSpace(final CharSequence cs) {
    3867        if (cs == null) {
    3868            return false;
    3869        }
    3870        final int sz = cs.length();
    3871        for (int i = 0; i < sz; i++) {
    3872            final char nowChar = cs.charAt(i);
    3873            if (nowChar != ' ' && !Character.isDigit(nowChar)) {
    3874                return false;
    3875            }
    3876        }
    3877        return true;
    3878    }
    3879
    3880    /**
    3881     * Checks if the CharSequence contains only whitespace.
    3882     *
    3883     * <p>Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
    3884     *
    3885     * <p>{@code null} will return {@code false}.
    3886     * An empty CharSequence (length()=0) will return {@code true}.</p>
    3887     *
    3888     * <pre>
    3889     * StringUtils.isWhitespace(null)   = false
    3890     * StringUtils.isWhitespace("")     = true
    3891     * StringUtils.isWhitespace("  ")   = true
    3892     * StringUtils.isWhitespace("abc")  = false
    3893     * StringUtils.isWhitespace("ab2c") = false
    3894     * StringUtils.isWhitespace("ab-c") = false
    3895     * </pre>
    3896     *
    3897     * @param cs  the CharSequence to check, may be null
    3898     * @return {@code true} if only contains whitespace, and is non-null
    3899     * @since 2.0
    3900     * @since 3.0 Changed signature from isWhitespace(String) to isWhitespace(CharSequence)
    3901     */
    3902    public static boolean isWhitespace(final CharSequence cs) {
    3903        if (cs == null) {
    3904            return false;
    3905        }
    3906        final int sz = cs.length();
    3907        for (int i = 0; i < sz; i++) {
    3908            if (!Character.isWhitespace(cs.charAt(i))) {
    3909                return false;
    3910            }
    3911        }
    3912        return true;
    3913    }
    3914
    3915    /**
    3916     * Joins the elements of the provided array into a single String containing the provided list of elements.
    3917     *
    3918     * <p>
    3919     * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
    3920     * by empty strings.
    3921     * </p>
    3922     *
    3923     * <pre>
    3924     * StringUtils.join(null, *)             = null
    3925     * StringUtils.join([], *)               = ""
    3926     * StringUtils.join([null], *)           = ""
    3927     * StringUtils.join([false, false], ';') = "false;false"
    3928     * </pre>
    3929     *
    3930     * @param array
    3931     *            the array of values to join together, may be null
    3932     * @param delimiter
    3933     *            the separator character to use
    3934     * @return the joined String, {@code null} if null array input
    3935     * @since 3.12.0
    3936     */
    3937    public static String join(final boolean[] array, final char delimiter) {
    3938        if (array == null) {
    3939            return null;
    3940        }
    3941        return join(array, delimiter, 0, array.length);
    3942    }
    3943
    3944    /**
    3945     * Joins the elements of the provided array into a single String containing the provided list of elements.
    3946     *
    3947     * <p>
    3948     * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
    3949     * by empty strings.
    3950     * </p>
    3951     *
    3952     * <pre>
    3953     * StringUtils.join(null, *)                  = null
    3954     * StringUtils.join([], *)                    = ""
    3955     * StringUtils.join([null], *)                = ""
    3956     * StringUtils.join([true, false, true], ';') = "true;false;true"
    3957     * </pre>
    3958     *
    3959     * @param array
    3960     *            the array of values to join together, may be null
    3961     * @param delimiter
    3962     *            the separator character to use
    3963     * @param startIndex
    3964     *            the first index to start joining from. It is an error to pass in a start index past the end of the
    3965     *            array
    3966     * @param endIndex
    3967     *            the index to stop joining from (exclusive). It is an error to pass in an end index past the end of
    3968     *            the array
    3969     * @return the joined String, {@code null} if null array input
    3970     * @since 3.12.0
    3971     */
    3972    public static String join(final boolean[] array, final char delimiter, final int startIndex, final int endIndex) {
    3973        if (array == null) {
    3974            return null;
    3975        }
    3976        if (endIndex - startIndex <= 0) {
    3977            return EMPTY;
    3978        }
    3979        final StringBuilder stringBuilder = new StringBuilder(array.length * 5 + array.length - 1);
    3980        for (int i = startIndex; i < endIndex; i++) {
    3981            stringBuilder
    3982                    .append(array[i])
    3983                    .append(delimiter);
    3984        }
    3985        return stringBuilder.substring(0, stringBuilder.length() - 1);
    3986    }
    3987
    3988    /**
    3989     * Joins the elements of the provided array into a single String containing the provided list of elements.
    3990     *
    3991     * <p>
    3992     * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
    3993     * by empty strings.
    3994     * </p>
    3995     *
    3996     * <pre>
    3997     * StringUtils.join(null, *)         = null
    3998     * StringUtils.join([], *)           = ""
    3999     * StringUtils.join([null], *)       = ""
    4000     * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
    4001     * StringUtils.join([1, 2, 3], null) = "123"
    4002     * </pre>
    4003     *
    4004     * @param array
    4005     *            the array of values to join together, may be null
    4006     * @param delimiter
    4007     *            the separator character to use
    4008     * @return the joined String, {@code null} if null array input
    4009     * @since 3.2
    4010     */
    4011    public static String join(final byte[] array, final char delimiter) {
    4012        if (array == null) {
    4013            return null;
    4014        }
    4015        return join(array, delimiter, 0, array.length);
    4016    }
    4017
    4018    /**
    4019     * Joins the elements of the provided array into a single String containing the provided list of elements.
    4020     *
    4021     * <p>
    4022     * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
    4023     * by empty strings.
    4024     * </p>
    4025     *
    4026     * <pre>
    4027     * StringUtils.join(null, *)         = null
    4028     * StringUtils.join([], *)           = ""
    4029     * StringUtils.join([null], *)       = ""
    4030     * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
    4031     * StringUtils.join([1, 2, 3], null) = "123"
    4032     * </pre>
    4033     *
    4034     * @param array
    4035     *            the array of values to join together, may be null
    4036     * @param delimiter
    4037     *            the separator character to use
    4038     * @param startIndex
    4039     *            the first index to start joining from. It is an error to pass in a start index past the end of the
    4040     *            array
    4041     * @param endIndex
    4042     *            the index to stop joining from (exclusive). It is an error to pass in an end index past the end of
    4043     *            the array
    4044     * @return the joined String, {@code null} if null array input
    4045     * @since 3.2
    4046     */
    4047    public static String join(final byte[] array, final char delimiter, final int startIndex, final int endIndex) {
    4048        if (array == null) {
    4049            return null;
    4050        }
    4051        if (endIndex - startIndex <= 0) {
    4052            return EMPTY;
    4053        }
    4054        final StringBuilder stringBuilder = new StringBuilder();
    4055        for (int i = startIndex; i < endIndex; i++) {
    4056            stringBuilder
    4057                    .append(array[i])
    4058                    .append(delimiter);
    4059        }
    4060        return stringBuilder.substring(0, stringBuilder.length() - 1);
    4061    }
    4062
    4063    /**
    4064     * Joins the elements of the provided array into a single String containing the provided list of elements.
    4065     *
    4066     * <p>
    4067     * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
    4068     * by empty strings.
    4069     * </p>
    4070     *
    4071     * <pre>
    4072     * StringUtils.join(null, *)         = null
    4073     * StringUtils.join([], *)           = ""
    4074     * StringUtils.join([null], *)       = ""
    4075     * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
    4076     * StringUtils.join([1, 2, 3], null) = "123"
    4077     * </pre>
    4078     *
    4079     * @param array
    4080     *            the array of values to join together, may be null
    4081     * @param delimiter
    4082     *            the separator character to use
    4083     * @return the joined String, {@code null} if null array input
    4084     * @since 3.2
    4085     */
    4086    public static String join(final char[] array, final char delimiter) {
    4087        if (array == null) {
    4088            return null;
    4089        }
    4090        return join(array, delimiter, 0, array.length);
    4091    }
    4092
    4093    /**
    4094     * Joins the elements of the provided array into a single String containing the provided list of elements.
    4095     *
    4096     * <p>
    4097     * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
    4098     * by empty strings.
    4099     * </p>
    4100     *
    4101     * <pre>
    4102     * StringUtils.join(null, *)         = null
    4103     * StringUtils.join([], *)           = ""
    4104     * StringUtils.join([null], *)       = ""
    4105     * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
    4106     * StringUtils.join([1, 2, 3], null) = "123"
    4107     * </pre>
    4108     *
    4109     * @param array
    4110     *            the array of values to join together, may be null
    4111     * @param delimiter
    4112     *            the separator character to use
    4113     * @param startIndex
    4114     *            the first index to start joining from. It is an error to pass in a start index past the end of the
    4115     *            array
    4116     * @param endIndex
    4117     *            the index to stop joining from (exclusive). It is an error to pass in an end index past the end of
    4118     *            the array
    4119     * @return the joined String, {@code null} if null array input
    4120     * @since 3.2
    4121     */
    4122    public static String join(final char[] array, final char delimiter, final int startIndex, final int endIndex) {
    4123        if (array == null) {
    4124            return null;
    4125        }
    4126        if (endIndex - startIndex <= 0) {
    4127            return EMPTY;
    4128        }
    4129        final StringBuilder stringBuilder = new StringBuilder(array.length * 2 - 1);
    4130        for (int i = startIndex; i < endIndex; i++) {
    4131            stringBuilder
    4132                    .append(array[i])
    4133                    .append(delimiter);
    4134        }
    4135        return stringBuilder.substring(0, stringBuilder.length() - 1);
    4136    }
    4137
    4138    /**
    4139     * Joins the elements of the provided array into a single String containing the provided list of elements.
    4140     *
    4141     * <p>
    4142     * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
    4143     * by empty strings.
    4144     * </p>
    4145     *
    4146     * <pre>
    4147     * StringUtils.join(null, *)               = null
    4148     * StringUtils.join([], *)                 = ""
    4149     * StringUtils.join([null], *)             = ""
    4150     * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
    4151     * StringUtils.join([1, 2, 3], null) = "123"
    4152     * </pre>
    4153     *
    4154     * @param array
    4155     *            the array of values to join together, may be null
    4156     * @param delimiter
    4157     *            the separator character to use
    4158     * @return the joined String, {@code null} if null array input
    4159     * @since 3.2
    4160     */
    4161    public static String join(final double[] array, final char delimiter) {
    4162        if (array == null) {
    4163            return null;
    4164        }
    4165        return join(array, delimiter, 0, array.length);
    4166    }
    4167
    4168    /**
    4169     * Joins the elements of the provided array into a single String containing the provided list of elements.
    4170     *
    4171     * <p>
    4172     * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
    4173     * by empty strings.
    4174     * </p>
    4175     *
    4176     * <pre>
    4177     * StringUtils.join(null, *)               = null
    4178     * StringUtils.join([], *)                 = ""
    4179     * StringUtils.join([null], *)             = ""
    4180     * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
    4181     * StringUtils.join([1, 2, 3], null) = "123"
    4182     * </pre>
    4183     *
    4184     * @param array
    4185     *            the array of values to join together, may be null
    4186     * @param delimiter
    4187     *            the separator character to use
    4188     * @param startIndex
    4189     *            the first index to start joining from. It is an error to pass in a start index past the end of the
    4190     *            array
    4191     * @param endIndex
    4192     *            the index to stop joining from (exclusive). It is an error to pass in an end index past the end of
    4193     *            the array
    4194     * @return the joined String, {@code null} if null array input
    4195     * @since 3.2
    4196     */
    4197    public static String join(final double[] array, final char delimiter, final int startIndex, final int endIndex) {
    4198        if (array == null) {
    4199            return null;
    4200        }
    4201        if (endIndex - startIndex <= 0) {
    4202            return EMPTY;
    4203        }
    4204        final StringBuilder stringBuilder = new StringBuilder();
    4205        for (int i = startIndex; i < endIndex; i++) {
    4206            stringBuilder
    4207                    .append(array[i])
    4208                    .append(delimiter);
    4209        }
    4210        return stringBuilder.substring(0, stringBuilder.length() - 1);
    4211    }
    4212
    4213    /**
    4214     * Joins the elements of the provided array into a single String containing the provided list of elements.
    4215     *
    4216     * <p>
    4217     * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
    4218     * by empty strings.
    4219     * </p>
    4220     *
    4221     * <pre>
    4222     * StringUtils.join(null, *)               = null
    4223     * StringUtils.join([], *)                 = ""
    4224     * StringUtils.join([null], *)             = ""
    4225     * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
    4226     * StringUtils.join([1, 2, 3], null) = "123"
    4227     * </pre>
    4228     *
    4229     * @param array
    4230     *            the array of values to join together, may be null
    4231     * @param delimiter
    4232     *            the separator character to use
    4233     * @return the joined String, {@code null} if null array input
    4234     * @since 3.2
    4235     */
    4236    public static String join(final float[] array, final char delimiter) {
    4237        if (array == null) {
    4238            return null;
    4239        }
    4240        return join(array, delimiter, 0, array.length);
    4241    }
    4242
    4243    /**
    4244     * Joins the elements of the provided array into a single String containing the provided list of elements.
    4245     *
    4246     * <p>
    4247     * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
    4248     * by empty strings.
    4249     * </p>
    4250     *
    4251     * <pre>
    4252     * StringUtils.join(null, *)               = null
    4253     * StringUtils.join([], *)                 = ""
    4254     * StringUtils.join([null], *)             = ""
    4255     * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
    4256     * StringUtils.join([1, 2, 3], null) = "123"
    4257     * </pre>
    4258     *
    4259     * @param array
    4260     *            the array of values to join together, may be null
    4261     * @param delimiter
    4262     *            the separator character to use
    4263     * @param startIndex
    4264     *            the first index to start joining from. It is an error to pass in a start index past the end of the
    4265     *            array
    4266     * @param endIndex
    4267     *            the index to stop joining from (exclusive). It is an error to pass in an end index past the end of
    4268     *            the array
    4269     * @return the joined String, {@code null} if null array input
    4270     * @since 3.2
    4271     */
    4272    public static String join(final float[] array, final char delimiter, final int startIndex, final int endIndex) {
    4273        if (array == null) {
    4274            return null;
    4275        }
    4276        if (endIndex - startIndex <= 0) {
    4277            return EMPTY;
    4278        }
    4279        final StringBuilder stringBuilder = new StringBuilder();
    4280        for (int i = startIndex; i < endIndex; i++) {
    4281            stringBuilder
    4282                    .append(array[i])
    4283                    .append(delimiter);
    4284        }
    4285        return stringBuilder.substring(0, stringBuilder.length() - 1);
    4286    }
    4287
    4288    /**
    4289     * Joins the elements of the provided array into a single String containing the provided list of elements.
    4290     *
    4291     * <p>
    4292     * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
    4293     * by empty strings.
    4294     * </p>
    4295     *
    4296     * <pre>
    4297     * StringUtils.join(null, *)               = null
    4298     * StringUtils.join([], *)                 = ""
    4299     * StringUtils.join([null], *)             = ""
    4300     * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
    4301     * StringUtils.join([1, 2, 3], null) = "123"
    4302     * </pre>
    4303     *
    4304     * @param array
    4305     *            the array of values to join together, may be null
    4306     * @param separator
    4307     *            the separator character to use
    4308     * @return the joined String, {@code null} if null array input
    4309     * @since 3.2
    4310     */
    4311    public static String join(final int[] array, final char separator) {
    4312        if (array == null) {
    4313            return null;
    4314        }
    4315        return join(array, separator, 0, array.length);
    4316    }
    4317
    4318    /**
    4319     * Joins the elements of the provided array into a single String containing the provided list of elements.
    4320     *
    4321     * <p>
    4322     * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
    4323     * by empty strings.
    4324     * </p>
    4325     *
    4326     * <pre>
    4327     * StringUtils.join(null, *)               = null
    4328     * StringUtils.join([], *)                 = ""
    4329     * StringUtils.join([null], *)             = ""
    4330     * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
    4331     * StringUtils.join([1, 2, 3], null) = "123"
    4332     * </pre>
    4333     *
    4334     * @param array
    4335     *            the array of values to join together, may be null
    4336     * @param delimiter
    4337     *            the separator character to use
    4338     * @param startIndex
    4339     *            the first index to start joining from. It is an error to pass in a start index past the end of the
    4340     *            array
    4341     * @param endIndex
    4342     *            the index to stop joining from (exclusive). It is an error to pass in an end index past the end of
    4343     *            the array
    4344     * @return the joined String, {@code null} if null array input
    4345     * @since 3.2
    4346     */
    4347    public static String join(final int[] array, final char delimiter, final int startIndex, final int endIndex) {
    4348        if (array == null) {
    4349            return null;
    4350        }
    4351        if (endIndex - startIndex <= 0) {
    4352            return EMPTY;
    4353        }
    4354        final StringBuilder stringBuilder = new StringBuilder();
    4355        for (int i = startIndex; i < endIndex; i++) {
    4356            stringBuilder
    4357                    .append(array[i])
    4358                    .append(delimiter);
    4359        }
    4360        return stringBuilder.substring(0, stringBuilder.length() - 1);
    4361    }
    4362
    4363    /**
    4364     * Joins the elements of the provided {@link Iterable} into
    4365     * a single String containing the provided elements.
    4366     *
    4367     * <p>No delimiter is added before or after the list. Null objects or empty
    4368     * strings within the iteration are represented by empty strings.</p>
    4369     *
    4370     * <p>See the examples here: {@link #join(Object[],char)}.</p>
    4371     *
    4372     * @param iterable  the {@link Iterable} providing the values to join together, may be null
    4373     * @param separator  the separator character to use
    4374     * @return the joined String, {@code null} if null iterator input
    4375     * @since 2.3
    4376     */
    4377    public static String join(final Iterable<?> iterable, final char separator) {
    4378        return iterable != null ? join(iterable.iterator(), separator) : null;
    4379    }
    4380
    4381    /**
    4382     * Joins the elements of the provided {@link Iterable} into
    4383     * a single String containing the provided elements.
    4384     *
    4385     * <p>No delimiter is added before or after the list.
    4386     * A {@code null} separator is the same as an empty String ("").</p>
    4387     *
    4388     * <p>See the examples here: {@link #join(Object[],String)}.</p>
    4389     *
    4390     * @param iterable  the {@link Iterable} providing the values to join together, may be null
    4391     * @param separator  the separator character to use, null treated as ""
    4392     * @return the joined String, {@code null} if null iterator input
    4393     * @since 2.3
    4394     */
    4395    public static String join(final Iterable<?> iterable, final String separator) {
    4396        return iterable != null ? join(iterable.iterator(), separator) : null;
    4397    }
    4398
    4399    /**
    4400     * Joins the elements of the provided {@link Iterator} into
    4401     * a single String containing the provided elements.
    4402     *
    4403     * <p>No delimiter is added before or after the list. Null objects or empty
    4404     * strings within the iteration are represented by empty strings.</p>
    4405     *
    4406     * <p>See the examples here: {@link #join(Object[],char)}.</p>
    4407     *
    4408     * @param iterator  the {@link Iterator} of values to join together, may be null
    4409     * @param separator  the separator character to use
    4410     * @return the joined String, {@code null} if null iterator input
    4411     * @since 2.0
    4412     */
    4413    public static String join(final Iterator<?> iterator, final char separator) {
    4414        // handle null, zero and one elements before building a buffer
    4415        if (iterator == null) {
    4416            return null;
    4417        }
    4418        if (!iterator.hasNext()) {
    4419            return EMPTY;
    4420        }
    4421        return Streams.of(iterator).collect(LangCollectors.joining(toStringOrEmpty(String.valueOf(separator)), EMPTY, EMPTY, StringUtils::toStringOrEmpty));
    4422    }
    4423
    4424    /**
    4425     * Joins the elements of the provided {@link Iterator} into
    4426     * a single String containing the provided elements.
    4427     *
    4428     * <p>No delimiter is added before or after the list.
    4429     * A {@code null} separator is the same as an empty String ("").</p>
    4430     *
    4431     * <p>See the examples here: {@link #join(Object[],String)}.</p>
    4432     *
    4433     * @param iterator  the {@link Iterator} of values to join together, may be null
    4434     * @param separator  the separator character to use, null treated as ""
    4435     * @return the joined String, {@code null} if null iterator input
    4436     */
    4437    public static String join(final Iterator<?> iterator, final String separator) {
    4438        // handle null, zero and one elements before building a buffer
    4439        if (iterator == null) {
    4440            return null;
    4441        }
    4442        if (!iterator.hasNext()) {
    4443            return EMPTY;
    4444        }
    4445        return Streams.of(iterator).collect(LangCollectors.joining(toStringOrEmpty(separator), EMPTY, EMPTY, StringUtils::toStringOrEmpty));
    4446    }
    4447
    4448    /**
    4449     * Joins the elements of the provided {@link List} into a single String
    4450     * containing the provided list of elements.
    4451     *
    4452     * <p>No delimiter is added before or after the list.
    4453     * Null objects or empty strings within the array are represented by
    4454     * empty strings.</p>
    4455     *
    4456     * <pre>
    4457     * StringUtils.join(null, *)               = null
    4458     * StringUtils.join([], *)                 = ""
    4459     * StringUtils.join([null], *)             = ""
    4460     * StringUtils.join(["a", "b", "c"], ';')  = "a;b;c"
    4461     * StringUtils.join(["a", "b", "c"], null) = "abc"
    4462     * StringUtils.join([null, "", "a"], ';')  = ";;a"
    4463     * </pre>
    4464     *
    4465     * @param list  the {@link List} of values to join together, may be null
    4466     * @param separator  the separator character to use
    4467     * @param startIndex the first index to start joining from.  It is
    4468     * an error to pass in a start index past the end of the list
    4469     * @param endIndex the index to stop joining from (exclusive). It is
    4470     * an error to pass in an end index past the end of the list
    4471     * @return the joined String, {@code null} if null list input
    4472     * @since 3.8
    4473     */
    4474    public static String join(final List<?> list, final char separator, final int startIndex, final int endIndex) {
    4475        if (list == null) {
    4476            return null;
    4477        }
    4478        final int noOfItems = endIndex - startIndex;
    4479        if (noOfItems <= 0) {
    4480            return EMPTY;
    4481        }
    4482        final List<?> subList = list.subList(startIndex, endIndex);
    4483        return join(subList.iterator(), separator);
    4484    }
    4485
    4486    /**
    4487     * Joins the elements of the provided {@link List} into a single String
    4488     * containing the provided list of elements.
    4489     *
    4490     * <p>No delimiter is added before or after the list.
    4491     * Null objects or empty strings within the array are represented by
    4492     * empty strings.</p>
    4493     *
    4494     * <pre>
    4495     * StringUtils.join(null, *)               = null
    4496     * StringUtils.join([], *)                 = ""
    4497     * StringUtils.join([null], *)             = ""
    4498     * StringUtils.join(["a", "b", "c"], ';')  = "a;b;c"
    4499     * StringUtils.join(["a", "b", "c"], null) = "abc"
    4500     * StringUtils.join([null, "", "a"], ';')  = ";;a"
    4501     * </pre>
    4502     *
    4503     * @param list  the {@link List} of values to join together, may be null
    4504     * @param separator  the separator character to use
    4505     * @param startIndex the first index to start joining from.  It is
    4506     * an error to pass in a start index past the end of the list
    4507     * @param endIndex the index to stop joining from (exclusive). It is
    4508     * an error to pass in an end index past the end of the list
    4509     * @return the joined String, {@code null} if null list input
    4510     * @since 3.8
    4511     */
    4512    public static String join(final List<?> list, final String separator, final int startIndex, final int endIndex) {
    4513        if (list == null) {
    4514            return null;
    4515        }
    4516        final int noOfItems = endIndex - startIndex;
    4517        if (noOfItems <= 0) {
    4518            return EMPTY;
    4519        }
    4520        final List<?> subList = list.subList(startIndex, endIndex);
    4521        return join(subList.iterator(), separator);
    4522    }
    4523
    4524    /**
    4525     * Joins the elements of the provided array into a single String containing the provided list of elements.
    4526     *
    4527     * <p>
    4528     * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
    4529     * by empty strings.
    4530     * </p>
    4531     *
    4532     * <pre>
    4533     * StringUtils.join(null, *)               = null
    4534     * StringUtils.join([], *)                 = ""
    4535     * StringUtils.join([null], *)             = ""
    4536     * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
    4537     * StringUtils.join([1, 2, 3], null) = "123"
    4538     * </pre>
    4539     *
    4540     * @param array
    4541     *            the array of values to join together, may be null
    4542     * @param separator
    4543     *            the separator character to use
    4544     * @return the joined String, {@code null} if null array input
    4545     * @since 3.2
    4546     */
    4547    public static String join(final long[] array, final char separator) {
    4548        if (array == null) {
    4549            return null;
    4550        }
    4551        return join(array, separator, 0, array.length);
    4552    }
    4553
    4554    /**
    4555     * Joins the elements of the provided array into a single String containing the provided list of elements.
    4556     *
    4557     * <p>
    4558     * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
    4559     * by empty strings.
    4560     * </p>
    4561     *
    4562     * <pre>
    4563     * StringUtils.join(null, *)               = null
    4564     * StringUtils.join([], *)                 = ""
    4565     * StringUtils.join([null], *)             = ""
    4566     * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
    4567     * StringUtils.join([1, 2, 3], null) = "123"
    4568     * </pre>
    4569     *
    4570     * @param array
    4571     *            the array of values to join together, may be null
    4572     * @param delimiter
    4573     *            the separator character to use
    4574     * @param startIndex
    4575     *            the first index to start joining from. It is an error to pass in a start index past the end of the
    4576     *            array
    4577     * @param endIndex
    4578     *            the index to stop joining from (exclusive). It is an error to pass in an end index past the end of
    4579     *            the array
    4580     * @return the joined String, {@code null} if null array input
    4581     * @since 3.2
    4582     */
    4583    public static String join(final long[] array, final char delimiter, final int startIndex, final int endIndex) {
    4584        if (array == null) {
    4585            return null;
    4586        }
    4587        if (endIndex - startIndex <= 0) {
    4588            return EMPTY;
    4589        }
    4590        final StringBuilder stringBuilder = new StringBuilder();
    4591        for (int i = startIndex; i < endIndex; i++) {
    4592            stringBuilder
    4593                    .append(array[i])
    4594                    .append(delimiter);
    4595        }
    4596        return stringBuilder.substring(0, stringBuilder.length() - 1);
    4597    }
    4598
    4599    /**
    4600     * Joins the elements of the provided array into a single String
    4601     * containing the provided list of elements.
    4602     *
    4603     * <p>No delimiter is added before or after the list.
    4604     * Null objects or empty strings within the array are represented by
    4605     * empty strings.</p>
    4606     *
    4607     * <pre>
    4608     * StringUtils.join(null, *)               = null
    4609     * StringUtils.join([], *)                 = ""
    4610     * StringUtils.join([null], *)             = ""
    4611     * StringUtils.join(["a", "b", "c"], ';')  = "a;b;c"
    4612     * StringUtils.join(["a", "b", "c"], null) = "abc"
    4613     * StringUtils.join([null, "", "a"], ';')  = ";;a"
    4614     * </pre>
    4615     *
    4616     * @param array  the array of values to join together, may be null
    4617     * @param delimiter  the separator character to use
    4618     * @return the joined String, {@code null} if null array input
    4619     * @since 2.0
    4620     */
    4621    public static String join(final Object[] array, final char delimiter) {
    4622        if (array == null) {
    4623            return null;
    4624        }
    4625        return join(array, delimiter, 0, array.length);
    4626    }
    4627
    4628    /**
    4629     * Joins the elements of the provided array into a single String
    4630     * containing the provided list of elements.
    4631     *
    4632     * <p>No delimiter is added before or after the list.
    4633     * Null objects or empty strings within the array are represented by
    4634     * empty strings.</p>
    4635     *
    4636     * <pre>
    4637     * StringUtils.join(null, *)               = null
    4638     * StringUtils.join([], *)                 = ""
    4639     * StringUtils.join([null], *)             = ""
    4640     * StringUtils.join(["a", "b", "c"], ';')  = "a;b;c"
    4641     * StringUtils.join(["a", "b", "c"], null) = "abc"
    4642     * StringUtils.join([null, "", "a"], ';')  = ";;a"
    4643     * </pre>
    4644     *
    4645     * @param array  the array of values to join together, may be null
    4646     * @param delimiter  the separator character to use
    4647     * @param startIndex the first index to start joining from.  It is
    4648     * an error to pass in a start index past the end of the array
    4649     * @param endIndex the index to stop joining from (exclusive). It is
    4650     * an error to pass in an end index past the end of the array
    4651     * @return the joined String, {@code null} if null array input
    4652     * @since 2.0
    4653     */
    4654    public static String join(final Object[] array, final char delimiter, final int startIndex, final int endIndex) {
    4655        return join(array, String.valueOf(delimiter), startIndex, endIndex);
    4656    }
    4657
    4658    /**
    4659     * Joins the elements of the provided array into a single String
    4660     * containing the provided list of elements.
    4661     *
    4662     * <p>No delimiter is added before or after the list.
    4663     * A {@code null} separator is the same as an empty String ("").
    4664     * Null objects or empty strings within the array are represented by
    4665     * empty strings.</p>
    4666     *
    4667     * <pre>
    4668     * StringUtils.join(null, *)                = null
    4669     * StringUtils.join([], *)                  = ""
    4670     * StringUtils.join([null], *)              = ""
    4671     * StringUtils.join(["a", "b", "c"], "--")  = "a--b--c"
    4672     * StringUtils.join(["a", "b", "c"], null)  = "abc"
    4673     * StringUtils.join(["a", "b", "c"], "")    = "abc"
    4674     * StringUtils.join([null, "", "a"], ',')   = ",,a"
    4675     * </pre>
    4676     *
    4677     * @param array  the array of values to join together, may be null
    4678     * @param delimiter  the separator character to use, null treated as ""
    4679     * @return the joined String, {@code null} if null array input
    4680     */
    4681    public static String join(final Object[] array, final String delimiter) {
    4682        return array != null ? join(array, toStringOrEmpty(delimiter), 0, array.length) : null;
    4683    }
    4684
    4685    /**
    4686     * Joins the elements of the provided array into a single String
    4687     * containing the provided list of elements.
    4688     *
    4689     * <p>No delimiter is added before or after the list.
    4690     * A {@code null} separator is the same as an empty String ("").
    4691     * Null objects or empty strings within the array are represented by
    4692     * empty strings.</p>
    4693     *
    4694     * <pre>
    4695     * StringUtils.join(null, *, *, *)                = null
    4696     * StringUtils.join([], *, *, *)                  = ""
    4697     * StringUtils.join([null], *, *, *)              = ""
    4698     * StringUtils.join(["a", "b", "c"], "--", 0, 3)  = "a--b--c"
    4699     * StringUtils.join(["a", "b", "c"], "--", 1, 3)  = "b--c"
    4700     * StringUtils.join(["a", "b", "c"], "--", 2, 3)  = "c"
    4701     * StringUtils.join(["a", "b", "c"], "--", 2, 2)  = ""
    4702     * StringUtils.join(["a", "b", "c"], null, 0, 3)  = "abc"
    4703     * StringUtils.join(["a", "b", "c"], "", 0, 3)    = "abc"
    4704     * StringUtils.join([null, "", "a"], ',', 0, 3)   = ",,a"
    4705     * </pre>
    4706     *
    4707     * @param array  the array of values to join together, may be null
    4708     * @param delimiter  the separator character to use, null treated as ""
    4709     * @param startIndex the first index to start joining from.
    4710     * @param endIndex the index to stop joining from (exclusive).
    4711     * @return the joined String, {@code null} if null array input; or the empty string
    4712     * if {@code endIndex - startIndex <= 0}. The number of joined entries is given by
    4713     * {@code endIndex - startIndex}
    4714     * @throws ArrayIndexOutOfBoundsException ife<br>
    4715     * {@code startIndex < 0} or <br>
    4716     * {@code startIndex >= array.length()} or <br>
    4717     * {@code endIndex < 0} or <br>
    4718     * {@code endIndex > array.length()}
    4719     */
    4720    public static String join(final Object[] array, final String delimiter, final int startIndex, final int endIndex) {
    4721        return array != null ? Streams.of(array).skip(startIndex).limit(Math.max(0, endIndex - startIndex))
    4722            .collect(LangCollectors.joining(delimiter, EMPTY, EMPTY, StringUtils::toStringOrEmpty)) : null;
    4723    }
    4724
    4725    /**
    4726     * Joins the elements of the provided array into a single String containing the provided list of elements.
    4727     *
    4728     * <p>
    4729     * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
    4730     * by empty strings.
    4731     * </p>
    4732     *
    4733     * <pre>
    4734     * StringUtils.join(null, *)               = null
    4735     * StringUtils.join([], *)                 = ""
    4736     * StringUtils.join([null], *)             = ""
    4737     * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
    4738     * StringUtils.join([1, 2, 3], null) = "123"
    4739     * </pre>
    4740     *
    4741     * @param array
    4742     *            the array of values to join together, may be null
    4743     * @param delimiter
    4744     *            the separator character to use
    4745     * @return the joined String, {@code null} if null array input
    4746     * @since 3.2
    4747     */
    4748    public static String join(final short[] array, final char delimiter) {
    4749        if (array == null) {
    4750            return null;
    4751        }
    4752        return join(array, delimiter, 0, array.length);
    4753    }
    4754
    4755    /**
    4756     * Joins the elements of the provided array into a single String containing the provided list of elements.
    4757     *
    4758     * <p>
    4759     * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
    4760     * by empty strings.
    4761     * </p>
    4762     *
    4763     * <pre>
    4764     * StringUtils.join(null, *)               = null
    4765     * StringUtils.join([], *)                 = ""
    4766     * StringUtils.join([null], *)             = ""
    4767     * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
    4768     * StringUtils.join([1, 2, 3], null) = "123"
    4769     * </pre>
    4770     *
    4771     * @param array
    4772     *            the array of values to join together, may be null
    4773     * @param delimiter
    4774     *            the separator character to use
    4775     * @param startIndex
    4776     *            the first index to start joining from. It is an error to pass in a start index past the end of the
    4777     *            array
    4778     * @param endIndex
    4779     *            the index to stop joining from (exclusive). It is an error to pass in an end index past the end of
    4780     *            the array
    4781     * @return the joined String, {@code null} if null array input
    4782     * @since 3.2
    4783     */
    4784    public static String join(final short[] array, final char delimiter, final int startIndex, final int endIndex) {
    4785        if (array == null) {
    4786            return null;
    4787        }
    4788        if (endIndex - startIndex <= 0) {
    4789            return EMPTY;
    4790        }
    4791        final StringBuilder stringBuilder = new StringBuilder();
    4792        for (int i = startIndex; i < endIndex; i++) {
    4793            stringBuilder
    4794                    .append(array[i])
    4795                    .append(delimiter);
    4796        }
    4797        return stringBuilder.substring(0, stringBuilder.length() - 1);
    4798    }
    4799
    4800    /**
    4801     * Joins the elements of the provided array into a single String
    4802     * containing the provided list of elements.
    4803     *
    4804     * <p>No separator is added to the joined String.
    4805     * Null objects or empty strings within the array are represented by
    4806     * empty strings.</p>
    4807     *
    4808     * <pre>
    4809     * StringUtils.join(null)            = null
    4810     * StringUtils.join([])              = ""
    4811     * StringUtils.join([null])          = ""
    4812     * StringUtils.join(["a", "b", "c"]) = "abc"
    4813     * StringUtils.join([null, "", "a"]) = "a"
    4814     * </pre>
    4815     *
    4816     * @param <T> the specific type of values to join together
    4817     * @param elements  the values to join together, may be null
    4818     * @return the joined String, {@code null} if null array input
    4819     * @since 2.0
    4820     * @since 3.0 Changed signature to use varargs
    4821     */
    4822    @SafeVarargs
    4823    public static <T> String join(final T... elements) {
    4824        return join(elements, null);
    4825    }
    4826
    4827    /**
    4828     * Joins the elements of the provided varargs into a
    4829     * single String containing the provided elements.
    4830     *
    4831     * <p>No delimiter is added before or after the list.
    4832     * {@code null} elements and separator are treated as empty Strings ("").</p>
    4833     *
    4834     * <pre>
    4835     * StringUtils.joinWith(",", {"a", "b"})        = "a,b"
    4836     * StringUtils.joinWith(",", {"a", "b",""})     = "a,b,"
    4837     * StringUtils.joinWith(",", {"a", null, "b"})  = "a,,b"
    4838     * StringUtils.joinWith(null, {"a", "b"})       = "ab"
    4839     * </pre>
    4840     *
    4841     * @param delimiter the separator character to use, null treated as ""
    4842     * @param array the varargs providing the values to join together. {@code null} elements are treated as ""
    4843     * @return the joined String.
    4844     * @throws IllegalArgumentException if a null varargs is provided
    4845     * @since 3.5
    4846     */
    4847    public static String joinWith(final String delimiter, final Object... array) {
    4848        if (array == null) {
    4849            throw new IllegalArgumentException("Object varargs must not be null");
    4850        }
    4851        return join(array, delimiter);
    4852    }
    4853
    4854    /**
    4855     * Finds the last index within a CharSequence, handling {@code null}.
    4856     * This method uses {@link String#lastIndexOf(String)} if possible.
    4857     *
    4858     * <p>A {@code null} CharSequence will return {@code -1}.</p>
    4859     *
    4860     * <pre>
    4861     * StringUtils.lastIndexOf(null, *)          = -1
    4862     * StringUtils.lastIndexOf(*, null)          = -1
    4863     * StringUtils.lastIndexOf("", "")           = 0
    4864     * StringUtils.lastIndexOf("aabaabaa", "a")  = 7
    4865     * StringUtils.lastIndexOf("aabaabaa", "b")  = 5
    4866     * StringUtils.lastIndexOf("aabaabaa", "ab") = 4
    4867     * StringUtils.lastIndexOf("aabaabaa", "")   = 8
    4868     * </pre>
    4869     *
    4870     * @param seq  the CharSequence to check, may be null
    4871     * @param searchSeq  the CharSequence to find, may be null
    4872     * @return the last index of the search String,
    4873     *  -1 if no match or {@code null} string input
    4874     * @since 2.0
    4875     * @since 3.0 Changed signature from lastIndexOf(String, String) to lastIndexOf(CharSequence, CharSequence)
    4876     */
    4877    public static int lastIndexOf(final CharSequence seq, final CharSequence searchSeq) {
    4878        if (seq == null) {
    4879            return INDEX_NOT_FOUND;
    4880        }
    4881        return CharSequenceUtils.lastIndexOf(seq, searchSeq, seq.length());
    4882    }
    4883
    4884    /**
    4885     * Finds the last index within a CharSequence, handling {@code null}.
    4886     * This method uses {@link String#lastIndexOf(String, int)} if possible.
    4887     *
    4888     * <p>A {@code null} CharSequence will return {@code -1}.
    4889     * A negative start position returns {@code -1}.
    4890     * An empty ("") search CharSequence always matches unless the start position is negative.
    4891     * A start position greater than the string length searches the whole string.
    4892     * The search starts at the startPos and works backwards; matches starting after the start
    4893     * position are ignored.
    4894     * </p>
    4895     *
    4896     * <pre>
    4897     * StringUtils.lastIndexOf(null, *, *)          = -1
    4898     * StringUtils.lastIndexOf(*, null, *)          = -1
    4899     * StringUtils.lastIndexOf("aabaabaa", "a", 8)  = 7
    4900     * StringUtils.lastIndexOf("aabaabaa", "b", 8)  = 5
    4901     * StringUtils.lastIndexOf("aabaabaa", "ab", 8) = 4
    4902     * StringUtils.lastIndexOf("aabaabaa", "b", 9)  = 5
    4903     * StringUtils.lastIndexOf("aabaabaa", "b", -1) = -1
    4904     * StringUtils.lastIndexOf("aabaabaa", "a", 0)  = 0
    4905     * StringUtils.lastIndexOf("aabaabaa", "b", 0)  = -1
    4906     * StringUtils.lastIndexOf("aabaabaa", "b", 1)  = -1
    4907     * StringUtils.lastIndexOf("aabaabaa", "b", 2)  = 2
    4908     * StringUtils.lastIndexOf("aabaabaa", "ba", 2)  = 2
    4909     * </pre>
    4910     *
    4911     * @param seq  the CharSequence to check, may be null
    4912     * @param searchSeq  the CharSequence to find, may be null
    4913     * @param startPos  the start position, negative treated as zero
    4914     * @return the last index of the search CharSequence (always &le; startPos),
    4915     *  -1 if no match or {@code null} string input
    4916     * @since 2.0
    4917     * @since 3.0 Changed signature from lastIndexOf(String, String, int) to lastIndexOf(CharSequence, CharSequence, int)
    4918     */
    4919    public static int lastIndexOf(final CharSequence seq, final CharSequence searchSeq, final int startPos) {
    4920        return CharSequenceUtils.lastIndexOf(seq, searchSeq, startPos);
    4921    }
    4922
    4923    /**
    4924     * Returns the index within {@code seq} of the last occurrence of
    4925     * the specified character. For values of {@code searchChar} in the
    4926     * range from 0 to 0xFFFF (inclusive), the index (in Unicode code
    4927     * units) returned is the largest value <em>k</em> such that:
    4928     * <blockquote><pre>
    4929     * this.charAt(<em>k</em>) == searchChar
    4930     * </pre></blockquote>
    4931     * is true. For other values of {@code searchChar}, it is the
    4932     * largest value <em>k</em> such that:
    4933     * <blockquote><pre>
    4934     * this.codePointAt(<em>k</em>) == searchChar
    4935     * </pre></blockquote>
    4936     * is true.  In either case, if no such character occurs in this
    4937     * string, then {@code -1} is returned. Furthermore, a {@code null} or empty ("")
    4938     * {@link CharSequence} will return {@code -1}. The
    4939     * {@code seq} {@link CharSequence} object is searched backwards
    4940     * starting at the last character.
    4941     *
    4942     * <pre>
    4943     * StringUtils.lastIndexOf(null, *)         = -1
    4944     * StringUtils.lastIndexOf("", *)           = -1
    4945     * StringUtils.lastIndexOf("aabaabaa", 'a') = 7
    4946     * StringUtils.lastIndexOf("aabaabaa", 'b') = 5
    4947     * </pre>
    4948     *
    4949     * @param seq  the {@link CharSequence} to check, may be null
    4950     * @param searchChar  the character to find
    4951     * @return the last index of the search character,
    4952     *  -1 if no match or {@code null} string input
    4953     * @since 2.0
    4954     * @since 3.0 Changed signature from lastIndexOf(String, int) to lastIndexOf(CharSequence, int)
    4955     * @since 3.6 Updated {@link CharSequenceUtils} call to behave more like {@link String}
    4956     */
    4957    public static int lastIndexOf(final CharSequence seq, final int searchChar) {
    4958        if (isEmpty(seq)) {
    4959            return INDEX_NOT_FOUND;
    4960        }
    4961        return CharSequenceUtils.lastIndexOf(seq, searchChar, seq.length());
    4962    }
    4963
    4964    /**
    4965     * Returns the index within {@code seq} of the last occurrence of
    4966     * the specified character, searching backward starting at the
    4967     * specified index. For values of {@code searchChar} in the range
    4968     * from 0 to 0xFFFF (inclusive), the index returned is the largest
    4969     * value <em>k</em> such that:
    4970     * <blockquote><pre>
    4971     * (this.charAt(<em>k</em>) == searchChar) &amp;&amp; (<em>k</em> &lt;= startPos)
    4972     * </pre></blockquote>
    4973     * is true. For other values of {@code searchChar}, it is the
    4974     * largest value <em>k</em> such that:
    4975     * <blockquote><pre>
    4976     * (this.codePointAt(<em>k</em>) == searchChar) &amp;&amp; (<em>k</em> &lt;= startPos)
    4977     * </pre></blockquote>
    4978     * is true. In either case, if no such character occurs in {@code seq}
    4979     * at or before position {@code startPos}, then
    4980     * {@code -1} is returned. Furthermore, a {@code null} or empty ("")
    4981     * {@link CharSequence} will return {@code -1}. A start position greater
    4982     * than the string length searches the whole string.
    4983     * The search starts at the {@code startPos} and works backwards;
    4984     * matches starting after the start position are ignored.
    4985     *
    4986     * <p>All indices are specified in {@code char} values
    4987     * (Unicode code units).
    4988     *
    4989     * <pre>
    4990     * StringUtils.lastIndexOf(null, *, *)          = -1
    4991     * StringUtils.lastIndexOf("", *,  *)           = -1
    4992     * StringUtils.lastIndexOf("aabaabaa", 'b', 8)  = 5
    4993     * StringUtils.lastIndexOf("aabaabaa", 'b', 4)  = 2
    4994     * StringUtils.lastIndexOf("aabaabaa", 'b', 0)  = -1
    4995     * StringUtils.lastIndexOf("aabaabaa", 'b', 9)  = 5
    4996     * StringUtils.lastIndexOf("aabaabaa", 'b', -1) = -1
    4997     * StringUtils.lastIndexOf("aabaabaa", 'a', 0)  = 0
    4998     * </pre>
    4999     *
    5000     * @param seq  the CharSequence to check, may be null
    5001     * @param searchChar  the character to find
    5002     * @param startPos  the start position
    5003     * @return the last index of the search character (always &le; startPos),
    5004     *  -1 if no match or {@code null} string input
    5005     * @since 2.0
    5006     * @since 3.0 Changed signature from lastIndexOf(String, int, int) to lastIndexOf(CharSequence, int, int)
    5007     */
    5008    public static int lastIndexOf(final CharSequence seq, final int searchChar, final int startPos) {
    5009        if (isEmpty(seq)) {
    5010            return INDEX_NOT_FOUND;
    5011        }
    5012        return CharSequenceUtils.lastIndexOf(seq, searchChar, startPos);
    5013    }
    5014
    5015    /**
    5016     * Find the latest index of any substring in a set of potential substrings.
    5017     *
    5018     * <p>A {@code null} CharSequence will return {@code -1}.
    5019     * A {@code null} search array will return {@code -1}.
    5020     * A {@code null} or zero length search array entry will be ignored,
    5021     * but a search array containing "" will return the length of {@code str}
    5022     * if {@code str} is not null. This method uses {@link String#indexOf(String)} if possible</p>
    5023     *
    5024     * <pre>
    5025     * StringUtils.lastIndexOfAny(null, *)                    = -1
    5026     * StringUtils.lastIndexOfAny(*, null)                    = -1
    5027     * StringUtils.lastIndexOfAny(*, [])                      = -1
    5028     * StringUtils.lastIndexOfAny(*, [null])                  = -1
    5029     * StringUtils.lastIndexOfAny("zzabyycdxx", ["ab", "cd"]) = 6
    5030     * StringUtils.lastIndexOfAny("zzabyycdxx", ["cd", "ab"]) = 6
    5031     * StringUtils.lastIndexOfAny("zzabyycdxx", ["mn", "op"]) = -1
    5032     * StringUtils.lastIndexOfAny("zzabyycdxx", ["mn", "op"]) = -1
    5033     * StringUtils.lastIndexOfAny("zzabyycdxx", ["mn", ""])   = 10
    5034     * </pre>
    5035     *
    5036     * @param str  the CharSequence to check, may be null
    5037     * @param searchStrs  the CharSequences to search for, may be null
    5038     * @return the last index of any of the CharSequences, -1 if no match
    5039     * @since 3.0 Changed signature from lastIndexOfAny(String, String[]) to lastIndexOfAny(CharSequence, CharSequence)
    5040     */
    5041    public static int lastIndexOfAny(final CharSequence str, final CharSequence... searchStrs) {
    5042        if (str == null || searchStrs == null) {
    5043            return INDEX_NOT_FOUND;
    5044        }
    5045        int ret = INDEX_NOT_FOUND;
    5046        int tmp;
    5047        for (final CharSequence search : searchStrs) {
    5048            if (search == null) {
    5049                continue;
    5050            }
    5051            tmp = CharSequenceUtils.lastIndexOf(str, search, str.length());
    5052            if (tmp > ret) {
    5053                ret = tmp;
    5054            }
    5055        }
    5056        return ret;
    5057    }
    5058
    5059    /**
    5060     * Case in-sensitive find of the last index within a CharSequence.
    5061     *
    5062     * <p>A {@code null} CharSequence will return {@code -1}.
    5063     * A negative start position returns {@code -1}.
    5064     * An empty ("") search CharSequence always matches unless the start position is negative.
    5065     * A start position greater than the string length searches the whole string.</p>
    5066     *
    5067     * <pre>
    5068     * StringUtils.lastIndexOfIgnoreCase(null, *)          = -1
    5069     * StringUtils.lastIndexOfIgnoreCase(*, null)          = -1
    5070     * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "A")  = 7
    5071     * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B")  = 5
    5072     * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "AB") = 4
    5073     * </pre>
    5074     *
    5075     * @param str  the CharSequence to check, may be null
    5076     * @param searchStr  the CharSequence to find, may be null
    5077     * @return the first index of the search CharSequence,
    5078     *  -1 if no match or {@code null} string input
    5079     * @since 2.5
    5080     * @since 3.0 Changed signature from lastIndexOfIgnoreCase(String, String) to lastIndexOfIgnoreCase(CharSequence, CharSequence)
    5081     */
    5082    public static int lastIndexOfIgnoreCase(final CharSequence str, final CharSequence searchStr) {
    5083        if (str == null || searchStr == null) {
    5084            return INDEX_NOT_FOUND;
    5085        }
    5086        return lastIndexOfIgnoreCase(str, searchStr, str.length());
    5087    }
    5088
    5089    /**
    5090     * Case in-sensitive find of the last index within a CharSequence
    5091     * from the specified position.
    5092     *
    5093     * <p>A {@code null} CharSequence will return {@code -1}.
    5094     * A negative start position returns {@code -1}.
    5095     * An empty ("") search CharSequence always matches unless the start position is negative.
    5096     * A start position greater than the string length searches the whole string.
    5097     * The search starts at the startPos and works backwards; matches starting after the start
    5098     * position are ignored.
    5099     * </p>
    5100     *
    5101     * <pre>
    5102     * StringUtils.lastIndexOfIgnoreCase(null, *, *)          = -1
    5103     * StringUtils.lastIndexOfIgnoreCase(*, null, *)          = -1
    5104     * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "A", 8)  = 7
    5105     * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B", 8)  = 5
    5106     * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "AB", 8) = 4
    5107     * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B", 9)  = 5
    5108     * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B", -1) = -1
    5109     * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "A", 0)  = 0
    5110     * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B", 0)  = -1
    5111     * </pre>
    5112     *
    5113     * @param str  the CharSequence to check, may be null
    5114     * @param searchStr  the CharSequence to find, may be null
    5115     * @param startPos  the start position
    5116     * @return the last index of the search CharSequence (always &le; startPos),
    5117     *  -1 if no match or {@code null} input
    5118     * @since 2.5
    5119     * @since 3.0 Changed signature from lastIndexOfIgnoreCase(String, String, int) to lastIndexOfIgnoreCase(CharSequence, CharSequence, int)
    5120     */
    5121    public static int lastIndexOfIgnoreCase(final CharSequence str, final CharSequence searchStr, int startPos) {
    5122        if (str == null || searchStr == null) {
    5123            return INDEX_NOT_FOUND;
    5124        }
    5125        final int searchStrLength = searchStr.length();
    5126        final int strLength = str.length();
    5127        if (startPos > strLength - searchStrLength) {
    5128            startPos = strLength - searchStrLength;
    5129        }
    5130        if (startPos < 0) {
    5131            return INDEX_NOT_FOUND;
    5132        }
    5133        if (searchStrLength == 0) {
    5134            return startPos;
    5135        }
    5136
    5137        for (int i = startPos; i >= 0; i--) {
    5138            if (CharSequenceUtils.regionMatches(str, true, i, searchStr, 0, searchStrLength)) {
    5139                return i;
    5140            }
    5141        }
    5142        return INDEX_NOT_FOUND;
    5143    }
    5144
    5145    /**
    5146     * Finds the n-th last index within a String, handling {@code null}.
    5147     * This method uses {@link String#lastIndexOf(String)}.
    5148     *
    5149     * <p>A {@code null} String will return {@code -1}.</p>
    5150     *
    5151     * <pre>
    5152     * StringUtils.lastOrdinalIndexOf(null, *, *)          = -1
    5153     * StringUtils.lastOrdinalIndexOf(*, null, *)          = -1
    5154     * StringUtils.lastOrdinalIndexOf("", "", *)           = 0
    5155     * StringUtils.lastOrdinalIndexOf("aabaabaa", "a", 1)  = 7
    5156     * StringUtils.lastOrdinalIndexOf("aabaabaa", "a", 2)  = 6
    5157     * StringUtils.lastOrdinalIndexOf("aabaabaa", "b", 1)  = 5
    5158     * StringUtils.lastOrdinalIndexOf("aabaabaa", "b", 2)  = 2
    5159     * StringUtils.lastOrdinalIndexOf("aabaabaa", "ab", 1) = 4
    5160     * StringUtils.lastOrdinalIndexOf("aabaabaa", "ab", 2) = 1
    5161     * StringUtils.lastOrdinalIndexOf("aabaabaa", "", 1)   = 8
    5162     * StringUtils.lastOrdinalIndexOf("aabaabaa", "", 2)   = 8
    5163     * </pre>
    5164     *
    5165     * <p>Note that 'tail(CharSequence str, int n)' may be implemented as: </p>
    5166     *
    5167     * <pre>
    5168     *   str.substring(lastOrdinalIndexOf(str, "\n", n) + 1)
    5169     * </pre>
    5170     *
    5171     * @param str  the CharSequence to check, may be null
    5172     * @param searchStr  the CharSequence to find, may be null
    5173     * @param ordinal  the n-th last {@code searchStr} to find
    5174     * @return the n-th last index of the search CharSequence,
    5175     *  {@code -1} ({@code INDEX_NOT_FOUND}) if no match or {@code null} string input
    5176     * @since 2.5
    5177     * @since 3.0 Changed signature from lastOrdinalIndexOf(String, String, int) to lastOrdinalIndexOf(CharSequence, CharSequence, int)
    5178     */
    5179    public static int lastOrdinalIndexOf(final CharSequence str, final CharSequence searchStr, final int ordinal) {
    5180        return ordinalIndexOf(str, searchStr, ordinal, true);
    5181    }
    5182
    5183    /**
    5184     * Gets the leftmost {@code len} characters of a String.
    5185     *
    5186     * <p>If {@code len} characters are not available, or the
    5187     * String is {@code null}, the String will be returned without
    5188     * an exception. An empty String is returned if len is negative.</p>
    5189     *
    5190     * <pre>
    5191     * StringUtils.left(null, *)    = null
    5192     * StringUtils.left(*, -ve)     = ""
    5193     * StringUtils.left("", *)      = ""
    5194     * StringUtils.left("abc", 0)   = ""
    5195     * StringUtils.left("abc", 2)   = "ab"
    5196     * StringUtils.left("abc", 4)   = "abc"
    5197     * </pre>
    5198     *
    5199     * @param str  the String to get the leftmost characters from, may be null
    5200     * @param len  the length of the required String
    5201     * @return the leftmost characters, {@code null} if null String input
    5202     */
    5203    public static String left(final String str, final int len) {
    5204        if (str == null) {
    5205            return null;
    5206        }
    5207        if (len < 0) {
    5208            return EMPTY;
    5209        }
    5210        if (str.length() <= len) {
    5211            return str;
    5212        }
    5213        return str.substring(0, len);
    5214    }
    5215
    5216    /**
    5217     * Left pad a String with spaces (' ').
    5218     *
    5219     * <p>The String is padded to the size of {@code size}.</p>
    5220     *
    5221     * <pre>
    5222     * StringUtils.leftPad(null, *)   = null
    5223     * StringUtils.leftPad("", 3)     = "   "
    5224     * StringUtils.leftPad("bat", 3)  = "bat"
    5225     * StringUtils.leftPad("bat", 5)  = "  bat"
    5226     * StringUtils.leftPad("bat", 1)  = "bat"
    5227     * StringUtils.leftPad("bat", -1) = "bat"
    5228     * </pre>
    5229     *
    5230     * @param str  the String to pad out, may be null
    5231     * @param size  the size to pad to
    5232     * @return left padded String or original String if no padding is necessary,
    5233     *  {@code null} if null String input
    5234     */
    5235    public static String leftPad(final String str, final int size) {
    5236        return leftPad(str, size, ' ');
    5237    }
    5238
    5239    /**
    5240     * Left pad a String with a specified character.
    5241     *
    5242     * <p>Pad to a size of {@code size}.</p>
    5243     *
    5244     * <pre>
    5245     * StringUtils.leftPad(null, *, *)     = null
    5246     * StringUtils.leftPad("", 3, 'z')     = "zzz"
    5247     * StringUtils.leftPad("bat", 3, 'z')  = "bat"
    5248     * StringUtils.leftPad("bat", 5, 'z')  = "zzbat"
    5249     * StringUtils.leftPad("bat", 1, 'z')  = "bat"
    5250     * StringUtils.leftPad("bat", -1, 'z') = "bat"
    5251     * </pre>
    5252     *
    5253     * @param str  the String to pad out, may be null
    5254     * @param size  the size to pad to
    5255     * @param padChar  the character to pad with
    5256     * @return left padded String or original String if no padding is necessary,
    5257     *  {@code null} if null String input
    5258     * @since 2.0
    5259     */
    5260    public static String leftPad(final String str, final int size, final char padChar) {
    5261        if (str == null) {
    5262            return null;
    5263        }
    5264        final int pads = size - str.length();
    5265        if (pads <= 0) {
    5266            return str; // returns original String when possible
    5267        }
    5268        if (pads > PAD_LIMIT) {
    5269            return leftPad(str, size, String.valueOf(padChar));
    5270        }
    5271        return repeat(padChar, pads).concat(str);
    5272    }
    5273
    5274    /**
    5275     * Left pad a String with a specified String.
    5276     *
    5277     * <p>Pad to a size of {@code size}.</p>
    5278     *
    5279     * <pre>
    5280     * StringUtils.leftPad(null, *, *)      = null
    5281     * StringUtils.leftPad("", 3, "z")      = "zzz"
    5282     * StringUtils.leftPad("bat", 3, "yz")  = "bat"
    5283     * StringUtils.leftPad("bat", 5, "yz")  = "yzbat"
    5284     * StringUtils.leftPad("bat", 8, "yz")  = "yzyzybat"
    5285     * StringUtils.leftPad("bat", 1, "yz")  = "bat"
    5286     * StringUtils.leftPad("bat", -1, "yz") = "bat"
    5287     * StringUtils.leftPad("bat", 5, null)  = "  bat"
    5288     * StringUtils.leftPad("bat", 5, "")    = "  bat"
    5289     * </pre>
    5290     *
    5291     * @param str  the String to pad out, may be null
    5292     * @param size  the size to pad to
    5293     * @param padStr  the String to pad with, null or empty treated as single space
    5294     * @return left padded String or original String if no padding is necessary,
    5295     *  {@code null} if null String input
    5296     */
    5297    public static String leftPad(final String str, final int size, String padStr) {
    5298        if (str == null) {
    5299            return null;
    5300        }
    5301        if (isEmpty(padStr)) {
    5302            padStr = SPACE;
    5303        }
    5304        final int padLen = padStr.length();
    5305        final int strLen = str.length();
    5306        final int pads = size - strLen;
    5307        if (pads <= 0) {
    5308            return str; // returns original String when possible
    5309        }
    5310        if (padLen == 1 && pads <= PAD_LIMIT) {
    5311            return leftPad(str, size, padStr.charAt(0));
    5312        }
    5313
    5314        if (pads == padLen) {
    5315            return padStr.concat(str);
    5316        }
    5317        if (pads < padLen) {
    5318            return padStr.substring(0, pads).concat(str);
    5319        }
    5320        final char[] padding = new char[pads];
    5321        final char[] padChars = padStr.toCharArray();
    5322        for (int i = 0; i < pads; i++) {
    5323            padding[i] = padChars[i % padLen];
    5324        }
    5325        return new String(padding).concat(str);
    5326    }
    5327
    5328    /**
    5329     * Gets a CharSequence length or {@code 0} if the CharSequence is
    5330     * {@code null}.
    5331     *
    5332     * @param cs
    5333     *            a CharSequence or {@code null}
    5334     * @return CharSequence length or {@code 0} if the CharSequence is
    5335     *         {@code null}.
    5336     * @since 2.4
    5337     * @since 3.0 Changed signature from length(String) to length(CharSequence)
    5338     */
    5339    public static int length(final CharSequence cs) {
    5340        return cs == null ? 0 : cs.length();
    5341    }
    5342
    5343    /**
    5344     * Converts a String to lower case as per {@link String#toLowerCase()}.
    5345     *
    5346     * <p>A {@code null} input String returns {@code null}.</p>
    5347     *
    5348     * <pre>
    5349     * StringUtils.lowerCase(null)  = null
    5350     * StringUtils.lowerCase("")    = ""
    5351     * StringUtils.lowerCase("aBc") = "abc"
    5352     * </pre>
    5353     *
    5354     * <p><strong>Note:</strong> As described in the documentation for {@link String#toLowerCase()},
    5355     * the result of this method is affected by the current locale.
    5356     * For platform-independent case transformations, the method {@link #lowerCase(String, Locale)}
    5357     * should be used with a specific locale (e.g. {@link Locale#ENGLISH}).</p>
    5358     *
    5359     * @param str  the String to lower case, may be null
    5360     * @return the lower cased String, {@code null} if null String input
    5361     */
    5362    public static String lowerCase(final String str) {
    5363        if (str == null) {
    5364            return null;
    5365        }
    5366        return str.toLowerCase();
    5367    }
    5368
    5369    /**
    5370     * Converts a String to lower case as per {@link String#toLowerCase(Locale)}.
    5371     *
    5372     * <p>A {@code null} input String returns {@code null}.</p>
    5373     *
    5374     * <pre>
    5375     * StringUtils.lowerCase(null, Locale.ENGLISH)  = null
    5376     * StringUtils.lowerCase("", Locale.ENGLISH)    = ""
    5377     * StringUtils.lowerCase("aBc", Locale.ENGLISH) = "abc"
    5378     * </pre>
    5379     *
    5380     * @param str  the String to lower case, may be null
    5381     * @param locale  the locale that defines the case transformation rules, must not be null
    5382     * @return the lower cased String, {@code null} if null String input
    5383     * @since 2.5
    5384     */
    5385    public static String lowerCase(final String str, final Locale locale) {
    5386        if (str == null) {
    5387            return null;
    5388        }
    5389        return str.toLowerCase(LocaleUtils.toLocale(locale));
    5390    }
    5391
    5392    private static int[] matches(final CharSequence first, final CharSequence second) {
    5393        final CharSequence max;
    5394        final CharSequence min;
    5395        if (first.length() > second.length()) {
    5396            max = first;
    5397            min = second;
    5398        } else {
    5399            max = second;
    5400            min = first;
    5401        }
    5402        final int range = Math.max(max.length() / 2 - 1, 0);
    5403        final int[] matchIndexes = ArrayFill.fill(new int[min.length()], -1);
    5404        final boolean[] matchFlags = new boolean[max.length()];
    5405        int matches = 0;
    5406        for (int mi = 0; mi < min.length(); mi++) {
    5407            final char c1 = min.charAt(mi);
    5408            for (int xi = Math.max(mi - range, 0), xn = Math.min(mi + range + 1, max.length()); xi < xn; xi++) {
    5409                if (!matchFlags[xi] && c1 == max.charAt(xi)) {
    5410                    matchIndexes[mi] = xi;
    5411                    matchFlags[xi] = true;
    5412                    matches++;
    5413                    break;
    5414                }
    5415            }
    5416        }
    5417        final char[] ms1 = new char[matches];
    5418        final char[] ms2 = new char[matches];
    5419        for (int i = 0, si = 0; i < min.length(); i++) {
    5420            if (matchIndexes[i] != -1) {
    5421                ms1[si] = min.charAt(i);
    5422                si++;
    5423            }
    5424        }
    5425        for (int i = 0, si = 0; i < max.length(); i++) {
    5426            if (matchFlags[i]) {
    5427                ms2[si] = max.charAt(i);
    5428                si++;
    5429            }
    5430        }
    5431        int transpositions = 0;
    5432        for (int mi = 0; mi < ms1.length; mi++) {
    5433            if (ms1[mi] != ms2[mi]) {
    5434                transpositions++;
    5435            }
    5436        }
    5437        int prefix = 0;
    5438        for (int mi = 0; mi < min.length(); mi++) {
    5439            if (first.charAt(mi) != second.charAt(mi)) {
    5440                break;
    5441            }
    5442            prefix++;
    5443        }
    5444        return new int[] { matches, transpositions / 2, prefix, max.length() };
    5445    }
    5446
    5447    /**
    5448     * Gets {@code len} characters from the middle of a String.
    5449     *
    5450     * <p>If {@code len} characters are not available, the remainder
    5451     * of the String will be returned without an exception. If the
    5452     * String is {@code null}, {@code null} will be returned.
    5453     * An empty String is returned if len is negative or exceeds the
    5454     * length of {@code str}.</p>
    5455     *
    5456     * <pre>
    5457     * StringUtils.mid(null, *, *)    = null
    5458     * StringUtils.mid(*, *, -ve)     = ""
    5459     * StringUtils.mid("", 0, *)      = ""
    5460     * StringUtils.mid("abc", 0, 2)   = "ab"
    5461     * StringUtils.mid("abc", 0, 4)   = "abc"
    5462     * StringUtils.mid("abc", 2, 4)   = "c"
    5463     * StringUtils.mid("abc", 4, 2)   = ""
    5464     * StringUtils.mid("abc", -2, 2)  = "ab"
    5465     * </pre>
    5466     *
    5467     * @param str  the String to get the characters from, may be null
    5468     * @param pos  the position to start from, negative treated as zero
    5469     * @param len  the length of the required String
    5470     * @return the middle characters, {@code null} if null String input
    5471     */
    5472    public static String mid(final String str, int pos, final int len) {
    5473        if (str == null) {
    5474            return null;
    5475        }
    5476        if (len < 0 || pos > str.length()) {
    5477            return EMPTY;
    5478        }
    5479        if (pos < 0) {
    5480            pos = 0;
    5481        }
    5482        if (str.length() <= pos + len) {
    5483            return str.substring(pos);
    5484        }
    5485        return str.substring(pos, pos + len);
    5486    }
    5487
    5488    /**
    5489     * Similar to <a
    5490     * href="https://www.w3.org/TR/xpath/#function-normalize-space">https://www.w3.org/TR/xpath/#function-normalize
    5491     * -space</a>
    5492     *
    5493     * <p>
    5494     * The function returns the argument string with whitespace normalized by using
    5495     * {@code {@link #trim(String)}} to remove leading and trailing whitespace
    5496     * and then replacing sequences of whitespace characters by a single space.
    5497     * </p>
    5498     * In XML Whitespace characters are the same as those allowed by the <a
    5499     * href="https://www.w3.org/TR/REC-xml/#NT-S">S</a> production, which is S ::= (#x20 | #x9 | #xD | #xA)+
    5500     * <p>
    5501     * Java's regexp pattern \s defines whitespace as [ \t\n\x0B\f\r]
    5502     *
    5503     * <p>For reference:</p>
    5504     * <ul>
    5505     * <li>\x0B = vertical tab</li>
    5506     * <li>\f = #xC = form feed</li>
    5507     * <li>#x20 = space</li>
    5508     * <li>#x9 = \t</li>
    5509     * <li>#xA = \n</li>
    5510     * <li>#xD = \r</li>
    5511     * </ul>
    5512     *
    5513     * <p>
    5514     * The difference is that Java's whitespace includes vertical tab and form feed, which this functional will also
    5515     * normalize. Additionally {@code {@link #trim(String)}} removes control characters (char &lt;= 32) from both
    5516     * ends of this String.
    5517     * </p>
    5518     *
    5519     * @see Pattern
    5520     * @see #trim(String)
    5521     * @see <a
    5522     *      href="https://www.w3.org/TR/xpath/#function-normalize-space">https://www.w3.org/TR/xpath/#function-normalize-space</a>
    5523     * @param str the source String to normalize whitespaces from, may be null
    5524     * @return the modified string with whitespace normalized, {@code null} if null String input
    5525     *
    5526     * @since 3.0
    5527     */
    5528    public static String normalizeSpace(final String str) {
    5529        // LANG-1020: Improved performance significantly by normalizing manually instead of using regex
    5530        // See https://github.com/librucha/commons-lang-normalizespaces-benchmark for performance test
    5531        if (isEmpty(str)) {
    5532            return str;
    5533        }
    5534        final int size = str.length();
    5535        final char[] newChars = new char[size];
    5536        int count = 0;
    5537        int whitespacesCount = 0;
    5538        boolean startWhitespaces = true;
    5539        for (int i = 0; i < size; i++) {
    5540            final char actualChar = str.charAt(i);
    5541            final boolean isWhitespace = Character.isWhitespace(actualChar);
    5542            if (isWhitespace) {
    5543                if (whitespacesCount == 0 && !startWhitespaces) {
    5544                    newChars[count++] = SPACE.charAt(0);
    5545                }
    5546                whitespacesCount++;
    5547            } else {
    5548                startWhitespaces = false;
    5549                newChars[count++] = actualChar == 160 ? 32 : actualChar;
    5550                whitespacesCount = 0;
    5551            }
    5552        }
    5553        if (startWhitespaces) {
    5554            return EMPTY;
    5555        }
    5556        return new String(newChars, 0, count - (whitespacesCount > 0 ? 1 : 0)).trim();
    5557    }
    5558
    5559    /**
    5560     * Finds the n-th index within a CharSequence, handling {@code null}.
    5561     * This method uses {@link String#indexOf(String)} if possible.
    5562     * <p><b>Note:</b> The code starts looking for a match at the start of the target,
    5563     * incrementing the starting index by one after each successful match
    5564     * (unless {@code searchStr} is an empty string in which case the position
    5565     * is never incremented and {@code 0} is returned immediately).
    5566     * This means that matches may overlap.</p>
    5567     * <p>A {@code null} CharSequence will return {@code -1}.</p>
    5568     *
    5569     * <pre>
    5570     * StringUtils.ordinalIndexOf(null, *, *)          = -1
    5571     * StringUtils.ordinalIndexOf(*, null, *)          = -1
    5572     * StringUtils.ordinalIndexOf("", "", *)           = 0
    5573     * StringUtils.ordinalIndexOf("aabaabaa", "a", 1)  = 0
    5574     * StringUtils.ordinalIndexOf("aabaabaa", "a", 2)  = 1
    5575     * StringUtils.ordinalIndexOf("aabaabaa", "b", 1)  = 2
    5576     * StringUtils.ordinalIndexOf("aabaabaa", "b", 2)  = 5
    5577     * StringUtils.ordinalIndexOf("aabaabaa", "ab", 1) = 1
    5578     * StringUtils.ordinalIndexOf("aabaabaa", "ab", 2) = 4
    5579     * StringUtils.ordinalIndexOf("aabaabaa", "", 1)   = 0
    5580     * StringUtils.ordinalIndexOf("aabaabaa", "", 2)   = 0
    5581     * </pre>
    5582     *
    5583     * <p>Matches may overlap:</p>
    5584     * <pre>
    5585     * StringUtils.ordinalIndexOf("ababab", "aba", 1)   = 0
    5586     * StringUtils.ordinalIndexOf("ababab", "aba", 2)   = 2
    5587     * StringUtils.ordinalIndexOf("ababab", "aba", 3)   = -1
    5588     *
    5589     * StringUtils.ordinalIndexOf("abababab", "abab", 1) = 0
    5590     * StringUtils.ordinalIndexOf("abababab", "abab", 2) = 2
    5591     * StringUtils.ordinalIndexOf("abababab", "abab", 3) = 4
    5592     * StringUtils.ordinalIndexOf("abababab", "abab", 4) = -1
    5593     * </pre>
    5594     *
    5595     * <p>Note that 'head(CharSequence str, int n)' may be implemented as: </p>
    5596     *
    5597     * <pre>
    5598     *   str.substring(0, lastOrdinalIndexOf(str, "\n", n))
    5599     * </pre>
    5600     *
    5601     * @param str  the CharSequence to check, may be null
    5602     * @param searchStr  the CharSequence to find, may be null
    5603     * @param ordinal  the n-th {@code searchStr} to find
    5604     * @return the n-th index of the search CharSequence,
    5605     *  {@code -1} ({@code INDEX_NOT_FOUND}) if no match or {@code null} string input
    5606     * @since 2.1
    5607     * @since 3.0 Changed signature from ordinalIndexOf(String, String, int) to ordinalIndexOf(CharSequence, CharSequence, int)
    5608     */
    5609    public static int ordinalIndexOf(final CharSequence str, final CharSequence searchStr, final int ordinal) {
    5610        return ordinalIndexOf(str, searchStr, ordinal, false);
    5611    }
    5612
    5613    /**
    5614     * Finds the n-th index within a String, handling {@code null}.
    5615     * This method uses {@link String#indexOf(String)} if possible.
    5616     * <p>Note that matches may overlap<p>
    5617     *
    5618     * <p>A {@code null} CharSequence will return {@code -1}.</p>
    5619     *
    5620     * @param str  the CharSequence to check, may be null
    5621     * @param searchStr  the CharSequence to find, may be null
    5622     * @param ordinal  the n-th {@code searchStr} to find, overlapping matches are allowed.
    5623     * @param lastIndex true if lastOrdinalIndexOf() otherwise false if ordinalIndexOf()
    5624     * @return the n-th index of the search CharSequence,
    5625     *  {@code -1} ({@code INDEX_NOT_FOUND}) if no match or {@code null} string input
    5626     */
    5627    // Shared code between ordinalIndexOf(String, String, int) and lastOrdinalIndexOf(String, String, int)
    5628    private static int ordinalIndexOf(final CharSequence str, final CharSequence searchStr, final int ordinal, final boolean lastIndex) {
    5629        if (str == null || searchStr == null || ordinal <= 0) {
    5630            return INDEX_NOT_FOUND;
    5631        }
    5632        if (searchStr.length() == 0) {
    5633            return lastIndex ? str.length() : 0;
    5634        }
    5635        int found = 0;
    5636        // set the initial index beyond the end of the string
    5637        // this is to allow for the initial index decrement/increment
    5638        int index = lastIndex ? str.length() : INDEX_NOT_FOUND;
    5639        do {
    5640            if (lastIndex) {
    5641                index = CharSequenceUtils.lastIndexOf(str, searchStr, index - 1); // step backwards through string
    5642            } else {
    5643                index = CharSequenceUtils.indexOf(str, searchStr, index + 1); // step forwards through string
    5644            }
    5645            if (index < 0) {
    5646                return index;
    5647            }
    5648            found++;
    5649        } while (found < ordinal);
    5650        return index;
    5651    }
    5652
    5653    /**
    5654     * Overlays part of a String with another String.
    5655     *
    5656     * <p>A {@code null} string input returns {@code null}.
    5657     * A negative index is treated as zero.
    5658     * An index greater than the string length is treated as the string length.
    5659     * The start index is always the smaller of the two indices.</p>
    5660     *
    5661     * <pre>
    5662     * StringUtils.overlay(null, *, *, *)            = null
    5663     * StringUtils.overlay("", "abc", 0, 0)          = "abc"
    5664     * StringUtils.overlay("abcdef", null, 2, 4)     = "abef"
    5665     * StringUtils.overlay("abcdef", "", 2, 4)       = "abef"
    5666     * StringUtils.overlay("abcdef", "", 4, 2)       = "abef"
    5667     * StringUtils.overlay("abcdef", "zzzz", 2, 4)   = "abzzzzef"
    5668     * StringUtils.overlay("abcdef", "zzzz", 4, 2)   = "abzzzzef"
    5669     * StringUtils.overlay("abcdef", "zzzz", -1, 4)  = "zzzzef"
    5670     * StringUtils.overlay("abcdef", "zzzz", 2, 8)   = "abzzzz"
    5671     * StringUtils.overlay("abcdef", "zzzz", -2, -3) = "zzzzabcdef"
    5672     * StringUtils.overlay("abcdef", "zzzz", 8, 10)  = "abcdefzzzz"
    5673     * </pre>
    5674     *
    5675     * @param str  the String to do overlaying in, may be null
    5676     * @param overlay  the String to overlay, may be null
    5677     * @param start  the position to start overlaying at
    5678     * @param end  the position to stop overlaying before
    5679     * @return overlayed String, {@code null} if null String input
    5680     * @since 2.0
    5681     */
    5682    public static String overlay(final String str, String overlay, int start, int end) {
    5683        if (str == null) {
    5684            return null;
    5685        }
    5686        if (overlay == null) {
    5687            overlay = EMPTY;
    5688        }
    5689        final int len = str.length();
    5690        if (start < 0) {
    5691            start = 0;
    5692        }
    5693        if (start > len) {
    5694            start = len;
    5695        }
    5696        if (end < 0) {
    5697            end = 0;
    5698        }
    5699        if (end > len) {
    5700            end = len;
    5701        }
    5702        if (start > end) {
    5703            final int temp = start;
    5704            start = end;
    5705            end = temp;
    5706        }
    5707        return str.substring(0, start) +
    5708            overlay +
    5709            str.substring(end);
    5710    }
    5711
    5712    /**
    5713     * Prepends the prefix to the start of the string if the string does not
    5714     * already start with any of the prefixes.
    5715     *
    5716     * @param str The string.
    5717     * @param prefix The prefix to prepend to the start of the string.
    5718     * @param ignoreCase Indicates whether the compare should ignore case.
    5719     * @param prefixes Additional prefixes that are valid (optional).
    5720     *
    5721     * @return A new String if prefix was prepended, the same string otherwise.
    5722     */
    5723    private static String prependIfMissing(final String str, final CharSequence prefix, final boolean ignoreCase, final CharSequence... prefixes) {
    5724        if (str == null || isEmpty(prefix) || startsWith(str, prefix, ignoreCase)) {
    5725            return str;
    5726        }
    5727        if (ArrayUtils.isNotEmpty(prefixes)) {
    5728            for (final CharSequence p : prefixes) {
    5729                if (startsWith(str, p, ignoreCase)) {
    5730                    return str;
    5731                }
    5732            }
    5733        }
    5734        return prefix + str;
    5735    }
    5736
    5737    /**
    5738     * Prepends the prefix to the start of the string if the string does not
    5739     * already start with any of the prefixes.
    5740     *
    5741     * <pre>
    5742     * StringUtils.prependIfMissing(null, null) = null
    5743     * StringUtils.prependIfMissing("abc", null) = "abc"
    5744     * StringUtils.prependIfMissing("", "xyz") = "xyz"
    5745     * StringUtils.prependIfMissing("abc", "xyz") = "xyzabc"
    5746     * StringUtils.prependIfMissing("xyzabc", "xyz") = "xyzabc"
    5747     * StringUtils.prependIfMissing("XYZabc", "xyz") = "xyzXYZabc"
    5748     * </pre>
    5749     * <p>With additional prefixes,</p>
    5750     * <pre>
    5751     * StringUtils.prependIfMissing(null, null, null) = null
    5752     * StringUtils.prependIfMissing("abc", null, null) = "abc"
    5753     * StringUtils.prependIfMissing("", "xyz", null) = "xyz"
    5754     * StringUtils.prependIfMissing("abc", "xyz", new CharSequence[]{null}) = "xyzabc"
    5755     * StringUtils.prependIfMissing("abc", "xyz", "") = "abc"
    5756     * StringUtils.prependIfMissing("abc", "xyz", "mno") = "xyzabc"
    5757     * StringUtils.prependIfMissing("xyzabc", "xyz", "mno") = "xyzabc"
    5758     * StringUtils.prependIfMissing("mnoabc", "xyz", "mno") = "mnoabc"
    5759     * StringUtils.prependIfMissing("XYZabc", "xyz", "mno") = "xyzXYZabc"
    5760     * StringUtils.prependIfMissing("MNOabc", "xyz", "mno") = "xyzMNOabc"
    5761     * </pre>
    5762     *
    5763     * @param str The string.
    5764     * @param prefix The prefix to prepend to the start of the string.
    5765     * @param prefixes Additional prefixes that are valid.
    5766     *
    5767     * @return A new String if prefix was prepended, the same string otherwise.
    5768     *
    5769     * @since 3.2
    5770     */
    5771    public static String prependIfMissing(final String str, final CharSequence prefix, final CharSequence... prefixes) {
    5772        return prependIfMissing(str, prefix, false, prefixes);
    5773    }
    5774
    5775    /**
    5776     * Prepends the prefix to the start of the string if the string does not
    5777     * already start, case-insensitive, with any of the prefixes.
    5778     *
    5779     * <pre>
    5780     * StringUtils.prependIfMissingIgnoreCase(null, null) = null
    5781     * StringUtils.prependIfMissingIgnoreCase("abc", null) = "abc"
    5782     * StringUtils.prependIfMissingIgnoreCase("", "xyz") = "xyz"
    5783     * StringUtils.prependIfMissingIgnoreCase("abc", "xyz") = "xyzabc"
    5784     * StringUtils.prependIfMissingIgnoreCase("xyzabc", "xyz") = "xyzabc"
    5785     * StringUtils.prependIfMissingIgnoreCase("XYZabc", "xyz") = "XYZabc"
    5786     * </pre>
    5787     * <p>With additional prefixes,</p>
    5788     * <pre>
    5789     * StringUtils.prependIfMissingIgnoreCase(null, null, null) = null
    5790     * StringUtils.prependIfMissingIgnoreCase("abc", null, null) = "abc"
    5791     * StringUtils.prependIfMissingIgnoreCase("", "xyz", null) = "xyz"
    5792     * StringUtils.prependIfMissingIgnoreCase("abc", "xyz", new CharSequence[]{null}) = "xyzabc"
    5793     * StringUtils.prependIfMissingIgnoreCase("abc", "xyz", "") = "abc"
    5794     * StringUtils.prependIfMissingIgnoreCase("abc", "xyz", "mno") = "xyzabc"
    5795     * StringUtils.prependIfMissingIgnoreCase("xyzabc", "xyz", "mno") = "xyzabc"
    5796     * StringUtils.prependIfMissingIgnoreCase("mnoabc", "xyz", "mno") = "mnoabc"
    5797     * StringUtils.prependIfMissingIgnoreCase("XYZabc", "xyz", "mno") = "XYZabc"
    5798     * StringUtils.prependIfMissingIgnoreCase("MNOabc", "xyz", "mno") = "MNOabc"
    5799     * </pre>
    5800     *
    5801     * @param str The string.
    5802     * @param prefix The prefix to prepend to the start of the string.
    5803     * @param prefixes Additional prefixes that are valid (optional).
    5804     *
    5805     * @return A new String if prefix was prepended, the same string otherwise.
    5806     *
    5807     * @since 3.2
    5808     */
    5809    public static String prependIfMissingIgnoreCase(final String str, final CharSequence prefix, final CharSequence... prefixes) {
    5810        return prependIfMissing(str, prefix, true, prefixes);
    5811    }
    5812
    5813    /**
    5814     * Removes all occurrences of a character from within the source string.
    5815     *
    5816     * <p>A {@code null} source string will return {@code null}.
    5817     * An empty ("") source string will return the empty string.</p>
    5818     *
    5819     * <pre>
    5820     * StringUtils.remove(null, *)       = null
    5821     * StringUtils.remove("", *)         = ""
    5822     * StringUtils.remove("queued", 'u') = "qeed"
    5823     * StringUtils.remove("queued", 'z') = "queued"
    5824     * </pre>
    5825     *
    5826     * @param str  the source String to search, may be null
    5827     * @param remove  the char to search for and remove, may be null
    5828     * @return the substring with the char removed if found,
    5829     *  {@code null} if null String input
    5830     * @since 2.1
    5831     */
    5832    public static String remove(final String str, final char remove) {
    5833        if (isEmpty(str) || str.indexOf(remove) == INDEX_NOT_FOUND) {
    5834            return str;
    5835        }
    5836        final char[] chars = str.toCharArray();
    5837        int pos = 0;
    5838        for (int i = 0; i < chars.length; i++) {
    5839            if (chars[i] != remove) {
    5840                chars[pos++] = chars[i];
    5841            }
    5842        }
    5843        return new String(chars, 0, pos);
    5844    }
    5845
    5846    /**
    5847     * Removes all occurrences of a substring from within the source string.
    5848     *
    5849     * <p>A {@code null} source string will return {@code null}.
    5850     * An empty ("") source string will return the empty string.
    5851     * A {@code null} remove string will return the source string.
    5852     * An empty ("") remove string will return the source string.</p>
    5853     *
    5854     * <pre>
    5855     * StringUtils.remove(null, *)        = null
    5856     * StringUtils.remove("", *)          = ""
    5857     * StringUtils.remove(*, null)        = *
    5858     * StringUtils.remove(*, "")          = *
    5859     * StringUtils.remove("queued", "ue") = "qd"
    5860     * StringUtils.remove("queued", "zz") = "queued"
    5861     * </pre>
    5862     *
    5863     * @param str  the source String to search, may be null
    5864     * @param remove  the String to search for and remove, may be null
    5865     * @return the substring with the string removed if found,
    5866     *  {@code null} if null String input
    5867     * @since 2.1
    5868     */
    5869    public static String remove(final String str, final String remove) {
    5870        if (isEmpty(str) || isEmpty(remove)) {
    5871            return str;
    5872        }
    5873        return replace(str, remove, EMPTY, -1);
    5874    }
    5875
    5876    /**
    5877     * Removes each substring of the text String that matches the given regular expression.
    5878     *
    5879     * This method is a {@code null} safe equivalent to:
    5880     * <ul>
    5881     *  <li>{@code text.replaceAll(regex, StringUtils.EMPTY)}</li>
    5882     *  <li>{@code Pattern.compile(regex).matcher(text).replaceAll(StringUtils.EMPTY)}</li>
    5883     * </ul>
    5884     *
    5885     * <p>A {@code null} reference passed to this method is a no-op.</p>
    5886     *
    5887     * <p>Unlike in the {@link #removePattern(String, String)} method, the {@link Pattern#DOTALL} option
    5888     * is NOT automatically added.
    5889     * To use the DOTALL option prepend {@code "(?s)"} to the regex.
    5890     * DOTALL is also known as single-line mode in Perl.</p>
    5891     *
    5892     * <pre>{@code
    5893     * StringUtils.removeAll(null, *)      = null
    5894     * StringUtils.removeAll("any", (String) null)  = "any"
    5895     * StringUtils.removeAll("any", "")    = "any"
    5896     * StringUtils.removeAll("any", ".*")  = ""
    5897     * StringUtils.removeAll("any", ".+")  = ""
    5898     * StringUtils.removeAll("abc", ".?")  = ""
    5899     * StringUtils.removeAll("A<__>\n<__>B", "<.*>")      = "A\nB"
    5900     * StringUtils.removeAll("A<__>\n<__>B", "(?s)<.*>")  = "AB"
    5901     * StringUtils.removeAll("ABCabc123abc", "[a-z]")     = "ABC123"
    5902     * }</pre>
    5903     *
    5904     * @param text  text to remove from, may be null
    5905     * @param regex  the regular expression to which this string is to be matched
    5906     * @return  the text with any removes processed,
    5907     *              {@code null} if null String input
    5908     *
    5909     * @throws  java.util.regex.PatternSyntaxException
    5910     *              if the regular expression's syntax is invalid
    5911     *
    5912     * @see #replaceAll(String, String, String)
    5913     * @see #removePattern(String, String)
    5914     * @see String#replaceAll(String, String)
    5915     * @see java.util.regex.Pattern
    5916     * @see java.util.regex.Pattern#DOTALL
    5917     * @since 3.5
    5918     *
    5919     * @deprecated Moved to RegExUtils.
    5920     */
    5921    @Deprecated
    5922    public static String removeAll(final String text, final String regex) {
    5923        return RegExUtils.removeAll(text, regex);
    5924    }
    5925
    5926    /**
    5927     * Removes a substring only if it is at the end of a source string,
    5928     * otherwise returns the source string.
    5929     *
    5930     * <p>A {@code null} source string will return {@code null}.
    5931     * An empty ("") source string will return the empty string.
    5932     * A {@code null} search string will return the source string.</p>
    5933     *
    5934     * <pre>
    5935     * StringUtils.removeEnd(null, *)      = null
    5936     * StringUtils.removeEnd("", *)        = ""
    5937     * StringUtils.removeEnd(*, null)      = *
    5938     * StringUtils.removeEnd("www.domain.com", ".com.")  = "www.domain.com"
    5939     * StringUtils.removeEnd("www.domain.com", ".com")   = "www.domain"
    5940     * StringUtils.removeEnd("www.domain.com", "domain") = "www.domain.com"
    5941     * StringUtils.removeEnd("abc", "")    = "abc"
    5942     * </pre>
    5943     *
    5944     * @param str  the source String to search, may be null
    5945     * @param remove  the String to search for and remove, may be null
    5946     * @return the substring with the string removed if found,
    5947     *  {@code null} if null String input
    5948     * @since 2.1
    5949     */
    5950    public static String removeEnd(final String str, final String remove) {
    5951        if (isEmpty(str) || isEmpty(remove)) {
    5952            return str;
    5953        }
    5954        if (str.endsWith(remove)) {
    5955            return str.substring(0, str.length() - remove.length());
    5956        }
    5957        return str;
    5958    }
    5959
    5960    /**
    5961     * Case-insensitive removal of a substring if it is at the end of a source string,
    5962     * otherwise returns the source string.
    5963     *
    5964     * <p>A {@code null} source string will return {@code null}.
    5965     * An empty ("") source string will return the empty string.
    5966     * A {@code null} search string will return the source string.</p>
    5967     *
    5968     * <pre>
    5969     * StringUtils.removeEndIgnoreCase(null, *)      = null
    5970     * StringUtils.removeEndIgnoreCase("", *)        = ""
    5971     * StringUtils.removeEndIgnoreCase(*, null)      = *
    5972     * StringUtils.removeEndIgnoreCase("www.domain.com", ".com.")  = "www.domain.com"
    5973     * StringUtils.removeEndIgnoreCase("www.domain.com", ".com")   = "www.domain"
    5974     * StringUtils.removeEndIgnoreCase("www.domain.com", "domain") = "www.domain.com"
    5975     * StringUtils.removeEndIgnoreCase("abc", "")    = "abc"
    5976     * StringUtils.removeEndIgnoreCase("www.domain.com", ".COM") = "www.domain")
    5977     * StringUtils.removeEndIgnoreCase("www.domain.COM", ".com") = "www.domain")
    5978     * </pre>
    5979     *
    5980     * @param str  the source String to search, may be null
    5981     * @param remove  the String to search for (case-insensitive) and remove, may be null
    5982     * @return the substring with the string removed if found,
    5983     *  {@code null} if null String input
    5984     * @since 2.4
    5985     */
    5986    public static String removeEndIgnoreCase(final String str, final String remove) {
    5987        if (isEmpty(str) || isEmpty(remove)) {
    5988            return str;
    5989        }
    5990        if (endsWithIgnoreCase(str, remove)) {
    5991            return str.substring(0, str.length() - remove.length());
    5992        }
    5993        return str;
    5994    }
    5995
    5996    /**
    5997     * Removes the first substring of the text string that matches the given regular expression.
    5998     *
    5999     * This method is a {@code null} safe equivalent to:
    6000     * <ul>
    6001     *  <li>{@code text.replaceFirst(regex, StringUtils.EMPTY)}</li>
    6002     *  <li>{@code Pattern.compile(regex).matcher(text).replaceFirst(StringUtils.EMPTY)}</li>
    6003     * </ul>
    6004     *
    6005     * <p>A {@code null} reference passed to this method is a no-op.</p>
    6006     *
    6007     * <p>The {@link Pattern#DOTALL} option is NOT automatically added.
    6008     * To use the DOTALL option prepend {@code "(?s)"} to the regex.
    6009     * DOTALL is also known as single-line mode in Perl.</p>
    6010     *
    6011     * <pre>{@code
    6012     * StringUtils.removeFirst(null, *)      = null
    6013     * StringUtils.removeFirst("any", (String) null)  = "any"
    6014     * StringUtils.removeFirst("any", "")    = "any"
    6015     * StringUtils.removeFirst("any", ".*")  = ""
    6016     * StringUtils.removeFirst("any", ".+")  = ""
    6017     * StringUtils.removeFirst("abc", ".?")  = "bc"
    6018     * StringUtils.removeFirst("A<__>\n<__>B", "<.*>")      = "A\n<__>B"
    6019     * StringUtils.removeFirst("A<__>\n<__>B", "(?s)<.*>")  = "AB"
    6020     * StringUtils.removeFirst("ABCabc123", "[a-z]")          = "ABCbc123"
    6021     * StringUtils.removeFirst("ABCabc123abc", "[a-z]+")      = "ABC123abc"
    6022     * }</pre>
    6023     *
    6024     * @param text  text to remove from, may be null
    6025     * @param regex  the regular expression to which this string is to be matched
    6026     * @return  the text with the first replacement processed,
    6027     *              {@code null} if null String input
    6028     *
    6029     * @throws  java.util.regex.PatternSyntaxException
    6030     *              if the regular expression's syntax is invalid
    6031     *
    6032     * @see #replaceFirst(String, String, String)
    6033     * @see String#replaceFirst(String, String)
    6034     * @see java.util.regex.Pattern
    6035     * @see java.util.regex.Pattern#DOTALL
    6036     * @since 3.5
    6037     *
    6038     * @deprecated Moved to RegExUtils.
    6039     */
    6040    @Deprecated
    6041    public static String removeFirst(final String text, final String regex) {
    6042        return replaceFirst(text, regex, EMPTY);
    6043    }
    6044
    6045    /**
    6046     * Case-insensitive removal of all occurrences of a substring from within
    6047     * the source string.
    6048     *
    6049     * <p>
    6050     * A {@code null} source string will return {@code null}. An empty ("")
    6051     * source string will return the empty string. A {@code null} remove string
    6052     * will return the source string. An empty ("") remove string will return
    6053     * the source string.
    6054     * </p>
    6055     *
    6056     * <pre>
    6057     * StringUtils.removeIgnoreCase(null, *)        = null
    6058     * StringUtils.removeIgnoreCase("", *)          = ""
    6059     * StringUtils.removeIgnoreCase(*, null)        = *
    6060     * StringUtils.removeIgnoreCase(*, "")          = *
    6061     * StringUtils.removeIgnoreCase("queued", "ue") = "qd"
    6062     * StringUtils.removeIgnoreCase("queued", "zz") = "queued"
    6063     * StringUtils.removeIgnoreCase("quEUed", "UE") = "qd"
    6064     * StringUtils.removeIgnoreCase("queued", "zZ") = "queued"
    6065     * </pre>
    6066     *
    6067     * @param str
    6068     *            the source String to search, may be null
    6069     * @param remove
    6070     *            the String to search for (case-insensitive) and remove, may be
    6071     *            null
    6072     * @return the substring with the string removed if found, {@code null} if
    6073     *         null String input
    6074     * @since 3.5
    6075     */
    6076    public static String removeIgnoreCase(final String str, final String remove) {
    6077        return replaceIgnoreCase(str, remove, EMPTY, -1);
    6078    }
    6079
    6080    /**
    6081     * Removes each substring of the source String that matches the given regular expression using the DOTALL option.
    6082     *
    6083     * This call is a {@code null} safe equivalent to:
    6084     * <ul>
    6085     * <li>{@code source.replaceAll(&quot;(?s)&quot; + regex, StringUtils.EMPTY)}</li>
    6086     * <li>{@code Pattern.compile(regex, Pattern.DOTALL).matcher(source).replaceAll(StringUtils.EMPTY)}</li>
    6087     * </ul>
    6088     *
    6089     * <p>A {@code null} reference passed to this method is a no-op.</p>
    6090     *
    6091     * <pre>{@code
    6092     * StringUtils.removePattern(null, *)       = null
    6093     * StringUtils.removePattern("any", (String) null)   = "any"
    6094     * StringUtils.removePattern("A<__>\n<__>B", "<.*>")  = "AB"
    6095     * StringUtils.removePattern("ABCabc123", "[a-z]")    = "ABC123"
    6096     * }</pre>
    6097     *
    6098     * @param source
    6099     *            the source string
    6100     * @param regex
    6101     *            the regular expression to which this string is to be matched
    6102     * @return The resulting {@link String}
    6103     * @see #replacePattern(String, String, String)
    6104     * @see String#replaceAll(String, String)
    6105     * @see Pattern#DOTALL
    6106     * @since 3.2
    6107     * @since 3.5 Changed {@code null} reference passed to this method is a no-op.
    6108     *
    6109     * @deprecated Moved to RegExUtils.
    6110     */
    6111    @Deprecated
    6112    public static String removePattern(final String source, final String regex) {
    6113        return RegExUtils.removePattern(source, regex);
    6114    }
    6115
    6116    /**
    6117     * Removes a char only if it is at the beginning of a source string,
    6118     * otherwise returns the source string.
    6119     *
    6120     * <p>A {@code null} source string will return {@code null}.
    6121     * An empty ("") source string will return the empty string.
    6122     * A {@code null} search char will return the source string.</p>
    6123     *
    6124     * <pre>
    6125     * StringUtils.removeStart(null, *)      = null
    6126     * StringUtils.removeStart("", *)        = ""
    6127     * StringUtils.removeStart(*, null)      = *
    6128     * StringUtils.removeStart("/path", '/') = "path"
    6129     * StringUtils.removeStart("path", '/')  = "path"
    6130     * StringUtils.removeStart("path", 0)    = "path"
    6131     * </pre>
    6132     *
    6133     * @param str  the source String to search, may be null.
    6134     * @param remove  the char to search for and remove.
    6135     * @return the substring with the char removed if found,
    6136     *  {@code null} if null String input.
    6137     * @since 3.13.0
    6138     */
    6139    public static String removeStart(final String str, final char remove) {
    6140        if (isEmpty(str)) {
    6141            return str;
    6142        }
    6143        return str.charAt(0) == remove ? str.substring(1) : str;
    6144    }
    6145
    6146    /**
    6147     * Removes a substring only if it is at the beginning of a source string,
    6148     * otherwise returns the source string.
    6149     *
    6150     * <p>A {@code null} source string will return {@code null}.
    6151     * An empty ("") source string will return the empty string.
    6152     * A {@code null} search string will return the source string.</p>
    6153     *
    6154     * <pre>
    6155     * StringUtils.removeStart(null, *)      = null
    6156     * StringUtils.removeStart("", *)        = ""
    6157     * StringUtils.removeStart(*, null)      = *
    6158     * StringUtils.removeStart("www.domain.com", "www.")   = "domain.com"
    6159     * StringUtils.removeStart("domain.com", "www.")       = "domain.com"
    6160     * StringUtils.removeStart("www.domain.com", "domain") = "www.domain.com"
    6161     * StringUtils.removeStart("abc", "")    = "abc"
    6162     * </pre>
    6163     *
    6164     * @param str  the source String to search, may be null
    6165     * @param remove  the String to search for and remove, may be null
    6166     * @return the substring with the string removed if found,
    6167     *  {@code null} if null String input
    6168     * @since 2.1
    6169     */
    6170    public static String removeStart(final String str, final String remove) {
    6171        if (isEmpty(str) || isEmpty(remove)) {
    6172            return str;
    6173        }
    6174        if (str.startsWith(remove)) {
    6175            return str.substring(remove.length());
    6176        }
    6177        return str;
    6178    }
    6179
    6180    /**
    6181     * Case-insensitive removal of a substring if it is at the beginning of a source string,
    6182     * otherwise returns the source string.
    6183     *
    6184     * <p>A {@code null} source string will return {@code null}.
    6185     * An empty ("") source string will return the empty string.
    6186     * A {@code null} search string will return the source string.</p>
    6187     *
    6188     * <pre>
    6189     * StringUtils.removeStartIgnoreCase(null, *)      = null
    6190     * StringUtils.removeStartIgnoreCase("", *)        = ""
    6191     * StringUtils.removeStartIgnoreCase(*, null)      = *
    6192     * StringUtils.removeStartIgnoreCase("www.domain.com", "www.")   = "domain.com"
    6193     * StringUtils.removeStartIgnoreCase("www.domain.com", "WWW.")   = "domain.com"
    6194     * StringUtils.removeStartIgnoreCase("domain.com", "www.")       = "domain.com"
    6195     * StringUtils.removeStartIgnoreCase("www.domain.com", "domain") = "www.domain.com"
    6196     * StringUtils.removeStartIgnoreCase("abc", "")    = "abc"
    6197     * </pre>
    6198     *
    6199     * @param str  the source String to search, may be null
    6200     * @param remove  the String to search for (case-insensitive) and remove, may be null
    6201     * @return the substring with the string removed if found,
    6202     *  {@code null} if null String input
    6203     * @since 2.4
    6204     */
    6205    public static String removeStartIgnoreCase(final String str, final String remove) {
    6206        if (str != null && startsWithIgnoreCase(str, remove)) {
    6207            return str.substring(length(remove));
    6208        }
    6209        return str;
    6210    }
    6211
    6212    /**
    6213     * Returns padding using the specified delimiter repeated
    6214     * to a given length.
    6215     *
    6216     * <pre>
    6217     * StringUtils.repeat('e', 0)  = ""
    6218     * StringUtils.repeat('e', 3)  = "eee"
    6219     * StringUtils.repeat('e', -2) = ""
    6220     * </pre>
    6221     *
    6222     * <p>Note: this method does not support padding with
    6223     * <a href="https://www.unicode.org/glossary/#supplementary_character">Unicode Supplementary Characters</a>
    6224     * as they require a pair of {@code char}s to be represented.
    6225     * If you are needing to support full I18N of your applications
    6226     * consider using {@link #repeat(String, int)} instead.
    6227     * </p>
    6228     *
    6229     * @param ch  character to repeat
    6230     * @param repeat  number of times to repeat char, negative treated as zero
    6231     * @return String with repeated character
    6232     * @see #repeat(String, int)
    6233     */
    6234    public static String repeat(final char ch, final int repeat) {
    6235        if (repeat <= 0) {
    6236            return EMPTY;
    6237        }
    6238        return new String(ArrayFill.fill(new char[repeat], ch));
    6239    }
    6240
    6241    /**
    6242     * Repeat a String {@code repeat} times to form a
    6243     * new String.
    6244     *
    6245     * <pre>
    6246     * StringUtils.repeat(null, 2) = null
    6247     * StringUtils.repeat("", 0)   = ""
    6248     * StringUtils.repeat("", 2)   = ""
    6249     * StringUtils.repeat("a", 3)  = "aaa"
    6250     * StringUtils.repeat("ab", 2) = "abab"
    6251     * StringUtils.repeat("a", -2) = ""
    6252     * </pre>
    6253     *
    6254     * @param str  the String to repeat, may be null
    6255     * @param repeat  number of times to repeat str, negative treated as zero
    6256     * @return a new String consisting of the original String repeated,
    6257     *  {@code null} if null String input
    6258     */
    6259    public static String repeat(final String str, final int repeat) {
    6260        // Performance tuned for 2.0 (JDK1.4)
    6261        if (str == null) {
    6262            return null;
    6263        }
    6264        if (repeat <= 0) {
    6265            return EMPTY;
    6266        }
    6267        final int inputLength = str.length();
    6268        if (repeat == 1 || inputLength == 0) {
    6269            return str;
    6270        }
    6271        if (inputLength == 1 && repeat <= PAD_LIMIT) {
    6272            return repeat(str.charAt(0), repeat);
    6273        }
    6274
    6275        final int outputLength = inputLength * repeat;
    6276        switch (inputLength) {
    6277            case 1 :
    6278                return repeat(str.charAt(0), repeat);
    6279            case 2 :
    6280                final char ch0 = str.charAt(0);
    6281                final char ch1 = str.charAt(1);
    6282                final char[] output2 = new char[outputLength];
    6283                for (int i = repeat * 2 - 2; i >= 0; i--, i--) {
    6284                    output2[i] = ch0;
    6285                    output2[i + 1] = ch1;
    6286                }
    6287                return new String(output2);
    6288            default :
    6289                final StringBuilder buf = new StringBuilder(outputLength);
    6290                for (int i = 0; i < repeat; i++) {
    6291                    buf.append(str);
    6292                }
    6293                return buf.toString();
    6294        }
    6295    }
    6296
    6297    /**
    6298     * Repeat a String {@code repeat} times to form a
    6299     * new String, with a String separator injected each time.
    6300     *
    6301     * <pre>
    6302     * StringUtils.repeat(null, null, 2) = null
    6303     * StringUtils.repeat(null, "x", 2)  = null
    6304     * StringUtils.repeat("", null, 0)   = ""
    6305     * StringUtils.repeat("", "", 2)     = ""
    6306     * StringUtils.repeat("", "x", 3)    = "xx"
    6307     * StringUtils.repeat("?", ", ", 3)  = "?, ?, ?"
    6308     * </pre>
    6309     *
    6310     * @param str        the String to repeat, may be null
    6311     * @param separator  the String to inject, may be null
    6312     * @param repeat     number of times to repeat str, negative treated as zero
    6313     * @return a new String consisting of the original String repeated,
    6314     *  {@code null} if null String input
    6315     * @since 2.5
    6316     */
    6317    public static String repeat(final String str, final String separator, final int repeat) {
    6318        if (str == null || separator == null) {
    6319            return repeat(str, repeat);
    6320        }
    6321        // given that repeat(String, int) is quite optimized, better to rely on it than try and splice this into it
    6322        final String result = repeat(str + separator, repeat);
    6323        return removeEnd(result, separator);
    6324    }
    6325
    6326    /**
    6327     * Replaces all occurrences of a String within another String.
    6328     *
    6329     * <p>A {@code null} reference passed to this method is a no-op.</p>
    6330     *
    6331     * <pre>
    6332     * StringUtils.replace(null, *, *)        = null
    6333     * StringUtils.replace("", *, *)          = ""
    6334     * StringUtils.replace("any", null, *)    = "any"
    6335     * StringUtils.replace("any", *, null)    = "any"
    6336     * StringUtils.replace("any", "", *)      = "any"
    6337     * StringUtils.replace("aba", "a", null)  = "aba"
    6338     * StringUtils.replace("aba", "a", "")    = "b"
    6339     * StringUtils.replace("aba", "a", "z")   = "zbz"
    6340     * </pre>
    6341     *
    6342     * @see #replace(String text, String searchString, String replacement, int max)
    6343     * @param text  text to search and replace in, may be null
    6344     * @param searchString  the String to search for, may be null
    6345     * @param replacement  the String to replace it with, may be null
    6346     * @return the text with any replacements processed,
    6347     *  {@code null} if null String input
    6348     */
    6349    public static String replace(final String text, final String searchString, final String replacement) {
    6350        return replace(text, searchString, replacement, -1);
    6351    }
    6352
    6353    /**
    6354     * Replaces a String with another String inside a larger String,
    6355     * for the first {@code max} values of the search String.
    6356     *
    6357     * <p>A {@code null} reference passed to this method is a no-op.</p>
    6358     *
    6359     * <pre>
    6360     * StringUtils.replace(null, *, *, *)         = null
    6361     * StringUtils.replace("", *, *, *)           = ""
    6362     * StringUtils.replace("any", null, *, *)     = "any"
    6363     * StringUtils.replace("any", *, null, *)     = "any"
    6364     * StringUtils.replace("any", "", *, *)       = "any"
    6365     * StringUtils.replace("any", *, *, 0)        = "any"
    6366     * StringUtils.replace("abaa", "a", null, -1) = "abaa"
    6367     * StringUtils.replace("abaa", "a", "", -1)   = "b"
    6368     * StringUtils.replace("abaa", "a", "z", 0)   = "abaa"
    6369     * StringUtils.replace("abaa", "a", "z", 1)   = "zbaa"
    6370     * StringUtils.replace("abaa", "a", "z", 2)   = "zbza"
    6371     * StringUtils.replace("abaa", "a", "z", -1)  = "zbzz"
    6372     * </pre>
    6373     *
    6374     * @param text  text to search and replace in, may be null
    6375     * @param searchString  the String to search for, may be null
    6376     * @param replacement  the String to replace it with, may be null
    6377     * @param max  maximum number of values to replace, or {@code -1} if no maximum
    6378     * @return the text with any replacements processed,
    6379     *  {@code null} if null String input
    6380     */
    6381    public static String replace(final String text, final String searchString, final String replacement, final int max) {
    6382        return replace(text, searchString, replacement, max, false);
    6383    }
    6384
    6385    /**
    6386     * Replaces a String with another String inside a larger String,
    6387     * for the first {@code max} values of the search String,
    6388     * case-sensitively/insensitively based on {@code ignoreCase} value.
    6389     *
    6390     * <p>A {@code null} reference passed to this method is a no-op.</p>
    6391     *
    6392     * <pre>
    6393     * StringUtils.replace(null, *, *, *, false)         = null
    6394     * StringUtils.replace("", *, *, *, false)           = ""
    6395     * StringUtils.replace("any", null, *, *, false)     = "any"
    6396     * StringUtils.replace("any", *, null, *, false)     = "any"
    6397     * StringUtils.replace("any", "", *, *, false)       = "any"
    6398     * StringUtils.replace("any", *, *, 0, false)        = "any"
    6399     * StringUtils.replace("abaa", "a", null, -1, false) = "abaa"
    6400     * StringUtils.replace("abaa", "a", "", -1, false)   = "b"
    6401     * StringUtils.replace("abaa", "a", "z", 0, false)   = "abaa"
    6402     * StringUtils.replace("abaa", "A", "z", 1, false)   = "abaa"
    6403     * StringUtils.replace("abaa", "A", "z", 1, true)   = "zbaa"
    6404     * StringUtils.replace("abAa", "a", "z", 2, true)   = "zbza"
    6405     * StringUtils.replace("abAa", "a", "z", -1, true)  = "zbzz"
    6406     * </pre>
    6407     *
    6408     * @param text  text to search and replace in, may be null
    6409     * @param searchString  the String to search for (case-insensitive), may be null
    6410     * @param replacement  the String to replace it with, may be null
    6411     * @param max  maximum number of values to replace, or {@code -1} if no maximum
    6412     * @param ignoreCase if true replace is case-insensitive, otherwise case-sensitive
    6413     * @return the text with any replacements processed,
    6414     *  {@code null} if null String input
    6415     */
    6416     private static String replace(final String text, String searchString, final String replacement, int max, final boolean ignoreCase) {
    6417         if (isEmpty(text) || isEmpty(searchString) || replacement == null || max == 0) {
    6418             return text;
    6419         }
    6420         if (ignoreCase) {
    6421             searchString = searchString.toLowerCase();
    6422         }
    6423         int start = 0;
    6424         int end = ignoreCase ? indexOfIgnoreCase(text, searchString, start) : indexOf(text, searchString, start);
    6425         if (end == INDEX_NOT_FOUND) {
    6426             return text;
    6427         }
    6428         final int replLength = searchString.length();
    6429         int increase = Math.max(replacement.length() - replLength, 0);
    6430         increase *= max < 0 ? 16 : Math.min(max, 64);
    6431         final StringBuilder buf = new StringBuilder(text.length() + increase);
    6432         while (end != INDEX_NOT_FOUND) {
    6433             buf.append(text, start, end).append(replacement);
    6434             start = end + replLength;
    6435             if (--max == 0) {
    6436                 break;
    6437             }
    6438             end = ignoreCase ? indexOfIgnoreCase(text, searchString, start) : indexOf(text, searchString, start);
    6439         }
    6440         buf.append(text, start, text.length());
    6441         return buf.toString();
    6442     }
    6443
    6444    /**
    6445     * Replaces each substring of the text String that matches the given regular expression
    6446     * with the given replacement.
    6447     *
    6448     * This method is a {@code null} safe equivalent to:
    6449     * <ul>
    6450     *  <li>{@code text.replaceAll(regex, replacement)}</li>
    6451     *  <li>{@code Pattern.compile(regex).matcher(text).replaceAll(replacement)}</li>
    6452     * </ul>
    6453     *
    6454     * <p>A {@code null} reference passed to this method is a no-op.</p>
    6455     *
    6456     * <p>Unlike in the {@link #replacePattern(String, String, String)} method, the {@link Pattern#DOTALL} option
    6457     * is NOT automatically added.
    6458     * To use the DOTALL option prepend {@code "(?s)"} to the regex.
    6459     * DOTALL is also known as single-line mode in Perl.</p>
    6460     *
    6461     * <pre>{@code
    6462     * StringUtils.replaceAll(null, *, *)       = null
    6463     * StringUtils.replaceAll("any", (String) null, *)   = "any"
    6464     * StringUtils.replaceAll("any", *, null)   = "any"
    6465     * StringUtils.replaceAll("", "", "zzz")    = "zzz"
    6466     * StringUtils.replaceAll("", ".*", "zzz")  = "zzz"
    6467     * StringUtils.replaceAll("", ".+", "zzz")  = ""
    6468     * StringUtils.replaceAll("abc", "", "ZZ")  = "ZZaZZbZZcZZ"
    6469     * StringUtils.replaceAll("<__>\n<__>", "<.*>", "z")      = "z\nz"
    6470     * StringUtils.replaceAll("<__>\n<__>", "(?s)<.*>", "z")  = "z"
    6471     * StringUtils.replaceAll("ABCabc123", "[a-z]", "_")       = "ABC___123"
    6472     * StringUtils.replaceAll("ABCabc123", "[^A-Z0-9]+", "_")  = "ABC_123"
    6473     * StringUtils.replaceAll("ABCabc123", "[^A-Z0-9]+", "")   = "ABC123"
    6474     * StringUtils.replaceAll("Lorem ipsum  dolor   sit", "( +)([a-z]+)", "_$2")  = "Lorem_ipsum_dolor_sit"
    6475     * }</pre>
    6476     *
    6477     * @param text  text to search and replace in, may be null
    6478     * @param regex  the regular expression to which this string is to be matched
    6479     * @param replacement  the string to be substituted for each match
    6480     * @return  the text with any replacements processed,
    6481     *              {@code null} if null String input
    6482     *
    6483     * @throws  java.util.regex.PatternSyntaxException
    6484     *              if the regular expression's syntax is invalid
    6485     *
    6486     * @see #replacePattern(String, String, String)
    6487     * @see String#replaceAll(String, String)
    6488     * @see java.util.regex.Pattern
    6489     * @see java.util.regex.Pattern#DOTALL
    6490     * @since 3.5
    6491     *
    6492     * @deprecated Moved to RegExUtils.
    6493     */
    6494    @Deprecated
    6495    public static String replaceAll(final String text, final String regex, final String replacement) {
    6496        return RegExUtils.replaceAll(text, regex, replacement);
    6497    }
    6498
    6499    /**
    6500     * Replaces all occurrences of a character in a String with another.
    6501     * This is a null-safe version of {@link String#replace(char, char)}.
    6502     *
    6503     * <p>A {@code null} string input returns {@code null}.
    6504     * An empty ("") string input returns an empty string.</p>
    6505     *
    6506     * <pre>
    6507     * StringUtils.replaceChars(null, *, *)        = null
    6508     * StringUtils.replaceChars("", *, *)          = ""
    6509     * StringUtils.replaceChars("abcba", 'b', 'y') = "aycya"
    6510     * StringUtils.replaceChars("abcba", 'z', 'y') = "abcba"
    6511     * </pre>
    6512     *
    6513     * @param str  String to replace characters in, may be null
    6514     * @param searchChar  the character to search for, may be null
    6515     * @param replaceChar  the character to replace, may be null
    6516     * @return modified String, {@code null} if null string input
    6517     * @since 2.0
    6518     */
    6519    public static String replaceChars(final String str, final char searchChar, final char replaceChar) {
    6520        if (str == null) {
    6521            return null;
    6522        }
    6523        return str.replace(searchChar, replaceChar);
    6524    }
    6525
    6526    /**
    6527     * Replaces multiple characters in a String in one go.
    6528     * This method can also be used to delete characters.
    6529     *
    6530     * <p>For example:<br>
    6531     * {@code replaceChars(&quot;hello&quot;, &quot;ho&quot;, &quot;jy&quot;) = jelly}.</p>
    6532     *
    6533     * <p>A {@code null} string input returns {@code null}.
    6534     * An empty ("") string input returns an empty string.
    6535     * A null or empty set of search characters returns the input string.</p>
    6536     *
    6537     * <p>The length of the search characters should normally equal the length
    6538     * of the replace characters.
    6539     * If the search characters is longer, then the extra search characters
    6540     * are deleted.
    6541     * If the search characters is shorter, then the extra replace characters
    6542     * are ignored.</p>
    6543     *
    6544     * <pre>
    6545     * StringUtils.replaceChars(null, *, *)           = null
    6546     * StringUtils.replaceChars("", *, *)             = ""
    6547     * StringUtils.replaceChars("abc", null, *)       = "abc"
    6548     * StringUtils.replaceChars("abc", "", *)         = "abc"
    6549     * StringUtils.replaceChars("abc", "b", null)     = "ac"
    6550     * StringUtils.replaceChars("abc", "b", "")       = "ac"
    6551     * StringUtils.replaceChars("abcba", "bc", "yz")  = "ayzya"
    6552     * StringUtils.replaceChars("abcba", "bc", "y")   = "ayya"
    6553     * StringUtils.replaceChars("abcba", "bc", "yzx") = "ayzya"
    6554     * </pre>
    6555     *
    6556     * @param str  String to replace characters in, may be null
    6557     * @param searchChars  a set of characters to search for, may be null
    6558     * @param replaceChars  a set of characters to replace, may be null
    6559     * @return modified String, {@code null} if null string input
    6560     * @since 2.0
    6561     */
    6562    public static String replaceChars(final String str, final String searchChars, String replaceChars) {
    6563        if (isEmpty(str) || isEmpty(searchChars)) {
    6564            return str;
    6565        }
    6566        if (replaceChars == null) {
    6567            replaceChars = EMPTY;
    6568        }
    6569        boolean modified = false;
    6570        final int replaceCharsLength = replaceChars.length();
    6571        final int strLength = str.length();
    6572        final StringBuilder buf = new StringBuilder(strLength);
    6573        for (int i = 0; i < strLength; i++) {
    6574            final char ch = str.charAt(i);
    6575            final int index = searchChars.indexOf(ch);
    6576            if (index >= 0) {
    6577                modified = true;
    6578                if (index < replaceCharsLength) {
    6579                    buf.append(replaceChars.charAt(index));
    6580                }
    6581            } else {
    6582                buf.append(ch);
    6583            }
    6584        }
    6585        if (modified) {
    6586            return buf.toString();
    6587        }
    6588        return str;
    6589    }
    6590
    6591    /**
    6592     * Replaces all occurrences of Strings within another String.
    6593     *
    6594     * <p>
    6595     * A {@code null} reference passed to this method is a no-op, or if
    6596     * any "search string" or "string to replace" is null, that replace will be
    6597     * ignored. This will not repeat. For repeating replaces, call the
    6598     * overloaded method.
    6599     * </p>
    6600     *
    6601     * <pre>
    6602     *  StringUtils.replaceEach(null, *, *)        = null
    6603     *  StringUtils.replaceEach("", *, *)          = ""
    6604     *  StringUtils.replaceEach("aba", null, null) = "aba"
    6605     *  StringUtils.replaceEach("aba", new String[0], null) = "aba"
    6606     *  StringUtils.replaceEach("aba", null, new String[0]) = "aba"
    6607     *  StringUtils.replaceEach("aba", new String[]{"a"}, null)  = "aba"
    6608     *  StringUtils.replaceEach("aba", new String[]{"a"}, new String[]{""})  = "b"
    6609     *  StringUtils.replaceEach("aba", new String[]{null}, new String[]{"a"})  = "aba"
    6610     *  StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"w", "t"})  = "wcte"
    6611     *  (example of how it does not repeat)
    6612     *  StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "t"})  = "dcte"
    6613     * </pre>
    6614     *
    6615     * @param text
    6616     *            text to search and replace in, no-op if null
    6617     * @param searchList
    6618     *            the Strings to search for, no-op if null
    6619     * @param replacementList
    6620     *            the Strings to replace them with, no-op if null
    6621     * @return the text with any replacements processed, {@code null} if
    6622     *         null String input
    6623     * @throws IllegalArgumentException
    6624     *             if the lengths of the arrays are not the same (null is ok,
    6625     *             and/or size 0)
    6626     * @since 2.4
    6627     */
    6628    public static String replaceEach(final String text, final String[] searchList, final String[] replacementList) {
    6629        return replaceEach(text, searchList, replacementList, false, 0);
    6630    }
    6631
    6632    /**
    6633     * Replace all occurrences of Strings within another String.
    6634     * This is a private recursive helper method for {@link #replaceEachRepeatedly(String, String[], String[])} and
    6635     * {@link #replaceEach(String, String[], String[])}
    6636     *
    6637     * <p>
    6638     * A {@code null} reference passed to this method is a no-op, or if
    6639     * any "search string" or "string to replace" is null, that replace will be
    6640     * ignored.
    6641     * </p>
    6642     *
    6643     * <pre>
    6644     *  StringUtils.replaceEach(null, *, *, *, *) = null
    6645     *  StringUtils.replaceEach("", *, *, *, *) = ""
    6646     *  StringUtils.replaceEach("aba", null, null, *, *) = "aba"
    6647     *  StringUtils.replaceEach("aba", new String[0], null, *, *) = "aba"
    6648     *  StringUtils.replaceEach("aba", null, new String[0], *, *) = "aba"
    6649     *  StringUtils.replaceEach("aba", new String[]{"a"}, null, *, *) = "aba"
    6650     *  StringUtils.replaceEach("aba", new String[]{"a"}, new String[]{""}, *, >=0) = "b"
    6651     *  StringUtils.replaceEach("aba", new String[]{null}, new String[]{"a"}, *, >=0) = "aba"
    6652     *  StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"w", "t"}, *, >=0) = "wcte"
    6653     *  (example of how it repeats)
    6654     *  StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "t"}, false, >=0) = "dcte"
    6655     *  StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "t"}, true, >=2) = "tcte"
    6656     *  StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "ab"}, *, *) = IllegalStateException
    6657     * </pre>
    6658     *
    6659     * @param text
    6660     *            text to search and replace in, no-op if null
    6661     * @param searchList
    6662     *            the Strings to search for, no-op if null
    6663     * @param replacementList
    6664     *            the Strings to replace them with, no-op if null
    6665     * @param repeat if true, then replace repeatedly
    6666     *       until there are no more possible replacements or timeToLive < 0
    6667     * @param timeToLive
    6668     *            if less than 0 then there is a circular reference and endless
    6669     *            loop
    6670     * @return the text with any replacements processed, {@code null} if
    6671     *         null String input
    6672     * @throws IllegalStateException
    6673     *             if the search is repeating and there is an endless loop due
    6674     *             to outputs of one being inputs to another
    6675     * @throws IllegalArgumentException
    6676     *             if the lengths of the arrays are not the same (null is ok,
    6677     *             and/or size 0)
    6678     * @since 2.4
    6679     */
    6680    private static String replaceEach(
    6681            final String text, final String[] searchList, final String[] replacementList, final boolean repeat, final int timeToLive) {
    6682
    6683        // mchyzer Performance note: This creates very few new objects (one major goal)
    6684        // let me know if there are performance requests, we can create a harness to measure
    6685
    6686        // if recursing, this shouldn't be less than 0
    6687        if (timeToLive < 0) {
    6688            final Set<String> searchSet = new HashSet<>(Arrays.asList(searchList));
    6689            final Set<String> replacementSet = new HashSet<>(Arrays.asList(replacementList));
    6690            searchSet.retainAll(replacementSet);
    6691            if (!searchSet.isEmpty()) {
    6692                throw new IllegalStateException("Aborting to protect against StackOverflowError - " +
    6693                        "output of one loop is the input of another");
    6694            }
    6695        }
    6696
    6697        if (isEmpty(text) || ArrayUtils.isEmpty(searchList) || ArrayUtils.isEmpty(replacementList) || ArrayUtils.isNotEmpty(searchList) && timeToLive == -1) {
    6698            return text;
    6699        }
    6700
    6701        final int searchLength = searchList.length;
    6702        final int replacementLength = replacementList.length;
    6703
    6704        // make sure lengths are ok, these need to be equal
    6705        if (searchLength != replacementLength) {
    6706            throw new IllegalArgumentException("Search and Replace array lengths don't match: "
    6707                + searchLength
    6708                + " vs "
    6709                + replacementLength);
    6710        }
    6711
    6712        // keep track of which still have matches
    6713        final boolean[] noMoreMatchesForReplIndex = new boolean[searchLength];
    6714
    6715        // index on index that the match was found
    6716        int textIndex = -1;
    6717        int replaceIndex = -1;
    6718        int tempIndex;
    6719
    6720        // index of replace array that will replace the search string found
    6721        // NOTE: logic duplicated below START
    6722        for (int i = 0; i < searchLength; i++) {
    6723            if (noMoreMatchesForReplIndex[i] || isEmpty(searchList[i]) || replacementList[i] == null) {
    6724                continue;
    6725            }
    6726            tempIndex = text.indexOf(searchList[i]);
    6727
    6728            // see if we need to keep searching for this
    6729            if (tempIndex == -1) {
    6730                noMoreMatchesForReplIndex[i] = true;
    6731            } else if (textIndex == -1 || tempIndex < textIndex) {
    6732                textIndex = tempIndex;
    6733                replaceIndex = i;
    6734            }
    6735        }
    6736        // NOTE: logic mostly below END
    6737
    6738        // no search strings found, we are done
    6739        if (textIndex == -1) {
    6740            return text;
    6741        }
    6742
    6743        int start = 0;
    6744
    6745        // get a good guess on the size of the result buffer so it doesn't have to double if it goes over a bit
    6746        int increase = 0;
    6747
    6748        // count the replacement text elements that are larger than their corresponding text being replaced
    6749        for (int i = 0; i < searchList.length; i++) {
    6750            if (searchList[i] == null || replacementList[i] == null) {
    6751                continue;
    6752            }
    6753            final int greater = replacementList[i].length() - searchList[i].length();
    6754            if (greater > 0) {
    6755                increase += 3 * greater; // assume 3 matches
    6756            }
    6757        }
    6758        // have upper-bound at 20% increase, then let Java take over
    6759        increase = Math.min(increase, text.length() / 5);
    6760
    6761        final StringBuilder buf = new StringBuilder(text.length() + increase);
    6762
    6763        while (textIndex != -1) {
    6764
    6765            for (int i = start; i < textIndex; i++) {
    6766                buf.append(text.charAt(i));
    6767            }
    6768            buf.append(replacementList[replaceIndex]);
    6769
    6770            start = textIndex + searchList[replaceIndex].length();
    6771
    6772            textIndex = -1;
    6773            replaceIndex = -1;
    6774            // find the next earliest match
    6775            // NOTE: logic mostly duplicated above START
    6776            for (int i = 0; i < searchLength; i++) {
    6777                if (noMoreMatchesForReplIndex[i] || isEmpty(searchList[i]) || replacementList[i] == null) {
    6778                    continue;
    6779                }
    6780                tempIndex = text.indexOf(searchList[i], start);
    6781
    6782                // see if we need to keep searching for this
    6783                if (tempIndex == -1) {
    6784                    noMoreMatchesForReplIndex[i] = true;
    6785                } else if (textIndex == -1 || tempIndex < textIndex) {
    6786                    textIndex = tempIndex;
    6787                    replaceIndex = i;
    6788                }
    6789            }
    6790            // NOTE: logic duplicated above END
    6791
    6792        }
    6793        final int textLength = text.length();
    6794        for (int i = start; i < textLength; i++) {
    6795            buf.append(text.charAt(i));
    6796        }
    6797        final String result = buf.toString();
    6798        if (!repeat) {
    6799            return result;
    6800        }
    6801
    6802        return replaceEach(result, searchList, replacementList, repeat, timeToLive - 1);
    6803    }
    6804
    6805    /**
    6806     * Replaces all occurrences of Strings within another String.
    6807     *
    6808     * <p>
    6809     * A {@code null} reference passed to this method is a no-op, or if
    6810     * any "search string" or "string to replace" is null, that replace will be
    6811     * ignored.
    6812     * </p>
    6813     *
    6814     * <pre>
    6815     *  StringUtils.replaceEachRepeatedly(null, *, *) = null
    6816     *  StringUtils.replaceEachRepeatedly("", *, *) = ""
    6817     *  StringUtils.replaceEachRepeatedly("aba", null, null) = "aba"
    6818     *  StringUtils.replaceEachRepeatedly("aba", new String[0], null) = "aba"
    6819     *  StringUtils.replaceEachRepeatedly("aba", null, new String[0]) = "aba"
    6820     *  StringUtils.replaceEachRepeatedly("aba", new String[]{"a"}, null) = "aba"
    6821     *  StringUtils.replaceEachRepeatedly("aba", new String[]{"a"}, new String[]{""}) = "b"
    6822     *  StringUtils.replaceEachRepeatedly("aba", new String[]{null}, new String[]{"a"}) = "aba"
    6823     *  StringUtils.replaceEachRepeatedly("abcde", new String[]{"ab", "d"}, new String[]{"w", "t"}) = "wcte"
    6824     *  (example of how it repeats)
    6825     *  StringUtils.replaceEachRepeatedly("abcde", new String[]{"ab", "d"}, new String[]{"d", "t"}) = "tcte"
    6826     *  StringUtils.replaceEachRepeatedly("abcde", new String[]{"ab", "d"}, new String[]{"d", "ab"}) = IllegalStateException
    6827     * </pre>
    6828     *
    6829     * @param text
    6830     *            text to search and replace in, no-op if null
    6831     * @param searchList
    6832     *            the Strings to search for, no-op if null
    6833     * @param replacementList
    6834     *            the Strings to replace them with, no-op if null
    6835     * @return the text with any replacements processed, {@code null} if
    6836     *         null String input
    6837     * @throws IllegalStateException
    6838     *             if the search is repeating and there is an endless loop due
    6839     *             to outputs of one being inputs to another
    6840     * @throws IllegalArgumentException
    6841     *             if the lengths of the arrays are not the same (null is ok,
    6842     *             and/or size 0)
    6843     * @since 2.4
    6844     */
    6845    public static String replaceEachRepeatedly(final String text, final String[] searchList, final String[] replacementList) {
    6846        return replaceEach(text, searchList, replacementList, true, ArrayUtils.getLength(searchList));
    6847    }
    6848
    6849    /**
    6850     * Replaces the first substring of the text string that matches the given regular expression
    6851     * with the given replacement.
    6852     *
    6853     * This method is a {@code null} safe equivalent to:
    6854     * <ul>
    6855     *  <li>{@code text.replaceFirst(regex, replacement)}</li>
    6856     *  <li>{@code Pattern.compile(regex).matcher(text).replaceFirst(replacement)}</li>
    6857     * </ul>
    6858     *
    6859     * <p>A {@code null} reference passed to this method is a no-op.</p>
    6860     *
    6861     * <p>The {@link Pattern#DOTALL} option is NOT automatically added.
    6862     * To use the DOTALL option prepend {@code "(?s)"} to the regex.
    6863     * DOTALL is also known as single-line mode in Perl.</p>
    6864     *
    6865     * <pre>{@code
    6866     * StringUtils.replaceFirst(null, *, *)       = null
    6867     * StringUtils.replaceFirst("any", (String) null, *)   = "any"
    6868     * StringUtils.replaceFirst("any", *, null)   = "any"
    6869     * StringUtils.replaceFirst("", "", "zzz")    = "zzz"
    6870     * StringUtils.replaceFirst("", ".*", "zzz")  = "zzz"
    6871     * StringUtils.replaceFirst("", ".+", "zzz")  = ""
    6872     * StringUtils.replaceFirst("abc", "", "ZZ")  = "ZZabc"
    6873     * StringUtils.replaceFirst("<__>\n<__>", "<.*>", "z")      = "z\n<__>"
    6874     * StringUtils.replaceFirst("<__>\n<__>", "(?s)<.*>", "z")  = "z"
    6875     * StringUtils.replaceFirst("ABCabc123", "[a-z]", "_")          = "ABC_bc123"
    6876     * StringUtils.replaceFirst("ABCabc123abc", "[^A-Z0-9]+", "_")  = "ABC_123abc"
    6877     * StringUtils.replaceFirst("ABCabc123abc", "[^A-Z0-9]+", "")   = "ABC123abc"
    6878     * StringUtils.replaceFirst("Lorem ipsum  dolor   sit", "( +)([a-z]+)", "_$2")  = "Lorem_ipsum  dolor   sit"
    6879     * }</pre>
    6880     *
    6881     * @param text  text to search and replace in, may be null
    6882     * @param regex  the regular expression to which this string is to be matched
    6883     * @param replacement  the string to be substituted for the first match
    6884     * @return  the text with the first replacement processed,
    6885     *              {@code null} if null String input
    6886     *
    6887     * @throws  java.util.regex.PatternSyntaxException
    6888     *              if the regular expression's syntax is invalid
    6889     *
    6890     * @see String#replaceFirst(String, String)
    6891     * @see java.util.regex.Pattern
    6892     * @see java.util.regex.Pattern#DOTALL
    6893     * @since 3.5
    6894     *
    6895     * @deprecated Moved to RegExUtils.
    6896     */
    6897    @Deprecated
    6898    public static String replaceFirst(final String text, final String regex, final String replacement) {
    6899        return RegExUtils.replaceFirst(text, regex, replacement);
    6900    }
    6901
    6902    /**
    6903     * Case insensitively replaces all occurrences of a String within another String.
    6904     *
    6905     * <p>A {@code null} reference passed to this method is a no-op.</p>
    6906     *
    6907     * <pre>
    6908     * StringUtils.replaceIgnoreCase(null, *, *)        = null
    6909     * StringUtils.replaceIgnoreCase("", *, *)          = ""
    6910     * StringUtils.replaceIgnoreCase("any", null, *)    = "any"
    6911     * StringUtils.replaceIgnoreCase("any", *, null)    = "any"
    6912     * StringUtils.replaceIgnoreCase("any", "", *)      = "any"
    6913     * StringUtils.replaceIgnoreCase("aba", "a", null)  = "aba"
    6914     * StringUtils.replaceIgnoreCase("abA", "A", "")    = "b"
    6915     * StringUtils.replaceIgnoreCase("aba", "A", "z")   = "zbz"
    6916     * </pre>
    6917     *
    6918     * @see #replaceIgnoreCase(String text, String searchString, String replacement, int max)
    6919     * @param text  text to search and replace in, may be null
    6920     * @param searchString  the String to search for (case-insensitive), may be null
    6921     * @param replacement  the String to replace it with, may be null
    6922     * @return the text with any replacements processed,
    6923     *  {@code null} if null String input
    6924     * @since 3.5
    6925     */
    6926     public static String replaceIgnoreCase(final String text, final String searchString, final String replacement) {
    6927         return replaceIgnoreCase(text, searchString, replacement, -1);
    6928     }
    6929
    6930    /**
    6931     * Case insensitively replaces a String with another String inside a larger String,
    6932     * for the first {@code max} values of the search String.
    6933     *
    6934     * <p>A {@code null} reference passed to this method is a no-op.</p>
    6935     *
    6936     * <pre>
    6937     * StringUtils.replaceIgnoreCase(null, *, *, *)         = null
    6938     * StringUtils.replaceIgnoreCase("", *, *, *)           = ""
    6939     * StringUtils.replaceIgnoreCase("any", null, *, *)     = "any"
    6940     * StringUtils.replaceIgnoreCase("any", *, null, *)     = "any"
    6941     * StringUtils.replaceIgnoreCase("any", "", *, *)       = "any"
    6942     * StringUtils.replaceIgnoreCase("any", *, *, 0)        = "any"
    6943     * StringUtils.replaceIgnoreCase("abaa", "a", null, -1) = "abaa"
    6944     * StringUtils.replaceIgnoreCase("abaa", "a", "", -1)   = "b"
    6945     * StringUtils.replaceIgnoreCase("abaa", "a", "z", 0)   = "abaa"
    6946     * StringUtils.replaceIgnoreCase("abaa", "A", "z", 1)   = "zbaa"
    6947     * StringUtils.replaceIgnoreCase("abAa", "a", "z", 2)   = "zbza"
    6948     * StringUtils.replaceIgnoreCase("abAa", "a", "z", -1)  = "zbzz"
    6949     * </pre>
    6950     *
    6951     * @param text  text to search and replace in, may be null
    6952     * @param searchString  the String to search for (case-insensitive), may be null
    6953     * @param replacement  the String to replace it with, may be null
    6954     * @param max  maximum number of values to replace, or {@code -1} if no maximum
    6955     * @return the text with any replacements processed,
    6956     *  {@code null} if null String input
    6957     * @since 3.5
    6958     */
    6959    public static String replaceIgnoreCase(final String text, final String searchString, final String replacement, final int max) {
    6960        return replace(text, searchString, replacement, max, true);
    6961    }
    6962
    6963    /**
    6964     * Replaces a String with another String inside a larger String, once.
    6965     *
    6966     * <p>A {@code null} reference passed to this method is a no-op.</p>
    6967     *
    6968     * <pre>
    6969     * StringUtils.replaceOnce(null, *, *)        = null
    6970     * StringUtils.replaceOnce("", *, *)          = ""
    6971     * StringUtils.replaceOnce("any", null, *)    = "any"
    6972     * StringUtils.replaceOnce("any", *, null)    = "any"
    6973     * StringUtils.replaceOnce("any", "", *)      = "any"
    6974     * StringUtils.replaceOnce("aba", "a", null)  = "aba"
    6975     * StringUtils.replaceOnce("aba", "a", "")    = "ba"
    6976     * StringUtils.replaceOnce("aba", "a", "z")   = "zba"
    6977     * </pre>
    6978     *
    6979     * @see #replace(String text, String searchString, String replacement, int max)
    6980     * @param text  text to search and replace in, may be null
    6981     * @param searchString  the String to search for, may be null
    6982     * @param replacement  the String to replace with, may be null
    6983     * @return the text with any replacements processed,
    6984     *  {@code null} if null String input
    6985     */
    6986    public static String replaceOnce(final String text, final String searchString, final String replacement) {
    6987        return replace(text, searchString, replacement, 1);
    6988    }
    6989
    6990    /**
    6991     * Case insensitively replaces a String with another String inside a larger String, once.
    6992     *
    6993     * <p>A {@code null} reference passed to this method is a no-op.</p>
    6994     *
    6995     * <pre>
    6996     * StringUtils.replaceOnceIgnoreCase(null, *, *)        = null
    6997     * StringUtils.replaceOnceIgnoreCase("", *, *)          = ""
    6998     * StringUtils.replaceOnceIgnoreCase("any", null, *)    = "any"
    6999     * StringUtils.replaceOnceIgnoreCase("any", *, null)    = "any"
    7000     * StringUtils.replaceOnceIgnoreCase("any", "", *)      = "any"
    7001     * StringUtils.replaceOnceIgnoreCase("aba", "a", null)  = "aba"
    7002     * StringUtils.replaceOnceIgnoreCase("aba", "a", "")    = "ba"
    7003     * StringUtils.replaceOnceIgnoreCase("aba", "a", "z")   = "zba"
    7004     * StringUtils.replaceOnceIgnoreCase("FoOFoofoo", "foo", "") = "Foofoo"
    7005     * </pre>
    7006     *
    7007     * @see #replaceIgnoreCase(String text, String searchString, String replacement, int max)
    7008     * @param text  text to search and replace in, may be null
    7009     * @param searchString  the String to search for (case-insensitive), may be null
    7010     * @param replacement  the String to replace with, may be null
    7011     * @return the text with any replacements processed,
    7012     *  {@code null} if null String input
    7013     * @since 3.5
    7014     */
    7015    public static String replaceOnceIgnoreCase(final String text, final String searchString, final String replacement) {
    7016        return replaceIgnoreCase(text, searchString, replacement, 1);
    7017    }
    7018
    7019    /**
    7020     * Replaces each substring of the source String that matches the given regular expression with the given
    7021     * replacement using the {@link Pattern#DOTALL} option. DOTALL is also known as single-line mode in Perl.
    7022     *
    7023     * This call is a {@code null} safe equivalent to:
    7024     * <ul>
    7025     * <li>{@code source.replaceAll(&quot;(?s)&quot; + regex, replacement)}</li>
    7026     * <li>{@code Pattern.compile(regex, Pattern.DOTALL).matcher(source).replaceAll(replacement)}</li>
    7027     * </ul>
    7028     *
    7029     * <p>A {@code null} reference passed to this method is a no-op.</p>
    7030     *
    7031     * <pre>{@code
    7032     * StringUtils.replacePattern(null, *, *)       = null
    7033     * StringUtils.replacePattern("any", (String) null, *)   = "any"
    7034     * StringUtils.replacePattern("any", *, null)   = "any"
    7035     * StringUtils.replacePattern("", "", "zzz")    = "zzz"
    7036     * StringUtils.replacePattern("", ".*", "zzz")  = "zzz"
    7037     * StringUtils.replacePattern("", ".+", "zzz")  = ""
    7038     * StringUtils.replacePattern("<__>\n<__>", "<.*>", "z")       = "z"
    7039     * StringUtils.replacePattern("ABCabc123", "[a-z]", "_")       = "ABC___123"
    7040     * StringUtils.replacePattern("ABCabc123", "[^A-Z0-9]+", "_")  = "ABC_123"
    7041     * StringUtils.replacePattern("ABCabc123", "[^A-Z0-9]+", "")   = "ABC123"
    7042     * StringUtils.replacePattern("Lorem ipsum  dolor   sit", "( +)([a-z]+)", "_$2")  = "Lorem_ipsum_dolor_sit"
    7043     * }</pre>
    7044     *
    7045     * @param source
    7046     *            the source string
    7047     * @param regex
    7048     *            the regular expression to which this string is to be matched
    7049     * @param replacement
    7050     *            the string to be substituted for each match
    7051     * @return The resulting {@link String}
    7052     * @see #replaceAll(String, String, String)
    7053     * @see String#replaceAll(String, String)
    7054     * @see Pattern#DOTALL
    7055     * @since 3.2
    7056     * @since 3.5 Changed {@code null} reference passed to this method is a no-op.
    7057     *
    7058     * @deprecated Moved to RegExUtils.
    7059     */
    7060    @Deprecated
    7061    public static String replacePattern(final String source, final String regex, final String replacement) {
    7062        return RegExUtils.replacePattern(source, regex, replacement);
    7063    }
    7064
    7065    /**
    7066     * Reverses a String as per {@link StringBuilder#reverse()}.
    7067     *
    7068     * <p>A {@code null} String returns {@code null}.</p>
    7069     *
    7070     * <pre>
    7071     * StringUtils.reverse(null)  = null
    7072     * StringUtils.reverse("")    = ""
    7073     * StringUtils.reverse("bat") = "tab"
    7074     * </pre>
    7075     *
    7076     * @param str  the String to reverse, may be null
    7077     * @return the reversed String, {@code null} if null String input
    7078     */
    7079    public static String reverse(final String str) {
    7080        if (str == null) {
    7081            return null;
    7082        }
    7083        return new StringBuilder(str).reverse().toString();
    7084    }
    7085
    7086    /**
    7087     * Reverses a String that is delimited by a specific character.
    7088     *
    7089     * <p>The Strings between the delimiters are not reversed.
    7090     * Thus java.lang.String becomes String.lang.java (if the delimiter
    7091     * is {@code '.'}).</p>
    7092     *
    7093     * <pre>
    7094     * StringUtils.reverseDelimited(null, *)      = null
    7095     * StringUtils.reverseDelimited("", *)        = ""
    7096     * StringUtils.reverseDelimited("a.b.c", 'x') = "a.b.c"
    7097     * StringUtils.reverseDelimited("a.b.c", ".") = "c.b.a"
    7098     * </pre>
    7099     *
    7100     * @param str  the String to reverse, may be null
    7101     * @param separatorChar  the separator character to use
    7102     * @return the reversed String, {@code null} if null String input
    7103     * @since 2.0
    7104     */
    7105    public static String reverseDelimited(final String str, final char separatorChar) {
    7106        final String[] strs = split(str, separatorChar);
    7107        ArrayUtils.reverse(strs);
    7108        return join(strs, separatorChar);
    7109    }
    7110
    7111    /**
    7112     * Gets the rightmost {@code len} characters of a String.
    7113     *
    7114     * <p>If {@code len} characters are not available, or the String
    7115     * is {@code null}, the String will be returned without an
    7116     * an exception. An empty String is returned if len is negative.</p>
    7117     *
    7118     * <pre>
    7119     * StringUtils.right(null, *)    = null
    7120     * StringUtils.right(*, -ve)     = ""
    7121     * StringUtils.right("", *)      = ""
    7122     * StringUtils.right("abc", 0)   = ""
    7123     * StringUtils.right("abc", 2)   = "bc"
    7124     * StringUtils.right("abc", 4)   = "abc"
    7125     * </pre>
    7126     *
    7127     * @param str  the String to get the rightmost characters from, may be null
    7128     * @param len  the length of the required String
    7129     * @return the rightmost characters, {@code null} if null String input
    7130     */
    7131    public static String right(final String str, final int len) {
    7132        if (str == null) {
    7133            return null;
    7134        }
    7135        if (len < 0) {
    7136            return EMPTY;
    7137        }
    7138        if (str.length() <= len) {
    7139            return str;
    7140        }
    7141        return str.substring(str.length() - len);
    7142    }
    7143
    7144    /**
    7145     * Right pad a String with spaces (' ').
    7146     *
    7147     * <p>The String is padded to the size of {@code size}.</p>
    7148     *
    7149     * <pre>
    7150     * StringUtils.rightPad(null, *)   = null
    7151     * StringUtils.rightPad("", 3)     = "   "
    7152     * StringUtils.rightPad("bat", 3)  = "bat"
    7153     * StringUtils.rightPad("bat", 5)  = "bat  "
    7154     * StringUtils.rightPad("bat", 1)  = "bat"
    7155     * StringUtils.rightPad("bat", -1) = "bat"
    7156     * </pre>
    7157     *
    7158     * @param str  the String to pad out, may be null
    7159     * @param size  the size to pad to
    7160     * @return right padded String or original String if no padding is necessary,
    7161     *  {@code null} if null String input
    7162     */
    7163    public static String rightPad(final String str, final int size) {
    7164        return rightPad(str, size, ' ');
    7165    }
    7166
    7167    /**
    7168     * Right pad a String with a specified character.
    7169     *
    7170     * <p>The String is padded to the size of {@code size}.</p>
    7171     *
    7172     * <pre>
    7173     * StringUtils.rightPad(null, *, *)     = null
    7174     * StringUtils.rightPad("", 3, 'z')     = "zzz"
    7175     * StringUtils.rightPad("bat", 3, 'z')  = "bat"
    7176     * StringUtils.rightPad("bat", 5, 'z')  = "batzz"
    7177     * StringUtils.rightPad("bat", 1, 'z')  = "bat"
    7178     * StringUtils.rightPad("bat", -1, 'z') = "bat"
    7179     * </pre>
    7180     *
    7181     * @param str  the String to pad out, may be null
    7182     * @param size  the size to pad to
    7183     * @param padChar  the character to pad with
    7184     * @return right padded String or original String if no padding is necessary,
    7185     *  {@code null} if null String input
    7186     * @since 2.0
    7187     */
    7188    public static String rightPad(final String str, final int size, final char padChar) {
    7189        if (str == null) {
    7190            return null;
    7191        }
    7192        final int pads = size - str.length();
    7193        if (pads <= 0) {
    7194            return str; // returns original String when possible
    7195        }
    7196        if (pads > PAD_LIMIT) {
    7197            return rightPad(str, size, String.valueOf(padChar));
    7198        }
    7199        return str.concat(repeat(padChar, pads));
    7200    }
    7201
    7202    /**
    7203     * Right pad a String with a specified String.
    7204     *
    7205     * <p>The String is padded to the size of {@code size}.</p>
    7206     *
    7207     * <pre>
    7208     * StringUtils.rightPad(null, *, *)      = null
    7209     * StringUtils.rightPad("", 3, "z")      = "zzz"
    7210     * StringUtils.rightPad("bat", 3, "yz")  = "bat"
    7211     * StringUtils.rightPad("bat", 5, "yz")  = "batyz"
    7212     * StringUtils.rightPad("bat", 8, "yz")  = "batyzyzy"
    7213     * StringUtils.rightPad("bat", 1, "yz")  = "bat"
    7214     * StringUtils.rightPad("bat", -1, "yz") = "bat"
    7215     * StringUtils.rightPad("bat", 5, null)  = "bat  "
    7216     * StringUtils.rightPad("bat", 5, "")    = "bat  "
    7217     * </pre>
    7218     *
    7219     * @param str  the String to pad out, may be null
    7220     * @param size  the size to pad to
    7221     * @param padStr  the String to pad with, null or empty treated as single space
    7222     * @return right padded String or original String if no padding is necessary,
    7223     *  {@code null} if null String input
    7224     */
    7225    public static String rightPad(final String str, final int size, String padStr) {
    7226        if (str == null) {
    7227            return null;
    7228        }
    7229        if (isEmpty(padStr)) {
    7230            padStr = SPACE;
    7231        }
    7232        final int padLen = padStr.length();
    7233        final int strLen = str.length();
    7234        final int pads = size - strLen;
    7235        if (pads <= 0) {
    7236            return str; // returns original String when possible
    7237        }
    7238        if (padLen == 1 && pads <= PAD_LIMIT) {
    7239            return rightPad(str, size, padStr.charAt(0));
    7240        }
    7241
    7242        if (pads == padLen) {
    7243            return str.concat(padStr);
    7244        }
    7245        if (pads < padLen) {
    7246            return str.concat(padStr.substring(0, pads));
    7247        }
    7248        final char[] padding = new char[pads];
    7249        final char[] padChars = padStr.toCharArray();
    7250        for (int i = 0; i < pads; i++) {
    7251            padding[i] = padChars[i % padLen];
    7252        }
    7253        return str.concat(new String(padding));
    7254    }
    7255
    7256    /**
    7257     * Rotate (circular shift) a String of {@code shift} characters.
    7258     * <ul>
    7259     *  <li>If {@code shift > 0}, right circular shift (ex : ABCDEF =&gt; FABCDE)</li>
    7260     *  <li>If {@code shift < 0}, left circular shift (ex : ABCDEF =&gt; BCDEFA)</li>
    7261     * </ul>
    7262     *
    7263     * <pre>
    7264     * StringUtils.rotate(null, *)        = null
    7265     * StringUtils.rotate("", *)          = ""
    7266     * StringUtils.rotate("abcdefg", 0)   = "abcdefg"
    7267     * StringUtils.rotate("abcdefg", 2)   = "fgabcde"
    7268     * StringUtils.rotate("abcdefg", -2)  = "cdefgab"
    7269     * StringUtils.rotate("abcdefg", 7)   = "abcdefg"
    7270     * StringUtils.rotate("abcdefg", -7)  = "abcdefg"
    7271     * StringUtils.rotate("abcdefg", 9)   = "fgabcde"
    7272     * StringUtils.rotate("abcdefg", -9)  = "cdefgab"
    7273     * </pre>
    7274     *
    7275     * @param str  the String to rotate, may be null
    7276     * @param shift  number of time to shift (positive : right shift, negative : left shift)
    7277     * @return the rotated String,
    7278     *          or the original String if {@code shift == 0},
    7279     *          or {@code null} if null String input
    7280     * @since 3.5
    7281     */
    7282    public static String rotate(final String str, final int shift) {
    7283        if (str == null) {
    7284            return null;
    7285        }
    7286
    7287        final int strLen = str.length();
    7288        if (shift == 0 || strLen == 0 || shift % strLen == 0) {
    7289            return str;
    7290        }
    7291
    7292        final StringBuilder builder = new StringBuilder(strLen);
    7293        final int offset = - (shift % strLen);
    7294        builder.append(substring(str, offset));
    7295        builder.append(substring(str, 0, offset));
    7296        return builder.toString();
    7297    }
    7298
    7299    /**
    7300     * Splits the provided text into an array, using whitespace as the
    7301     * separator.
    7302     * Whitespace is defined by {@link Character#isWhitespace(char)}.
    7303     *
    7304     * <p>The separator is not included in the returned String array.
    7305     * Adjacent separators are treated as one separator.
    7306     * For more control over the split use the StrTokenizer class.</p>
    7307     *
    7308     * <p>A {@code null} input String returns {@code null}.</p>
    7309     *
    7310     * <pre>
    7311     * StringUtils.split(null)       = null
    7312     * StringUtils.split("")         = []
    7313     * StringUtils.split("abc def")  = ["abc", "def"]
    7314     * StringUtils.split("abc  def") = ["abc", "def"]
    7315     * StringUtils.split(" abc ")    = ["abc"]
    7316     * </pre>
    7317     *
    7318     * @param str  the String to parse, may be null
    7319     * @return an array of parsed Strings, {@code null} if null String input
    7320     */
    7321    public static String[] split(final String str) {
    7322        return split(str, null, -1);
    7323    }
    7324
    7325    /**
    7326     * Splits the provided text into an array, separator specified.
    7327     * This is an alternative to using StringTokenizer.
    7328     *
    7329     * <p>The separator is not included in the returned String array.
    7330     * Adjacent separators are treated as one separator.
    7331     * For more control over the split use the StrTokenizer class.</p>
    7332     *
    7333     * <p>A {@code null} input String returns {@code null}.</p>
    7334     *
    7335     * <pre>
    7336     * StringUtils.split(null, *)         = null
    7337     * StringUtils.split("", *)           = []
    7338     * StringUtils.split("a.b.c", '.')    = ["a", "b", "c"]
    7339     * StringUtils.split("a..b.c", '.')   = ["a", "b", "c"]
    7340     * StringUtils.split("a:b:c", '.')    = ["a:b:c"]
    7341     * StringUtils.split("a b c", ' ')    = ["a", "b", "c"]
    7342     * </pre>
    7343     *
    7344     * @param str  the String to parse, may be null
    7345     * @param separatorChar  the character used as the delimiter
    7346     * @return an array of parsed Strings, {@code null} if null String input
    7347     * @since 2.0
    7348     */
    7349    public static String[] split(final String str, final char separatorChar) {
    7350        return splitWorker(str, separatorChar, false);
    7351    }
    7352
    7353    /**
    7354     * Splits the provided text into an array, separators specified.
    7355     * This is an alternative to using StringTokenizer.
    7356     *
    7357     * <p>The separator is not included in the returned String array.
    7358     * Adjacent separators are treated as one separator.
    7359     * For more control over the split use the StrTokenizer class.</p>
    7360     *
    7361     * <p>A {@code null} input String returns {@code null}.
    7362     * A {@code null} separatorChars splits on whitespace.</p>
    7363     *
    7364     * <pre>
    7365     * StringUtils.split(null, *)         = null
    7366     * StringUtils.split("", *)           = []
    7367     * StringUtils.split("abc def", null) = ["abc", "def"]
    7368     * StringUtils.split("abc def", " ")  = ["abc", "def"]
    7369     * StringUtils.split("abc  def", " ") = ["abc", "def"]
    7370     * StringUtils.split("ab:cd:ef", ":") = ["ab", "cd", "ef"]
    7371     * </pre>
    7372     *
    7373     * @param str  the String to parse, may be null
    7374     * @param separatorChars  the characters used as the delimiters,
    7375     *  {@code null} splits on whitespace
    7376     * @return an array of parsed Strings, {@code null} if null String input
    7377     */
    7378    public static String[] split(final String str, final String separatorChars) {
    7379        return splitWorker(str, separatorChars, -1, false);
    7380    }
    7381
    7382    /**
    7383     * Splits the provided text into an array with a maximum length,
    7384     * separators specified.
    7385     *
    7386     * <p>The separator is not included in the returned String array.
    7387     * Adjacent separators are treated as one separator.</p>
    7388     *
    7389     * <p>A {@code null} input String returns {@code null}.
    7390     * A {@code null} separatorChars splits on whitespace.</p>
    7391     *
    7392     * <p>If more than {@code max} delimited substrings are found, the last
    7393     * returned string includes all characters after the first {@code max - 1}
    7394     * returned strings (including separator characters).</p>
    7395     *
    7396     * <pre>
    7397     * StringUtils.split(null, *, *)            = null
    7398     * StringUtils.split("", *, *)              = []
    7399     * StringUtils.split("ab cd ef", null, 0)   = ["ab", "cd", "ef"]
    7400     * StringUtils.split("ab   cd ef", null, 0) = ["ab", "cd", "ef"]
    7401     * StringUtils.split("ab:cd:ef", ":", 0)    = ["ab", "cd", "ef"]
    7402     * StringUtils.split("ab:cd:ef", ":", 2)    = ["ab", "cd:ef"]
    7403     * </pre>
    7404     *
    7405     * @param str  the String to parse, may be null
    7406     * @param separatorChars  the characters used as the delimiters,
    7407     *  {@code null} splits on whitespace
    7408     * @param max  the maximum number of elements to include in the
    7409     *  array. A zero or negative value implies no limit
    7410     * @return an array of parsed Strings, {@code null} if null String input
    7411     */
    7412    public static String[] split(final String str, final String separatorChars, final int max) {
    7413        return splitWorker(str, separatorChars, max, false);
    7414    }
    7415
    7416    /**
    7417     * Splits a String by Character type as returned by
    7418     * {@code java.lang.Character.getType(char)}. Groups of contiguous
    7419     * characters of the same type are returned as complete tokens.
    7420     * <pre>
    7421     * StringUtils.splitByCharacterType(null)         = null
    7422     * StringUtils.splitByCharacterType("")           = []
    7423     * StringUtils.splitByCharacterType("ab de fg")   = ["ab", " ", "de", " ", "fg"]
    7424     * StringUtils.splitByCharacterType("ab   de fg") = ["ab", "   ", "de", " ", "fg"]
    7425     * StringUtils.splitByCharacterType("ab:cd:ef")   = ["ab", ":", "cd", ":", "ef"]
    7426     * StringUtils.splitByCharacterType("number5")    = ["number", "5"]
    7427     * StringUtils.splitByCharacterType("fooBar")     = ["foo", "B", "ar"]
    7428     * StringUtils.splitByCharacterType("foo200Bar")  = ["foo", "200", "B", "ar"]
    7429     * StringUtils.splitByCharacterType("ASFRules")   = ["ASFR", "ules"]
    7430     * </pre>
    7431     * @param str the String to split, may be {@code null}
    7432     * @return an array of parsed Strings, {@code null} if null String input
    7433     * @since 2.4
    7434     */
    7435    public static String[] splitByCharacterType(final String str) {
    7436        return splitByCharacterType(str, false);
    7437    }
    7438
    7439    /**
    7440     * <p>Splits a String by Character type as returned by
    7441     * {@code java.lang.Character.getType(char)}. Groups of contiguous
    7442     * characters of the same type are returned as complete tokens, with the
    7443     * following exception: if {@code camelCase} is {@code true},
    7444     * the character of type {@code Character.UPPERCASE_LETTER}, if any,
    7445     * immediately preceding a token of type {@code Character.LOWERCASE_LETTER}
    7446     * will belong to the following token rather than to the preceding, if any,
    7447     * {@code Character.UPPERCASE_LETTER} token.
    7448     * @param str the String to split, may be {@code null}
    7449     * @param camelCase whether to use so-called "camel-case" for letter types
    7450     * @return an array of parsed Strings, {@code null} if null String input
    7451     * @since 2.4
    7452     */
    7453    private static String[] splitByCharacterType(final String str, final boolean camelCase) {
    7454        if (str == null) {
    7455            return null;
    7456        }
    7457        if (str.isEmpty()) {
    7458            return ArrayUtils.EMPTY_STRING_ARRAY;
    7459        }
    7460        final char[] c = str.toCharArray();
    7461        final List<String> list = new ArrayList<>();
    7462        int tokenStart = 0;
    7463        int currentType = Character.getType(c[tokenStart]);
    7464        for (int pos = tokenStart + 1; pos < c.length; pos++) {
    7465            final int type = Character.getType(c[pos]);
    7466            if (type == currentType) {
    7467                continue;
    7468            }
    7469            if (camelCase && type == Character.LOWERCASE_LETTER && currentType == Character.UPPERCASE_LETTER) {
    7470                final int newTokenStart = pos - 1;
    7471                if (newTokenStart != tokenStart) {
    7472                    list.add(new String(c, tokenStart, newTokenStart - tokenStart));
    7473                    tokenStart = newTokenStart;
    7474                }
    7475            } else {
    7476                list.add(new String(c, tokenStart, pos - tokenStart));
    7477                tokenStart = pos;
    7478            }
    7479            currentType = type;
    7480        }
    7481        list.add(new String(c, tokenStart, c.length - tokenStart));
    7482        return list.toArray(ArrayUtils.EMPTY_STRING_ARRAY);
    7483    }
    7484
    7485    /**
    7486     * <p>Splits a String by Character type as returned by
    7487     * {@code java.lang.Character.getType(char)}. Groups of contiguous
    7488     * characters of the same type are returned as complete tokens, with the
    7489     * following exception: the character of type
    7490     * {@code Character.UPPERCASE_LETTER}, if any, immediately
    7491     * preceding a token of type {@code Character.LOWERCASE_LETTER}
    7492     * will belong to the following token rather than to the preceding, if any,
    7493     * {@code Character.UPPERCASE_LETTER} token.
    7494     * <pre>
    7495     * StringUtils.splitByCharacterTypeCamelCase(null)         = null
    7496     * StringUtils.splitByCharacterTypeCamelCase("")           = []
    7497     * StringUtils.splitByCharacterTypeCamelCase("ab de fg")   = ["ab", " ", "de", " ", "fg"]
    7498     * StringUtils.splitByCharacterTypeCamelCase("ab   de fg") = ["ab", "   ", "de", " ", "fg"]
    7499     * StringUtils.splitByCharacterTypeCamelCase("ab:cd:ef")   = ["ab", ":", "cd", ":", "ef"]
    7500     * StringUtils.splitByCharacterTypeCamelCase("number5")    = ["number", "5"]
    7501     * StringUtils.splitByCharacterTypeCamelCase("fooBar")     = ["foo", "Bar"]
    7502     * StringUtils.splitByCharacterTypeCamelCase("foo200Bar")  = ["foo", "200", "Bar"]
    7503     * StringUtils.splitByCharacterTypeCamelCase("ASFRules")   = ["ASF", "Rules"]
    7504     * </pre>
    7505     * @param str the String to split, may be {@code null}
    7506     * @return an array of parsed Strings, {@code null} if null String input
    7507     * @since 2.4
    7508     */
    7509    public static String[] splitByCharacterTypeCamelCase(final String str) {
    7510        return splitByCharacterType(str, true);
    7511    }
    7512
    7513    /**
    7514     * <p>Splits the provided text into an array, separator string specified.
    7515     *
    7516     * <p>The separator(s) will not be included in the returned String array.
    7517     * Adjacent separators are treated as one separator.</p>
    7518     *
    7519     * <p>A {@code null} input String returns {@code null}.
    7520     * A {@code null} separator splits on whitespace.</p>
    7521     *
    7522     * <pre>
    7523     * StringUtils.splitByWholeSeparator(null, *)               = null
    7524     * StringUtils.splitByWholeSeparator("", *)                 = []
    7525     * StringUtils.splitByWholeSeparator("ab de fg", null)      = ["ab", "de", "fg"]
    7526     * StringUtils.splitByWholeSeparator("ab   de fg", null)    = ["ab", "de", "fg"]
    7527     * StringUtils.splitByWholeSeparator("ab:cd:ef", ":")       = ["ab", "cd", "ef"]
    7528     * StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-") = ["ab", "cd", "ef"]
    7529     * </pre>
    7530     *
    7531     * @param str  the String to parse, may be null
    7532     * @param separator  String containing the String to be used as a delimiter,
    7533     *  {@code null} splits on whitespace
    7534     * @return an array of parsed Strings, {@code null} if null String was input
    7535     */
    7536    public static String[] splitByWholeSeparator(final String str, final String separator) {
    7537        return splitByWholeSeparatorWorker(str, separator, -1, false);
    7538    }
    7539
    7540    /**
    7541     * Splits the provided text into an array, separator string specified.
    7542     * Returns a maximum of {@code max} substrings.
    7543     *
    7544     * <p>The separator(s) will not be included in the returned String array.
    7545     * Adjacent separators are treated as one separator.</p>
    7546     *
    7547     * <p>A {@code null} input String returns {@code null}.
    7548     * A {@code null} separator splits on whitespace.</p>
    7549     *
    7550     * <pre>
    7551     * StringUtils.splitByWholeSeparator(null, *, *)               = null
    7552     * StringUtils.splitByWholeSeparator("", *, *)                 = []
    7553     * StringUtils.splitByWholeSeparator("ab de fg", null, 0)      = ["ab", "de", "fg"]
    7554     * StringUtils.splitByWholeSeparator("ab   de fg", null, 0)    = ["ab", "de", "fg"]
    7555     * StringUtils.splitByWholeSeparator("ab:cd:ef", ":", 2)       = ["ab", "cd:ef"]
    7556     * StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-", 5) = ["ab", "cd", "ef"]
    7557     * StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-", 2) = ["ab", "cd-!-ef"]
    7558     * </pre>
    7559     *
    7560     * @param str  the String to parse, may be null
    7561     * @param separator  String containing the String to be used as a delimiter,
    7562     *  {@code null} splits on whitespace
    7563     * @param max  the maximum number of elements to include in the returned
    7564     *  array. A zero or negative value implies no limit.
    7565     * @return an array of parsed Strings, {@code null} if null String was input
    7566     */
    7567    public static String[] splitByWholeSeparator( final String str, final String separator, final int max) {
    7568        return splitByWholeSeparatorWorker(str, separator, max, false);
    7569    }
    7570
    7571    /**
    7572     * Splits the provided text into an array, separator string specified.
    7573     *
    7574     * <p>The separator is not included in the returned String array.
    7575     * Adjacent separators are treated as separators for empty tokens.
    7576     * For more control over the split use the StrTokenizer class.</p>
    7577     *
    7578     * <p>A {@code null} input String returns {@code null}.
    7579     * A {@code null} separator splits on whitespace.</p>
    7580     *
    7581     * <pre>
    7582     * StringUtils.splitByWholeSeparatorPreserveAllTokens(null, *)               = null
    7583     * StringUtils.splitByWholeSeparatorPreserveAllTokens("", *)                 = []
    7584     * StringUtils.splitByWholeSeparatorPreserveAllTokens("ab de fg", null)      = ["ab", "de", "fg"]
    7585     * StringUtils.splitByWholeSeparatorPreserveAllTokens("ab   de fg", null)    = ["ab", "", "", "de", "fg"]
    7586     * StringUtils.splitByWholeSeparatorPreserveAllTokens("ab:cd:ef", ":")       = ["ab", "cd", "ef"]
    7587     * StringUtils.splitByWholeSeparatorPreserveAllTokens("ab-!-cd-!-ef", "-!-") = ["ab", "cd", "ef"]
    7588     * </pre>
    7589     *
    7590     * @param str  the String to parse, may be null
    7591     * @param separator  String containing the String to be used as a delimiter,
    7592     *  {@code null} splits on whitespace
    7593     * @return an array of parsed Strings, {@code null} if null String was input
    7594     * @since 2.4
    7595     */
    7596    public static String[] splitByWholeSeparatorPreserveAllTokens(final String str, final String separator) {
    7597        return splitByWholeSeparatorWorker(str, separator, -1, true);
    7598    }
    7599
    7600    /**
    7601     * Splits the provided text into an array, separator string specified.
    7602     * Returns a maximum of {@code max} substrings.
    7603     *
    7604     * <p>The separator is not included in the returned String array.
    7605     * Adjacent separators are treated as separators for empty tokens.
    7606     * For more control over the split use the StrTokenizer class.</p>
    7607     *
    7608     * <p>A {@code null} input String returns {@code null}.
    7609     * A {@code null} separator splits on whitespace.</p>
    7610     *
    7611     * <pre>
    7612     * StringUtils.splitByWholeSeparatorPreserveAllTokens(null, *, *)               = null
    7613     * StringUtils.splitByWholeSeparatorPreserveAllTokens("", *, *)                 = []
    7614     * StringUtils.splitByWholeSeparatorPreserveAllTokens("ab de fg", null, 0)      = ["ab", "de", "fg"]
    7615     * StringUtils.splitByWholeSeparatorPreserveAllTokens("ab   de fg", null, 0)    = ["ab", "", "", "de", "fg"]
    7616     * StringUtils.splitByWholeSeparatorPreserveAllTokens("ab:cd:ef", ":", 2)       = ["ab", "cd:ef"]
    7617     * StringUtils.splitByWholeSeparatorPreserveAllTokens("ab-!-cd-!-ef", "-!-", 5) = ["ab", "cd", "ef"]
    7618     * StringUtils.splitByWholeSeparatorPreserveAllTokens("ab-!-cd-!-ef", "-!-", 2) = ["ab", "cd-!-ef"]
    7619     * </pre>
    7620     *
    7621     * @param str  the String to parse, may be null
    7622     * @param separator  String containing the String to be used as a delimiter,
    7623     *  {@code null} splits on whitespace
    7624     * @param max  the maximum number of elements to include in the returned
    7625     *  array. A zero or negative value implies no limit.
    7626     * @return an array of parsed Strings, {@code null} if null String was input
    7627     * @since 2.4
    7628     */
    7629    public static String[] splitByWholeSeparatorPreserveAllTokens(final String str, final String separator, final int max) {
    7630        return splitByWholeSeparatorWorker(str, separator, max, true);
    7631    }
    7632
    7633    /**
    7634     * Performs the logic for the {@code splitByWholeSeparatorPreserveAllTokens} methods.
    7635     *
    7636     * @param str  the String to parse, may be {@code null}
    7637     * @param separator  String containing the String to be used as a delimiter,
    7638     *  {@code null} splits on whitespace
    7639     * @param max  the maximum number of elements to include in the returned
    7640     *  array. A zero or negative value implies no limit.
    7641     * @param preserveAllTokens if {@code true}, adjacent separators are
    7642     * treated as empty token separators; if {@code false}, adjacent
    7643     * separators are treated as one separator.
    7644     * @return an array of parsed Strings, {@code null} if null String input
    7645     * @since 2.4
    7646     */
    7647    private static String[] splitByWholeSeparatorWorker(
    7648            final String str, final String separator, final int max, final boolean preserveAllTokens) {
    7649        if (str == null) {
    7650            return null;
    7651        }
    7652
    7653        final int len = str.length();
    7654
    7655        if (len == 0) {
    7656            return ArrayUtils.EMPTY_STRING_ARRAY;
    7657        }
    7658
    7659        if (separator == null || EMPTY.equals(separator)) {
    7660            // Split on whitespace.
    7661            return splitWorker(str, null, max, preserveAllTokens);
    7662        }
    7663
    7664        final int separatorLength = separator.length();
    7665
    7666        final ArrayList<String> substrings = new ArrayList<>();
    7667        int numberOfSubstrings = 0;
    7668        int beg = 0;
    7669        int end = 0;
    7670        while (end < len) {
    7671            end = str.indexOf(separator, beg);
    7672
    7673            if (end > -1) {
    7674                if (end > beg) {
    7675                    numberOfSubstrings += 1;
    7676
    7677                    if (numberOfSubstrings == max) {
    7678                        end = len;
    7679                        substrings.add(str.substring(beg));
    7680                    } else {
    7681                        // The following is OK, because String.substring( beg, end ) excludes
    7682                        // the character at the position 'end'.
    7683                        substrings.add(str.substring(beg, end));
    7684
    7685                        // Set the starting point for the next search.
    7686                        // The following is equivalent to beg = end + (separatorLength - 1) + 1,
    7687                        // which is the right calculation:
    7688                        beg = end + separatorLength;
    7689                    }
    7690                } else {
    7691                    // We found a consecutive occurrence of the separator, so skip it.
    7692                    if (preserveAllTokens) {
    7693                        numberOfSubstrings += 1;
    7694                        if (numberOfSubstrings == max) {
    7695                            end = len;
    7696                            substrings.add(str.substring(beg));
    7697                        } else {
    7698                            substrings.add(EMPTY);
    7699                        }
    7700                    }
    7701                    beg = end + separatorLength;
    7702                }
    7703            } else {
    7704                // String.substring( beg ) goes from 'beg' to the end of the String.
    7705                substrings.add(str.substring(beg));
    7706                end = len;
    7707            }
    7708        }
    7709
    7710        return substrings.toArray(ArrayUtils.EMPTY_STRING_ARRAY);
    7711    }
    7712
    7713    /**
    7714     * Splits the provided text into an array, using whitespace as the
    7715     * separator, preserving all tokens, including empty tokens created by
    7716     * adjacent separators. This is an alternative to using StringTokenizer.
    7717     * Whitespace is defined by {@link Character#isWhitespace(char)}.
    7718     *
    7719     * <p>The separator is not included in the returned String array.
    7720     * Adjacent separators are treated as separators for empty tokens.
    7721     * For more control over the split use the StrTokenizer class.</p>
    7722     *
    7723     * <p>A {@code null} input String returns {@code null}.</p>
    7724     *
    7725     * <pre>
    7726     * StringUtils.splitPreserveAllTokens(null)       = null
    7727     * StringUtils.splitPreserveAllTokens("")         = []
    7728     * StringUtils.splitPreserveAllTokens("abc def")  = ["abc", "def"]
    7729     * StringUtils.splitPreserveAllTokens("abc  def") = ["abc", "", "def"]
    7730     * StringUtils.splitPreserveAllTokens(" abc ")    = ["", "abc", ""]
    7731     * </pre>
    7732     *
    7733     * @param str  the String to parse, may be {@code null}
    7734     * @return an array of parsed Strings, {@code null} if null String input
    7735     * @since 2.1
    7736     */
    7737    public static String[] splitPreserveAllTokens(final String str) {
    7738        return splitWorker(str, null, -1, true);
    7739    }
    7740
    7741    /**
    7742     * Splits the provided text into an array, separator specified,
    7743     * preserving all tokens, including empty tokens created by adjacent
    7744     * separators. This is an alternative to using StringTokenizer.
    7745     *
    7746     * <p>The separator is not included in the returned String array.
    7747     * Adjacent separators are treated as separators for empty tokens.
    7748     * For more control over the split use the StrTokenizer class.</p>
    7749     *
    7750     * <p>A {@code null} input String returns {@code null}.</p>
    7751     *
    7752     * <pre>
    7753     * StringUtils.splitPreserveAllTokens(null, *)         = null
    7754     * StringUtils.splitPreserveAllTokens("", *)           = []
    7755     * StringUtils.splitPreserveAllTokens("a.b.c", '.')    = ["a", "b", "c"]
    7756     * StringUtils.splitPreserveAllTokens("a..b.c", '.')   = ["a", "", "b", "c"]
    7757     * StringUtils.splitPreserveAllTokens("a:b:c", '.')    = ["a:b:c"]
    7758     * StringUtils.splitPreserveAllTokens("a\tb\nc", null) = ["a", "b", "c"]
    7759     * StringUtils.splitPreserveAllTokens("a b c", ' ')    = ["a", "b", "c"]
    7760     * StringUtils.splitPreserveAllTokens("a b c ", ' ')   = ["a", "b", "c", ""]
    7761     * StringUtils.splitPreserveAllTokens("a b c  ", ' ')  = ["a", "b", "c", "", ""]
    7762     * StringUtils.splitPreserveAllTokens(" a b c", ' ')   = ["", "a", "b", "c"]
    7763     * StringUtils.splitPreserveAllTokens("  a b c", ' ')  = ["", "", "a", "b", "c"]
    7764     * StringUtils.splitPreserveAllTokens(" a b c ", ' ')  = ["", "a", "b", "c", ""]
    7765     * </pre>
    7766     *
    7767     * @param str  the String to parse, may be {@code null}
    7768     * @param separatorChar  the character used as the delimiter,
    7769     *  {@code null} splits on whitespace
    7770     * @return an array of parsed Strings, {@code null} if null String input
    7771     * @since 2.1
    7772     */
    7773    public static String[] splitPreserveAllTokens(final String str, final char separatorChar) {
    7774        return splitWorker(str, separatorChar, true);
    7775    }
    7776
    7777    /**
    7778     * Splits the provided text into an array, separators specified,
    7779     * preserving all tokens, including empty tokens created by adjacent
    7780     * separators. This is an alternative to using StringTokenizer.
    7781     *
    7782     * <p>The separator is not included in the returned String array.
    7783     * Adjacent separators are treated as separators for empty tokens.
    7784     * For more control over the split use the StrTokenizer class.</p>
    7785     *
    7786     * <p>A {@code null} input String returns {@code null}.
    7787     * A {@code null} separatorChars splits on whitespace.</p>
    7788     *
    7789     * <pre>
    7790     * StringUtils.splitPreserveAllTokens(null, *)           = null
    7791     * StringUtils.splitPreserveAllTokens("", *)             = []
    7792     * StringUtils.splitPreserveAllTokens("abc def", null)   = ["abc", "def"]
    7793     * StringUtils.splitPreserveAllTokens("abc def", " ")    = ["abc", "def"]
    7794     * StringUtils.splitPreserveAllTokens("abc  def", " ")   = ["abc", "", "def"]
    7795     * StringUtils.splitPreserveAllTokens("ab:cd:ef", ":")   = ["ab", "cd", "ef"]
    7796     * StringUtils.splitPreserveAllTokens("ab:cd:ef:", ":")  = ["ab", "cd", "ef", ""]
    7797     * StringUtils.splitPreserveAllTokens("ab:cd:ef::", ":") = ["ab", "cd", "ef", "", ""]
    7798     * StringUtils.splitPreserveAllTokens("ab::cd:ef", ":")  = ["ab", "", "cd", "ef"]
    7799     * StringUtils.splitPreserveAllTokens(":cd:ef", ":")     = ["", "cd", "ef"]
    7800     * StringUtils.splitPreserveAllTokens("::cd:ef", ":")    = ["", "", "cd", "ef"]
    7801     * StringUtils.splitPreserveAllTokens(":cd:ef:", ":")    = ["", "cd", "ef", ""]
    7802     * </pre>
    7803     *
    7804     * @param str  the String to parse, may be {@code null}
    7805     * @param separatorChars  the characters used as the delimiters,
    7806     *  {@code null} splits on whitespace
    7807     * @return an array of parsed Strings, {@code null} if null String input
    7808     * @since 2.1
    7809     */
    7810    public static String[] splitPreserveAllTokens(final String str, final String separatorChars) {
    7811        return splitWorker(str, separatorChars, -1, true);
    7812    }
    7813
    7814    /**
    7815     * Splits the provided text into an array with a maximum length,
    7816     * separators specified, preserving all tokens, including empty tokens
    7817     * created by adjacent separators.
    7818     *
    7819     * <p>The separator is not included in the returned String array.
    7820     * Adjacent separators are treated as separators for empty tokens.
    7821     * Adjacent separators are treated as one separator.</p>
    7822     *
    7823     * <p>A {@code null} input String returns {@code null}.
    7824     * A {@code null} separatorChars splits on whitespace.</p>
    7825     *
    7826     * <p>If more than {@code max} delimited substrings are found, the last
    7827     * returned string includes all characters after the first {@code max - 1}
    7828     * returned strings (including separator characters).</p>
    7829     *
    7830     * <pre>
    7831     * StringUtils.splitPreserveAllTokens(null, *, *)            = null
    7832     * StringUtils.splitPreserveAllTokens("", *, *)              = []
    7833     * StringUtils.splitPreserveAllTokens("ab de fg", null, 0)   = ["ab", "de", "fg"]
    7834     * StringUtils.splitPreserveAllTokens("ab   de fg", null, 0) = ["ab", "", "", "de", "fg"]
    7835     * StringUtils.splitPreserveAllTokens("ab:cd:ef", ":", 0)    = ["ab", "cd", "ef"]
    7836     * StringUtils.splitPreserveAllTokens("ab:cd:ef", ":", 2)    = ["ab", "cd:ef"]
    7837     * StringUtils.splitPreserveAllTokens("ab   de fg", null, 2) = ["ab", "  de fg"]
    7838     * StringUtils.splitPreserveAllTokens("ab   de fg", null, 3) = ["ab", "", " de fg"]
    7839     * StringUtils.splitPreserveAllTokens("ab   de fg", null, 4) = ["ab", "", "", "de fg"]
    7840     * </pre>
    7841     *
    7842     * @param str  the String to parse, may be {@code null}
    7843     * @param separatorChars  the characters used as the delimiters,
    7844     *  {@code null} splits on whitespace
    7845     * @param max  the maximum number of elements to include in the
    7846     *  array. A zero or negative value implies no limit
    7847     * @return an array of parsed Strings, {@code null} if null String input
    7848     * @since 2.1
    7849     */
    7850    public static String[] splitPreserveAllTokens(final String str, final String separatorChars, final int max) {
    7851        return splitWorker(str, separatorChars, max, true);
    7852    }
    7853
    7854    /**
    7855     * Performs the logic for the {@code split} and
    7856     * {@code splitPreserveAllTokens} methods that do not return a
    7857     * maximum array length.
    7858     *
    7859     * @param str  the String to parse, may be {@code null}
    7860     * @param separatorChar the separate character
    7861     * @param preserveAllTokens if {@code true}, adjacent separators are
    7862     * treated as empty token separators; if {@code false}, adjacent
    7863     * separators are treated as one separator.
    7864     * @return an array of parsed Strings, {@code null} if null String input
    7865     */
    7866    private static String[] splitWorker(final String str, final char separatorChar, final boolean preserveAllTokens) {
    7867        // Performance tuned for 2.0 (JDK1.4)
    7868        if (str == null) {
    7869            return null;
    7870        }
    7871        final int len = str.length();
    7872        if (len == 0) {
    7873            return ArrayUtils.EMPTY_STRING_ARRAY;
    7874        }
    7875        final List<String> list = new ArrayList<>();
    7876        int i = 0;
    7877        int start = 0;
    7878        boolean match = false;
    7879        boolean lastMatch = false;
    7880        while (i < len) {
    7881            if (str.charAt(i) == separatorChar) {
    7882                if (match || preserveAllTokens) {
    7883                    list.add(str.substring(start, i));
    7884                    match = false;
    7885                    lastMatch = true;
    7886                }
    7887                start = ++i;
    7888                continue;
    7889            }
    7890            lastMatch = false;
    7891            match = true;
    7892            i++;
    7893        }
    7894        if (match || preserveAllTokens && lastMatch) {
    7895            list.add(str.substring(start, i));
    7896        }
    7897        return list.toArray(ArrayUtils.EMPTY_STRING_ARRAY);
    7898    }
    7899
    7900    /**
    7901     * Performs the logic for the {@code split} and
    7902     * {@code splitPreserveAllTokens} methods that return a maximum array
    7903     * length.
    7904     *
    7905     * @param str  the String to parse, may be {@code null}
    7906     * @param separatorChars the separate character
    7907     * @param max  the maximum number of elements to include in the
    7908     *  array. A zero or negative value implies no limit.
    7909     * @param preserveAllTokens if {@code true}, adjacent separators are
    7910     * treated as empty token separators; if {@code false}, adjacent
    7911     * separators are treated as one separator.
    7912     * @return an array of parsed Strings, {@code null} if null String input
    7913     */
    7914    private static String[] splitWorker(final String str, final String separatorChars, final int max, final boolean preserveAllTokens) {
    7915        // Performance tuned for 2.0 (JDK1.4)
    7916        // Direct code is quicker than StringTokenizer.
    7917        // Also, StringTokenizer uses isSpace() not isWhitespace()
    7918
    7919        if (str == null) {
    7920            return null;
    7921        }
    7922        final int len = str.length();
    7923        if (len == 0) {
    7924            return ArrayUtils.EMPTY_STRING_ARRAY;
    7925        }
    7926        final List<String> list = new ArrayList<>();
    7927        int sizePlus1 = 1;
    7928        int i = 0;
    7929        int start = 0;
    7930        boolean match = false;
    7931        boolean lastMatch = false;
    7932        if (separatorChars == null) {
    7933            // Null separator means use whitespace
    7934            while (i < len) {
    7935                if (Character.isWhitespace(str.charAt(i))) {
    7936                    if (match || preserveAllTokens) {
    7937                        lastMatch = true;
    7938                        if (sizePlus1++ == max) {
    7939                            i = len;
    7940                            lastMatch = false;
    7941                        }
    7942                        list.add(str.substring(start, i));
    7943                        match = false;
    7944                    }
    7945                    start = ++i;
    7946                    continue;
    7947                }
    7948                lastMatch = false;
    7949                match = true;
    7950                i++;
    7951            }
    7952        } else if (separatorChars.length() == 1) {
    7953            // Optimise 1 character case
    7954            final char sep = separatorChars.charAt(0);
    7955            while (i < len) {
    7956                if (str.charAt(i) == sep) {
    7957                    if (match || preserveAllTokens) {
    7958                        lastMatch = true;
    7959                        if (sizePlus1++ == max) {
    7960                            i = len;
    7961                            lastMatch = false;
    7962                        }
    7963                        list.add(str.substring(start, i));
    7964                        match = false;
    7965                    }
    7966                    start = ++i;
    7967                    continue;
    7968                }
    7969                lastMatch = false;
    7970                match = true;
    7971                i++;
    7972            }
    7973        } else {
    7974            // standard case
    7975            while (i < len) {
    7976                if (separatorChars.indexOf(str.charAt(i)) >= 0) {
    7977                    if (match || preserveAllTokens) {
    7978                        lastMatch = true;
    7979                        if (sizePlus1++ == max) {
    7980                            i = len;
    7981                            lastMatch = false;
    7982                        }
    7983                        list.add(str.substring(start, i));
    7984                        match = false;
    7985                    }
    7986                    start = ++i;
    7987                    continue;
    7988                }
    7989                lastMatch = false;
    7990                match = true;
    7991                i++;
    7992            }
    7993        }
    7994        if (match || preserveAllTokens && lastMatch) {
    7995            list.add(str.substring(start, i));
    7996        }
    7997        return list.toArray(ArrayUtils.EMPTY_STRING_ARRAY);
    7998    }
    7999
    8000    /**
    8001     * Check if a CharSequence starts with a specified prefix.
    8002     *
    8003     * <p>{@code null}s are handled without exceptions. Two {@code null}
    8004     * references are considered to be equal. The comparison is case-sensitive.</p>
    8005     *
    8006     * <pre>
    8007     * StringUtils.startsWith(null, null)      = true
    8008     * StringUtils.startsWith(null, "abc")     = false
    8009     * StringUtils.startsWith("abcdef", null)  = false
    8010     * StringUtils.startsWith("abcdef", "abc") = true
    8011     * StringUtils.startsWith("ABCDEF", "abc") = false
    8012     * </pre>
    8013     *
    8014     * @see String#startsWith(String)
    8015     * @param str  the CharSequence to check, may be null
    8016     * @param prefix the prefix to find, may be null
    8017     * @return {@code true} if the CharSequence starts with the prefix, case-sensitive, or
    8018     *  both {@code null}
    8019     * @since 2.4
    8020     * @since 3.0 Changed signature from startsWith(String, String) to startsWith(CharSequence, CharSequence)
    8021     */
    8022    public static boolean startsWith(final CharSequence str, final CharSequence prefix) {
    8023        return startsWith(str, prefix, false);
    8024    }
    8025
    8026    /**
    8027     * Check if a CharSequence starts with a specified prefix (optionally case-insensitive).
    8028     *
    8029     * @see String#startsWith(String)
    8030     * @param str  the CharSequence to check, may be null
    8031     * @param prefix the prefix to find, may be null
    8032     * @param ignoreCase indicates whether the compare should ignore case
    8033     *  (case-insensitive) or not.
    8034     * @return {@code true} if the CharSequence starts with the prefix or
    8035     *  both {@code null}
    8036     */
    8037    private static boolean startsWith(final CharSequence str, final CharSequence prefix, final boolean ignoreCase) {
    8038        if (str == null || prefix == null) {
    8039            return str == prefix;
    8040        }
    8041        // Get length once instead of twice in the unlikely case that it changes.
    8042        final int preLen = prefix.length();
    8043        if (preLen > str.length()) {
    8044            return false;
    8045        }
    8046        return CharSequenceUtils.regionMatches(str, ignoreCase, 0, prefix, 0, preLen);
    8047    }
    8048
    8049    /**
    8050     * Check if a CharSequence starts with any of the provided case-sensitive prefixes.
    8051     *
    8052     * <pre>
    8053     * StringUtils.startsWithAny(null, null)      = false
    8054     * StringUtils.startsWithAny(null, new String[] {"abc"})  = false
    8055     * StringUtils.startsWithAny("abcxyz", null)     = false
    8056     * StringUtils.startsWithAny("abcxyz", new String[] {""}) = true
    8057     * StringUtils.startsWithAny("abcxyz", new String[] {"abc"}) = true
    8058     * StringUtils.startsWithAny("abcxyz", new String[] {null, "xyz", "abc"}) = true
    8059     * StringUtils.startsWithAny("abcxyz", null, "xyz", "ABCX") = false
    8060     * StringUtils.startsWithAny("ABCXYZ", null, "xyz", "abc") = false
    8061     * </pre>
    8062     *
    8063     * @param sequence the CharSequence to check, may be null
    8064     * @param searchStrings the case-sensitive CharSequence prefixes, may be empty or contain {@code null}
    8065     * @see StringUtils#startsWith(CharSequence, CharSequence)
    8066     * @return {@code true} if the input {@code sequence} is {@code null} AND no {@code searchStrings} are provided, or
    8067     *   the input {@code sequence} begins with any of the provided case-sensitive {@code searchStrings}.
    8068     * @since 2.5
    8069     * @since 3.0 Changed signature from startsWithAny(String, String[]) to startsWithAny(CharSequence, CharSequence...)
    8070     */
    8071    public static boolean startsWithAny(final CharSequence sequence, final CharSequence... searchStrings) {
    8072        if (isEmpty(sequence) || ArrayUtils.isEmpty(searchStrings)) {
    8073            return false;
    8074        }
    8075        for (final CharSequence searchString : searchStrings) {
    8076            if (startsWith(sequence, searchString)) {
    8077                return true;
    8078            }
    8079        }
    8080        return false;
    8081    }
    8082
    8083    /**
    8084     * Case-insensitive check if a CharSequence starts with a specified prefix.
    8085     *
    8086     * <p>{@code null}s are handled without exceptions. Two {@code null}
    8087     * references are considered to be equal. The comparison is case insensitive.</p>
    8088     *
    8089     * <pre>
    8090     * StringUtils.startsWithIgnoreCase(null, null)      = true
    8091     * StringUtils.startsWithIgnoreCase(null, "abc")     = false
    8092     * StringUtils.startsWithIgnoreCase("abcdef", null)  = false
    8093     * StringUtils.startsWithIgnoreCase("abcdef", "abc") = true
    8094     * StringUtils.startsWithIgnoreCase("ABCDEF", "abc") = true
    8095     * </pre>
    8096     *
    8097     * @see String#startsWith(String)
    8098     * @param str  the CharSequence to check, may be null
    8099     * @param prefix the prefix to find, may be null
    8100     * @return {@code true} if the CharSequence starts with the prefix, case-insensitive, or
    8101     *  both {@code null}
    8102     * @since 2.4
    8103     * @since 3.0 Changed signature from startsWithIgnoreCase(String, String) to startsWithIgnoreCase(CharSequence, CharSequence)
    8104     */
    8105    public static boolean startsWithIgnoreCase(final CharSequence str, final CharSequence prefix) {
    8106        return startsWith(str, prefix, true);
    8107    }
    8108
    8109    /**
    8110     * Strips whitespace from the start and end of a String.
    8111     *
    8112     * <p>This is similar to {@link #trim(String)} but removes whitespace.
    8113     * Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
    8114     *
    8115     * <p>A {@code null} input String returns {@code null}.</p>
    8116     *
    8117     * <pre>
    8118     * StringUtils.strip(null)     = null
    8119     * StringUtils.strip("")       = ""
    8120     * StringUtils.strip("   ")    = ""
    8121     * StringUtils.strip("abc")    = "abc"
    8122     * StringUtils.strip("  abc")  = "abc"
    8123     * StringUtils.strip("abc  ")  = "abc"
    8124     * StringUtils.strip(" abc ")  = "abc"
    8125     * StringUtils.strip(" ab c ") = "ab c"
    8126     * </pre>
    8127     *
    8128     * @param str  the String to remove whitespace from, may be null
    8129     * @return the stripped String, {@code null} if null String input
    8130     */
    8131    public static String strip(final String str) {
    8132        return strip(str, null);
    8133    }
    8134
    8135    /**
    8136     * Strips any of a set of characters from the start and end of a String.
    8137     * This is similar to {@link String#trim()} but allows the characters
    8138     * to be stripped to be controlled.
    8139     *
    8140     * <p>A {@code null} input String returns {@code null}.
    8141     * An empty string ("") input returns the empty string.</p>
    8142     *
    8143     * <p>If the stripChars String is {@code null}, whitespace is
    8144     * stripped as defined by {@link Character#isWhitespace(char)}.
    8145     * Alternatively use {@link #strip(String)}.</p>
    8146     *
    8147     * <pre>
    8148     * StringUtils.strip(null, *)          = null
    8149     * StringUtils.strip("", *)            = ""
    8150     * StringUtils.strip("abc", null)      = "abc"
    8151     * StringUtils.strip("  abc", null)    = "abc"
    8152     * StringUtils.strip("abc  ", null)    = "abc"
    8153     * StringUtils.strip(" abc ", null)    = "abc"
    8154     * StringUtils.strip("  abcyx", "xyz") = "  abc"
    8155     * </pre>
    8156     *
    8157     * @param str  the String to remove characters from, may be null
    8158     * @param stripChars  the characters to remove, null treated as whitespace
    8159     * @return the stripped String, {@code null} if null String input
    8160     */
    8161    public static String strip(String str, final String stripChars) {
    8162        str = stripStart(str, stripChars);
    8163        return stripEnd(str, stripChars);
    8164    }
    8165
    8166    /**
    8167     * Removes diacritics (~= accents) from a string. The case will not be altered.
    8168     * <p>For instance, '&agrave;' will be replaced by 'a'.</p>
    8169     * <p>Decomposes ligatures and digraphs per the KD column in the
    8170     * <a href = "https://www.unicode.org/charts/normalization/">Unicode Normalization Chart.</a></p>
    8171     *
    8172     * <pre>
    8173     * StringUtils.stripAccents(null)                = null
    8174     * StringUtils.stripAccents("")                  = ""
    8175     * StringUtils.stripAccents("control")           = "control"
    8176     * StringUtils.stripAccents("&eacute;clair")     = "eclair"
    8177     * </pre>
    8178     *
    8179     * @param input String to be stripped
    8180     * @return input text with diacritics removed
    8181     *
    8182     * @since 3.0
    8183     */
    8184    // See also Lucene's ASCIIFoldingFilter (Lucene 2.9) that replaces accented characters by their unaccented equivalent (and uncommitted bug fix: https://issues.apache.org/jira/browse/LUCENE-1343?focusedCommentId=12858907&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#action_12858907).
    8185    public static String stripAccents(final String input) {
    8186        if (isEmpty(input)) {
    8187            return input;
    8188        }
    8189        final StringBuilder decomposed = new StringBuilder(Normalizer.normalize(input, Normalizer.Form.NFKD));
    8190        convertRemainingAccentCharacters(decomposed);
    8191        return STRIP_ACCENTS_PATTERN.matcher(decomposed).replaceAll(EMPTY);
    8192    }
    8193
    8194    /**
    8195     * Strips whitespace from the start and end of every String in an array.
    8196     * Whitespace is defined by {@link Character#isWhitespace(char)}.
    8197     *
    8198     * <p>A new array is returned each time, except for length zero.
    8199     * A {@code null} array will return {@code null}.
    8200     * An empty array will return itself.
    8201     * A {@code null} array entry will be ignored.</p>
    8202     *
    8203     * <pre>
    8204     * StringUtils.stripAll(null)             = null
    8205     * StringUtils.stripAll([])               = []
    8206     * StringUtils.stripAll(["abc", "  abc"]) = ["abc", "abc"]
    8207     * StringUtils.stripAll(["abc  ", null])  = ["abc", null]
    8208     * </pre>
    8209     *
    8210     * @param strs  the array to remove whitespace from, may be null
    8211     * @return the stripped Strings, {@code null} if null array input
    8212     */
    8213    public static String[] stripAll(final String... strs) {
    8214        return stripAll(strs, null);
    8215    }
    8216
    8217    /**
    8218     * Strips any of a set of characters from the start and end of every
    8219     * String in an array.
    8220     * <p>Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
    8221     *
    8222     * <p>A new array is returned each time, except for length zero.
    8223     * A {@code null} array will return {@code null}.
    8224     * An empty array will return itself.
    8225     * A {@code null} array entry will be ignored.
    8226     * A {@code null} stripChars will strip whitespace as defined by
    8227     * {@link Character#isWhitespace(char)}.</p>
    8228     *
    8229     * <pre>
    8230     * StringUtils.stripAll(null, *)                = null
    8231     * StringUtils.stripAll([], *)                  = []
    8232     * StringUtils.stripAll(["abc", "  abc"], null) = ["abc", "abc"]
    8233     * StringUtils.stripAll(["abc  ", null], null)  = ["abc", null]
    8234     * StringUtils.stripAll(["abc  ", null], "yz")  = ["abc  ", null]
    8235     * StringUtils.stripAll(["yabcz", null], "yz")  = ["abc", null]
    8236     * </pre>
    8237     *
    8238     * @param strs  the array to remove characters from, may be null
    8239     * @param stripChars  the characters to remove, null treated as whitespace
    8240     * @return the stripped Strings, {@code null} if null array input
    8241     */
    8242    public static String[] stripAll(final String[] strs, final String stripChars) {
    8243        final int strsLen = ArrayUtils.getLength(strs);
    8244        if (strsLen == 0) {
    8245            return strs;
    8246        }
    8247        final String[] newArr = new String[strsLen];
    8248        Arrays.setAll(newArr, i -> strip(strs[i], stripChars));
    8249        return newArr;
    8250    }
    8251
    8252    /**
    8253     * Strips any of a set of characters from the end of a String.
    8254     *
    8255     * <p>A {@code null} input String returns {@code null}.
    8256     * An empty string ("") input returns the empty string.</p>
    8257     *
    8258     * <p>If the stripChars String is {@code null}, whitespace is
    8259     * stripped as defined by {@link Character#isWhitespace(char)}.</p>
    8260     *
    8261     * <pre>
    8262     * StringUtils.stripEnd(null, *)          = null
    8263     * StringUtils.stripEnd("", *)            = ""
    8264     * StringUtils.stripEnd("abc", "")        = "abc"
    8265     * StringUtils.stripEnd("abc", null)      = "abc"
    8266     * StringUtils.stripEnd("  abc", null)    = "  abc"
    8267     * StringUtils.stripEnd("abc  ", null)    = "abc"
    8268     * StringUtils.stripEnd(" abc ", null)    = " abc"
    8269     * StringUtils.stripEnd("  abcyx", "xyz") = "  abc"
    8270     * StringUtils.stripEnd("120.00", ".0")   = "12"
    8271     * </pre>
    8272     *
    8273     * @param str  the String to remove characters from, may be null
    8274     * @param stripChars  the set of characters to remove, null treated as whitespace
    8275     * @return the stripped String, {@code null} if null String input
    8276     */
    8277    public static String stripEnd(final String str, final String stripChars) {
    8278        int end = length(str);
    8279        if (end == 0) {
    8280            return str;
    8281        }
    8282
    8283        if (stripChars == null) {
    8284            while (end != 0 && Character.isWhitespace(str.charAt(end - 1))) {
    8285                end--;
    8286            }
    8287        } else if (stripChars.isEmpty()) {
    8288            return str;
    8289        } else {
    8290            while (end != 0 && stripChars.indexOf(str.charAt(end - 1)) != INDEX_NOT_FOUND) {
    8291                end--;
    8292            }
    8293        }
    8294        return str.substring(0, end);
    8295    }
    8296
    8297    /**
    8298     * Strips any of a set of characters from the start of a String.
    8299     *
    8300     * <p>A {@code null} input String returns {@code null}.
    8301     * An empty string ("") input returns the empty string.</p>
    8302     *
    8303     * <p>If the stripChars String is {@code null}, whitespace is
    8304     * stripped as defined by {@link Character#isWhitespace(char)}.</p>
    8305     *
    8306     * <pre>
    8307     * StringUtils.stripStart(null, *)          = null
    8308     * StringUtils.stripStart("", *)            = ""
    8309     * StringUtils.stripStart("abc", "")        = "abc"
    8310     * StringUtils.stripStart("abc", null)      = "abc"
    8311     * StringUtils.stripStart("  abc", null)    = "abc"
    8312     * StringUtils.stripStart("abc  ", null)    = "abc  "
    8313     * StringUtils.stripStart(" abc ", null)    = "abc "
    8314     * StringUtils.stripStart("yxabc  ", "xyz") = "abc  "
    8315     * </pre>
    8316     *
    8317     * @param str  the String to remove characters from, may be null
    8318     * @param stripChars  the characters to remove, null treated as whitespace
    8319     * @return the stripped String, {@code null} if null String input
    8320     */
    8321    public static String stripStart(final String str, final String stripChars) {
    8322        final int strLen = length(str);
    8323        if (strLen == 0) {
    8324            return str;
    8325        }
    8326        int start = 0;
    8327        if (stripChars == null) {
    8328            while (start != strLen && Character.isWhitespace(str.charAt(start))) {
    8329                start++;
    8330            }
    8331        } else if (stripChars.isEmpty()) {
    8332            return str;
    8333        } else {
    8334            while (start != strLen && stripChars.indexOf(str.charAt(start)) != INDEX_NOT_FOUND) {
    8335                start++;
    8336            }
    8337        }
    8338        return str.substring(start);
    8339    }
    8340
    8341    /**
    8342     * Strips whitespace from the start and end of a String  returning
    8343     * an empty String if {@code null} input.
    8344     *
    8345     * <p>This is similar to {@link #trimToEmpty(String)} but removes whitespace.
    8346     * Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
    8347     *
    8348     * <pre>
    8349     * StringUtils.stripToEmpty(null)     = ""
    8350     * StringUtils.stripToEmpty("")       = ""
    8351     * StringUtils.stripToEmpty("   ")    = ""
    8352     * StringUtils.stripToEmpty("abc")    = "abc"
    8353     * StringUtils.stripToEmpty("  abc")  = "abc"
    8354     * StringUtils.stripToEmpty("abc  ")  = "abc"
    8355     * StringUtils.stripToEmpty(" abc ")  = "abc"
    8356     * StringUtils.stripToEmpty(" ab c ") = "ab c"
    8357     * </pre>
    8358     *
    8359     * @param str  the String to be stripped, may be null
    8360     * @return the trimmed String, or an empty String if {@code null} input
    8361     * @since 2.0
    8362     */
    8363    public static String stripToEmpty(final String str) {
    8364        return str == null ? EMPTY : strip(str, null);
    8365    }
    8366
    8367    /**
    8368     * Strips whitespace from the start and end of a String  returning
    8369     * {@code null} if the String is empty ("") after the strip.
    8370     *
    8371     * <p>This is similar to {@link #trimToNull(String)} but removes whitespace.
    8372     * Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
    8373     *
    8374     * <pre>
    8375     * StringUtils.stripToNull(null)     = null
    8376     * StringUtils.stripToNull("")       = null
    8377     * StringUtils.stripToNull("   ")    = null
    8378     * StringUtils.stripToNull("abc")    = "abc"
    8379     * StringUtils.stripToNull("  abc")  = "abc"
    8380     * StringUtils.stripToNull("abc  ")  = "abc"
    8381     * StringUtils.stripToNull(" abc ")  = "abc"
    8382     * StringUtils.stripToNull(" ab c ") = "ab c"
    8383     * </pre>
    8384     *
    8385     * @param str  the String to be stripped, may be null
    8386     * @return the stripped String,
    8387     *  {@code null} if whitespace, empty or null String input
    8388     * @since 2.0
    8389     */
    8390    public static String stripToNull(String str) {
    8391        if (str == null) {
    8392            return null;
    8393        }
    8394        str = strip(str, null);
    8395        return str.isEmpty() ? null : str; // NOSONARLINT str cannot be null here
    8396    }
    8397
    8398    /**
    8399     * Gets a substring from the specified String avoiding exceptions.
    8400     *
    8401     * <p>A negative start position can be used to start {@code n}
    8402     * characters from the end of the String.</p>
    8403     *
    8404     * <p>A {@code null} String will return {@code null}.
    8405     * An empty ("") String will return "".</p>
    8406     *
    8407     * <pre>
    8408     * StringUtils.substring(null, *)   = null
    8409     * StringUtils.substring("", *)     = ""
    8410     * StringUtils.substring("abc", 0)  = "abc"
    8411     * StringUtils.substring("abc", 2)  = "c"
    8412     * StringUtils.substring("abc", 4)  = ""
    8413     * StringUtils.substring("abc", -2) = "bc"
    8414     * StringUtils.substring("abc", -4) = "abc"
    8415     * </pre>
    8416     *
    8417     * @param str  the String to get the substring from, may be null
    8418     * @param start  the position to start from, negative means
    8419     *  count back from the end of the String by this many characters
    8420     * @return substring from start position, {@code null} if null String input
    8421     */
    8422    public static String substring(final String str, int start) {
    8423        if (str == null) {
    8424            return null;
    8425        }
    8426
    8427        // handle negatives, which means last n characters
    8428        if (start < 0) {
    8429            start = str.length() + start; // remember start is negative
    8430        }
    8431
    8432        if (start < 0) {
    8433            start = 0;
    8434        }
    8435        if (start > str.length()) {
    8436            return EMPTY;
    8437        }
    8438
    8439        return str.substring(start);
    8440    }
    8441
    8442    /**
    8443     * Gets a substring from the specified String avoiding exceptions.
    8444     *
    8445     * <p>A negative start position can be used to start/end {@code n}
    8446     * characters from the end of the String.</p>
    8447     *
    8448     * <p>The returned substring starts with the character in the {@code start}
    8449     * position and ends before the {@code end} position. All position counting is
    8450     * zero-based -- i.e., to start at the beginning of the string use
    8451     * {@code start = 0}. Negative start and end positions can be used to
    8452     * specify offsets relative to the end of the String.</p>
    8453     *
    8454     * <p>If {@code start} is not strictly to the left of {@code end}, ""
    8455     * is returned.</p>
    8456     *
    8457     * <pre>
    8458     * StringUtils.substring(null, *, *)    = null
    8459     * StringUtils.substring("", * ,  *)    = "";
    8460     * StringUtils.substring("abc", 0, 2)   = "ab"
    8461     * StringUtils.substring("abc", 2, 0)   = ""
    8462     * StringUtils.substring("abc", 2, 4)   = "c"
    8463     * StringUtils.substring("abc", 4, 6)   = ""
    8464     * StringUtils.substring("abc", 2, 2)   = ""
    8465     * StringUtils.substring("abc", -2, -1) = "b"
    8466     * StringUtils.substring("abc", -4, 2)  = "ab"
    8467     * </pre>
    8468     *
    8469     * @param str  the String to get the substring from, may be null
    8470     * @param start  the position to start from, negative means
    8471     *  count back from the end of the String by this many characters
    8472     * @param end  the position to end at (exclusive), negative means
    8473     *  count back from the end of the String by this many characters
    8474     * @return substring from start position to end position,
    8475     *  {@code null} if null String input
    8476     */
    8477    public static String substring(final String str, int start, int end) {
    8478        if (str == null) {
    8479            return null;
    8480        }
    8481
    8482        // handle negatives
    8483        if (end < 0) {
    8484            end = str.length() + end; // remember end is negative
    8485        }
    8486        if (start < 0) {
    8487            start = str.length() + start; // remember start is negative
    8488        }
    8489
    8490        // check length next
    8491        if (end > str.length()) {
    8492            end = str.length();
    8493        }
    8494
    8495        // if start is greater than end, return ""
    8496        if (start > end) {
    8497            return EMPTY;
    8498        }
    8499
    8500        if (start < 0) {
    8501            start = 0;
    8502        }
    8503        if (end < 0) {
    8504            end = 0;
    8505        }
    8506
    8507        return str.substring(start, end);
    8508    }
    8509
    8510    /**
    8511     * Gets the substring after the first occurrence of a separator.
    8512     * The separator is not returned.
    8513     *
    8514     * <p>A {@code null} string input will return {@code null}.
    8515     * An empty ("") string input will return the empty string.
    8516     *
    8517     * <p>If nothing is found, the empty string is returned.</p>
    8518     *
    8519     * <pre>
    8520     * StringUtils.substringAfter(null, *)      = null
    8521     * StringUtils.substringAfter("", *)        = ""
    8522     * StringUtils.substringAfter("abc", 'a')   = "bc"
    8523     * StringUtils.substringAfter("abcba", 'b') = "cba"
    8524     * StringUtils.substringAfter("abc", 'c')   = ""
    8525     * StringUtils.substringAfter("abc", 'd')   = ""
    8526     * StringUtils.substringAfter(" abc", 32)   = "abc"
    8527     * </pre>
    8528     *
    8529     * @param str  the String to get a substring from, may be null
    8530     * @param separator  the character (Unicode code point) to search.
    8531     * @return the substring after the first occurrence of the separator,
    8532     *  {@code null} if null String input
    8533     * @since 3.11
    8534     */
    8535    public static String substringAfter(final String str, final int separator) {
    8536        if (isEmpty(str)) {
    8537            return str;
    8538        }
    8539        final int pos = str.indexOf(separator);
    8540        if (pos == INDEX_NOT_FOUND) {
    8541            return EMPTY;
    8542        }
    8543        return str.substring(pos + 1);
    8544    }
    8545
    8546    /**
    8547     * Gets the substring after the first occurrence of a separator.
    8548     * The separator is not returned.
    8549     *
    8550     * <p>A {@code null} string input will return {@code null}.
    8551     * An empty ("") string input will return the empty string.
    8552     * A {@code null} separator will return the empty string if the
    8553     * input string is not {@code null}.</p>
    8554     *
    8555     * <p>If nothing is found, the empty string is returned.</p>
    8556     *
    8557     * <pre>
    8558     * StringUtils.substringAfter(null, *)      = null
    8559     * StringUtils.substringAfter("", *)        = ""
    8560     * StringUtils.substringAfter(*, null)      = ""
    8561     * StringUtils.substringAfter("abc", "a")   = "bc"
    8562     * StringUtils.substringAfter("abcba", "b") = "cba"
    8563     * StringUtils.substringAfter("abc", "c")   = ""
    8564     * StringUtils.substringAfter("abc", "d")   = ""
    8565     * StringUtils.substringAfter("abc", "")    = "abc"
    8566     * </pre>
    8567     *
    8568     * @param str  the String to get a substring from, may be null
    8569     * @param separator  the String to search for, may be null
    8570     * @return the substring after the first occurrence of the separator,
    8571     *  {@code null} if null String input
    8572     * @since 2.0
    8573     */
    8574    public static String substringAfter(final String str, final String separator) {
    8575        if (isEmpty(str)) {
    8576            return str;
    8577        }
    8578        if (separator == null) {
    8579            return EMPTY;
    8580        }
    8581        final int pos = str.indexOf(separator);
    8582        if (pos == INDEX_NOT_FOUND) {
    8583            return EMPTY;
    8584        }
    8585        return str.substring(pos + separator.length());
    8586    }
    8587
    8588    /**
    8589     * Gets the substring after the last occurrence of a separator.
    8590     * The separator is not returned.
    8591     *
    8592     * <p>A {@code null} string input will return {@code null}.
    8593     * An empty ("") string input will return the empty string.
    8594     *
    8595     * <p>If nothing is found, the empty string is returned.</p>
    8596     *
    8597     * <pre>
    8598     * StringUtils.substringAfterLast(null, *)      = null
    8599     * StringUtils.substringAfterLast("", *)        = ""
    8600     * StringUtils.substringAfterLast("abc", 'a')   = "bc"
    8601     * StringUtils.substringAfterLast(" bc", 32)    = "bc"
    8602     * StringUtils.substringAfterLast("abcba", 'b') = "a"
    8603     * StringUtils.substringAfterLast("abc", 'c')   = ""
    8604     * StringUtils.substringAfterLast("a", 'a')     = ""
    8605     * StringUtils.substringAfterLast("a", 'z')     = ""
    8606     * </pre>
    8607     *
    8608     * @param str  the String to get a substring from, may be null
    8609     * @param separator  the character (Unicode code point) to search.
    8610     * @return the substring after the last occurrence of the separator,
    8611     *  {@code null} if null String input
    8612     * @since 3.11
    8613     */
    8614    public static String substringAfterLast(final String str, final int separator) {
    8615        if (isEmpty(str)) {
    8616            return str;
    8617        }
    8618        final int pos = str.lastIndexOf(separator);
    8619        if (pos == INDEX_NOT_FOUND || pos == str.length() - 1) {
    8620            return EMPTY;
    8621        }
    8622        return str.substring(pos + 1);
    8623    }
    8624
    8625    /**
    8626     * Gets the substring after the last occurrence of a separator.
    8627     * The separator is not returned.
    8628     *
    8629     * <p>A {@code null} string input will return {@code null}.
    8630     * An empty ("") string input will return the empty string.
    8631     * An empty or {@code null} separator will return the empty string if
    8632     * the input string is not {@code null}.</p>
    8633     *
    8634     * <p>If nothing is found, the empty string is returned.</p>
    8635     *
    8636     * <pre>
    8637     * StringUtils.substringAfterLast(null, *)      = null
    8638     * StringUtils.substringAfterLast("", *)        = ""
    8639     * StringUtils.substringAfterLast(*, "")        = ""
    8640     * StringUtils.substringAfterLast(*, null)      = ""
    8641     * StringUtils.substringAfterLast("abc", "a")   = "bc"
    8642     * StringUtils.substringAfterLast("abcba", "b") = "a"
    8643     * StringUtils.substringAfterLast("abc", "c")   = ""
    8644     * StringUtils.substringAfterLast("a", "a")     = ""
    8645     * StringUtils.substringAfterLast("a", "z")     = ""
    8646     * </pre>
    8647     *
    8648     * @param str  the String to get a substring from, may be null
    8649     * @param separator  the String to search for, may be null
    8650     * @return the substring after the last occurrence of the separator,
    8651     *  {@code null} if null String input
    8652     * @since 2.0
    8653     */
    8654    public static String substringAfterLast(final String str, final String separator) {
    8655        if (isEmpty(str)) {
    8656            return str;
    8657        }
    8658        if (isEmpty(separator)) {
    8659            return EMPTY;
    8660        }
    8661        final int pos = str.lastIndexOf(separator);
    8662        if (pos == INDEX_NOT_FOUND || pos == str.length() - separator.length()) {
    8663            return EMPTY;
    8664        }
    8665        return str.substring(pos + separator.length());
    8666    }
    8667
    8668    /**
    8669     * Gets the substring before the first occurrence of a separator. The separator is not returned.
    8670     *
    8671     * <p>
    8672     * A {@code null} string input will return {@code null}. An empty ("") string input will return the empty string.
    8673     * </p>
    8674     *
    8675     * <p>
    8676     * If nothing is found, the string input is returned.
    8677     * </p>
    8678     *
    8679     * <pre>
    8680     * StringUtils.substringBefore(null, *)      = null
    8681     * StringUtils.substringBefore("", *)        = ""
    8682     * StringUtils.substringBefore("abc", 'a')   = ""
    8683     * StringUtils.substringBefore("abcba", 'b') = "a"
    8684     * StringUtils.substringBefore("abc", 'c')   = "ab"
    8685     * StringUtils.substringBefore("abc", 'd')   = "abc"
    8686     * </pre>
    8687     *
    8688     * @param str the String to get a substring from, may be null
    8689     * @param separator the character (Unicode code point) to search.
    8690     * @return the substring before the first occurrence of the separator, {@code null} if null String input
    8691     * @since 3.12.0
    8692     */
    8693    public static String substringBefore(final String str, final int separator) {
    8694        if (isEmpty(str)) {
    8695            return str;
    8696        }
    8697        final int pos = str.indexOf(separator);
    8698        if (pos == INDEX_NOT_FOUND) {
    8699            return str;
    8700        }
    8701        return str.substring(0, pos);
    8702    }
    8703
    8704    /**
    8705     * Gets the substring before the first occurrence of a separator.
    8706     * The separator is not returned.
    8707     *
    8708     * <p>A {@code null} string input will return {@code null}.
    8709     * An empty ("") string input will return the empty string.
    8710     * A {@code null} separator will return the input string.</p>
    8711     *
    8712     * <p>If nothing is found, the string input is returned.</p>
    8713     *
    8714     * <pre>
    8715     * StringUtils.substringBefore(null, *)      = null
    8716     * StringUtils.substringBefore("", *)        = ""
    8717     * StringUtils.substringBefore("abc", "a")   = ""
    8718     * StringUtils.substringBefore("abcba", "b") = "a"
    8719     * StringUtils.substringBefore("abc", "c")   = "ab"
    8720     * StringUtils.substringBefore("abc", "d")   = "abc"
    8721     * StringUtils.substringBefore("abc", "")    = ""
    8722     * StringUtils.substringBefore("abc", null)  = "abc"
    8723     * </pre>
    8724     *
    8725     * @param str  the String to get a substring from, may be null
    8726     * @param separator  the String to search for, may be null
    8727     * @return the substring before the first occurrence of the separator,
    8728     *  {@code null} if null String input
    8729     * @since 2.0
    8730     */
    8731    public static String substringBefore(final String str, final String separator) {
    8732        if (isEmpty(str) || separator == null) {
    8733            return str;
    8734        }
    8735        if (separator.isEmpty()) {
    8736            return EMPTY;
    8737        }
    8738        final int pos = str.indexOf(separator);
    8739        if (pos == INDEX_NOT_FOUND) {
    8740            return str;
    8741        }
    8742        return str.substring(0, pos);
    8743    }
    8744
    8745    /**
    8746     * Gets the substring before the last occurrence of a separator.
    8747     * The separator is not returned.
    8748     *
    8749     * <p>A {@code null} string input will return {@code null}.
    8750     * An empty ("") string input will return the empty string.
    8751     * An empty or {@code null} separator will return the input string.</p>
    8752     *
    8753     * <p>If nothing is found, the string input is returned.</p>
    8754     *
    8755     * <pre>
    8756     * StringUtils.substringBeforeLast(null, *)      = null
    8757     * StringUtils.substringBeforeLast("", *)        = ""
    8758     * StringUtils.substringBeforeLast("abcba", "b") = "abc"
    8759     * StringUtils.substringBeforeLast("abc", "c")   = "ab"
    8760     * StringUtils.substringBeforeLast("a", "a")     = ""
    8761     * StringUtils.substringBeforeLast("a", "z")     = "a"
    8762     * StringUtils.substringBeforeLast("a", null)    = "a"
    8763     * StringUtils.substringBeforeLast("a", "")      = "a"
    8764     * </pre>
    8765     *
    8766     * @param str  the String to get a substring from, may be null
    8767     * @param separator  the String to search for, may be null
    8768     * @return the substring before the last occurrence of the separator,
    8769     *  {@code null} if null String input
    8770     * @since 2.0
    8771     */
    8772    public static String substringBeforeLast(final String str, final String separator) {
    8773        if (isEmpty(str) || isEmpty(separator)) {
    8774            return str;
    8775        }
    8776        final int pos = str.lastIndexOf(separator);
    8777        if (pos == INDEX_NOT_FOUND) {
    8778            return str;
    8779        }
    8780        return str.substring(0, pos);
    8781    }
    8782
    8783    /**
    8784     * Gets the String that is nested in between two instances of the
    8785     * same String.
    8786     *
    8787     * <p>A {@code null} input String returns {@code null}.
    8788     * A {@code null} tag returns {@code null}.</p>
    8789     *
    8790     * <pre>
    8791     * StringUtils.substringBetween(null, *)            = null
    8792     * StringUtils.substringBetween("", "")             = ""
    8793     * StringUtils.substringBetween("", "tag")          = null
    8794     * StringUtils.substringBetween("tagabctag", null)  = null
    8795     * StringUtils.substringBetween("tagabctag", "")    = ""
    8796     * StringUtils.substringBetween("tagabctag", "tag") = "abc"
    8797     * </pre>
    8798     *
    8799     * @param str  the String containing the substring, may be null
    8800     * @param tag  the String before and after the substring, may be null
    8801     * @return the substring, {@code null} if no match
    8802     * @since 2.0
    8803     */
    8804    public static String substringBetween(final String str, final String tag) {
    8805        return substringBetween(str, tag, tag);
    8806    }
    8807
    8808    /**
    8809     * Gets the String that is nested in between two Strings.
    8810     * Only the first match is returned.
    8811     *
    8812     * <p>A {@code null} input String returns {@code null}.
    8813     * A {@code null} open/close returns {@code null} (no match).
    8814     * An empty ("") open and close returns an empty string.</p>
    8815     *
    8816     * <pre>
    8817     * StringUtils.substringBetween("wx[b]yz", "[", "]") = "b"
    8818     * StringUtils.substringBetween(null, *, *)          = null
    8819     * StringUtils.substringBetween(*, null, *)          = null
    8820     * StringUtils.substringBetween(*, *, null)          = null
    8821     * StringUtils.substringBetween("", "", "")          = ""
    8822     * StringUtils.substringBetween("", "", "]")         = null
    8823     * StringUtils.substringBetween("", "[", "]")        = null
    8824     * StringUtils.substringBetween("yabcz", "", "")     = ""
    8825     * StringUtils.substringBetween("yabcz", "y", "z")   = "abc"
    8826     * StringUtils.substringBetween("yabczyabcz", "y", "z")   = "abc"
    8827     * </pre>
    8828     *
    8829     * @param str  the String containing the substring, may be null
    8830     * @param open  the String before the substring, may be null
    8831     * @param close  the String after the substring, may be null
    8832     * @return the substring, {@code null} if no match
    8833     * @since 2.0
    8834     */
    8835    public static String substringBetween(final String str, final String open, final String close) {
    8836        if (!ObjectUtils.allNotNull(str, open, close)) {
    8837            return null;
    8838        }
    8839        final int start = str.indexOf(open);
    8840        if (start != INDEX_NOT_FOUND) {
    8841            final int end = str.indexOf(close, start + open.length());
    8842            if (end != INDEX_NOT_FOUND) {
    8843                return str.substring(start + open.length(), end);
    8844            }
    8845        }
    8846        return null;
    8847    }
    8848
    8849    /**
    8850     * Searches a String for substrings delimited by a start and end tag,
    8851     * returning all matching substrings in an array.
    8852     *
    8853     * <p>A {@code null} input String returns {@code null}.
    8854     * A {@code null} open/close returns {@code null} (no match).
    8855     * An empty ("") open/close returns {@code null} (no match).</p>
    8856     *
    8857     * <pre>
    8858     * StringUtils.substringsBetween("[a][b][c]", "[", "]") = ["a","b","c"]
    8859     * StringUtils.substringsBetween(null, *, *)            = null
    8860     * StringUtils.substringsBetween(*, null, *)            = null
    8861     * StringUtils.substringsBetween(*, *, null)            = null
    8862     * StringUtils.substringsBetween("", "[", "]")          = []
    8863     * </pre>
    8864     *
    8865     * @param str  the String containing the substrings, null returns null, empty returns empty
    8866     * @param open  the String identifying the start of the substring, empty returns null
    8867     * @param close  the String identifying the end of the substring, empty returns null
    8868     * @return a String Array of substrings, or {@code null} if no match
    8869     * @since 2.3
    8870     */
    8871    public static String[] substringsBetween(final String str, final String open, final String close) {
    8872        if (str == null || isEmpty(open) || isEmpty(close)) {
    8873            return null;
    8874        }
    8875        final int strLen = str.length();
    8876        if (strLen == 0) {
    8877            return ArrayUtils.EMPTY_STRING_ARRAY;
    8878        }
    8879        final int closeLen = close.length();
    8880        final int openLen = open.length();
    8881        final List<String> list = new ArrayList<>();
    8882        int pos = 0;
    8883        while (pos < strLen - closeLen) {
    8884            int start = str.indexOf(open, pos);
    8885            if (start < 0) {
    8886                break;
    8887            }
    8888            start += openLen;
    8889            final int end = str.indexOf(close, start);
    8890            if (end < 0) {
    8891                break;
    8892            }
    8893            list.add(str.substring(start, end));
    8894            pos = end + closeLen;
    8895        }
    8896        if (list.isEmpty()) {
    8897            return null;
    8898        }
    8899        return list.toArray(ArrayUtils.EMPTY_STRING_ARRAY);
    8900    }
    8901
    8902    /**
    8903     * Swaps the case of a String changing upper and title case to
    8904     * lower case, and lower case to upper case.
    8905     *
    8906     * <ul>
    8907     *  <li>Upper case character converts to Lower case</li>
    8908     *  <li>Title case character converts to Lower case</li>
    8909     *  <li>Lower case character converts to Upper case</li>
    8910     * </ul>
    8911     *
    8912     * <p>For a word based algorithm, see {@link org.apache.commons.text.WordUtils#swapCase(String)}.
    8913     * A {@code null} input String returns {@code null}.</p>
    8914     *
    8915     * <pre>
    8916     * StringUtils.swapCase(null)                 = null
    8917     * StringUtils.swapCase("")                   = ""
    8918     * StringUtils.swapCase("The dog has a BONE") = "tHE DOG HAS A bone"
    8919     * </pre>
    8920     *
    8921     * <p>NOTE: This method changed in Lang version 2.0.
    8922     * It no longer performs a word based algorithm.
    8923     * If you only use ASCII, you will notice no change.
    8924     * That functionality is available in org.apache.commons.lang3.text.WordUtils.</p>
    8925     *
    8926     * @param str  the String to swap case, may be null
    8927     * @return the changed String, {@code null} if null String input
    8928     */
    8929    public static String swapCase(final String str) {
    8930        if (isEmpty(str)) {
    8931            return str;
    8932        }
    8933
    8934        final int strLen = str.length();
    8935        final int[] newCodePoints = new int[strLen]; // cannot be longer than the char array
    8936        int outOffset = 0;
    8937        for (int i = 0; i < strLen; ) {
    8938            final int oldCodepoint = str.codePointAt(i);
    8939            final int newCodePoint;
    8940            if (Character.isUpperCase(oldCodepoint) || Character.isTitleCase(oldCodepoint)) {
    8941                newCodePoint = Character.toLowerCase(oldCodepoint);
    8942            } else if (Character.isLowerCase(oldCodepoint)) {
    8943                newCodePoint = Character.toUpperCase(oldCodepoint);
    8944            } else {
    8945                newCodePoint = oldCodepoint;
    8946            }
    8947            newCodePoints[outOffset++] = newCodePoint;
    8948            i += Character.charCount(newCodePoint);
    8949         }
    8950        return new String(newCodePoints, 0, outOffset);
    8951    }
    8952
    8953    /**
    8954     * Converts a {@link CharSequence} into an array of code points.
    8955     *
    8956     * <p>Valid pairs of surrogate code units will be converted into a single supplementary
    8957     * code point. Isolated surrogate code units (i.e. a high surrogate not followed by a low surrogate or
    8958     * a low surrogate not preceded by a high surrogate) will be returned as-is.</p>
    8959     *
    8960     * <pre>
    8961     * StringUtils.toCodePoints(null)   =  null
    8962     * StringUtils.toCodePoints("")     =  []  // empty array
    8963     * </pre>
    8964     *
    8965     * @param cs the character sequence to convert
    8966     * @return an array of code points
    8967     * @since 3.6
    8968     */
    8969    public static int[] toCodePoints(final CharSequence cs) {
    8970        if (cs == null) {
    8971            return null;
    8972        }
    8973        if (cs.length() == 0) {
    8974            return ArrayUtils.EMPTY_INT_ARRAY;
    8975        }
    8976
    8977        final String s = cs.toString();
    8978        final int[] result = new int[s.codePointCount(0, s.length())];
    8979        int index = 0;
    8980        for (int i = 0; i < result.length; i++) {
    8981            result[i] = s.codePointAt(index);
    8982            index += Character.charCount(result[i]);
    8983        }
    8984        return result;
    8985    }
    8986
    8987    /**
    8988     * Converts a {@code byte[]} to a String using the specified character encoding.
    8989     *
    8990     * @param bytes
    8991     *            the byte array to read from
    8992     * @param charset
    8993     *            the encoding to use, if null then use the platform default
    8994     * @return a new String
    8995     * @throws NullPointerException
    8996     *             if {@code bytes} is null
    8997     * @since 3.2
    8998     * @since 3.3 No longer throws {@link UnsupportedEncodingException}.
    8999     */
    9000    public static String toEncodedString(final byte[] bytes, final Charset charset) {
    9001        return new String(bytes, Charsets.toCharset(charset));
    9002    }
    9003
    9004    /**
    9005     * Converts the given source String as a lower-case using the {@link Locale#ROOT} locale in a null-safe manner.
    9006     *
    9007     * @param source A source String or null.
    9008     * @return the given source String as a lower-case using the {@link Locale#ROOT} locale or null.
    9009     * @since 3.10
    9010     */
    9011    public static String toRootLowerCase(final String source) {
    9012        return source == null ? null : source.toLowerCase(Locale.ROOT);
    9013    }
    9014
    9015    /**
    9016     * Converts the given source String as an upper-case using the {@link Locale#ROOT} locale in a null-safe manner.
    9017     *
    9018     * @param source A source String or null.
    9019     * @return the given source String as an upper-case using the {@link Locale#ROOT} locale or null.
    9020     * @since 3.10
    9021     */
    9022    public static String toRootUpperCase(final String source) {
    9023        return source == null ? null : source.toUpperCase(Locale.ROOT);
    9024    }
    9025
    9026    /**
    9027     * Converts a {@code byte[]} to a String using the specified character encoding.
    9028     *
    9029     * @param bytes
    9030     *            the byte array to read from
    9031     * @param charsetName
    9032     *            the encoding to use, if null then use the platform default
    9033     * @return a new String
    9034     * @throws NullPointerException
    9035     *             if the input is null
    9036     * @deprecated use {@link StringUtils#toEncodedString(byte[], Charset)} instead of String constants in your code
    9037     * @since 3.1
    9038     */
    9039    @Deprecated
    9040    public static String toString(final byte[] bytes, final String charsetName) {
    9041        return new String(bytes, Charsets.toCharset(charsetName));
    9042    }
    9043
    9044    private static String toStringOrEmpty(final Object obj) {
    9045        return Objects.toString(obj, EMPTY);
    9046    }
    9047
    9048    /**
    9049     * Removes control characters (char &lt;= 32) from both
    9050     * ends of this String, handling {@code null} by returning
    9051     * {@code null}.
    9052     *
    9053     * <p>The String is trimmed using {@link String#trim()}.
    9054     * Trim removes start and end characters &lt;= 32.
    9055     * To strip whitespace use {@link #strip(String)}.</p>
    9056     *
    9057     * <p>To trim your choice of characters, use the
    9058     * {@link #strip(String, String)} methods.</p>
    9059     *
    9060     * <pre>
    9061     * StringUtils.trim(null)          = null
    9062     * StringUtils.trim("")            = ""
    9063     * StringUtils.trim("     ")       = ""
    9064     * StringUtils.trim("abc")         = "abc"
    9065     * StringUtils.trim("    abc    ") = "abc"
    9066     * </pre>
    9067     *
    9068     * @param str  the String to be trimmed, may be null
    9069     * @return the trimmed string, {@code null} if null String input
    9070     */
    9071    public static String trim(final String str) {
    9072        return str == null ? null : str.trim();
    9073    }
    9074
    9075    /**
    9076     * Removes control characters (char &lt;= 32) from both
    9077     * ends of this String returning an empty String ("") if the String
    9078     * is empty ("") after the trim or if it is {@code null}.
    9079     *
    9080     * <p>The String is trimmed using {@link String#trim()}.
    9081     * Trim removes start and end characters &lt;= 32.
    9082     * To strip whitespace use {@link #stripToEmpty(String)}.
    9083     *
    9084     * <pre>
    9085     * StringUtils.trimToEmpty(null)          = ""
    9086     * StringUtils.trimToEmpty("")            = ""
    9087     * StringUtils.trimToEmpty("     ")       = ""
    9088     * StringUtils.trimToEmpty("abc")         = "abc"
    9089     * StringUtils.trimToEmpty("    abc    ") = "abc"
    9090     * </pre>
    9091     *
    9092     * @param str  the String to be trimmed, may be null
    9093     * @return the trimmed String, or an empty String if {@code null} input
    9094     * @since 2.0
    9095     */
    9096    public static String trimToEmpty(final String str) {
    9097        return str == null ? EMPTY : str.trim();
    9098    }
    9099
    9100    /**
    9101     * Removes control characters (char &lt;= 32) from both
    9102     * ends of this String returning {@code null} if the String is
    9103     * empty ("") after the trim or if it is {@code null}.
    9104     *
    9105     * <p>The String is trimmed using {@link String#trim()}.
    9106     * Trim removes start and end characters &lt;= 32.
    9107     * To strip whitespace use {@link #stripToNull(String)}.
    9108     *
    9109     * <pre>
    9110     * StringUtils.trimToNull(null)          = null
    9111     * StringUtils.trimToNull("")            = null
    9112     * StringUtils.trimToNull("     ")       = null
    9113     * StringUtils.trimToNull("abc")         = "abc"
    9114     * StringUtils.trimToNull("    abc    ") = "abc"
    9115     * </pre>
    9116     *
    9117     * @param str  the String to be trimmed, may be null
    9118     * @return the trimmed String,
    9119     *  {@code null} if only chars &lt;= 32, empty or null String input
    9120     * @since 2.0
    9121     */
    9122    public static String trimToNull(final String str) {
    9123        final String ts = trim(str);
    9124        return isEmpty(ts) ? null : ts;
    9125    }
    9126
    9127    /**
    9128     * Truncates a String. This will turn
    9129     * "Now is the time for all good men" into "Now is the time for".
    9130     *
    9131     * <p>Specifically:</p>
    9132     * <ul>
    9133     *   <li>If {@code str} is less than {@code maxWidth} characters
    9134     *       long, return it.</li>
    9135     *   <li>Else truncate it to {@code substring(str, 0, maxWidth)}.</li>
    9136     *   <li>If {@code maxWidth} is less than {@code 0}, throw an
    9137     *       {@link IllegalArgumentException}.</li>
    9138     *   <li>In no case will it return a String of length greater than
    9139     *       {@code maxWidth}.</li>
    9140     * </ul>
    9141     *
    9142     * <pre>
    9143     * StringUtils.truncate(null, 0)       = null
    9144     * StringUtils.truncate(null, 2)       = null
    9145     * StringUtils.truncate("", 4)         = ""
    9146     * StringUtils.truncate("abcdefg", 4)  = "abcd"
    9147     * StringUtils.truncate("abcdefg", 6)  = "abcdef"
    9148     * StringUtils.truncate("abcdefg", 7)  = "abcdefg"
    9149     * StringUtils.truncate("abcdefg", 8)  = "abcdefg"
    9150     * StringUtils.truncate("abcdefg", -1) = throws an IllegalArgumentException
    9151     * </pre>
    9152     *
    9153     * @param str  the String to truncate, may be null
    9154     * @param maxWidth  maximum length of result String, must be positive
    9155     * @return truncated String, {@code null} if null String input
    9156     * @throws IllegalArgumentException If {@code maxWidth} is less than {@code 0}
    9157     * @since 3.5
    9158     */
    9159    public static String truncate(final String str, final int maxWidth) {
    9160        return truncate(str, 0, maxWidth);
    9161    }
    9162
    9163    /**
    9164     * Truncates a String. This will turn
    9165     * "Now is the time for all good men" into "is the time for all".
    9166     *
    9167     * <p>Works like {@code truncate(String, int)}, but allows you to specify
    9168     * a "left edge" offset.
    9169     *
    9170     * <p>Specifically:</p>
    9171     * <ul>
    9172     *   <li>If {@code str} is less than {@code maxWidth} characters
    9173     *       long, return it.</li>
    9174     *   <li>Else truncate it to {@code substring(str, offset, maxWidth)}.</li>
    9175     *   <li>If {@code maxWidth} is less than {@code 0}, throw an
    9176     *       {@link IllegalArgumentException}.</li>
    9177     *   <li>If {@code offset} is less than {@code 0}, throw an
    9178     *       {@link IllegalArgumentException}.</li>
    9179     *   <li>In no case will it return a String of length greater than
    9180     *       {@code maxWidth}.</li>
    9181     * </ul>
    9182     *
    9183     * <pre>
    9184     * StringUtils.truncate(null, 0, 0) = null
    9185     * StringUtils.truncate(null, 2, 4) = null
    9186     * StringUtils.truncate("", 0, 10) = ""
    9187     * StringUtils.truncate("", 2, 10) = ""
    9188     * StringUtils.truncate("abcdefghij", 0, 3) = "abc"
    9189     * StringUtils.truncate("abcdefghij", 5, 6) = "fghij"
    9190     * StringUtils.truncate("raspberry peach", 10, 15) = "peach"
    9191     * StringUtils.truncate("abcdefghijklmno", 0, 10) = "abcdefghij"
    9192     * StringUtils.truncate("abcdefghijklmno", -1, 10) = throws an IllegalArgumentException
    9193     * StringUtils.truncate("abcdefghijklmno", Integer.MIN_VALUE, 10) = throws an IllegalArgumentException
    9194     * StringUtils.truncate("abcdefghijklmno", Integer.MIN_VALUE, Integer.MAX_VALUE) = throws an IllegalArgumentException
    9195     * StringUtils.truncate("abcdefghijklmno", 0, Integer.MAX_VALUE) = "abcdefghijklmno"
    9196     * StringUtils.truncate("abcdefghijklmno", 1, 10) = "bcdefghijk"
    9197     * StringUtils.truncate("abcdefghijklmno", 2, 10) = "cdefghijkl"
    9198     * StringUtils.truncate("abcdefghijklmno", 3, 10) = "defghijklm"
    9199     * StringUtils.truncate("abcdefghijklmno", 4, 10) = "efghijklmn"
    9200     * StringUtils.truncate("abcdefghijklmno", 5, 10) = "fghijklmno"
    9201     * StringUtils.truncate("abcdefghijklmno", 5, 5) = "fghij"
    9202     * StringUtils.truncate("abcdefghijklmno", 5, 3) = "fgh"
    9203     * StringUtils.truncate("abcdefghijklmno", 10, 3) = "klm"
    9204     * StringUtils.truncate("abcdefghijklmno", 10, Integer.MAX_VALUE) = "klmno"
    9205     * StringUtils.truncate("abcdefghijklmno", 13, 1) = "n"
    9206     * StringUtils.truncate("abcdefghijklmno", 13, Integer.MAX_VALUE) = "no"
    9207     * StringUtils.truncate("abcdefghijklmno", 14, 1) = "o"
    9208     * StringUtils.truncate("abcdefghijklmno", 14, Integer.MAX_VALUE) = "o"
    9209     * StringUtils.truncate("abcdefghijklmno", 15, 1) = ""
    9210     * StringUtils.truncate("abcdefghijklmno", 15, Integer.MAX_VALUE) = ""
    9211     * StringUtils.truncate("abcdefghijklmno", Integer.MAX_VALUE, Integer.MAX_VALUE) = ""
    9212     * StringUtils.truncate("abcdefghij", 3, -1) = throws an IllegalArgumentException
    9213     * StringUtils.truncate("abcdefghij", -2, 4) = throws an IllegalArgumentException
    9214     * </pre>
    9215     *
    9216     * @param str  the String to truncate, may be null
    9217     * @param offset  left edge of source String
    9218     * @param maxWidth  maximum length of result String, must be positive
    9219     * @return truncated String, {@code null} if null String input
    9220     * @throws IllegalArgumentException If {@code offset} or {@code maxWidth} is less than {@code 0}
    9221     * @since 3.5
    9222     */
    9223    public static String truncate(final String str, final int offset, final int maxWidth) {
    9224        if (offset < 0) {
    9225            throw new IllegalArgumentException("offset cannot be negative");
    9226        }
    9227        if (maxWidth < 0) {
    9228            throw new IllegalArgumentException("maxWith cannot be negative");
    9229        }
    9230        if (str == null) {
    9231            return null;
    9232        }
    9233        if (offset > str.length()) {
    9234            return EMPTY;
    9235        }
    9236        if (str.length() > maxWidth) {
    9237            final int ix = Math.min(offset + maxWidth, str.length());
    9238            return str.substring(offset, ix);
    9239        }
    9240        return str.substring(offset);
    9241    }
    9242
    9243    /**
    9244     * Uncapitalizes a String, changing the first character to lower case as
    9245     * per {@link Character#toLowerCase(int)}. No other characters are changed.
    9246     *
    9247     * <p>For a word based algorithm, see {@link org.apache.commons.text.WordUtils#uncapitalize(String)}.
    9248     * A {@code null} input String returns {@code null}.</p>
    9249     *
    9250     * <pre>
    9251     * StringUtils.uncapitalize(null)  = null
    9252     * StringUtils.uncapitalize("")    = ""
    9253     * StringUtils.uncapitalize("cat") = "cat"
    9254     * StringUtils.uncapitalize("Cat") = "cat"
    9255     * StringUtils.uncapitalize("CAT") = "cAT"
    9256     * </pre>
    9257     *
    9258     * @param str the String to uncapitalize, may be null
    9259     * @return the uncapitalized String, {@code null} if null String input
    9260     * @see org.apache.commons.text.WordUtils#uncapitalize(String)
    9261     * @see #capitalize(String)
    9262     * @since 2.0
    9263     */
    9264    public static String uncapitalize(final String str) {
    9265        final int strLen = length(str);
    9266        if (strLen == 0) {
    9267            return str;
    9268        }
    9269
    9270        final int firstCodePoint = str.codePointAt(0);
    9271        final int newCodePoint = Character.toLowerCase(firstCodePoint);
    9272        if (firstCodePoint == newCodePoint) {
    9273            // already capitalized
    9274            return str;
    9275        }
    9276
    9277        final int[] newCodePoints = new int[strLen]; // cannot be longer than the char array
    9278        int outOffset = 0;
    9279        newCodePoints[outOffset++] = newCodePoint; // copy the first code point
    9280        for (int inOffset = Character.charCount(firstCodePoint); inOffset < strLen; ) {
    9281            final int codePoint = str.codePointAt(inOffset);
    9282            newCodePoints[outOffset++] = codePoint; // copy the remaining ones
    9283            inOffset += Character.charCount(codePoint);
    9284         }
    9285        return new String(newCodePoints, 0, outOffset);
    9286    }
    9287
    9288    /**
    9289     * Unwraps a given string from a character.
    9290     *
    9291     * <pre>
    9292     * StringUtils.unwrap(null, null)         = null
    9293     * StringUtils.unwrap(null, '\0')         = null
    9294     * StringUtils.unwrap(null, '1')          = null
    9295     * StringUtils.unwrap("a", 'a')           = "a"
    9296     * StringUtils.unwrap("aa", 'a')           = ""
    9297     * StringUtils.unwrap("\'abc\'", '\'')    = "abc"
    9298     * StringUtils.unwrap("AABabcBAA", 'A')   = "ABabcBA"
    9299     * StringUtils.unwrap("A", '#')           = "A"
    9300     * StringUtils.unwrap("#A", '#')          = "#A"
    9301     * StringUtils.unwrap("A#", '#')          = "A#"
    9302     * </pre>
    9303     *
    9304     * @param str
    9305     *          the String to be unwrapped, can be null
    9306     * @param wrapChar
    9307     *          the character used to unwrap
    9308     * @return unwrapped String or the original string
    9309     *          if it is not quoted properly with the wrapChar
    9310     * @since 3.6
    9311     */
    9312    public static String unwrap(final String str, final char wrapChar) {
    9313        if (isEmpty(str) || wrapChar == CharUtils.NUL || str.length() == 1) {
    9314            return str;
    9315        }
    9316
    9317        if (str.charAt(0) == wrapChar && str.charAt(str.length() - 1) == wrapChar) {
    9318            final int startIndex = 0;
    9319            final int endIndex = str.length() - 1;
    9320
    9321            return str.substring(startIndex + 1, endIndex);
    9322        }
    9323
    9324        return str;
    9325    }
    9326
    9327    /**
    9328     * Unwraps a given string from another string.
    9329     *
    9330     * <pre>
    9331     * StringUtils.unwrap(null, null)         = null
    9332     * StringUtils.unwrap(null, "")           = null
    9333     * StringUtils.unwrap(null, "1")          = null
    9334     * StringUtils.unwrap("a", "a")           = "a"
    9335     * StringUtils.unwrap("aa", "a")          = ""
    9336     * StringUtils.unwrap("\'abc\'", "\'")    = "abc"
    9337     * StringUtils.unwrap("\"abc\"", "\"")    = "abc"
    9338     * StringUtils.unwrap("AABabcBAA", "AA")  = "BabcB"
    9339     * StringUtils.unwrap("A", "#")           = "A"
    9340     * StringUtils.unwrap("#A", "#")          = "#A"
    9341     * StringUtils.unwrap("A#", "#")          = "A#"
    9342     * </pre>
    9343     *
    9344     * @param str
    9345     *          the String to be unwrapped, can be null
    9346     * @param wrapToken
    9347     *          the String used to unwrap
    9348     * @return unwrapped String or the original string
    9349     *          if it is not quoted properly with the wrapToken
    9350     * @since 3.6
    9351     */
    9352    public static String unwrap(final String str, final String wrapToken) {
    9353        if (isEmpty(str) || isEmpty(wrapToken) || str.length() < 2 * wrapToken.length()) {
    9354            return str;
    9355        }
    9356
    9357        if (startsWith(str, wrapToken) && endsWith(str, wrapToken)) {
    9358            return str.substring(wrapToken.length(), str.lastIndexOf(wrapToken));
    9359        }
    9360
    9361        return str;
    9362    }
    9363
    9364    /**
    9365     * Converts a String to upper case as per {@link String#toUpperCase()}.
    9366     *
    9367     * <p>A {@code null} input String returns {@code null}.</p>
    9368     *
    9369     * <pre>
    9370     * StringUtils.upperCase(null)  = null
    9371     * StringUtils.upperCase("")    = ""
    9372     * StringUtils.upperCase("aBc") = "ABC"
    9373     * </pre>
    9374     *
    9375     * <p><strong>Note:</strong> As described in the documentation for {@link String#toUpperCase()},
    9376     * the result of this method is affected by the current locale.
    9377     * For platform-independent case transformations, the method {@link #upperCase(String, Locale)}
    9378     * should be used with a specific locale (e.g. {@link Locale#ENGLISH}).</p>
    9379     *
    9380     * @param str  the String to upper case, may be null
    9381     * @return the upper-cased String, {@code null} if null String input
    9382     */
    9383    public static String upperCase(final String str) {
    9384        if (str == null) {
    9385            return null;
    9386        }
    9387        return str.toUpperCase();
    9388    }
    9389
    9390    /**
    9391     * Converts a String to upper case as per {@link String#toUpperCase(Locale)}.
    9392     *
    9393     * <p>A {@code null} input String returns {@code null}.</p>
    9394     *
    9395     * <pre>
    9396     * StringUtils.upperCase(null, Locale.ENGLISH)  = null
    9397     * StringUtils.upperCase("", Locale.ENGLISH)    = ""
    9398     * StringUtils.upperCase("aBc", Locale.ENGLISH) = "ABC"
    9399     * </pre>
    9400     *
    9401     * @param str  the String to upper case, may be null
    9402     * @param locale  the locale that defines the case transformation rules, must not be null
    9403     * @return the upper-cased String, {@code null} if null String input
    9404     * @since 2.5
    9405     */
    9406    public static String upperCase(final String str, final Locale locale) {
    9407        if (str == null) {
    9408            return null;
    9409        }
    9410        return str.toUpperCase(LocaleUtils.toLocale(locale));
    9411    }
    9412
    9413    /**
    9414     * Returns the string representation of the {@code char} array or null.
    9415     *
    9416     * @param value the character array.
    9417     * @return a String or null
    9418     * @see String#valueOf(char[])
    9419     * @since 3.9
    9420     */
    9421    public static String valueOf(final char[] value) {
    9422        return value == null ? null : String.valueOf(value);
    9423    }
    9424
    9425    /**
    9426     * Wraps a string with a char.
    9427     *
    9428     * <pre>
    9429     * StringUtils.wrap(null, *)        = null
    9430     * StringUtils.wrap("", *)          = ""
    9431     * StringUtils.wrap("ab", '\0')     = "ab"
    9432     * StringUtils.wrap("ab", 'x')      = "xabx"
    9433     * StringUtils.wrap("ab", '\'')     = "'ab'"
    9434     * StringUtils.wrap("\"ab\"", '\"') = "\"\"ab\"\""
    9435     * </pre>
    9436     *
    9437     * @param str
    9438     *            the string to be wrapped, may be {@code null}
    9439     * @param wrapWith
    9440     *            the char that will wrap {@code str}
    9441     * @return the wrapped string, or {@code null} if {@code str == null}
    9442     * @since 3.4
    9443     */
    9444    public static String wrap(final String str, final char wrapWith) {
    9445
    9446        if (isEmpty(str) || wrapWith == CharUtils.NUL) {
    9447            return str;
    9448        }
    9449
    9450        return wrapWith + str + wrapWith;
    9451    }
    9452
    9453    /**
    9454     * Wraps a String with another String.
    9455     *
    9456     * <p>
    9457     * A {@code null} input String returns {@code null}.
    9458     * </p>
    9459     *
    9460     * <pre>
    9461     * StringUtils.wrap(null, *)         = null
    9462     * StringUtils.wrap("", *)           = ""
    9463     * StringUtils.wrap("ab", null)      = "ab"
    9464     * StringUtils.wrap("ab", "x")       = "xabx"
    9465     * StringUtils.wrap("ab", "\"")      = "\"ab\""
    9466     * StringUtils.wrap("\"ab\"", "\"")  = "\"\"ab\"\""
    9467     * StringUtils.wrap("ab", "'")       = "'ab'"
    9468     * StringUtils.wrap("'abcd'", "'")   = "''abcd''"
    9469     * StringUtils.wrap("\"abcd\"", "'") = "'\"abcd\"'"
    9470     * StringUtils.wrap("'abcd'", "\"")  = "\"'abcd'\""
    9471     * </pre>
    9472     *
    9473     * @param str
    9474     *            the String to be wrapper, may be null
    9475     * @param wrapWith
    9476     *            the String that will wrap str
    9477     * @return wrapped String, {@code null} if null String input
    9478     * @since 3.4
    9479     */
    9480    public static String wrap(final String str, final String wrapWith) {
    9481
    9482        if (isEmpty(str) || isEmpty(wrapWith)) {
    9483            return str;
    9484        }
    9485
    9486        return wrapWith.concat(str).concat(wrapWith);
    9487    }
    9488
    9489    /**
    9490     * Wraps a string with a char if that char is missing from the start or end of the given string.
    9491     *
    9492     * <p>A new {@link String} will not be created if {@code str} is already wrapped.</p>
    9493     *
    9494     * <pre>
    9495     * StringUtils.wrapIfMissing(null, *)        = null
    9496     * StringUtils.wrapIfMissing("", *)          = ""
    9497     * StringUtils.wrapIfMissing("ab", '\0')     = "ab"
    9498     * StringUtils.wrapIfMissing("ab", 'x')      = "xabx"
    9499     * StringUtils.wrapIfMissing("ab", '\'')     = "'ab'"
    9500     * StringUtils.wrapIfMissing("\"ab\"", '\"') = "\"ab\""
    9501     * StringUtils.wrapIfMissing("/", '/')  = "/"
    9502     * StringUtils.wrapIfMissing("a/b/c", '/')  = "/a/b/c/"
    9503     * StringUtils.wrapIfMissing("/a/b/c", '/')  = "/a/b/c/"
    9504     * StringUtils.wrapIfMissing("a/b/c/", '/')  = "/a/b/c/"
    9505     * </pre>
    9506     *
    9507     * @param str
    9508     *            the string to be wrapped, may be {@code null}
    9509     * @param wrapWith
    9510     *            the char that will wrap {@code str}
    9511     * @return the wrapped string, or {@code null} if {@code str == null}
    9512     * @since 3.5
    9513     */
    9514    public static String wrapIfMissing(final String str, final char wrapWith) {
    9515        if (isEmpty(str) || wrapWith == CharUtils.NUL) {
    9516            return str;
    9517        }
    9518        final boolean wrapStart = str.charAt(0) != wrapWith;
    9519        final boolean wrapEnd = str.charAt(str.length() - 1) != wrapWith;
    9520        if (!wrapStart && !wrapEnd) {
    9521            return str;
    9522        }
    9523
    9524        final StringBuilder builder = new StringBuilder(str.length() + 2);
    9525        if (wrapStart) {
    9526            builder.append(wrapWith);
    9527        }
    9528        builder.append(str);
    9529        if (wrapEnd) {
    9530            builder.append(wrapWith);
    9531        }
    9532        return builder.toString();
    9533    }
    9534
    9535    /**
    9536     * Wraps a string with a string if that string is missing from the start or end of the given string.
    9537     *
    9538     * <p>A new {@link String} will not be created if {@code str} is already wrapped.</p>
    9539     *
    9540     * <pre>
    9541     * StringUtils.wrapIfMissing(null, *)         = null
    9542     * StringUtils.wrapIfMissing("", *)           = ""
    9543     * StringUtils.wrapIfMissing("ab", null)      = "ab"
    9544     * StringUtils.wrapIfMissing("ab", "x")       = "xabx"
    9545     * StringUtils.wrapIfMissing("ab", "\"")      = "\"ab\""
    9546     * StringUtils.wrapIfMissing("\"ab\"", "\"")  = "\"ab\""
    9547     * StringUtils.wrapIfMissing("ab", "'")       = "'ab'"
    9548     * StringUtils.wrapIfMissing("'abcd'", "'")   = "'abcd'"
    9549     * StringUtils.wrapIfMissing("\"abcd\"", "'") = "'\"abcd\"'"
    9550     * StringUtils.wrapIfMissing("'abcd'", "\"")  = "\"'abcd'\""
    9551     * StringUtils.wrapIfMissing("/", "/")  = "/"
    9552     * StringUtils.wrapIfMissing("a/b/c", "/")  = "/a/b/c/"
    9553     * StringUtils.wrapIfMissing("/a/b/c", "/")  = "/a/b/c/"
    9554     * StringUtils.wrapIfMissing("a/b/c/", "/")  = "/a/b/c/"
    9555     * </pre>
    9556     *
    9557     * @param str
    9558     *            the string to be wrapped, may be {@code null}
    9559     * @param wrapWith
    9560     *            the string that will wrap {@code str}
    9561     * @return the wrapped string, or {@code null} if {@code str == null}
    9562     * @since 3.5
    9563     */
    9564    public static String wrapIfMissing(final String str, final String wrapWith) {
    9565        if (isEmpty(str) || isEmpty(wrapWith)) {
    9566            return str;
    9567        }
    9568
    9569        final boolean wrapStart = !str.startsWith(wrapWith);
    9570        final boolean wrapEnd = !str.endsWith(wrapWith);
    9571        if (!wrapStart && !wrapEnd) {
    9572            return str;
    9573        }
    9574
    9575        final StringBuilder builder = new StringBuilder(str.length() + wrapWith.length() + wrapWith.length());
    9576        if (wrapStart) {
    9577            builder.append(wrapWith);
    9578        }
    9579        builder.append(str);
    9580        if (wrapEnd) {
    9581            builder.append(wrapWith);
    9582        }
    9583        return builder.toString();
    9584    }
    9585
    9586    /**
    9587     * {@link StringUtils} instances should NOT be constructed in
    9588     * standard programming. Instead, the class should be used as
    9589     * {@code StringUtils.trim(" foo ");}.
    9590     *
    9591     * <p>This constructor is public to permit tools that require a JavaBean
    9592     * instance to operate.</p>
    9593     *
    9594     * @deprecated TODO Make private in 4.0.
    9595     */
    9596    @Deprecated
    9597    public StringUtils() {
    9598        // empty
    9599    }
    9600
    9601}