View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      https://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.lang3;
18  
19  import java.io.UnsupportedEncodingException;
20  import java.nio.CharBuffer;
21  import java.nio.charset.Charset;
22  import java.text.Normalizer;
23  import java.util.ArrayList;
24  import java.util.Arrays;
25  import java.util.Iterator;
26  import java.util.List;
27  import java.util.Locale;
28  import java.util.Objects;
29  import java.util.Set;
30  import java.util.function.Supplier;
31  import java.util.regex.Pattern;
32  import java.util.stream.Collectors;
33  
34  import org.apache.commons.lang3.function.Suppliers;
35  import org.apache.commons.lang3.stream.LangCollectors;
36  import org.apache.commons.lang3.stream.Streams;
37  
38  /**
39   * Operations on {@link String} that are
40   * {@code null} safe.
41   *
42   * <ul>
43   *  <li><strong>IsEmpty/IsBlank</strong>
44   *      - checks if a String contains text</li>
45   *  <li><strong>Trim/Strip</strong>
46   *      - removes leading and trailing whitespace</li>
47   *  <li><strong>Equals/Compare</strong>
48   *      - compares two strings in a null-safe manner</li>
49   *  <li><strong>startsWith</strong>
50   *      - check if a String starts with a prefix in a null-safe manner</li>
51   *  <li><strong>endsWith</strong>
52   *      - check if a String ends with a suffix in a null-safe manner</li>
53   *  <li><strong>IndexOf/LastIndexOf/Contains</strong>
54   *      - null-safe index-of checks</li>
55   *  <li><strong>IndexOfAny/LastIndexOfAny/IndexOfAnyBut/LastIndexOfAnyBut</strong>
56   *      - index-of any of a set of Strings</li>
57   *  <li><strong>ContainsOnly/ContainsNone/ContainsAny</strong>
58   *      - checks if String contains only/none/any of these characters</li>
59   *  <li><strong>Substring/Left/Right/Mid</strong>
60   *      - null-safe substring extractions</li>
61   *  <li><strong>SubstringBefore/SubstringAfter/SubstringBetween</strong>
62   *      - substring extraction relative to other strings</li>
63   *  <li><strong>Split/Join</strong>
64   *      - splits a String into an array of substrings and vice versa</li>
65   *  <li><strong>Remove/Delete</strong>
66   *      - removes part of a String</li>
67   *  <li><strong>Replace/Overlay</strong>
68   *      - Searches a String and replaces one String with another</li>
69   *  <li><strong>Chomp/Chop</strong>
70   *      - removes the last part of a String</li>
71   *  <li><strong>AppendIfMissing</strong>
72   *      - appends a suffix to the end of the String if not present</li>
73   *  <li><strong>PrependIfMissing</strong>
74   *      - prepends a prefix to the start of the String if not present</li>
75   *  <li><strong>Wrap</strong>
76   *      - wraps a String with a character or another String</li>
77   *  <li><strong>WrapIfMissing</strong>
78   *      - wraps a String only where the wrapping character or String is missing</li>
79   *  <li><strong>Unwrap</strong>
80   *      - removes matching wrapping characters or Strings from both ends of a String</li>
81   *  <li><strong>LeftPad/RightPad/Center/Repeat</strong>
82   *      - pads a String</li>
83   *  <li><strong>UpperCase/LowerCase/SwapCase/Capitalize/Uncapitalize</strong>
84   *      - changes the case of a String</li>
85   *  <li><strong>CountMatches</strong>
86   *      - counts the number of occurrences of one String in another</li>
87   *  <li><strong>IsAlpha/IsNumeric/IsWhitespace/IsAsciiPrintable</strong>
88   *      - checks the characters in a String</li>
89   *  <li><strong>DefaultString</strong>
90   *      - protects against a null input String</li>
91   *  <li><strong>Rotate</strong>
92   *      - rotate (circular shift) a String</li>
93   *  <li><strong>Reverse/ReverseDelimited</strong>
94   *      - reverses a String</li>
95   *  <li><strong>Abbreviate</strong>
96   *      - abbreviates a string using ellipses or another given String</li>
97   *  <li><strong>Difference</strong>
98   *      - compares Strings and reports on their differences</li>
99   *  <li><strong>LevenshteinDistance</strong>
100  *      - the number of changes needed to change one String into another</li>
101  * </ul>
102  *
103  * <p>
104  * The {@link StringUtils} class defines certain words related to
105  * String handling.
106  * </p>
107  *
108  * <ul>
109  *  <li>null - {@code null}</li>
110  *  <li>empty - a zero-length string ({@code ""})</li>
111  *  <li>space - the space character ({@code ' '}, char 32)</li>
112  *  <li>whitespace - the characters defined by {@link Character#isWhitespace(char)}</li>
113  *  <li>trim - the characters &lt;= 32 as in {@link String#trim()}</li>
114  * </ul>
115  *
116  * <p>
117  * {@link StringUtils} handles {@code null} input Strings quietly.
118  * That is to say that a {@code null} input will return {@code null}.
119  * Where a {@code boolean} or {@code int} is being returned
120  * details vary by method.
121  * </p>
122  *
123  * <p>
124  * A side effect of the {@code null} handling is that a
125  * {@link NullPointerException} should be considered a bug in
126  * {@link StringUtils}.
127  * </p>
128  *
129  * <p>
130  * Methods in this class include sample code in their Javadoc comments to explain their operation.
131  * The symbol {@code *} is used to indicate any input including {@code null}.
132  * </p>
133  *
134  * <p>
135  * #ThreadSafe#
136  * </p>
137  *
138  * @see String
139  * @since 1.0
140  */
141 //@Immutable
142 public class StringUtils {
143 
144     // Performance testing notes (JDK 1.4, Jul03, scolebourne)
145     // Whitespace:
146     // Character.isWhitespace() is faster than WHITESPACE.indexOf()
147     // where WHITESPACE is a string of all whitespace characters
148     //
149     // Character access:
150     // String.charAt(n) versus toCharArray(), then array[n]
151     // String.charAt(n) is about 15% worse for a 10K string
152     // They are about equal for a length 50 string
153     // String.charAt(n) is about 4 times better for a length 3 string
154     // String.charAt(n) is best bet overall
155     //
156     // Append:
157     // String.concat about twice as fast as StringBuffer.append
158     // (not sure who tested this)
159 
160     /**
161      * This is a 3 character version of an ellipsis. There is a Unicode character for a HORIZONTAL ELLIPSIS, U+2026 '…', this isn't it.
162      */
163     private static final String ELLIPSIS3 = "...";
164 
165     /**
166      * A String for a space character.
167      *
168      * @since 3.2
169      */
170     public static final String SPACE = " ";
171 
172     /**
173      * The empty String {@code ""}.
174      *
175      * @since 2.0
176      */
177     public static final String EMPTY = "";
178 
179     /**
180      * The null String {@code null}. Package-private only.
181      */
182     static final String NULL = null;
183 
184     /**
185      * A String for linefeed LF ("\n").
186      *
187      * @see <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-3.html#jls-3.10.6">JLF: Escape Sequences
188      *      for Character and String Literals</a>
189      * @since 3.2
190      */
191     public static final String LF = "\n";
192 
193     /**
194      * A String for carriage return CR ("\r").
195      *
196      * @see <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-3.html#jls-3.10.6">JLF: Escape Sequences
197      *      for Character and String Literals</a>
198      * @since 3.2
199      */
200     public static final String CR = "\r";
201 
202     /**
203      * Represents a failed index search.
204      *
205      * @since 2.1
206      */
207     public static final int INDEX_NOT_FOUND = -1;
208 
209     /**
210      * The maximum size to which the padding constant(s) can expand.
211      */
212     private static final int PAD_LIMIT = 8192;
213 
214     /**
215      * The default maximum depth at which recursive replacement will continue until no further search replacements are possible.
216      */
217     private static final int DEFAULT_TTL = 5;
218 
219     /**
220      * Pattern used in {@link #stripAccents(String)}.
221      */
222     private static final Pattern STRIP_ACCENTS_PATTERN = Pattern.compile("\\p{InCombiningDiacriticalMarks}+"); //$NON-NLS-1$
223 
224     /**
225      * Abbreviates a String using ellipses. This will convert "Now is the time for all good men" into "Now is the time for..."
226      *
227      * <p>
228      * Specifically:
229      * </p>
230      * <ul>
231      * <li>If the number of characters in {@code str} is less than or equal to {@code maxWidth}, return {@code str}.</li>
232      * <li>Else abbreviate it to {@code (substring(str, 0, max - 3) + "...")}.</li>
233      * <li>If {@code maxWidth} is less than {@code 4}, throw an {@link IllegalArgumentException}.</li>
234      * <li>In no case will it return a String of length greater than {@code maxWidth}.</li>
235      * </ul>
236      *
237      * <pre>
238      * StringUtils.abbreviate(null, *)      = null
239      * StringUtils.abbreviate("", 4)        = ""
240      * StringUtils.abbreviate("abcdefg", 6) = "abc..."
241      * StringUtils.abbreviate("abcdefg", 7) = "abcdefg"
242      * StringUtils.abbreviate("abcdefg", 8) = "abcdefg"
243      * StringUtils.abbreviate("abcdefg", 4) = "a..."
244      * StringUtils.abbreviate("abcdefg", 3) = Throws {@link IllegalArgumentException}.
245      * </pre>
246      *
247      * @param str      The String to check, may be null.
248      * @param maxWidth maximum length of result String, must be at least 4.
249      * @return abbreviated String, {@code null} if null String input.
250      * @throws IllegalArgumentException Thrown if the width is too small.
251      * @since 2.0
252      */
253     public static String abbreviate(final String str, final int maxWidth) {
254         return abbreviate(str, ELLIPSIS3, 0, maxWidth);
255     }
256 
257     /**
258      * Abbreviates a String using ellipses. This will convert "Now is the time for all good men" into "...is the time for...".
259      *
260      * <p>
261      * Works like {@code abbreviate(String, int)}, but allows you to specify a "left edge" offset. Note that this left edge is not necessarily going to be the
262      * leftmost character in the result, or the first character following the ellipses, but it will appear somewhere in the result.
263      * </p>
264      * <p>
265      * In no case will it return a String of length greater than {@code maxWidth}.
266      * </p>
267      *
268      * <pre>
269      * StringUtils.abbreviate(null, *, *)                = null
270      * StringUtils.abbreviate("", 0, 4)                  = ""
271      * StringUtils.abbreviate("abcdefghijklmno", -1, 10) = "abcdefg..."
272      * StringUtils.abbreviate("abcdefghijklmno", 0, 10)  = "abcdefg..."
273      * StringUtils.abbreviate("abcdefghijklmno", 1, 10)  = "abcdefg..."
274      * StringUtils.abbreviate("abcdefghijklmno", 4, 10)  = "abcdefg..."
275      * StringUtils.abbreviate("abcdefghijklmno", 5, 10)  = "...fghi..."
276      * StringUtils.abbreviate("abcdefghijklmno", 6, 10)  = "...ghij..."
277      * StringUtils.abbreviate("abcdefghijklmno", 8, 10)  = "...ijklmno"
278      * StringUtils.abbreviate("abcdefghijklmno", 10, 10) = "...ijklmno"
279      * StringUtils.abbreviate("abcdefghijklmno", 12, 10) = "...ijklmno"
280      * StringUtils.abbreviate("abcdefghij", 0, 3)        = Throws {@link IllegalArgumentException}.
281      * StringUtils.abbreviate("abcdefghij", 5, 6)        = Throws {@link IllegalArgumentException}.
282      * </pre>
283      *
284      * @param str      The String to check, may be null.
285      * @param offset   left edge of source String.
286      * @param maxWidth maximum length of result String, must be at least 4.
287      * @return abbreviated String, {@code null} if null String input.
288      * @throws IllegalArgumentException Thrown if the width is too small.
289      * @since 2.0
290      */
291     public static String abbreviate(final String str, final int offset, final int maxWidth) {
292         return abbreviate(str, ELLIPSIS3, offset, maxWidth);
293     }
294 
295     /**
296      * Abbreviates a String using another given String as replacement marker. This will convert "Now is the time for all good men" into "Now is the time for..."
297      * when "..." is the replacement marker.
298      *
299      * <p>
300      * Specifically:
301      * </p>
302      * <ul>
303      * <li>If the number of characters in {@code str} is less than or equal to {@code maxWidth}, return {@code str}.</li>
304      * <li>Else abbreviate it to {@code (substring(str, 0, max - abbrevMarker.length) + abbrevMarker)}.</li>
305      * <li>If {@code maxWidth} is less than {@code abbrevMarker.length + 1}, throw an {@link IllegalArgumentException}.</li>
306      * <li>In no case will it return a String of length greater than {@code maxWidth}.</li>
307      * </ul>
308      *
309      * <pre>
310      * StringUtils.abbreviate(null, "...", *)      = null
311      * StringUtils.abbreviate("abcdefg", null, *)  = "abcdefg"
312      * StringUtils.abbreviate("", "...", 4)        = ""
313      * StringUtils.abbreviate("abcdefg", ".", 5)   = "abcd."
314      * StringUtils.abbreviate("abcdefg", ".", 7)   = "abcdefg"
315      * StringUtils.abbreviate("abcdefg", ".", 8)   = "abcdefg"
316      * StringUtils.abbreviate("abcdefg", "..", 4)  = "ab.."
317      * StringUtils.abbreviate("abcdefg", "..", 3)  = "a.."
318      * StringUtils.abbreviate("abcdefg", "..", 2)  = Throws {@link IllegalArgumentException}.
319      * StringUtils.abbreviate("abcdefg", "...", 3) = Throws {@link IllegalArgumentException}.
320      * </pre>
321      *
322      * @param str          The String to check, may be null.
323      * @param abbrevMarker The String used as replacement marker.
324      * @param maxWidth     maximum length of result String, must be at least {@code abbrevMarker.length + 1}.
325      * @return abbreviated String, {@code null} if null String input.
326      * @throws IllegalArgumentException Thrown if the width is too small.
327      * @since 3.6
328      */
329     public static String abbreviate(final String str, final String abbrevMarker, final int maxWidth) {
330         return abbreviate(str, abbrevMarker, 0, maxWidth);
331     }
332 
333     /**
334      * Abbreviates a String using a given replacement marker. This will convert "Now is the time for all good men" into "...is the time for..." when "..." is
335      * the replacement marker.
336      * <p>
337      * Works like {@code abbreviate(String, String, int)}, but allows you to specify a "left edge" offset. Note that this left edge is not necessarily going to
338      * be the leftmost character in the result, or the first character following the replacement marker, but it will appear somewhere in the result.
339      * </p>
340      * <p>
341      * In no case will it return a String of length greater than {@code maxWidth}.
342      * </p>
343      *
344      * <pre>
345      * StringUtils.abbreviate(null, null, *, *)                 = null
346      * StringUtils.abbreviate("abcdefghijklmno", null, *, *)    = "abcdefghijklmno"
347      * StringUtils.abbreviate("", "...", 0, 4)                  = ""
348      * StringUtils.abbreviate("abcdefghijklmno", "---", -1, 10) = "abcdefg---"
349      * StringUtils.abbreviate("abcdefghijklmno", ",", 0, 10)    = "abcdefghi,"
350      * StringUtils.abbreviate("abcdefghijklmno", ",", 1, 10)    = "abcdefghi,"
351      * StringUtils.abbreviate("abcdefghijklmno", ",", 2, 10)    = "abcdefghi,"
352      * StringUtils.abbreviate("abcdefghijklmno", "::", 4, 10)   = "::efghij::"
353      * StringUtils.abbreviate("abcdefghijklmno", "...", 6, 10)  = "...ghij..."
354      * StringUtils.abbreviate("abcdefghijklmno", "…", 6, 10)    = "…ghijklmno"
355      * StringUtils.abbreviate("abcdefghijklmno", "*", 9, 10)    = "*ghijklmno"
356      * StringUtils.abbreviate("abcdefghijklmno", "'", 10, 10)   = "'ghijklmno"
357      * StringUtils.abbreviate("abcdefghijklmno", "!", 12, 10)   = "!ghijklmno"
358      * StringUtils.abbreviate("abcdefghij", "abra", 0, 4)       = Throws {@link IllegalArgumentException}.
359      * StringUtils.abbreviate("abcdefghij", "...", 5, 6)        = Throws {@link IllegalArgumentException}.
360      * </pre>
361      *
362      * @param str          The String to check, may be null.
363      * @param abbrevMarker The String used as replacement marker, for example "...", or Unicode HORIZONTAL ELLIPSIS, U+2026 '…'.
364      * @param offset       left edge of source String.
365      * @param maxWidth     maximum length of result String, must be at least 4.
366      * @return abbreviated String, {@code null} if null String input.
367      * @throws IllegalArgumentException Thrown if the width is too small.
368      * @since 3.6
369      */
370     public static String abbreviate(final String str, String abbrevMarker, final int offset, final int maxWidth) {
371         if (isEmpty(str)) {
372             return str;
373         }
374         if (abbrevMarker == null) {
375             abbrevMarker = EMPTY;
376         }
377         final int abbrevMarkerLength = abbrevMarker.length();
378         final int minAbbrevWidth = abbrevMarkerLength + 1;
379         final int minAbbrevWidthOffset = abbrevMarkerLength + abbrevMarkerLength + 1;
380 
381         if (maxWidth < minAbbrevWidth) {
382             throw new IllegalArgumentException(String.format("Minimum abbreviation width is %d", minAbbrevWidth));
383         }
384         final int strLen = str.length();
385         if (strLen <= maxWidth) {
386             return str;
387         }
388         if (strLen - offset <= maxWidth - abbrevMarkerLength) {
389             int tailStart = strLen - (maxWidth - abbrevMarkerLength);
390             if (splitsSurrogatePair(str, tailStart)) {
391                 tailStart++;
392             }
393             return abbrevMarker + str.substring(tailStart);
394         }
395         if (offset <= abbrevMarkerLength + 1) {
396             int headEnd = maxWidth - abbrevMarkerLength;
397             if (splitsSurrogatePair(str, headEnd)) {
398                 headEnd--;
399             }
400             return str.substring(0, headEnd) + abbrevMarker;
401         }
402         if (maxWidth < minAbbrevWidthOffset) {
403             throw new IllegalArgumentException(String.format("Minimum abbreviation width with offset is %d", minAbbrevWidthOffset));
404         }
405         int from = offset;
406         if (splitsSurrogatePair(str, from)) {
407             from++;
408         }
409         return abbrevMarker + abbreviate(str.substring(from), abbrevMarker, maxWidth - abbrevMarkerLength);
410     }
411 
412     /**
413      * Abbreviates a String to the length passed, replacing the middle characters with the supplied replacement String.
414      *
415      * <p>
416      * This abbreviation only occurs if the following criteria is met:
417      * </p>
418      * <ul>
419      * <li>Neither the String for abbreviation nor the replacement String are null or empty</li>
420      * <li>The length to truncate to is less than the length of the supplied String</li>
421      * <li>The length to truncate to is greater than 0</li>
422      * <li>The abbreviated String will have enough room for the length supplied replacement String and the first and last characters of the supplied String for
423      * abbreviation</li>
424      * </ul>
425      * <p>
426      * Otherwise, the returned String will be the same as the supplied String for abbreviation.
427      * </p>
428      *
429      * <pre>
430      * StringUtils.abbreviateMiddle(null, null, 0)    = null
431      * StringUtils.abbreviateMiddle("abc", null, 0)   = "abc"
432      * StringUtils.abbreviateMiddle("abc", ".", 0)    = "abc"
433      * StringUtils.abbreviateMiddle("abc", ".", 3)    = "abc"
434      * StringUtils.abbreviateMiddle("abcdef", ".", 4) = "ab.f"
435      * </pre>
436      *
437      * @param str    The String to abbreviate, may be null.
438      * @param middle The String to replace the middle characters with, may be null.
439      * @param length The length to abbreviate {@code str} to.
440      * @return The abbreviated String if the above criteria is met, or the original String supplied for abbreviation.
441      * @since 2.5
442      */
443     public static String abbreviateMiddle(final String str, final String middle, final int length) {
444         if (isAnyEmpty(str, middle) || length >= str.length() || length < middle.length() + 2) {
445             return str;
446         }
447         final int targetString = length - middle.length();
448         int startOffset = targetString / 2 + targetString % 2;
449         int endOffset = str.length() - targetString / 2;
450         // keep both cuts off the middle of a surrogate pair so the result is never left holding a lone surrogate
451         if (splitsSurrogatePair(str, startOffset)) {
452             startOffset--;
453         }
454         if (splitsSurrogatePair(str, endOffset)) {
455             endOffset++;
456         }
457         return str.substring(0, startOffset) + middle + str.substring(endOffset);
458     }
459 
460     /**
461      * Appends the suffix to the end of the string if the string does not already end with any of the suffixes.
462      *
463      * <pre>
464      * StringUtils.appendIfMissing(null, null)      = null
465      * StringUtils.appendIfMissing("abc", null)     = "abc"
466      * StringUtils.appendIfMissing("", "xyz")       = "xyz"
467      * StringUtils.appendIfMissing("abc", "xyz")    = "abcxyz"
468      * StringUtils.appendIfMissing("abcxyz", "xyz") = "abcxyz"
469      * StringUtils.appendIfMissing("abcXYZ", "xyz") = "abcXYZxyz"
470      * </pre>
471      * <p>
472      * With additional suffixes,
473      * </p>
474      *
475      * <pre>
476      * StringUtils.appendIfMissing(null, null, null)       = null
477      * StringUtils.appendIfMissing("abc", null, null)      = "abc"
478      * StringUtils.appendIfMissing("", "xyz", null)        = "xyz"
479      * StringUtils.appendIfMissing("abc", "xyz", new CharSequence[]{null}) = "abcxyz"
480      * StringUtils.appendIfMissing("abc", "xyz", "")       = "abc"
481      * StringUtils.appendIfMissing("abc", "xyz", "mno")    = "abcxyz"
482      * StringUtils.appendIfMissing("abcxyz", "xyz", "mno") = "abcxyz"
483      * StringUtils.appendIfMissing("abcmno", "xyz", "mno") = "abcmno"
484      * StringUtils.appendIfMissing("abcXYZ", "xyz", "mno") = "abcXYZxyz"
485      * StringUtils.appendIfMissing("abcMNO", "xyz", "mno") = "abcMNOxyz"
486      * </pre>
487      *
488      * @param str      The string.
489      * @param suffix   The suffix to append to the end of the string.
490      * @param suffixes Additional suffixes that are valid terminators.
491      * @return A new String if suffix was appended, the same string otherwise.
492      * @since 3.2
493      * @deprecated Use {@link Strings#appendIfMissing(String, CharSequence, CharSequence...) Strings.CS.appendIfMissing(String, CharSequence, CharSequence...)}.
494      */
495     @Deprecated
496     public static String appendIfMissing(final String str, final CharSequence suffix, final CharSequence... suffixes) {
497         return Strings.CS.appendIfMissing(str, suffix, suffixes);
498     }
499 
500     /**
501      * Appends the suffix to the end of the string if the string does not
502      * already end, case-insensitive, with any of the suffixes.
503      *
504      * <pre>
505      * StringUtils.appendIfMissingIgnoreCase(null, null)      = null
506      * StringUtils.appendIfMissingIgnoreCase("abc", null)     = "abc"
507      * StringUtils.appendIfMissingIgnoreCase("", "xyz")       = "xyz"
508      * StringUtils.appendIfMissingIgnoreCase("abc", "xyz")    = "abcxyz"
509      * StringUtils.appendIfMissingIgnoreCase("abcxyz", "xyz") = "abcxyz"
510      * StringUtils.appendIfMissingIgnoreCase("abcXYZ", "xyz") = "abcXYZ"
511      * </pre>
512      * <p>
513      * With additional suffixes,
514      * </p>
515      * <pre>
516      * StringUtils.appendIfMissingIgnoreCase(null, null, null)       = null
517      * StringUtils.appendIfMissingIgnoreCase("abc", null, null)      = "abc"
518      * StringUtils.appendIfMissingIgnoreCase("", "xyz", null)        = "xyz"
519      * StringUtils.appendIfMissingIgnoreCase("abc", "xyz", new CharSequence[]{null}) = "abcxyz"
520      * StringUtils.appendIfMissingIgnoreCase("abc", "xyz", "")       = "abc"
521      * StringUtils.appendIfMissingIgnoreCase("abc", "xyz", "mno")    = "abcxyz"
522      * StringUtils.appendIfMissingIgnoreCase("abcxyz", "xyz", "mno") = "abcxyz"
523      * StringUtils.appendIfMissingIgnoreCase("abcmno", "xyz", "mno") = "abcmno"
524      * StringUtils.appendIfMissingIgnoreCase("abcXYZ", "xyz", "mno") = "abcXYZ"
525      * StringUtils.appendIfMissingIgnoreCase("abcMNO", "xyz", "mno") = "abcMNO"
526      * </pre>
527      *
528      * @param str The string.
529      * @param suffix The suffix to append to the end of the string.
530      * @param suffixes Additional suffixes that are valid terminators.
531      * @return A new String if suffix was appended, the same string otherwise.
532      * @since 3.2
533      * @deprecated Use {@link Strings#appendIfMissing(String, CharSequence, CharSequence...) Strings.CI.appendIfMissing(String, CharSequence, CharSequence...)}.
534      */
535     @Deprecated
536     public static String appendIfMissingIgnoreCase(final String str, final CharSequence suffix, final CharSequence... suffixes) {
537         return Strings.CI.appendIfMissing(str, suffix, suffixes);
538     }
539 
540     /**
541      * Computes the capacity required for a StringBuilder to hold {@code items} of {@code maxElementChars} characters plus the separators between them. The
542      * separator is assumed to be 1 character.
543      *
544      * @param count           The number of items.
545      * @param maxElementChars The maximum number of characters per item.
546      * @return A StringBuilder with the appropriate capacity.
547      */
548     private static StringBuilder capacity(final int count, final byte maxElementChars) {
549         return new StringBuilder(count * maxElementChars + count - 1);
550     }
551 
552     /**
553      * Capitalizes a String changing the first character to title case as per {@link Character#toTitleCase(int)}. No other characters are changed.
554      *
555      * <p>
556      * For a word based algorithm, see {@link org.apache.commons.text.WordUtils#capitalize(String)}. A {@code null} input String returns {@code null}.
557      * </p>
558      *
559      * <pre>
560      * StringUtils.capitalize(null)    = null
561      * StringUtils.capitalize("")      = ""
562      * StringUtils.capitalize("cat")   = "Cat"
563      * StringUtils.capitalize("cAt")   = "CAt"
564      * StringUtils.capitalize("'cat'") = "'cat'"
565      * </pre>
566      *
567      * @param str The String to capitalize, may be null.
568      * @return The capitalized String, {@code null} if null String input.
569      * @see org.apache.commons.text.WordUtils#capitalize(String)
570      * @see #uncapitalize(String)
571      * @since 2.0
572      */
573     public static String capitalize(final String str) {
574         if (isEmpty(str)) {
575             return str;
576         }
577         final int firstCodepoint = str.codePointAt(0);
578         final int newCodePoint = Character.toTitleCase(firstCodepoint);
579         if (firstCodepoint == newCodePoint) {
580             // already capitalized
581             return str;
582         }
583         final int[] newCodePoints = str.codePoints().toArray();
584         newCodePoints[0] = newCodePoint; // copy the first code point
585         return new String(newCodePoints, 0, newCodePoints.length);
586     }
587 
588     /**
589      * Centers a String in a larger String of size {@code size} using the space character (' ').
590      *
591      * <p>
592      * If the size is less than the String length, the original String is returned. A {@code null} String returns {@code null}. A negative size is treated as
593      * zero.
594      * </p>
595      *
596      * <p>
597      * Equivalent to {@code center(str, size, " ")}.
598      * </p>
599      *
600      * <pre>
601      * StringUtils.center(null, *)   = null
602      * StringUtils.center("", 4)     = "    "
603      * StringUtils.center("ab", -1)  = "ab"
604      * StringUtils.center("ab", 4)   = " ab "
605      * StringUtils.center("abcd", 2) = "abcd"
606      * StringUtils.center("a", 4)    = " a  "
607      * </pre>
608      *
609      * @param str  The String to center, may be null.
610      * @param size The int size of new String, negative treated as zero.
611      * @return centered String, {@code null} if null String input.
612      */
613     public static String center(final String str, final int size) {
614         return center(str, size, ' ');
615     }
616 
617     /**
618      * Centers a String in a larger String of size {@code size}. Uses a supplied character as the value to pad the String with.
619      *
620      * <p>
621      * If the size is less than the String length, the String is returned. A {@code null} String returns {@code null}. A negative size is treated as zero.
622      * </p>
623      *
624      * <pre>
625      * StringUtils.center(null, *, *)     = null
626      * StringUtils.center("", 4, ' ')     = "    "
627      * StringUtils.center("ab", -1, ' ')  = "ab"
628      * StringUtils.center("ab", 4, ' ')   = " ab "
629      * StringUtils.center("abcd", 2, ' ') = "abcd"
630      * StringUtils.center("a", 4, ' ')    = " a  "
631      * StringUtils.center("a", 4, 'y')    = "yayy"
632      * </pre>
633      *
634      * @param str     The String to center, may be null.
635      * @param size    The int size of new String, negative treated as zero.
636      * @param padChar The character to pad the new String with.
637      * @return centered String, {@code null} if null String input.
638      * @since 2.0
639      */
640     public static String center(String str, final int size, final char padChar) {
641         if (str == null || size <= 0) {
642             return str;
643         }
644         final int strLen = str.length();
645         final int pads = size - strLen;
646         if (pads <= 0) {
647             return str;
648         }
649         str = leftPad(str, strLen + pads / 2, padChar);
650         return rightPad(str, size, padChar);
651     }
652 
653     /**
654      * Centers a String in a larger String of size {@code size}. Uses a supplied String as the value to pad the String with.
655      *
656      * <p>
657      * If the size is less than the String length, the String is returned. A {@code null} String returns {@code null}. A negative size is treated as zero.
658      * If the requested padding length on either side would split a Unicode surrogate pair in {@code padStr}, the padding is shortened by one {@code char}
659      * (via delegation to {@link #leftPad(String, int, String)} and {@link #rightPad(String, int, String)}) to avoid introducing an unpaired
660      * surrogate by splitting the pair. In that case, the returned String may be shorter than {@code size}, but by no more than one {@code char}.
661      * </p>
662      *
663      * <pre>
664      * StringUtils.center(null, *, *)     = null
665      * StringUtils.center("", 4, " ")     = "    "
666      * StringUtils.center("ab", -1, " ")  = "ab"
667      * StringUtils.center("ab", 4, " ")   = " ab "
668      * StringUtils.center("abcd", 2, " ") = "abcd"
669      * StringUtils.center("a", 4, " ")    = " a  "
670      * StringUtils.center("a", 4, "yz")   = "yayz"
671      * StringUtils.center("abc", 7, null) = "  abc  "
672      * StringUtils.center("abc", 7, "")   = "  abc  "
673      * StringUtils.center("a", 2, "\uD83D\uDE00")   = "a"
674      * StringUtils.center("a", 3, "\uD83D\uDE00")   = "a\uD83D\uDE00"
675      * </pre>
676      *
677      * @param str    The String to center, may be null.
678      * @param size   The int size of new String, negative treated as zero.
679      * @param padStr The String to pad the new String with, must not be null or empty.
680      * @return centered String, {@code null} if null String input.
681      * @throws IllegalArgumentException Thrown if padStr is {@code null} or empty.
682      */
683     public static String center(String str, final int size, String padStr) {
684         if (str == null || size <= 0) {
685             return str;
686         }
687         if (isEmpty(padStr)) {
688             padStr = SPACE;
689         }
690         final int strLen = str.length();
691         final int pads = size - strLen;
692         if (pads <= 0) {
693             return str;
694         }
695         str = leftPad(str, strLen + pads / 2, padStr);
696         return rightPad(str, size, padStr);
697     }
698 
699     private static void checkFromToIndex(final int startIndex, final int endIndex, final int length) {
700         if (startIndex < 0) {
701             throw new ArrayIndexOutOfBoundsException(startIndex);
702         }
703         if (endIndex > length) {
704             throw new ArrayIndexOutOfBoundsException(endIndex);
705         }
706     }
707 
708     /**
709      * Removes one newline from end of a String if it's there, otherwise leave it alone. A newline is &quot;{@code \n}&quot;, &quot;{@code \r}&quot;, or
710      * &quot;{@code \r\n}&quot;.
711      *
712      * <p>
713      * NOTE: This method changed in 2.0. It now more closely matches Perl chomp.
714      * </p>
715      *
716      * <pre>
717      * StringUtils.chomp(null)          = null
718      * StringUtils.chomp("")            = ""
719      * StringUtils.chomp("abc \r")      = "abc "
720      * StringUtils.chomp("abc\n")       = "abc"
721      * StringUtils.chomp("abc\r\n")     = "abc"
722      * StringUtils.chomp("abc\r\n\r\n") = "abc\r\n"
723      * StringUtils.chomp("abc\n\r")     = "abc\n"
724      * StringUtils.chomp("abc\n\rabc")  = "abc\n\rabc"
725      * StringUtils.chomp("\r")          = ""
726      * StringUtils.chomp("\n")          = ""
727      * StringUtils.chomp("\r\n")        = ""
728      * </pre>
729      *
730      * @param str The String to chomp a newline from, may be null.
731      * @return String without newline, {@code null} if null String input.
732      */
733     public static String chomp(final String str) {
734         if (isEmpty(str)) {
735             return str;
736         }
737         if (str.length() == 1) {
738             final char ch = str.charAt(0);
739             if (ch == CharUtils.CR || ch == CharUtils.LF) {
740                 return EMPTY;
741             }
742             return str;
743         }
744         int lastIdx = str.length() - 1;
745         final char last = str.charAt(lastIdx);
746         if (last == CharUtils.LF) {
747             if (str.charAt(lastIdx - 1) == CharUtils.CR) {
748                 lastIdx--;
749             }
750         } else if (last != CharUtils.CR) {
751             lastIdx++;
752         }
753         return str.substring(0, lastIdx);
754     }
755 
756     /**
757      * Removes {@code separator} from the end of {@code str} if it's there, otherwise leave it alone.
758      *
759      * <p>
760      * NOTE: This method changed in version 2.0. It now more closely matches Perl chomp. For the previous behavior, use
761      * {@link #substringBeforeLast(String, String)}. This method uses {@link String#endsWith(String)}.
762      * </p>
763      *
764      * <pre>
765      * StringUtils.chomp(null, *)         = null
766      * StringUtils.chomp("", *)           = ""
767      * StringUtils.chomp("foobar", "bar") = "foo"
768      * StringUtils.chomp("foobar", "baz") = "foobar"
769      * StringUtils.chomp("foo", "foo")    = ""
770      * StringUtils.chomp("foo ", "foo")   = "foo "
771      * StringUtils.chomp(" foo", "foo")   = " "
772      * StringUtils.chomp("foo", "foooo")  = "foo"
773      * StringUtils.chomp("foo", "")       = "foo"
774      * StringUtils.chomp("foo", null)     = "foo"
775      * </pre>
776      *
777      * @param str       The String to chomp from, may be null.
778      * @param separator separator String, may be null.
779      * @return String without trailing separator, {@code null} if null String input.
780      * @deprecated This feature will be removed in Lang 4, use {@link StringUtils#removeEnd(String, String)} instead.
781      */
782     @Deprecated
783     public static String chomp(final String str, final String separator) {
784         return Strings.CS.removeEnd(str, separator);
785     }
786 
787     /**
788      * Removes the last character from a String.
789      *
790      * <p>
791      * If the String ends in {@code \r\n}, then remove both of them.
792      * </p>
793      *
794      * <pre>
795      * StringUtils.chop(null)          = null
796      * StringUtils.chop("")            = ""
797      * StringUtils.chop("abc \r")      = "abc "
798      * StringUtils.chop("abc\n")       = "abc"
799      * StringUtils.chop("abc\r\n")     = "abc"
800      * StringUtils.chop("abc")         = "ab"
801      * StringUtils.chop("abc\nabc")    = "abc\nab"
802      * StringUtils.chop("a")           = ""
803      * StringUtils.chop("\r")          = ""
804      * StringUtils.chop("\n")          = ""
805      * StringUtils.chop("\r\n")        = ""
806      * </pre>
807      *
808      * @param str The String to chop last character from, may be null.
809      * @return String without last character, {@code null} if null String input.
810      */
811     public static String chop(final String str) {
812         if (str == null) {
813             return null;
814         }
815         final int strLen = str.length();
816         if (strLen < 2) {
817             return EMPTY;
818         }
819         final int lastIdx = strLen - 1;
820         // keep the cut off the middle of a surrogate pair so the result is never left holding a lone surrogate
821         if (splitsSurrogatePair(str, lastIdx)) {
822             return str.substring(0, lastIdx - 1);
823         }
824         final String ret = str.substring(0, lastIdx);
825         final char last = str.charAt(lastIdx);
826         if (last == CharUtils.LF && ret.charAt(lastIdx - 1) == CharUtils.CR) {
827             return ret.substring(0, lastIdx - 1);
828         }
829         return ret;
830     }
831 
832     /**
833      * Compares two Strings lexicographically, as per {@link String#compareTo(String)}, returning :
834      * <ul>
835      * <li>{@code int = 0}, if {@code str1} is equal to {@code str2} (or both {@code null})</li>
836      * <li>{@code int < 0}, if {@code str1} is less than {@code str2}</li>
837      * <li>{@code int > 0}, if {@code str1} is greater than {@code str2}</li>
838      * </ul>
839      *
840      * <p>
841      * This is a {@code null} safe version of:
842      * </p>
843      *
844      * <pre>
845      * str1.compareTo(str2)
846      * </pre>
847      *
848      * <p>
849      * {@code null} value is considered less than non-{@code null} value. Two {@code null} references are considered equal.
850      * </p>
851      *
852      * <pre>{@code
853      * StringUtils.compare(null, null)   = 0
854      * StringUtils.compare(null , "a")   < 0
855      * StringUtils.compare("a", null)   > 0
856      * StringUtils.compare("abc", "abc") = 0
857      * StringUtils.compare("a", "b")     < 0
858      * StringUtils.compare("b", "a")     > 0
859      * StringUtils.compare("a", "B")     > 0
860      * StringUtils.compare("ab", "abc")  < 0
861      * }</pre>
862      *
863      * @param str1 The String to compare from.
864      * @param str2 The String to compare to.
865      * @return &lt; 0, 0, &gt; 0, if {@code str1} is respectively less, equal or greater than {@code str2}.
866      * @see #compare(String, String, boolean)
867      * @see String#compareTo(String)
868      * @since 3.5
869      * @deprecated Use {@link Strings#compare(String, String) Strings.CS.compare(String, String)}.
870      */
871     @Deprecated
872     public static int compare(final String str1, final String str2) {
873         return Strings.CS.compare(str1, str2);
874     }
875 
876     /**
877      * Compares two Strings lexicographically, as per {@link String#compareTo(String)}, returning :
878      * <ul>
879      * <li>{@code int = 0}, if {@code str1} is equal to {@code str2} (or both {@code null})</li>
880      * <li>{@code int < 0}, if {@code str1} is less than {@code str2}</li>
881      * <li>{@code int > 0}, if {@code str1} is greater than {@code str2}</li>
882      * </ul>
883      *
884      * <p>
885      * This is a {@code null} safe version of :
886      * </p>
887      *
888      * <pre>
889      * str1.compareTo(str2)
890      * </pre>
891      *
892      * <p>
893      * {@code null} inputs are handled according to the {@code nullIsLess} parameter. Two {@code null} references are considered equal.
894      * </p>
895      *
896      * <pre>{@code
897      * StringUtils.compare(null, null, *)     = 0
898      * StringUtils.compare(null , "a", true)  < 0
899      * StringUtils.compare(null , "a", false) > 0
900      * StringUtils.compare("a", null, true)   > 0
901      * StringUtils.compare("a", null, false)  < 0
902      * StringUtils.compare("abc", "abc", *)   = 0
903      * StringUtils.compare("a", "b", *)       < 0
904      * StringUtils.compare("b", "a", *)       > 0
905      * StringUtils.compare("a", "B", *)       > 0
906      * StringUtils.compare("ab", "abc", *)    < 0
907      * }</pre>
908      *
909      * @param str1       The String to compare from.
910      * @param str2       The String to compare to.
911      * @param nullIsLess whether consider {@code null} value less than non-{@code null} value.
912      * @return &lt; 0, 0, &gt; 0, if {@code str1} is respectively less, equal ou greater than {@code str2}.
913      * @see String#compareTo(String)
914      * @since 3.5
915      */
916     public static int compare(final String str1, final String str2, final boolean nullIsLess) {
917         if (str1 == str2) { // NOSONARLINT this intentionally uses == to allow for both null
918             return 0;
919         }
920         if (str1 == null) {
921             return nullIsLess ? -1 : 1;
922         }
923         if (str2 == null) {
924             return nullIsLess ? 1 : -1;
925         }
926         return str1.compareTo(str2);
927     }
928 
929     /**
930      * Compares two Strings lexicographically, ignoring case differences, as per {@link String#compareToIgnoreCase(String)}, returning :
931      * <ul>
932      * <li>{@code int = 0}, if {@code str1} is equal to {@code str2} (or both {@code null})</li>
933      * <li>{@code int < 0}, if {@code str1} is less than {@code str2}</li>
934      * <li>{@code int > 0}, if {@code str1} is greater than {@code str2}</li>
935      * </ul>
936      *
937      * <p>
938      * This is a {@code null} safe version of:
939      * </p>
940      *
941      * <pre>
942      * str1.compareToIgnoreCase(str2)
943      * </pre>
944      *
945      * <p>
946      * {@code null} value is considered less than non-{@code null} value. Two {@code null} references are considered equal. Comparison is case insensitive.
947      * </p>
948      *
949      * <pre>{@code
950      * StringUtils.compareIgnoreCase(null, null)   = 0
951      * StringUtils.compareIgnoreCase(null , "a")   < 0
952      * StringUtils.compareIgnoreCase("a", null)    > 0
953      * StringUtils.compareIgnoreCase("abc", "abc") = 0
954      * StringUtils.compareIgnoreCase("abc", "ABC") = 0
955      * StringUtils.compareIgnoreCase("a", "b")     < 0
956      * StringUtils.compareIgnoreCase("b", "a")     > 0
957      * StringUtils.compareIgnoreCase("a", "B")     < 0
958      * StringUtils.compareIgnoreCase("A", "b")     < 0
959      * StringUtils.compareIgnoreCase("ab", "ABC")  < 0
960      * }</pre>
961      *
962      * @param str1 The String to compare from.
963      * @param str2 The String to compare to.
964      * @return &lt; 0, 0, &gt; 0, if {@code str1} is respectively less, equal ou greater than {@code str2}, ignoring case differences.
965      * @see #compareIgnoreCase(String, String, boolean)
966      * @see String#compareToIgnoreCase(String)
967      * @since 3.5
968      * @deprecated Use {@link Strings#compare(String, String) Strings.CI.compare(String, String)}.
969      */
970     @Deprecated
971     public static int compareIgnoreCase(final String str1, final String str2) {
972         return Strings.CI.compare(str1, str2);
973     }
974 
975     /**
976      * Compares two Strings lexicographically, ignoring case differences, as per {@link String#compareToIgnoreCase(String)}, returning :
977      * <ul>
978      * <li>{@code int = 0}, if {@code str1} is equal to {@code str2} (or both {@code null})</li>
979      * <li>{@code int < 0}, if {@code str1} is less than {@code str2}</li>
980      * <li>{@code int > 0}, if {@code str1} is greater than {@code str2}</li>
981      * </ul>
982      *
983      * <p>
984      * This is a {@code null} safe version of :
985      * </p>
986      * <pre>
987      * str1.compareToIgnoreCase(str2)
988      * </pre>
989      *
990      * <p>
991      * {@code null} inputs are handled according to the {@code nullIsLess} parameter. Two {@code null} references are considered equal. Comparison is case
992      * insensitive.
993      * </p>
994      *
995      * <pre>{@code
996      * StringUtils.compareIgnoreCase(null, null, *)     = 0
997      * StringUtils.compareIgnoreCase(null , "a", true)  < 0
998      * StringUtils.compareIgnoreCase(null , "a", false) > 0
999      * StringUtils.compareIgnoreCase("a", null, true)   > 0
1000      * StringUtils.compareIgnoreCase("a", null, false)  < 0
1001      * StringUtils.compareIgnoreCase("abc", "abc", *)   = 0
1002      * StringUtils.compareIgnoreCase("abc", "ABC", *)   = 0
1003      * StringUtils.compareIgnoreCase("a", "b", *)       < 0
1004      * StringUtils.compareIgnoreCase("b", "a", *)       > 0
1005      * StringUtils.compareIgnoreCase("a", "B", *)       < 0
1006      * StringUtils.compareIgnoreCase("A", "b", *)       < 0
1007      * StringUtils.compareIgnoreCase("ab", "abc", *)    < 0
1008      * }</pre>
1009      *
1010      * @param str1       The String to compare from.
1011      * @param str2       The String to compare to.
1012      * @param nullIsLess whether consider {@code null} value less than non-{@code null} value.
1013      * @return &lt; 0, 0, &gt; 0, if {@code str1} is respectively less, equal ou greater than {@code str2}, ignoring case differences.
1014      * @see String#compareToIgnoreCase(String)
1015      * @since 3.5
1016      */
1017     public static int compareIgnoreCase(final String str1, final String str2, final boolean nullIsLess) {
1018         if (str1 == str2) { // NOSONARLINT this intentionally uses == to allow for both null
1019             return 0;
1020         }
1021         if (str1 == null) {
1022             return nullIsLess ? -1 : 1;
1023         }
1024         if (str2 == null) {
1025             return nullIsLess ? 1 : -1;
1026         }
1027         return str1.compareToIgnoreCase(str2);
1028     }
1029 
1030     /**
1031      * Tests if CharSequence contains a search CharSequence, handling {@code null}.
1032      * This method uses {@link String#indexOf(String)} if possible.
1033      *
1034      * <p>
1035      * A {@code null} CharSequence will return {@code false}.
1036      * </p>
1037      *
1038      * <pre>
1039      * StringUtils.contains(null, *)     = false
1040      * StringUtils.contains(*, null)     = false
1041      * StringUtils.contains("", "")      = true
1042      * StringUtils.contains("abc", "")   = true
1043      * StringUtils.contains("abc", "a")  = true
1044      * StringUtils.contains("abc", "z")  = false
1045      * </pre>
1046      *
1047      * @param seq  The CharSequence to check, may be null
1048      * @param searchSeq  The CharSequence to find, may be null
1049      * @return true if the CharSequence contains the search CharSequence,
1050      *  false if not or {@code null} string input
1051      * @since 2.0
1052      * @since 3.0 Changed signature from contains(String, String) to contains(CharSequence, CharSequence)
1053      * @deprecated Use {@link Strings#contains(CharSequence, CharSequence) Strings.CS.contains(CharSequence, CharSequence)}.
1054      */
1055     @Deprecated
1056     public static boolean contains(final CharSequence seq, final CharSequence searchSeq) {
1057         return Strings.CS.contains(seq, searchSeq);
1058     }
1059 
1060     /**
1061      * Tests if CharSequence contains a search character, handling {@code null}. This method uses {@link String#indexOf(int)} if possible.
1062      *
1063      * <p>
1064      * A {@code null} or empty ("") CharSequence will return {@code false}.
1065      * </p>
1066      *
1067      * <pre>
1068      * StringUtils.contains(null, *)    = false
1069      * StringUtils.contains("", *)      = false
1070      * StringUtils.contains("abc", 'a') = true
1071      * StringUtils.contains("abc", 'z') = false
1072      * </pre>
1073      *
1074      * @param seq        The CharSequence to check, may be null
1075      * @param searchChar The character to find
1076      * @return true if the CharSequence contains the search character, false if not or {@code null} string input
1077      * @since 2.0
1078      * @since 3.0 Changed signature from contains(String, int) to contains(CharSequence, int)
1079      */
1080     public static boolean contains(final CharSequence seq, final int searchChar) {
1081         if (isEmpty(seq)) {
1082             return false;
1083         }
1084         return CharSequenceUtils.indexOf(seq, searchChar, 0) >= 0;
1085     }
1086 
1087     /**
1088      * Tests if the CharSequence contains any character in the given set of characters.
1089      *
1090      * <p>
1091      * A {@code null} CharSequence will return {@code false}. A {@code null} or zero length search array will return {@code false}.
1092      * </p>
1093      *
1094      * <pre>
1095      * StringUtils.containsAny(null, *)                  = false
1096      * StringUtils.containsAny("", *)                    = false
1097      * StringUtils.containsAny(*, null)                  = false
1098      * StringUtils.containsAny(*, [])                    = false
1099      * StringUtils.containsAny("zzabyycdxx", 'z', 'a')   = true
1100      * StringUtils.containsAny("zzabyycdxx", 'b', 'y')   = true
1101      * StringUtils.containsAny("zzabyycdxx", 'z', 'y')   = true
1102      * StringUtils.containsAny("aba", 'z])               = false
1103      * </pre>
1104      *
1105      * @param cs          The CharSequence to check, may be null.
1106      * @param searchChars The chars to search for, may be null.
1107      * @return The {@code true} if any of the chars are found, {@code false} if no match or null input.
1108      * @since 2.4
1109      * @since 3.0 Changed signature from containsAny(String, char[]) to containsAny(CharSequence, char...)
1110      */
1111     public static boolean containsAny(final CharSequence cs, final char... searchChars) {
1112         if (isEmpty(cs) || ArrayUtils.isEmpty(searchChars)) {
1113             return false;
1114         }
1115         final int csLength = cs.length();
1116         final int searchLength = searchChars.length;
1117         final int csLast = csLength - 1;
1118         final int searchLast = searchLength - 1;
1119         for (int i = 0; i < csLength; i++) {
1120             final char ch = cs.charAt(i);
1121             for (int j = 0; j < searchLength; j++) {
1122                 if (searchChars[j] == ch) {
1123                     if (Character.isHighSurrogate(ch)
1124                             ? j == searchLast || i < csLast && searchChars[j + 1] == cs.charAt(i + 1)
1125                             : j == 0 || !Character.isLowSurrogate(ch) || !Character.isHighSurrogate(searchChars[j - 1]) || i > 0 && searchChars[j - 1] == cs.charAt(i - 1)) {
1126                         return true;
1127                     }
1128                 }
1129             }
1130         }
1131         return false;
1132     }
1133 
1134     /**
1135      * Tests if the CharSequence contains any character in the given set of characters.
1136      *
1137      * <p>
1138      * A {@code null} CharSequence will return {@code false}. A {@code null} search CharSequence will return {@code false}.
1139      * </p>
1140      *
1141      * <pre>
1142      * StringUtils.containsAny(null, *)               = false
1143      * StringUtils.containsAny("", *)                 = false
1144      * StringUtils.containsAny(*, null)               = false
1145      * StringUtils.containsAny(*, "")                 = false
1146      * StringUtils.containsAny("zzabyycdxx", "za")    = true
1147      * StringUtils.containsAny("zzabyycdxx", "by")    = true
1148      * StringUtils.containsAny("zzabyycdxx", "zy")    = true
1149      * StringUtils.containsAny("zzabyycdxx", "\tx")   = true
1150      * StringUtils.containsAny("zzabyycdxx", "$.#yF") = true
1151      * StringUtils.containsAny("aba", "z")            = false
1152      * </pre>
1153      *
1154      * @param cs          The CharSequence to check, may be null.
1155      * @param searchChars The chars to search for, may be null.
1156      * @return The {@code true} if any of the chars are found, {@code false} if no match or null input.
1157      * @since 2.4
1158      * @since 3.0 Changed signature from containsAny(String, String) to containsAny(CharSequence, CharSequence)
1159      */
1160     public static boolean containsAny(final CharSequence cs, final CharSequence searchChars) {
1161         if (searchChars == null) {
1162             return false;
1163         }
1164         return containsAny(cs, CharSequenceUtils.toCharArray(searchChars));
1165     }
1166 
1167     /**
1168      * Tests if the CharSequence contains any of the CharSequences in the given array.
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      * </pre>
1184      *
1185      * @param cs The CharSequence to check, may be null.
1186      * @param searchCharSequences The array of CharSequences to search for, may be null. Individual CharSequences may be
1187      *        null as well.
1188      * @return {@code true} if any of the search CharSequences are found, {@code false} otherwise.
1189      * @since 3.4
1190      * @deprecated Use {@link Strings#containsAny(CharSequence, CharSequence...) Strings.CS.containsAny(CharSequence, CharSequence...)}.
1191      */
1192     @Deprecated
1193     public static boolean containsAny(final CharSequence cs, final CharSequence... searchCharSequences) {
1194         return Strings.CS.containsAny(cs, searchCharSequences);
1195     }
1196 
1197     /**
1198      * Tests if the CharSequence contains any of the CharSequences in the given array, ignoring case.
1199      *
1200      * <p>
1201      * A {@code null} {@code cs} CharSequence will return {@code false}. A {@code null} or zero length search array will
1202      * return {@code false}.
1203      * </p>
1204      *
1205      * <pre>
1206      * StringUtils.containsAnyIgnoreCase(null, *)            = false
1207      * StringUtils.containsAnyIgnoreCase("", *)              = false
1208      * StringUtils.containsAnyIgnoreCase(*, null)            = false
1209      * StringUtils.containsAnyIgnoreCase(*, [])              = false
1210      * StringUtils.containsAnyIgnoreCase("abcd", "ab", null) = true
1211      * StringUtils.containsAnyIgnoreCase("abcd", "ab", "cd") = true
1212      * StringUtils.containsAnyIgnoreCase("abc", "d", "abc")  = true
1213      * StringUtils.containsAnyIgnoreCase("abc", "D", "ABC")  = true
1214      * StringUtils.containsAnyIgnoreCase("ABC", "d", "abc")  = true
1215      * </pre>
1216      *
1217      * @param cs The CharSequence to check, may be null.
1218      * @param searchCharSequences The array of CharSequences to search for, may be null. Individual CharSequences may be
1219      *        null as well.
1220      * @return {@code true} if any of the search CharSequences are found, {@code false} otherwise
1221      * @since 3.12.0
1222      * @deprecated Use {@link Strings#containsAny(CharSequence, CharSequence...) Strings.CI.containsAny(CharSequence, CharSequence...)}.
1223      */
1224     @Deprecated
1225     public static boolean containsAnyIgnoreCase(final CharSequence cs, final CharSequence... searchCharSequences) {
1226         return Strings.CI.containsAny(cs, searchCharSequences);
1227     }
1228 
1229     /**
1230      * Tests if CharSequence contains a search CharSequence irrespective of case, handling {@code null}. Case-insensitivity is defined as by
1231      * {@link String#equalsIgnoreCase(String)}.
1232      *
1233      * <p>
1234      * A {@code null} CharSequence will return {@code false}.
1235      * </p>
1236      *
1237      * <pre>
1238      * StringUtils.containsIgnoreCase(null, *)    = false
1239      * StringUtils.containsIgnoreCase(*, null)    = false
1240      * StringUtils.containsIgnoreCase("", "")     = true
1241      * StringUtils.containsIgnoreCase("abc", "")  = true
1242      * StringUtils.containsIgnoreCase("abc", "a") = true
1243      * StringUtils.containsIgnoreCase("abc", "z") = false
1244      * StringUtils.containsIgnoreCase("abc", "A") = true
1245      * StringUtils.containsIgnoreCase("abc", "Z") = false
1246      * </pre>
1247      *
1248      * @param str       The CharSequence to check, may be null.
1249      * @param searchStr The CharSequence to find, may be null.
1250      * @return true if the CharSequence contains the search CharSequence irrespective of case or false if not or {@code null} string input.
1251      * @since 3.0 Changed signature from containsIgnoreCase(String, String) to containsIgnoreCase(CharSequence, CharSequence).
1252      * @deprecated Use {@link Strings#contains(CharSequence, CharSequence) Strings.CI.contains(CharSequence, CharSequence)}.
1253      */
1254     @Deprecated
1255     public static boolean containsIgnoreCase(final CharSequence str, final CharSequence searchStr) {
1256         return Strings.CI.contains(str, searchStr);
1257     }
1258 
1259     /**
1260      * Tests that the CharSequence does not contain certain characters.
1261      *
1262      * <p>
1263      * A {@code null} CharSequence will return {@code true}. A {@code null} invalid character array will return {@code true}. An empty CharSequence (length()=0)
1264      * always returns true.
1265      * </p>
1266      *
1267      * <pre>
1268      * StringUtils.containsNone(null, *)               = true
1269      * StringUtils.containsNone(*, null)               = true
1270      * StringUtils.containsNone("", *)                 = true
1271      * StringUtils.containsNone("ab", '')              = true
1272      * StringUtils.containsNone("abab", 'x', 'y', 'z') = true
1273      * StringUtils.containsNone("ab1", 'x', 'y', 'z')  = true
1274      * StringUtils.containsNone("abz", 'x', 'y', 'z')  = false
1275      * </pre>
1276      *
1277      * @param cs          The CharSequence to check, may be null.
1278      * @param searchChars An array of invalid chars, may be null.
1279      * @return true if it contains none of the invalid chars, or is null.
1280      * @since 2.0
1281      * @since 3.0 Changed signature from containsNone(String, char[]) to containsNone(CharSequence, char...)
1282      */
1283     public static boolean containsNone(final CharSequence cs, final char... searchChars) {
1284         if (cs == null || searchChars == null) {
1285             return true;
1286         }
1287         final int csLen = cs.length();
1288         final int csLast = csLen - 1;
1289         final int searchLen = searchChars.length;
1290         final int searchLast = searchLen - 1;
1291         for (int i = 0; i < csLen; i++) {
1292             final char ch = cs.charAt(i);
1293             for (int j = 0; j < searchLen; j++) {
1294                 if (searchChars[j] == ch) {
1295                     if (Character.isHighSurrogate(ch)
1296                             ? j == searchLast || i < csLast && searchChars[j + 1] == cs.charAt(i + 1)
1297                             : j == 0 || !Character.isLowSurrogate(ch) || !Character.isHighSurrogate(searchChars[j - 1]) || i > 0 && searchChars[j - 1] == cs.charAt(i - 1)) {
1298                         return false;
1299                     }
1300                 }
1301             }
1302         }
1303         return true;
1304     }
1305 
1306     /**
1307      * Tests that the CharSequence does not contain certain characters.
1308      *
1309      * <p>
1310      * A {@code null} CharSequence will return {@code true}. A {@code null} invalid character array will return {@code true}. An empty String ("") always
1311      * returns true.
1312      * </p>
1313      *
1314      * <pre>
1315      * StringUtils.containsNone(null, *)       = true
1316      * StringUtils.containsNone(*, null)       = true
1317      * StringUtils.containsNone("", *)         = true
1318      * StringUtils.containsNone("ab", "")      = true
1319      * StringUtils.containsNone("abab", "xyz") = true
1320      * StringUtils.containsNone("ab1", "xyz")  = true
1321      * StringUtils.containsNone("abz", "xyz")  = false
1322      * </pre>
1323      *
1324      * @param cs           The CharSequence to check, may be null.
1325      * @param invalidChars A String of invalid chars, may be null.
1326      * @return true if it contains none of the invalid chars, or is null.
1327      * @since 2.0
1328      * @since 3.0 Changed signature from containsNone(String, String) to containsNone(CharSequence, String)
1329      */
1330     public static boolean containsNone(final CharSequence cs, final String invalidChars) {
1331         if (invalidChars == null) {
1332             return true;
1333         }
1334         return containsNone(cs, invalidChars.toCharArray());
1335     }
1336 
1337     /**
1338      * Tests if the CharSequence contains only certain characters.
1339      *
1340      * <p>
1341      * A {@code null} CharSequence will return {@code false}. A {@code null} valid character array will return {@code false}. An empty CharSequence (length()=0)
1342      * always returns {@code true}.
1343      * </p>
1344      *
1345      * <pre>
1346      * StringUtils.containsOnly(null, *)               = false
1347      * StringUtils.containsOnly(*, null)               = false
1348      * StringUtils.containsOnly("", *)                 = true
1349      * StringUtils.containsOnly("ab", '')              = false
1350      * StringUtils.containsOnly("abab", 'a', 'b', 'c') = true
1351      * StringUtils.containsOnly("ab1", 'a', 'b', 'c')  = false
1352      * StringUtils.containsOnly("abz", 'a', 'b', 'c')  = false
1353      * </pre>
1354      *
1355      * @param cs    The String to check, may be null.
1356      * @param valid An array of valid chars, may be null.
1357      * @return true if it only contains valid chars and is non-null.
1358      * @since 3.0 Changed signature from containsOnly(String, char[]) to containsOnly(CharSequence, char...)
1359      */
1360     public static boolean containsOnly(final CharSequence cs, final char... valid) {
1361         // All these pre-checks are to maintain API with an older version
1362         if (valid == null || cs == null) {
1363             return false;
1364         }
1365         if (isEmpty(cs)) {
1366             return true;
1367         }
1368         if (valid.length == 0) {
1369             return false;
1370         }
1371         return indexOfAnyBut(cs, valid) == INDEX_NOT_FOUND;
1372     }
1373 
1374     /**
1375      * Tests if the CharSequence contains only certain characters.
1376      *
1377      * <p>
1378      * A {@code null} CharSequence will return {@code false}. A {@code null} valid character String will return {@code false}. An empty String (length()=0)
1379      * always returns {@code true}.
1380      * </p>
1381      *
1382      * <pre>
1383      * StringUtils.containsOnly(null, *)       = false
1384      * StringUtils.containsOnly(*, null)       = false
1385      * StringUtils.containsOnly("", *)         = true
1386      * StringUtils.containsOnly("ab", "")      = false
1387      * StringUtils.containsOnly("abab", "abc") = true
1388      * StringUtils.containsOnly("ab1", "abc")  = false
1389      * StringUtils.containsOnly("abz", "abc")  = false
1390      * </pre>
1391      *
1392      * @param cs         The CharSequence to check, may be null.
1393      * @param validChars A String of valid chars, may be null.
1394      * @return true if it only contains valid chars and is non-null.
1395      * @since 2.0
1396      * @since 3.0 Changed signature from containsOnly(String, String) to containsOnly(CharSequence, String)
1397      */
1398     public static boolean containsOnly(final CharSequence cs, final String validChars) {
1399         if (cs == null || validChars == null) {
1400             return false;
1401         }
1402         return containsOnly(cs, validChars.toCharArray());
1403     }
1404 
1405     /**
1406      * Tests whether the given CharSequence contains any whitespace characters.
1407      *
1408      * <p>
1409      * Whitespace is defined by {@link Character#isWhitespace(char)}.
1410      * </p>
1411      *
1412      * <pre>
1413      * StringUtils.containsWhitespace(null)       = false
1414      * StringUtils.containsWhitespace("")         = false
1415      * StringUtils.containsWhitespace("ab")       = false
1416      * StringUtils.containsWhitespace(" ab")      = true
1417      * StringUtils.containsWhitespace("a b")      = true
1418      * StringUtils.containsWhitespace("ab ")      = true
1419      * </pre>
1420      *
1421      * @param seq The CharSequence to check (may be {@code null}).
1422      * @return {@code true} if the CharSequence is not empty and contains at least 1 (breaking) whitespace character.
1423      * @since 3.0
1424      */
1425     public static boolean containsWhitespace(final CharSequence seq) {
1426         if (isEmpty(seq)) {
1427             return false;
1428         }
1429         final int strLen = seq.length();
1430         for (int i = 0; i < strLen; i++) {
1431             if (Character.isWhitespace(seq.charAt(i))) {
1432                 return true;
1433             }
1434         }
1435         return false;
1436     }
1437 
1438     private static void convertRemainingAccentCharacters(final StringBuilder decomposed) {
1439         for (int i = 0; i < decomposed.length(); i++) {
1440             final char charAt = decomposed.charAt(i);
1441             switch (charAt) {
1442             case '\u0141':
1443                 decomposed.setCharAt(i, 'L');
1444                 break;
1445             case '\u0142':
1446                 decomposed.setCharAt(i, 'l');
1447                 break;
1448             // D with stroke
1449             case '\u0110':
1450                 // LATIN CAPITAL LETTER D WITH STROKE
1451                 decomposed.setCharAt(i, 'D');
1452                 break;
1453             case '\u0111':
1454                 // LATIN SMALL LETTER D WITH STROKE
1455                 decomposed.setCharAt(i, 'd');
1456                 break;
1457             // I with bar
1458             case '\u0197':
1459                 decomposed.setCharAt(i, 'I');
1460                 break;
1461             case '\u0268':
1462                 decomposed.setCharAt(i, 'i');
1463                 break;
1464             case '\u1D7B':
1465                 decomposed.setCharAt(i, 'I');
1466                 break;
1467             case '\u1DA4':
1468                 decomposed.setCharAt(i, 'i');
1469                 break;
1470             case '\u1DA7':
1471                 decomposed.setCharAt(i, 'I');
1472                 break;
1473             // U with bar
1474             case '\u0244':
1475                 // LATIN CAPITAL LETTER U BAR
1476                 decomposed.setCharAt(i, 'U');
1477                 break;
1478             case '\u0289':
1479                 // LATIN SMALL LETTER U BAR
1480                 decomposed.setCharAt(i, 'u');
1481                 break;
1482             case '\u1D7E':
1483                 // LATIN SMALL CAPITAL LETTER U WITH STROKE
1484                 decomposed.setCharAt(i, 'U');
1485                 break;
1486             case '\u1DB6':
1487                 // MODIFIER LETTER SMALL U BAR
1488                 decomposed.setCharAt(i, 'u');
1489                 break;
1490             // T with stroke
1491             case '\u0166':
1492                 // LATIN CAPITAL LETTER T WITH STROKE
1493                 decomposed.setCharAt(i, 'T');
1494                 break;
1495             case '\u0167':
1496                 // LATIN SMALL LETTER T WITH STROKE
1497                 decomposed.setCharAt(i, 't');
1498                 break;
1499             default:
1500                 break;
1501             }
1502         }
1503     }
1504 
1505     /**
1506      * Counts how many times the char appears in the given string.
1507      *
1508      * <p>
1509      * A {@code null} or empty ("") String input returns {@code 0}.
1510      * </p>
1511      *
1512      * <pre>
1513      * StringUtils.countMatches(null, *)      = 0
1514      * StringUtils.countMatches("", *)        = 0
1515      * StringUtils.countMatches("abba", '\0') = 0
1516      * StringUtils.countMatches("abba", 'a')  = 2
1517      * StringUtils.countMatches("abba", 'b')  = 2
1518      * StringUtils.countMatches("abba", 'x')  = 0
1519      * </pre>
1520      *
1521      * @param str The CharSequence to check, may be null.
1522      * @param ch  The char to count.
1523      * @return The number of occurrences, 0 if the CharSequence is {@code null}.
1524      * @since 3.4
1525      */
1526     public static int countMatches(final CharSequence str, final char ch) {
1527         if (isEmpty(str)) {
1528             return 0;
1529         }
1530         int count = 0;
1531         // We could also call str.toCharArray() for faster lookups but that would generate more garbage.
1532         for (int i = 0; i < str.length(); i++) {
1533             if (ch == str.charAt(i)) {
1534                 count++;
1535             }
1536         }
1537         return count;
1538     }
1539 
1540     /**
1541      * Counts how many times the substring appears in the larger string. Note that the code only counts non-overlapping matches.
1542      *
1543      * <p>
1544      * A {@code null} or empty ("") String input returns {@code 0}.
1545      * </p>
1546      *
1547      * <pre>
1548      * StringUtils.countMatches(null, *)        = 0
1549      * StringUtils.countMatches("", *)          = 0
1550      * StringUtils.countMatches("abba", null)   = 0
1551      * StringUtils.countMatches("abba", "")     = 0
1552      * StringUtils.countMatches("abba", "a")    = 2
1553      * StringUtils.countMatches("abba", "ab")   = 1
1554      * StringUtils.countMatches("abba", "xxx")  = 0
1555      * StringUtils.countMatches("ababa", "aba") = 1
1556      * </pre>
1557      *
1558      * @param str The CharSequence to check, may be null.
1559      * @param sub The substring to count, may be null.
1560      * @return The number of occurrences, 0 if either CharSequence is {@code null}.
1561      * @since 3.0 Changed signature from countMatches(String, String) to countMatches(CharSequence, CharSequence)
1562      */
1563     public static int countMatches(final CharSequence str, final CharSequence sub) {
1564         if (isEmpty(str) || isEmpty(sub)) {
1565             return 0;
1566         }
1567         int count = 0;
1568         int idx = 0;
1569         while ((idx = CharSequenceUtils.indexOf(str, sub, idx)) != INDEX_NOT_FOUND) {
1570             count++;
1571             idx += sub.length();
1572         }
1573         return count;
1574     }
1575 
1576     /**
1577      * Returns either the passed in CharSequence, or if the CharSequence is {@link #isBlank(CharSequence) blank} (whitespaces, empty ({@code ""}), or
1578      * {@code null}), the value of {@code defaultStr}.
1579      *
1580      * <p>
1581      * Whitespace is defined by {@link Character#isWhitespace(char)}.
1582      * </p>
1583      *
1584      * <pre>
1585      * StringUtils.defaultIfBlank(null, "NULL")  = "NULL"
1586      * StringUtils.defaultIfBlank("", "NULL")    = "NULL"
1587      * StringUtils.defaultIfBlank(" ", "NULL")   = "NULL"
1588      * StringUtils.defaultIfBlank("bat", "NULL") = "bat"
1589      * StringUtils.defaultIfBlank("", null)      = null
1590      * </pre>
1591      *
1592      * @param <T>        the specific kind of CharSequence.
1593      * @param str        The CharSequence to check, may be null.
1594      * @param defaultStr The default CharSequence to return if {@code str} is {@link #isBlank(CharSequence) blank} (whitespaces, empty ({@code ""}), or
1595      *                   {@code null}); may be null.
1596      * @return The passed in CharSequence, or the default.
1597      * @see StringUtils#defaultString(String, String)
1598      * @see #isBlank(CharSequence)
1599      */
1600     public static <T extends CharSequence> T defaultIfBlank(final T str, final T defaultStr) {
1601         return isBlank(str) ? defaultStr : str;
1602     }
1603 
1604     /**
1605      * Returns either the passed in CharSequence, or if the CharSequence is empty or {@code null}, the value of {@code defaultStr}.
1606      *
1607      * <pre>
1608      * StringUtils.defaultIfEmpty(null, "NULL")  = "NULL"
1609      * StringUtils.defaultIfEmpty("", "NULL")    = "NULL"
1610      * StringUtils.defaultIfEmpty(" ", "NULL")   = " "
1611      * StringUtils.defaultIfEmpty("bat", "NULL") = "bat"
1612      * StringUtils.defaultIfEmpty("", null)      = null
1613      * </pre>
1614      *
1615      * @param <T>        the specific kind of CharSequence.
1616      * @param str        The CharSequence to check, may be null.
1617      * @param defaultStr The default CharSequence to return if the input is empty ("") or {@code null}, may be null.
1618      * @return The passed in CharSequence, or the default.
1619      * @see StringUtils#defaultString(String, String)
1620      */
1621     public static <T extends CharSequence> T defaultIfEmpty(final T str, final T defaultStr) {
1622         return isEmpty(str) ? defaultStr : str;
1623     }
1624 
1625     /**
1626      * Returns either the passed in String, or if the String is {@code null}, an empty String ("").
1627      *
1628      * <pre>
1629      * StringUtils.defaultString(null)  = ""
1630      * StringUtils.defaultString("")    = ""
1631      * StringUtils.defaultString("bat") = "bat"
1632      * </pre>
1633      *
1634      * @param str The String to check, may be null.
1635      * @return The passed in String, or the empty String if it was {@code null}.
1636      * @see Objects#toString(Object, String)
1637      * @see String#valueOf(Object)
1638      */
1639     public static String defaultString(final String str) {
1640         return Objects.toString(str, EMPTY);
1641     }
1642 
1643     /**
1644      * Returns either the given String, or if the String is {@code null}, {@code nullDefault}.
1645      *
1646      * <pre>
1647      * StringUtils.defaultString(null, "NULL")  = "NULL"
1648      * StringUtils.defaultString("", "NULL")    = ""
1649      * StringUtils.defaultString("bat", "NULL") = "bat"
1650      * </pre>
1651      * <p>
1652      * Since this is now provided by Java, instead call {@link Objects#toString(Object, String)}:
1653      * </p>
1654      *
1655      * <pre>
1656      * Objects.toString(null, "NULL")  = "NULL"
1657      * Objects.toString("", "NULL")    = ""
1658      * Objects.toString("bat", "NULL") = "bat"
1659      * </pre>
1660      *
1661      * @param str         The String to check, may be null.
1662      * @param nullDefault The default String to return if the input is {@code null}, may be null.
1663      * @return The passed in String, or the default if it was {@code null}.
1664      * @see Objects#toString(Object, String)
1665      * @see String#valueOf(Object)
1666      * @deprecated Use {@link Objects#toString(Object, String)}.
1667      */
1668     @Deprecated
1669     public static String defaultString(final String str, final String nullDefault) {
1670         return Objects.toString(str, nullDefault);
1671     }
1672 
1673     /**
1674      * Deletes all whitespaces from a String as defined by {@link Character#isWhitespace(char)}.
1675      *
1676      * <pre>
1677      * StringUtils.deleteWhitespace(null)         = null
1678      * StringUtils.deleteWhitespace("")           = ""
1679      * StringUtils.deleteWhitespace("abc")        = "abc"
1680      * StringUtils.deleteWhitespace("   ab  c  ") = "abc"
1681      * </pre>
1682      *
1683      * @param str The String to delete whitespace from, may be null.
1684      * @return The String without whitespaces, {@code null} if null String input.
1685      */
1686     public static String deleteWhitespace(final String str) {
1687         if (isEmpty(str)) {
1688             return str;
1689         }
1690         final int sz = str.length();
1691         final char[] chs = new char[sz];
1692         int count = 0;
1693         for (int i = 0; i < sz; i++) {
1694             if (!Character.isWhitespace(str.charAt(i))) {
1695                 chs[count++] = str.charAt(i);
1696             }
1697         }
1698         if (count == sz) {
1699             return str;
1700         }
1701         if (count == 0) {
1702             return EMPTY;
1703         }
1704         return new String(chs, 0, count);
1705     }
1706 
1707     /**
1708      * Compares two Strings, and returns the portion where they differ. More precisely, return the remainder of the second String, starting from where it's
1709      * different from the first. This means that the difference between "abc" and "ab" is the empty String and not "c".
1710      *
1711      * <p>
1712      * For example, {@code difference("i am a machine", "i am a robot") -> "robot"}.
1713      * </p>
1714      *
1715      * <pre>
1716      * StringUtils.difference(null, null)       = null
1717      * StringUtils.difference("", "")           = ""
1718      * StringUtils.difference("", "abc")        = "abc"
1719      * StringUtils.difference("abc", "")        = ""
1720      * StringUtils.difference("abc", "abc")     = ""
1721      * StringUtils.difference("abc", "ab")      = ""
1722      * StringUtils.difference("ab", "abxyz")    = "xyz"
1723      * StringUtils.difference("abcde", "abxyz") = "xyz"
1724      * StringUtils.difference("abcde", "xyz")   = "xyz"
1725      * </pre>
1726      *
1727      * @param str1 The first String, may be null.
1728      * @param str2 The second String, may be null.
1729      * @return The portion of str2 where it differs from str1; returns the empty String if they are equal.
1730      * @see #indexOfDifference(CharSequence,CharSequence)
1731      * @since 2.0
1732      */
1733     public static String difference(final String str1, final String str2) {
1734         if (str1 == null) {
1735             return str2;
1736         }
1737         if (str2 == null) {
1738             return str1;
1739         }
1740         final int at = indexOfDifference(str1, str2);
1741         if (at == INDEX_NOT_FOUND) {
1742             return EMPTY;
1743         }
1744         return str2.substring(at);
1745     }
1746 
1747     /**
1748      * Tests if a CharSequence ends with a specified suffix.
1749      *
1750      * <p>
1751      * {@code null}s are handled without exceptions. Two {@code null} references are considered to be equal. The comparison is case-sensitive.
1752      * </p>
1753      *
1754      * <pre>
1755      * StringUtils.endsWith(null, null)      = true
1756      * StringUtils.endsWith(null, "def")     = false
1757      * StringUtils.endsWith("abcdef", null)  = false
1758      * StringUtils.endsWith("abcdef", "def") = true
1759      * StringUtils.endsWith("ABCDEF", "def") = false
1760      * StringUtils.endsWith("ABCDEF", "cde") = false
1761      * StringUtils.endsWith("ABCDEF", "")    = true
1762      * </pre>
1763      *
1764      * @param str    The CharSequence to check, may be null.
1765      * @param suffix The suffix to find, may be null.
1766      * @return {@code true} if the CharSequence ends with the suffix, case-sensitive, or both {@code null}.
1767      * @see String#endsWith(String)
1768      * @since 2.4
1769      * @since 3.0 Changed signature from endsWith(String, String) to endsWith(CharSequence, CharSequence)
1770      * @deprecated Use {@link Strings#endsWith(CharSequence, CharSequence) Strings.CS.endsWith(CharSequence, CharSequence)}.
1771      */
1772     @Deprecated
1773     public static boolean endsWith(final CharSequence str, final CharSequence suffix) {
1774         return Strings.CS.endsWith(str, suffix);
1775     }
1776 
1777     /**
1778      * Tests if a CharSequence ends with any of the provided case-sensitive suffixes.
1779      *
1780      * <pre>
1781      * StringUtils.endsWithAny(null, null)                  = false
1782      * StringUtils.endsWithAny(null, new String[] {"abc"})  = false
1783      * StringUtils.endsWithAny("abcxyz", null)              = false
1784      * StringUtils.endsWithAny("abcxyz", new String[] {""}) = true
1785      * StringUtils.endsWithAny("abcxyz", new String[] {"xyz"}) = true
1786      * StringUtils.endsWithAny("abcxyz", new String[] {null, "xyz", "abc"}) = true
1787      * StringUtils.endsWithAny("abcXYZ", "def", "XYZ")      = true
1788      * StringUtils.endsWithAny("abcXYZ", "def", "xyz")      = false
1789      * </pre>
1790      *
1791      * @param sequence      The CharSequence to check, may be null.
1792      * @param searchStrings The case-sensitive CharSequences to find, may be empty or contain {@code null}.
1793      * @return {@code true} if the input {@code sequence} is {@code null} AND no {@code searchStrings} are provided, or the input {@code sequence} ends in any
1794      *         of the provided case-sensitive {@code searchStrings}.
1795      * @see StringUtils#endsWith(CharSequence, CharSequence)
1796      * @since 3.0
1797      * @deprecated Use {@link Strings#endsWithAny(CharSequence, CharSequence...) Strings.CS.endsWithAny(CharSequence, CharSequence...)}.
1798      */
1799     @Deprecated
1800     public static boolean endsWithAny(final CharSequence sequence, final CharSequence... searchStrings) {
1801         return Strings.CS.endsWithAny(sequence, searchStrings);
1802     }
1803 
1804     /**
1805      * Case-insensitive check if a CharSequence ends with a specified suffix.
1806      *
1807      * <p>
1808      * {@code null}s are handled without exceptions. Two {@code null} references are considered to be equal. The comparison is case insensitive.
1809      * </p>
1810      *
1811      * <pre>
1812      * StringUtils.endsWithIgnoreCase(null, null)      = true
1813      * StringUtils.endsWithIgnoreCase(null, "def")     = false
1814      * StringUtils.endsWithIgnoreCase("abcdef", null)  = false
1815      * StringUtils.endsWithIgnoreCase("abcdef", "def") = true
1816      * StringUtils.endsWithIgnoreCase("ABCDEF", "def") = true
1817      * StringUtils.endsWithIgnoreCase("ABCDEF", "cde") = false
1818      * </pre>
1819      *
1820      * @param str    The CharSequence to check, may be null
1821      * @param suffix The suffix to find, may be null
1822      * @return {@code true} if the CharSequence ends with the suffix, case-insensitive, or both {@code null}
1823      * @see String#endsWith(String)
1824      * @since 2.4
1825      * @since 3.0 Changed signature from endsWithIgnoreCase(String, String) to endsWithIgnoreCase(CharSequence, CharSequence)
1826      * @deprecated Use {@link Strings#endsWith(CharSequence, CharSequence) Strings.CI.endsWith(CharSequence, CharSequence)}.
1827      */
1828     @Deprecated
1829     public static boolean endsWithIgnoreCase(final CharSequence str, final CharSequence suffix) {
1830         return Strings.CI.endsWith(str, suffix);
1831     }
1832 
1833     /**
1834      * Compares two CharSequences, returning {@code true} if they represent equal sequences of characters.
1835      *
1836      * <p>
1837      * {@code null}s are handled without exceptions. Two {@code null} references are considered to be equal. The comparison is <strong>case-sensitive</strong>.
1838      * </p>
1839      *
1840      * <pre>
1841      * StringUtils.equals(null, null)   = true
1842      * StringUtils.equals(null, "abc")  = false
1843      * StringUtils.equals("abc", null)  = false
1844      * StringUtils.equals("abc", "abc") = true
1845      * StringUtils.equals("abc", "ABC") = false
1846      * </pre>
1847      *
1848      * @param cs1 The first CharSequence, may be {@code null}.
1849      * @param cs2 The second CharSequence, may be {@code null}.
1850      * @return {@code true} if the CharSequences are equal (case-sensitive), or both {@code null}.
1851      * @since 3.0 Changed signature from equals(String, String) to equals(CharSequence, CharSequence)
1852      * @see Object#equals(Object)
1853      * @see #equalsIgnoreCase(CharSequence, CharSequence)
1854      * @deprecated Use {@link Strings#equals(CharSequence, CharSequence) Strings.CS.equals(CharSequence, CharSequence)}.
1855      */
1856     @Deprecated
1857     public static boolean equals(final CharSequence cs1, final CharSequence cs2) {
1858         return Strings.CS.equals(cs1, cs2);
1859     }
1860 
1861     /**
1862      * Compares given {@code string} to a CharSequences vararg of {@code searchStrings}, returning {@code true} if the {@code string} is equal to any of the
1863      * {@code searchStrings}.
1864      *
1865      * <pre>
1866      * StringUtils.equalsAny(null, (CharSequence[]) null) = false
1867      * StringUtils.equalsAny(null, null, null)    = true
1868      * StringUtils.equalsAny(null, "abc", "def")  = false
1869      * StringUtils.equalsAny("abc", null, "def")  = false
1870      * StringUtils.equalsAny("abc", "abc", "def") = true
1871      * StringUtils.equalsAny("abc", "ABC", "DEF") = false
1872      * </pre>
1873      *
1874      * @param string        to compare, may be {@code null}.
1875      * @param searchStrings A vararg of strings, may be {@code null}.
1876      * @return {@code true} if the string is equal (case-sensitive) to any other element of {@code searchStrings}; {@code false} if {@code searchStrings} is
1877      *         null or contains no matches.
1878      * @since 3.5
1879      * @deprecated Use {@link Strings#equalsAny(CharSequence, CharSequence...) Strings.CS.equalsAny(CharSequence, CharSequence...)}.
1880      */
1881     @Deprecated
1882     public static boolean equalsAny(final CharSequence string, final CharSequence... searchStrings) {
1883         return Strings.CS.equalsAny(string, searchStrings);
1884     }
1885 
1886     /**
1887      * Compares given {@code string} to a CharSequences vararg of {@code searchStrings},
1888      * returning {@code true} if the {@code string} is equal to any of the {@code searchStrings}, ignoring case.
1889      *
1890      * <pre>
1891      * StringUtils.equalsAnyIgnoreCase(null, (CharSequence[]) null) = false
1892      * StringUtils.equalsAnyIgnoreCase(null, null, null)    = true
1893      * StringUtils.equalsAnyIgnoreCase(null, "abc", "def")  = false
1894      * StringUtils.equalsAnyIgnoreCase("abc", null, "def")  = false
1895      * StringUtils.equalsAnyIgnoreCase("abc", "abc", "def") = true
1896      * StringUtils.equalsAnyIgnoreCase("abc", "ABC", "DEF") = true
1897      * </pre>
1898      *
1899      * @param string to compare, may be {@code null}.
1900      * @param searchStrings A vararg of strings, may be {@code null}.
1901      * @return {@code true} if the string is equal (case-insensitive) to any other element of {@code searchStrings};
1902      * {@code false} if {@code searchStrings} is null or contains no matches.
1903      * @since 3.5
1904      * @deprecated Use {@link Strings#equalsAny(CharSequence, CharSequence...) Strings.CI.equalsAny(CharSequence, CharSequence...)}.
1905      */
1906     @Deprecated
1907     public static boolean equalsAnyIgnoreCase(final CharSequence string, final CharSequence... searchStrings) {
1908         return Strings.CI.equalsAny(string, searchStrings);
1909     }
1910 
1911     /**
1912      * Compares two CharSequences, returning {@code true} if they represent equal sequences of characters, ignoring case.
1913      *
1914      * <p>
1915      * {@code null}s are handled without exceptions. Two {@code null} references are considered equal. The comparison is <strong>case insensitive</strong>.
1916      * </p>
1917      *
1918      * <pre>
1919      * StringUtils.equalsIgnoreCase(null, null)   = true
1920      * StringUtils.equalsIgnoreCase(null, "abc")  = false
1921      * StringUtils.equalsIgnoreCase("abc", null)  = false
1922      * StringUtils.equalsIgnoreCase("abc", "abc") = true
1923      * StringUtils.equalsIgnoreCase("abc", "ABC") = true
1924      * </pre>
1925      *
1926      * @param cs1 The first CharSequence, may be {@code null}.
1927      * @param cs2 The second CharSequence, may be {@code null}.
1928      * @return {@code true} if the CharSequences are equal (case-insensitive), or both {@code null}.
1929      * @since 3.0 Changed signature from equalsIgnoreCase(String, String) to equalsIgnoreCase(CharSequence, CharSequence)
1930      * @see #equals(CharSequence, CharSequence)
1931      * @deprecated Use {@link Strings#equals(CharSequence, CharSequence) Strings.CI.equals(CharSequence, CharSequence)}.
1932      */
1933     @Deprecated
1934     public static boolean equalsIgnoreCase(final CharSequence cs1, final CharSequence cs2) {
1935         return Strings.CI.equals(cs1, cs2);
1936     }
1937 
1938     /**
1939      * Returns the first value in the array which is not empty (""), {@code null} or whitespace only.
1940      *
1941      * <p>
1942      * Whitespace is defined by {@link Character#isWhitespace(char)}.
1943      * </p>
1944      *
1945      * <p>
1946      * If all values are blank or the array is {@code null} or empty then {@code null} is returned.
1947      * </p>
1948      *
1949      * <pre>
1950      * StringUtils.firstNonBlank(null, null, null)     = null
1951      * StringUtils.firstNonBlank(null, "", " ")        = null
1952      * StringUtils.firstNonBlank("abc")                = "abc"
1953      * StringUtils.firstNonBlank(null, "xyz")          = "xyz"
1954      * StringUtils.firstNonBlank(null, "", " ", "xyz") = "xyz"
1955      * StringUtils.firstNonBlank(null, "xyz", "abc")   = "xyz"
1956      * StringUtils.firstNonBlank()                     = null
1957      * </pre>
1958      *
1959      * @param <T>    the specific kind of CharSequence.
1960      * @param values The values to test, may be {@code null} or empty.
1961      * @return The first value from {@code values} which is not blank, or {@code null} if there are no non-blank values.
1962      * @since 3.8
1963      */
1964     @SafeVarargs
1965     public static <T extends CharSequence> T firstNonBlank(final T... values) {
1966         if (values != null) {
1967             for (final T val : values) {
1968                 if (isNotBlank(val)) {
1969                     return val;
1970                 }
1971             }
1972         }
1973         return null;
1974     }
1975 
1976     /**
1977      * Returns the first value in the array which is not empty.
1978      *
1979      * <p>
1980      * If all values are empty or the array is {@code null} or empty then {@code null} is returned.
1981      * </p>
1982      *
1983      * <pre>
1984      * StringUtils.firstNonEmpty(null, null, null)   = null
1985      * StringUtils.firstNonEmpty(null, null, "")     = null
1986      * StringUtils.firstNonEmpty(null, "", " ")      = " "
1987      * StringUtils.firstNonEmpty("abc")              = "abc"
1988      * StringUtils.firstNonEmpty(null, "xyz")        = "xyz"
1989      * StringUtils.firstNonEmpty("", "xyz")          = "xyz"
1990      * StringUtils.firstNonEmpty(null, "xyz", "abc") = "xyz"
1991      * StringUtils.firstNonEmpty()                   = null
1992      * </pre>
1993      *
1994      * @param <T>    the specific kind of CharSequence.
1995      * @param values The values to test, may be {@code null} or empty.
1996      * @return The first value from {@code values} which is not empty, or {@code null} if there are no non-empty values.
1997      * @since 3.8
1998      */
1999     @SafeVarargs
2000     public static <T extends CharSequence> T firstNonEmpty(final T... values) {
2001         if (values != null) {
2002             for (final T val : values) {
2003                 if (isNotEmpty(val)) {
2004                     return val;
2005                 }
2006             }
2007         }
2008         return null;
2009     }
2010 
2011     /**
2012      * Gets the bytes of the string using {@link String#getBytes(Charset)}, handling {@code null} safely.
2013      *
2014      * @param string input string.
2015      * @param charset The {@link Charset} to encode the {@link String}. If null, then use the default Charset.
2016      * @return The empty byte[] if {@code string} is null, the result of {@link String#getBytes(Charset)} otherwise.
2017      * @see String#getBytes(Charset)
2018      * @since 3.10
2019      */
2020     public static byte[] getBytes(final String string, final Charset charset) {
2021         return string == null ? ArrayUtils.EMPTY_BYTE_ARRAY : string.getBytes(Charsets.toCharset(charset));
2022     }
2023 
2024     /**
2025      * Gets the bytes of the string using {@link String#getBytes(String)}, handling {@code null} safely.
2026      *
2027      * @param string input string.
2028      * @param charset The {@link Charset} name to encode the {@link String}. If null, then use the default Charset.
2029      * @return The empty byte[] if {@code string} is null, the result of {@link String#getBytes(String)} otherwise.
2030      * @throws UnsupportedEncodingException Thrown when the named charset is not supported.
2031      * @see String#getBytes(String)
2032      * @since 3.10
2033      */
2034     public static byte[] getBytes(final String string, final String charset) throws UnsupportedEncodingException {
2035         return string == null ? ArrayUtils.EMPTY_BYTE_ARRAY : string.getBytes(Charsets.toCharsetName(charset));
2036     }
2037 
2038     /**
2039      * Gets the initial sequence of characters common to all strings in the array.
2040      *
2041      * <p>
2042      * For example, {@code getCommonPrefix("i am a machine", "i am a robot") -&gt; "i am a "}
2043      * </p>
2044      *
2045      * <pre>
2046      * StringUtils.getCommonPrefix(null)                             = ""
2047      * StringUtils.getCommonPrefix(new String[] {})                  = ""
2048      * StringUtils.getCommonPrefix(new String[] {"abc"})             = "abc"
2049      * StringUtils.getCommonPrefix(new String[] {null, null})        = ""
2050      * StringUtils.getCommonPrefix(new String[] {"", ""})            = ""
2051      * StringUtils.getCommonPrefix(new String[] {"", null})          = ""
2052      * StringUtils.getCommonPrefix(new String[] {"abc", null, null}) = ""
2053      * StringUtils.getCommonPrefix(new String[] {null, null, "abc"}) = ""
2054      * StringUtils.getCommonPrefix(new String[] {"", "abc"})         = ""
2055      * StringUtils.getCommonPrefix(new String[] {"abc", ""})         = ""
2056      * StringUtils.getCommonPrefix(new String[] {"abc", "abc"})      = "abc"
2057      * StringUtils.getCommonPrefix(new String[] {"abc", "a"})        = "a"
2058      * StringUtils.getCommonPrefix(new String[] {"ab", "abxyz"})     = "ab"
2059      * StringUtils.getCommonPrefix(new String[] {"abcde", "abxyz"})  = "ab"
2060      * StringUtils.getCommonPrefix(new String[] {"abcde", "xyz"})    = ""
2061      * StringUtils.getCommonPrefix(new String[] {"xyz", "abcde"})    = ""
2062      * StringUtils.getCommonPrefix(new String[] {"i am a machine", "i am a robot"}) = "i am a "
2063      * </pre>
2064      *
2065      * @param strs array of String objects, entries may be null.
2066      * @return The initial sequence of characters that are common to all Strings in the array; empty String if the array is null, the elements are all null or
2067      *         if there is no common prefix.
2068      * @since 2.4
2069      */
2070     public static String getCommonPrefix(final String... strs) {
2071         if (ArrayUtils.isEmpty(strs)) {
2072             return EMPTY;
2073         }
2074         final int smallestIndexOfDiff = indexOfDifference(strs);
2075         if (smallestIndexOfDiff == INDEX_NOT_FOUND) {
2076             // all strings were identical
2077             if (strs[0] == null) {
2078                 return EMPTY;
2079             }
2080             return strs[0];
2081         }
2082         if (smallestIndexOfDiff == 0) {
2083             // there were no common initial characters
2084             return EMPTY;
2085         }
2086         // we found a common initial character sequence
2087         return strs[0].substring(0, smallestIndexOfDiff);
2088     }
2089 
2090     /**
2091      * Gets the Unicode digits in {@code str}, concatenated in their original order.
2092      *
2093      * <p>
2094      * An empty ("") String will be returned if no digits are found in {@code str}.
2095      * </p>
2096      *
2097      * <pre>
2098      * StringUtils.getDigits(null)                 = null
2099      * StringUtils.getDigits("")                   = ""
2100      * StringUtils.getDigits("abc")                = ""
2101      * StringUtils.getDigits("1000$")              = "1000"
2102      * StringUtils.getDigits("1123~45")            = "112345"
2103      * StringUtils.getDigits("(541) 754-3010")     = "5417543010"
2104      * StringUtils.getDigits("\u0967\u0968\u0969") = "\u0967\u0968\u0969"
2105      * </pre>
2106      *
2107      * @param str The String to extract digits from, may be null.
2108      * @return String with only digits, or an empty ("") String if no digits are found, or {@code null} String if {@code str} is null.
2109      * @since 3.6
2110      */
2111     public static String getDigits(final String str) {
2112         if (isEmpty(str)) {
2113             return str;
2114         }
2115         final int len = str.length();
2116         final char[] buffer = new char[len];
2117         int count = 0;
2118 
2119         for (int i = 0; i < len;) {
2120             final int codePoint = str.codePointAt(i);
2121             if (Character.isDigit(codePoint)) {
2122                 count += Character.toChars(codePoint, buffer, count);
2123             }
2124             i += Character.charCount(codePoint);
2125         }
2126         return new String(buffer, 0, count);
2127     }
2128 
2129     /**
2130      * Gets the Fuzzy Distance which indicates the similarity score between two Strings.
2131      *
2132      * <p>
2133      * This string matching algorithm is similar to the algorithms of editors such as Sublime Text, TextMate, Atom and others. One point is given for every
2134      * matched character. Subsequent matches yield two bonus points. A higher score indicates a higher similarity.
2135      * </p>
2136      *
2137      * <pre>
2138      * StringUtils.getFuzzyDistance(null, null, null)                                    = Throws {@link IllegalArgumentException}
2139      * StringUtils.getFuzzyDistance("", "", Locale.ENGLISH)                              = 0
2140      * StringUtils.getFuzzyDistance("Workshop", "b", Locale.ENGLISH)                     = 0
2141      * StringUtils.getFuzzyDistance("Room", "o", Locale.ENGLISH)                         = 1
2142      * StringUtils.getFuzzyDistance("Workshop", "w", Locale.ENGLISH)                     = 1
2143      * StringUtils.getFuzzyDistance("Workshop", "ws", Locale.ENGLISH)                    = 2
2144      * StringUtils.getFuzzyDistance("Workshop", "wo", Locale.ENGLISH)                    = 4
2145      * StringUtils.getFuzzyDistance("Apache Software Foundation", "asf", Locale.ENGLISH) = 3
2146      * </pre>
2147      *
2148      * @param term   A full term that should be matched against, must not be null.
2149      * @param query  The query that will be matched against a term, must not be null.
2150      * @param locale This string matching logic is case-insensitive. A locale is necessary to normalize both Strings to lower case.
2151      * @return result score.
2152      * @throws IllegalArgumentException Thrown if either String input {@code null} or Locale input {@code null}.
2153      * @since 3.4
2154      * @deprecated As of 3.6, use Apache Commons Text
2155      *             <a href="https://commons.apache.org/proper/commons-text/javadocs/api-release/org/apache/commons/text/similarity/FuzzyScore.html">
2156      *             FuzzyScore</a> instead.
2157      */
2158     @Deprecated
2159     public static int getFuzzyDistance(final CharSequence term, final CharSequence query, final Locale locale) {
2160         if (term == null || query == null) {
2161             throw new IllegalArgumentException("Strings must not be null");
2162         }
2163         if (locale == null) {
2164             throw new IllegalArgumentException("Locale must not be null");
2165         }
2166         // fuzzy logic is case-insensitive. We normalize the Strings to lower
2167         // case right from the start. Turning characters to lower case
2168         // via Character.toLowerCase(char) is unfortunately insufficient
2169         // as it does not accept a locale.
2170         final String termLowerCase = term.toString().toLowerCase(locale);
2171         final String queryLowerCase = query.toString().toLowerCase(locale);
2172         // the resulting score
2173         int score = 0;
2174         // the position in the term which will be scanned next for potential
2175         // query character matches
2176         int termIndex = 0;
2177         // index of the previously matched character in the term
2178         int previousMatchingCharacterIndex = Integer.MIN_VALUE;
2179         for (int queryIndex = 0; queryIndex < queryLowerCase.length(); queryIndex++) {
2180             final char queryChar = queryLowerCase.charAt(queryIndex);
2181             boolean termCharacterMatchFound = false;
2182             for (; termIndex < termLowerCase.length() && !termCharacterMatchFound; termIndex++) {
2183                 final char termChar = termLowerCase.charAt(termIndex);
2184                 if (queryChar == termChar) {
2185                     // simple character matches result in one point
2186                     score++;
2187                     // subsequent character matches further improve
2188                     // the score.
2189                     if (previousMatchingCharacterIndex + 1 == termIndex) {
2190                         score += 2;
2191                     }
2192                     previousMatchingCharacterIndex = termIndex;
2193                     // we can leave the nested loop. Every character in the
2194                     // query can match at most one character in the term.
2195                     termCharacterMatchFound = true;
2196                 }
2197             }
2198         }
2199         return score;
2200     }
2201 
2202     /**
2203      * Gets either the passed in CharSequence, or if the CharSequence is {@link #isBlank(CharSequence) blank} (whitespaces, empty ({@code ""}), or
2204      * {@code null}), the value supplied by {@code defaultStrSupplier}.
2205      *
2206      * <p>
2207      * Whitespace is defined by {@link Character#isWhitespace(char)}.
2208      * </p>
2209      *
2210      * <p>
2211      * The caller is responsible for thread safety and exception handling for the default value supplier.
2212      * </p>
2213      *
2214      * <pre>
2215      * {@code
2216      * StringUtils.getIfBlank(null, () -> "NULL")   = "NULL"
2217      * StringUtils.getIfBlank("", () -> "NULL")     = "NULL"
2218      * StringUtils.getIfBlank(" ", () -> "NULL")    = "NULL"
2219      * StringUtils.getIfBlank("bat", () -> "NULL")  = "bat"
2220      * StringUtils.getIfBlank("", () -> null)       = null
2221      * StringUtils.getIfBlank("", null)             = null
2222      * }</pre>
2223      *
2224      * @param <T>             the specific kind of CharSequence.
2225      * @param str             The CharSequence to check, may be null.
2226      * @param defaultSupplier The supplier of default CharSequence to return if the input is {@link #isBlank(CharSequence) blank} (whitespaces, empty
2227      *                        ({@code ""}), or {@code null}); may be null.
2228      * @return The passed in CharSequence, or the default
2229      * @see StringUtils#defaultString(String, String)
2230      * @see #isBlank(CharSequence)
2231      * @since 3.10
2232      */
2233     public static <T extends CharSequence> T getIfBlank(final T str, final Supplier<T> defaultSupplier) {
2234         return isBlank(str) ? Suppliers.get(defaultSupplier) : str;
2235     }
2236 
2237     /**
2238      * Gets either the passed in CharSequence, or if the CharSequence is empty or {@code null}, the value supplied by {@code defaultStrSupplier}.
2239      *
2240      * <p>
2241      * The caller is responsible for thread safety and exception handling for the default value supplier.
2242      * </p>
2243      *
2244      * <pre>
2245      * {@code
2246      * StringUtils.getIfEmpty(null, () -> "NULL")    = "NULL"
2247      * StringUtils.getIfEmpty("", () -> "NULL")      = "NULL"
2248      * StringUtils.getIfEmpty(" ", () -> "NULL")     = " "
2249      * StringUtils.getIfEmpty("bat", () -> "NULL")   = "bat"
2250      * StringUtils.getIfEmpty("", () -> null)        = null
2251      * StringUtils.getIfEmpty("", null)              = null
2252      * }
2253      * </pre>
2254      *
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 if the input is empty ("") or {@code null}, may be null.
2258      * @return The passed in CharSequence, or the default.
2259      * @see StringUtils#defaultString(String, String)
2260      * @since 3.10
2261      */
2262     public static <T extends CharSequence> T getIfEmpty(final T str, final Supplier<T> defaultSupplier) {
2263         return isEmpty(str) ? Suppliers.get(defaultSupplier) : str;
2264     }
2265 
2266     /**
2267      * Gets the Jaro Winkler Distance which indicates the similarity score between two Strings.
2268      *
2269      * <p>
2270      * The Jaro measure is the weighted sum of percentage of matched characters from each file and transposed characters. Winkler increased this measure for
2271      * matching initial characters.
2272      * </p>
2273      *
2274      * <p>
2275      * This implementation is based on the Jaro Winkler similarity algorithm from
2276      * <a href="https://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance">https://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance</a>.
2277      * </p>
2278      *
2279      * <pre>
2280      * StringUtils.getJaroWinklerDistance(null, null)          = Throws {@link IllegalArgumentException}
2281      * StringUtils.getJaroWinklerDistance("", "")              = 0.0
2282      * StringUtils.getJaroWinklerDistance("", "a")             = 0.0
2283      * StringUtils.getJaroWinklerDistance("aaapppp", "")       = 0.0
2284      * StringUtils.getJaroWinklerDistance("frog", "fog")       = 0.93
2285      * StringUtils.getJaroWinklerDistance("fly", "ant")        = 0.0
2286      * StringUtils.getJaroWinklerDistance("elephant", "hippo") = 0.44
2287      * StringUtils.getJaroWinklerDistance("hippo", "elephant") = 0.44
2288      * StringUtils.getJaroWinklerDistance("hippo", "zzzzzzzz") = 0.0
2289      * StringUtils.getJaroWinklerDistance("hello", "hallo")    = 0.88
2290      * StringUtils.getJaroWinklerDistance("ABC Corporation", "ABC Corp") = 0.93
2291      * StringUtils.getJaroWinklerDistance("D N H Enterprises Inc", "D &amp; H Enterprises, Inc.") = 0.95
2292      * StringUtils.getJaroWinklerDistance("My Gym Children's Fitness Center", "My Gym. Childrens Fitness") = 0.92
2293      * StringUtils.getJaroWinklerDistance("PENNSYLVANIA", "PENNCISYLVNIA") = 0.88
2294      * </pre>
2295      *
2296      * @param first  The first String, must not be null.
2297      * @param second The second String, must not be null.
2298      * @return result distance.
2299      * @throws IllegalArgumentException Thrown if either String input {@code null}.
2300      * @since 3.3
2301      * @deprecated As of 3.6, use Apache Commons Text
2302      *             <a href="https://commons.apache.org/proper/commons-text/javadocs/api-release/org/apache/commons/text/similarity/JaroWinklerDistance.html">
2303      *             JaroWinklerDistance</a> instead.
2304      */
2305     @Deprecated
2306     public static double getJaroWinklerDistance(final CharSequence first, final CharSequence second) {
2307         final double DEFAULT_SCALING_FACTOR = 0.1;
2308 
2309         if (first == null || second == null) {
2310             throw new IllegalArgumentException("Strings must not be null");
2311         }
2312 
2313         final int[] mtp = matches(first, second);
2314         final double m = mtp[0];
2315         if (m == 0) {
2316             return 0D;
2317         }
2318         final double j = (m / first.length() + m / second.length() + (m - mtp[1]) / m) / 3;
2319         final double jw = j < 0.7D ? j : j + Math.min(DEFAULT_SCALING_FACTOR, 1D / mtp[3]) * mtp[2] * (1D - j);
2320         return Math.round(jw * 100.0D) / 100.0D;
2321     }
2322 
2323     /**
2324      * Gets the Levenshtein distance between two Strings.
2325      *
2326      * <p>
2327      * This is the number of changes needed to change one String into another, where each change is a single character modification (deletion, insertion or
2328      * substitution).
2329      * </p>
2330      *
2331      * <p>
2332      * The implementation uses a single-dimensional array of length s.length() + 1. See
2333      * <a href="https://blog.softwx.net/2014/12/optimizing-levenshtein-algorithm-in-c.html">
2334      * https://blog.softwx.net/2014/12/optimizing-levenshtein-algorithm-in-c.html</a> for details.
2335      * </p>
2336      *
2337      * <pre>
2338      * StringUtils.getLevenshteinDistance(null, *)             = Throws {@link IllegalArgumentException}
2339      * StringUtils.getLevenshteinDistance(*, null)             = Throws {@link IllegalArgumentException}
2340      * StringUtils.getLevenshteinDistance("", "")              = 0
2341      * StringUtils.getLevenshteinDistance("", "a")             = 1
2342      * StringUtils.getLevenshteinDistance("aaapppp", "")       = 7
2343      * StringUtils.getLevenshteinDistance("frog", "fog")       = 1
2344      * StringUtils.getLevenshteinDistance("fly", "ant")        = 3
2345      * StringUtils.getLevenshteinDistance("elephant", "hippo") = 7
2346      * StringUtils.getLevenshteinDistance("hippo", "elephant") = 7
2347      * StringUtils.getLevenshteinDistance("hippo", "zzzzzzzz") = 8
2348      * StringUtils.getLevenshteinDistance("hello", "hallo")    = 1
2349      * </pre>
2350      *
2351      * @param s The first String, must not be null.
2352      * @param t The second String, must not be null.
2353      * @return result distance.
2354      * @throws IllegalArgumentException Thrown if either String input {@code null}.
2355      * @since 3.0 Changed signature from getLevenshteinDistance(String, String) to getLevenshteinDistance(CharSequence, CharSequence)
2356      * @deprecated As of 3.6, use Apache Commons Text
2357      *             <a href="https://commons.apache.org/proper/commons-text/javadocs/api-release/org/apache/commons/text/similarity/LevenshteinDistance.html">
2358      *             LevenshteinDistance</a> instead.
2359      */
2360     @Deprecated
2361     public static int getLevenshteinDistance(CharSequence s, CharSequence t) {
2362         if (s == null || t == null) {
2363             throw new IllegalArgumentException("Strings must not be null");
2364         }
2365 
2366         int n = s.length();
2367         int m = t.length();
2368 
2369         if (n == 0) {
2370             return m;
2371         }
2372         if (m == 0) {
2373             return n;
2374         }
2375 
2376         if (n > m) {
2377             // swap the input strings to consume less memory
2378             final CharSequence tmp = s;
2379             s = t;
2380             t = tmp;
2381             n = m;
2382             m = t.length();
2383         }
2384 
2385         final int[] p = new int[n + 1];
2386         // indexes into strings s and t
2387         int i; // iterates through s
2388         int j; // iterates through t
2389         int upperleft;
2390         int upper;
2391 
2392         char jOfT; // jth character of t
2393         int cost;
2394 
2395         for (i = 0; i <= n; i++) {
2396             p[i] = i;
2397         }
2398 
2399         for (j = 1; j <= m; j++) {
2400             upperleft = p[0];
2401             jOfT = t.charAt(j - 1);
2402             p[0] = j;
2403 
2404             for (i = 1; i <= n; i++) {
2405                 upper = p[i];
2406                 cost = s.charAt(i - 1) == jOfT ? 0 : 1;
2407                 // minimum of cell to the left+1, to the top+1, diagonally left and up +cost
2408                 p[i] = Math.min(Math.min(p[i - 1] + 1, p[i] + 1), upperleft + cost);
2409                 upperleft = upper;
2410             }
2411         }
2412 
2413         return p[n];
2414     }
2415 
2416     /**
2417      * Gets the Levenshtein distance between two Strings if it's less than or equal to a given threshold.
2418      *
2419      * <p>
2420      * This is the number of changes needed to change one String into another, where each change is a single character modification (deletion, insertion or
2421      * substitution).
2422      * </p>
2423      *
2424      * <p>
2425      * This implementation follows from Algorithms on Strings, Trees and Sequences by Dan Gusfield and Chas Emerick's implementation of the Levenshtein distance
2426      * algorithm.
2427      * </p>
2428      *
2429      * <pre>
2430      * StringUtils.getLevenshteinDistance(null, *, *)             = Throws {@link IllegalArgumentException}
2431      * StringUtils.getLevenshteinDistance(*, null, *)             = Throws {@link IllegalArgumentException}
2432      * StringUtils.getLevenshteinDistance(*, *, -1)               = Throws {@link IllegalArgumentException}
2433      * StringUtils.getLevenshteinDistance("", "", 0)              = 0
2434      * StringUtils.getLevenshteinDistance("aaapppp", "", 8)       = 7
2435      * StringUtils.getLevenshteinDistance("aaapppp", "", 7)       = 7
2436      * StringUtils.getLevenshteinDistance("aaapppp", "", 6))      = -1
2437      * StringUtils.getLevenshteinDistance("elephant", "hippo", 7) = 7
2438      * StringUtils.getLevenshteinDistance("elephant", "hippo", 6) = -1
2439      * StringUtils.getLevenshteinDistance("hippo", "elephant", 7) = 7
2440      * StringUtils.getLevenshteinDistance("hippo", "elephant", 6) = -1
2441      * </pre>
2442      *
2443      * @param s         The first String, must not be null.
2444      * @param t         The second String, must not be null.
2445      * @param threshold The target threshold, must not be negative.
2446      * @return result distance, or {@code -1} if the distance would be greater than the threshold.
2447      * @throws IllegalArgumentException Thrown if either String input {@code null} or negative threshold.
2448      * @deprecated As of 3.6, use Apache Commons Text
2449      *             <a href="https://commons.apache.org/proper/commons-text/javadocs/api-release/org/apache/commons/text/similarity/LevenshteinDistance.html">
2450      *             LevenshteinDistance</a> instead.
2451      */
2452     @Deprecated
2453     public static int getLevenshteinDistance(CharSequence s, CharSequence t, final int threshold) {
2454         if (s == null || t == null) {
2455             throw new IllegalArgumentException("Strings must not be null");
2456         }
2457         if (threshold < 0) {
2458             throw new IllegalArgumentException("Threshold must not be negative");
2459         }
2460 
2461         /*
2462         This implementation only computes the distance if it's less than or equal to the
2463         threshold value, returning -1 if it's greater.  The advantage is performance: unbounded
2464         distance is O(nm), but a bound of k allows us to reduce it to O(km) time by only
2465         computing a diagonal stripe of width 2k + 1 of the cost table.
2466         It is also possible to use this to compute the unbounded Levenshtein distance by starting
2467         the threshold at 1 and doubling each time until the distance is found; this is O(dm), where
2468         d is the distance.
2469 
2470         One subtlety comes from needing to ignore entries on the border of our stripe
2471         for example,
2472         p[] = |#|#|#|*
2473         d[] =  *|#|#|#|
2474         We must ignore the entry to the left of the leftmost member
2475         We must ignore the entry above the rightmost member
2476 
2477         Another subtlety comes from our stripe running off the matrix if the strings aren't
2478         of the same size.  Since string s is always swapped to be the shorter of the two,
2479         the stripe will always run off to the upper right instead of the lower left of the matrix.
2480 
2481         As a concrete example, suppose s is of length 5, t is of length 7, and our threshold is 1.
2482         In this case we're going to walk a stripe of length 3.  The matrix would look like so:
2483 
2484            1 2 3 4 5
2485         1 |#|#| | | |
2486         2 |#|#|#| | |
2487         3 | |#|#|#| |
2488         4 | | |#|#|#|
2489         5 | | | |#|#|
2490         6 | | | | |#|
2491         7 | | | | | |
2492 
2493         Note how the stripe leads off the table as there is no possible way to turn a string of length 5
2494         into one of length 7 in edit distance of 1.
2495 
2496         Additionally, this implementation decreases memory usage by using two
2497         single-dimensional arrays and swapping them back and forth instead of allocating
2498         an entire n by m matrix.  This requires a few minor changes, such as immediately returning
2499         when it's detected that the stripe has run off the matrix and initially filling the arrays with
2500         large values so that entries we don't compute are ignored.
2501 
2502         See Algorithms on Strings, Trees and Sequences by Dan Gusfield for some discussion.
2503          */
2504 
2505         int n = s.length(); // length of s
2506         int m = t.length(); // length of t
2507 
2508         // if one string is empty, the edit distance is necessarily the length of the other
2509         if (n == 0) {
2510             return m <= threshold ? m : -1;
2511         }
2512         if (m == 0) {
2513             return n <= threshold ? n : -1;
2514         }
2515         if (Math.abs(n - m) > threshold) {
2516             // no need to calculate the distance if the length difference is greater than the threshold
2517             return -1;
2518         }
2519 
2520         if (n > m) {
2521             // swap the two strings to consume less memory
2522             final CharSequence tmp = s;
2523             s = t;
2524             t = tmp;
2525             n = m;
2526             m = t.length();
2527         }
2528 
2529         int[] p = new int[n + 1]; // 'previous' cost array, horizontally
2530         int[] d = new int[n + 1]; // cost array, horizontally
2531         int[] tmp; // placeholder to assist in swapping p and d
2532 
2533         // fill in starting table values
2534         final int boundary = Math.min(n, threshold) + 1;
2535         for (int i = 0; i < boundary; i++) {
2536             p[i] = i;
2537         }
2538         // these fills ensure that the value above the rightmost entry of our
2539         // stripe will be ignored in following loop iterations
2540         Arrays.fill(p, boundary, p.length, Integer.MAX_VALUE);
2541         Arrays.fill(d, Integer.MAX_VALUE);
2542 
2543         // iterates through t
2544         for (int j = 1; j <= m; j++) {
2545             final char jOfT = t.charAt(j - 1); // jth character of t
2546             d[0] = j;
2547 
2548             // compute stripe indices, constrain to array size
2549             final int min = Math.max(1, j - threshold);
2550             final int max = j > Integer.MAX_VALUE - threshold ? n : Math.min(n, j + threshold);
2551 
2552             // the stripe may lead off of the table if s and t are of different sizes
2553             if (min > max) {
2554                 return -1;
2555             }
2556 
2557             // ignore entry left of leftmost
2558             if (min > 1) {
2559                 d[min - 1] = Integer.MAX_VALUE;
2560             }
2561 
2562             // iterates through [min, max] in s
2563             for (int i = min; i <= max; i++) {
2564                 if (s.charAt(i - 1) == jOfT) {
2565                     // diagonally left and up
2566                     d[i] = p[i - 1];
2567                 } else {
2568                     // 1 + minimum of cell to the left, to the top, diagonally left and up
2569                     d[i] = 1 + Math.min(Math.min(d[i - 1], p[i]), p[i - 1]);
2570                 }
2571             }
2572 
2573             // copy current distance counts to 'previous row' distance counts
2574             tmp = p;
2575             p = d;
2576             d = tmp;
2577         }
2578 
2579         // if p[n] is greater than the threshold, there's no guarantee on it being the correct
2580         // distance
2581         if (p[n] <= threshold) {
2582             return p[n];
2583         }
2584         return -1;
2585     }
2586 
2587     /**
2588      * Finds the first index within a CharSequence, handling {@code null}. This method uses {@link String#indexOf(String, int)} if possible.
2589      *
2590      * <p>
2591      * A {@code null} CharSequence will return {@code -1}.
2592      * </p>
2593      *
2594      * <pre>
2595      * StringUtils.indexOf(null, *)          = -1
2596      * StringUtils.indexOf(*, null)          = -1
2597      * StringUtils.indexOf("", "")           = 0
2598      * StringUtils.indexOf("", *)            = -1 (except when * = "")
2599      * StringUtils.indexOf("aabaabaa", "a")  = 0
2600      * StringUtils.indexOf("aabaabaa", "b")  = 2
2601      * StringUtils.indexOf("aabaabaa", "ab") = 1
2602      * StringUtils.indexOf("aabaabaa", "")   = 0
2603      * </pre>
2604      *
2605      * @param seq       The CharSequence to check, may be null.
2606      * @param searchSeq The CharSequence to find, may be null.
2607      * @return The first index of the search CharSequence, -1 if no match or {@code null} string input.
2608      * @since 2.0
2609      * @since 3.0 Changed signature from indexOf(String, String) to indexOf(CharSequence, CharSequence)
2610      * @deprecated Use {@link Strings#indexOf(CharSequence, CharSequence) Strings.CS.indexOf(CharSequence, CharSequence)}.
2611      */
2612     @Deprecated
2613     public static int indexOf(final CharSequence seq, final CharSequence searchSeq) {
2614         return Strings.CS.indexOf(seq, searchSeq);
2615     }
2616 
2617     /**
2618      * Finds the first index within a CharSequence, handling {@code null}. This method uses {@link String#indexOf(String, int)} if possible.
2619      *
2620      * <p>
2621      * A {@code null} CharSequence will return {@code -1}. A negative start position is treated as zero. An empty ("") search CharSequence always matches. A
2622      * start position greater than the string length only matches an empty search CharSequence.
2623      * </p>
2624      *
2625      * <pre>
2626      * StringUtils.indexOf(null, *, *)          = -1
2627      * StringUtils.indexOf(*, null, *)          = -1
2628      * StringUtils.indexOf("", "", 0)           = 0
2629      * StringUtils.indexOf("", *, 0)            = -1 (except when * = "")
2630      * StringUtils.indexOf("aabaabaa", "a", 0)  = 0
2631      * StringUtils.indexOf("aabaabaa", "b", 0)  = 2
2632      * StringUtils.indexOf("aabaabaa", "ab", 0) = 1
2633      * StringUtils.indexOf("aabaabaa", "b", 3)  = 5
2634      * StringUtils.indexOf("aabaabaa", "b", 9)  = -1
2635      * StringUtils.indexOf("aabaabaa", "b", -1) = 2
2636      * StringUtils.indexOf("aabaabaa", "", 2)   = 2
2637      * StringUtils.indexOf("abc", "", 9)        = 3
2638      * </pre>
2639      *
2640      * @param seq       The CharSequence to check, may be null.
2641      * @param searchSeq The CharSequence to find, may be null.
2642      * @param startPos  The start position, negative treated as zero.
2643      * @return The first index of the search CharSequence (always &ge; startPos), -1 if no match or {@code null} string input.
2644      * @since 2.0
2645      * @since 3.0 Changed signature from indexOf(String, String, int) to indexOf(CharSequence, CharSequence, int)
2646      * @deprecated Use {@link Strings#indexOf(CharSequence, CharSequence, int) Strings.CS.indexOf(CharSequence, CharSequence, int)}.
2647      */
2648     @Deprecated
2649     public static int indexOf(final CharSequence seq, final CharSequence searchSeq, final int startPos) {
2650         return Strings.CS.indexOf(seq, searchSeq, startPos);
2651     }
2652 
2653     /**
2654      * Returns the index within {@code seq} of the first occurrence of the specified character. If a character with value {@code searchChar} occurs in the
2655      * character sequence represented by {@code seq} {@link CharSequence} object, then the index (in Unicode code units) of the first such occurrence is
2656      * returned. For values of {@code searchChar} in the range from 0 to 0xFFFF (inclusive), this is the smallest value <em>k</em> such that:
2657      *
2658      * <pre>
2659      * this.charAt(<em>k</em>) == searchChar
2660      * </pre>
2661      *
2662      * <p>
2663      * is true. For other values of {@code searchChar}, it is the smallest value <em>k</em> such that:
2664      * </p>
2665      *
2666      * <pre>
2667      * this.codePointAt(<em>k</em>) == searchChar
2668      * </pre>
2669      *
2670      * <p>
2671      * is true. In either case, if no such character occurs in {@code seq}, then {@code INDEX_NOT_FOUND (-1)} is returned.
2672      * </p>
2673      *
2674      * <p>
2675      * Furthermore, a {@code null} or empty ("") CharSequence will return {@code INDEX_NOT_FOUND (-1)}.
2676      * </p>
2677      *
2678      * <pre>
2679      * StringUtils.indexOf(null, *)         = -1
2680      * StringUtils.indexOf("", *)           = -1
2681      * StringUtils.indexOf("aabaabaa", 'a') = 0
2682      * StringUtils.indexOf("aabaabaa", 'b') = 2
2683      * StringUtils.indexOf("aaaaaaaa", 'Z') = -1
2684      * </pre>
2685      *
2686      * @param seq        The CharSequence to check, may be null.
2687      * @param searchChar The character to find.
2688      * @return The first index of the search character, -1 if no match or {@code null} string input.
2689      * @since 2.0
2690      * @since 3.0 Changed signature from indexOf(String, int) to indexOf(CharSequence, int)
2691      * @since 3.6 Updated {@link CharSequenceUtils} call to behave more like {@link String}
2692      */
2693     public static int indexOf(final CharSequence seq, final int searchChar) {
2694         if (isEmpty(seq)) {
2695             return INDEX_NOT_FOUND;
2696         }
2697         return CharSequenceUtils.indexOf(seq, searchChar, 0);
2698     }
2699 
2700     /**
2701      * Returns the index within {@code seq} of the first occurrence of the specified character, starting the search at the specified index.
2702      * <p>
2703      * If a character with value {@code searchChar} occurs in the character sequence represented by the {@code seq} {@link CharSequence} object at an index no
2704      * smaller than {@code startPos}, then the index of the first such occurrence is returned. For values of {@code searchChar} in the range from 0 to 0xFFFF
2705      * (inclusive), this is the smallest value <em>k</em> such that:
2706      * </p>
2707      *
2708      * <pre>
2709      * (this.charAt(<em>k</em>) == searchChar) &amp;&amp; (<em>k</em> &gt;= startPos)
2710      * </pre>
2711      *
2712      * <p>
2713      * is true. For other values of {@code searchChar}, it is the smallest value <em>k</em> such that:
2714      * </p>
2715      *
2716      * <pre>
2717      * (this.codePointAt(<em>k</em>) == searchChar) &amp;&amp; (<em>k</em> &gt;= startPos)
2718      * </pre>
2719      *
2720      * <p>
2721      * is true. In either case, if no such character occurs in {@code seq} at or after position {@code startPos}, then {@code -1} is returned.
2722      * </p>
2723      *
2724      * <p>
2725      * There is no restriction on the value of {@code startPos}. If it is negative, it has the same effect as if it were zero: this entire string may be
2726      * searched. If it is greater than the length of this string, it has the same effect as if it were equal to the length of this string:
2727      * {@code (INDEX_NOT_FOUND) -1} is returned. Furthermore, a {@code null} or empty ("") CharSequence will return {@code (INDEX_NOT_FOUND) -1}.
2728      * </p>
2729      * <p>
2730      * All indices are specified in {@code char} values (Unicode code units).
2731      * </p>
2732      *
2733      * <pre>
2734      * StringUtils.indexOf(null, *, *)          = -1
2735      * StringUtils.indexOf("", *, *)            = -1
2736      * StringUtils.indexOf("aabaabaa", 'b', 0)  = 2
2737      * StringUtils.indexOf("aabaabaa", 'b', 3)  = 5
2738      * StringUtils.indexOf("aabaabaa", 'b', 9)  = -1
2739      * StringUtils.indexOf("aabaabaa", 'b', -1) = 2
2740      * </pre>
2741      *
2742      * @param seq        The CharSequence to check, may be null.
2743      * @param searchChar The character to find.
2744      * @param startPos   The start position, negative treated as zero.
2745      * @return The first index of the search character (always &ge; startPos), -1 if no match or {@code null} string input.
2746      * @since 2.0
2747      * @since 3.0 Changed signature from indexOf(String, int, int) to indexOf(CharSequence, int, int)
2748      * @since 3.6 Updated {@link CharSequenceUtils} call to behave more like {@link String}
2749      */
2750     public static int indexOf(final CharSequence seq, final int searchChar, final int startPos) {
2751         if (isEmpty(seq)) {
2752             return INDEX_NOT_FOUND;
2753         }
2754         return CharSequenceUtils.indexOf(seq, searchChar, startPos);
2755     }
2756 
2757     /**
2758      * Search a CharSequence to find the first index of any character in the given set of characters.
2759      *
2760      * <p>
2761      * A {@code null} String will return {@code -1}. A {@code null} or zero length search array will return {@code -1}.
2762      * </p>
2763      *
2764      * <pre>
2765      * StringUtils.indexOfAny(null, *)                  = -1
2766      * StringUtils.indexOfAny("", *)                    = -1
2767      * StringUtils.indexOfAny(*, null)                  = -1
2768      * StringUtils.indexOfAny(*, [])                    = -1
2769      * StringUtils.indexOfAny("zzabyycdxx", 'z', 'a')   = 0
2770      * StringUtils.indexOfAny("zzabyycdxx", 'b', 'y')   = 3
2771      * StringUtils.indexOfAny("aba", 'z')               = -1
2772      * </pre>
2773      *
2774      * @param cs          The CharSequence to check, may be null.
2775      * @param searchChars The chars to search for, may be null.
2776      * @return The index of any of the chars, -1 if no match or null input.
2777      * @since 2.0
2778      * @since 3.0 Changed signature from indexOfAny(String, char[]) to indexOfAny(CharSequence, char...)
2779      */
2780     public static int indexOfAny(final CharSequence cs, final char... searchChars) {
2781         return indexOfAny(cs, 0, searchChars);
2782     }
2783 
2784     /**
2785      * Find the first index of any of a set of potential substrings.
2786      *
2787      * <p>
2788      * A {@code null} CharSequence will return {@code -1}. A {@code null} or zero length search array will return {@code -1}. A {@code null} search array entry
2789      * will be ignored, but a search array containing "" will return {@code 0} if {@code str} is not null. This method uses {@link String#indexOf(String)} if
2790      * possible.
2791      * </p>
2792      *
2793      * <pre>
2794      * StringUtils.indexOfAny(null, *)                    = -1
2795      * StringUtils.indexOfAny(*, null)                    = -1
2796      * StringUtils.indexOfAny(*, [])                      = -1
2797      * StringUtils.indexOfAny("zzabyycdxx", "ab", "cd")   = 2
2798      * StringUtils.indexOfAny("zzabyycdxx", "cd", "ab")   = 2
2799      * StringUtils.indexOfAny("zzabyycdxx", "mn", "op")   = -1
2800      * StringUtils.indexOfAny("zzabyycdxx", "zab", "aby") = 1
2801      * StringUtils.indexOfAny("zzabyycdxx", new CharSequence[] { "" }) = 0
2802      * StringUtils.indexOfAny("", new CharSequence[] { "" })           = 0
2803      * StringUtils.indexOfAny("", new CharSequence[] { "a" })          = -1
2804      * </pre>
2805      *
2806      * <p>
2807      * Use an explicit array when searching for a single substring. Passing a single {@link String} as the second argument instead selects
2808      * {@link #indexOfAny(CharSequence, String)}, which searches for individual characters.
2809      * </p>
2810      *
2811      * @param str        The CharSequence to check, may be null.
2812      * @param searchStrs The CharSequences to search for, may be null.
2813      * @return The first index of any of the searchStrs in str, -1 if no match.
2814      * @since 3.0 Changed signature from indexOfAny(String, String[]) to indexOfAny(CharSequence, CharSequence...)
2815      */
2816     public static int indexOfAny(final CharSequence str, final CharSequence... searchStrs) {
2817         if (str == null || searchStrs == null) {
2818             return INDEX_NOT_FOUND;
2819         }
2820         // String's can't have a MAX_VALUEth index.
2821         int ret = Integer.MAX_VALUE;
2822         int tmp;
2823         for (final CharSequence search : searchStrs) {
2824             if (search == null) {
2825                 continue;
2826             }
2827             tmp = CharSequenceUtils.indexOf(str, search, 0);
2828             if (tmp == INDEX_NOT_FOUND) {
2829                 continue;
2830             }
2831             if (tmp < ret) {
2832                 ret = tmp;
2833             }
2834         }
2835         return ret == Integer.MAX_VALUE ? INDEX_NOT_FOUND : ret;
2836     }
2837 
2838     /**
2839      * Search a CharSequence to find the first index of any character in the given set of characters.
2840      *
2841      * <p>
2842      * A {@code null} String will return {@code -1}. A {@code null} or zero length search array will return {@code -1}.
2843      * </p>
2844      * <p>
2845      * The following is the same as {@code indexOfAny(cs, 0, searchChars)}.
2846      * </p>
2847      * <pre>
2848      * StringUtils.indexOfAny(null, 0, *)                  = -1
2849      * StringUtils.indexOfAny("", 0, *)                    = -1
2850      * StringUtils.indexOfAny(*, 0, null)                  = -1
2851      * StringUtils.indexOfAny(*, 0, [])                    = -1
2852      * StringUtils.indexOfAny("zzabyycdxx", 0, ['z', 'a']) = 0
2853      * StringUtils.indexOfAny("zzabyycdxx", 0, ['b', 'y']) = 3
2854      * StringUtils.indexOfAny("aba", 0, ['z'])             = -1
2855      * </pre>
2856      *
2857      * @param cs          The CharSequence to check, may be null.
2858      * @param csStart Start searching the input {@code cs} at this index.
2859      * @param searchChars The chars to search for, may be null.
2860      * @return The index of any of the chars, -1 if no match or null input.
2861      * @since 2.0
2862      * @since 3.0 Changed signature from indexOfAny(String, char[]) to indexOfAny(CharSequence, char...)
2863      */
2864     public static int indexOfAny(final CharSequence cs, final int csStart, final char... searchChars) {
2865         if (isEmpty(cs) || ArrayUtils.isEmpty(searchChars)) {
2866             return INDEX_NOT_FOUND;
2867         }
2868         final int csLen = cs.length();
2869         final int csLast = csLen - 1;
2870         final int searchLen = searchChars.length;
2871         final int searchLast = searchLen - 1;
2872         for (int i = Math.max(csStart, 0); i < csLen; i++) {
2873             final char ch = cs.charAt(i);
2874             for (int j = 0; j < searchLen; j++) {
2875                 if (searchChars[j] == ch) {
2876                     if (Character.isHighSurrogate(ch)
2877                             ? j == searchLast || i < csLast && searchChars[j + 1] == cs.charAt(i + 1)
2878                             : j == 0 || !Character.isLowSurrogate(ch) || !Character.isHighSurrogate(searchChars[j - 1]) || i > 0 && searchChars[j - 1] == cs.charAt(i - 1)) {
2879                         return i;
2880                     }
2881                 }
2882             }
2883         }
2884         return INDEX_NOT_FOUND;
2885     }
2886 
2887     /**
2888      * Search a CharSequence to find the first index of any character in the given set of characters.
2889      *
2890      * <p>
2891      * A {@code null} String will return {@code -1}. A {@code null} search string will return {@code -1}.
2892      * </p>
2893      *
2894      * <pre>
2895      * StringUtils.indexOfAny(null, *)            = -1
2896      * StringUtils.indexOfAny("", *)              = -1
2897      * StringUtils.indexOfAny(*, null)            = -1
2898      * StringUtils.indexOfAny(*, "")              = -1
2899      * StringUtils.indexOfAny("zzabyycdxx", "za") = 0
2900      * StringUtils.indexOfAny("zzabyycdxx", "by") = 3
2901      * StringUtils.indexOfAny("aba", "z")         = -1
2902      * </pre>
2903      *
2904      * @param cs          The CharSequence to check, may be null.
2905      * @param searchChars The chars to search for, may be null.
2906      * @return The index of any of the chars, -1 if no match or null input.
2907      * @since 2.0
2908      * @since 3.0 Changed signature from indexOfAny(String, String) to indexOfAny(CharSequence, String)
2909      */
2910     public static int indexOfAny(final CharSequence cs, final String searchChars) {
2911         if (isEmpty(cs) || isEmpty(searchChars)) {
2912             return INDEX_NOT_FOUND;
2913         }
2914         return indexOfAny(cs, searchChars.toCharArray());
2915     }
2916 
2917     /**
2918      * Searches a CharSequence to find the first index of any character not in the given set of characters, i.e., find index i of first char in cs such that
2919      * (cs.codePointAt(i) ∉ { x ∈ codepoints(searchChars) })
2920      *
2921      * <p>
2922      * A {@code null} CharSequence will return {@code -1}. A {@code null} or zero length search array will return {@code -1}.
2923      * </p>
2924      *
2925      * <pre>
2926      * StringUtils.indexOfAnyBut(null, *)                              = -1
2927      * StringUtils.indexOfAnyBut("", *)                                = -1
2928      * StringUtils.indexOfAnyBut(*, null)                              = -1
2929      * StringUtils.indexOfAnyBut(*, [])                                = -1
2930      * StringUtils.indexOfAnyBut("zzabyycdxx", new char[] {'z', 'a'} ) = 3
2931      * StringUtils.indexOfAnyBut("aba", new char[] {'z'} )             = 0
2932      * StringUtils.indexOfAnyBut("aba", new char[] {'a', 'b'} )        = -1
2933      * </pre>
2934      *
2935      * @param cs          The CharSequence to check, may be null.
2936      * @param searchChars The chars to search for, may be null.
2937      * @return The index of any of the chars, -1 if no match or null input.
2938      * @since 2.0
2939      * @since 3.0 Changed signature from indexOfAnyBut(String, char[]) to indexOfAnyBut(CharSequence, char...)
2940      */
2941     public static int indexOfAnyBut(final CharSequence cs, final char... searchChars) {
2942         if (isEmpty(cs) || ArrayUtils.isEmpty(searchChars)) {
2943             return INDEX_NOT_FOUND;
2944         }
2945         return indexOfAnyBut(cs, CharBuffer.wrap(searchChars));
2946     }
2947 
2948     /**
2949      * Search a CharSequence to find the first index of any character not in the given set of characters, i.e., find index i of first char in seq such that
2950      * (seq.codePointAt(i) ∉ { x ∈ codepoints(searchChars) })
2951      *
2952      * <p>
2953      * A {@code null} CharSequence will return {@code -1}. A {@code null} or empty search string will return {@code -1}.
2954      * </p>
2955      *
2956      * <pre>
2957      * StringUtils.indexOfAnyBut(null, *)            = -1
2958      * StringUtils.indexOfAnyBut("", *)              = -1
2959      * StringUtils.indexOfAnyBut(*, null)            = -1
2960      * StringUtils.indexOfAnyBut(*, "")              = -1
2961      * StringUtils.indexOfAnyBut("zzabyycdxx", "za") = 3
2962      * StringUtils.indexOfAnyBut("zzabyycdxx", "")   = -1
2963      * StringUtils.indexOfAnyBut("aba", "ab")        = -1
2964      * </pre>
2965      *
2966      * @param seq         The CharSequence to check, may be null.
2967      * @param searchChars The chars to search for, may be null.
2968      * @return The index of any of the chars, -1 if no match or null input.
2969      * @since 2.0
2970      * @since 3.0 Changed signature from indexOfAnyBut(String, String) to indexOfAnyBut(CharSequence, CharSequence)
2971      */
2972     public static int indexOfAnyBut(final CharSequence seq, final CharSequence searchChars) {
2973         if (isEmpty(seq) || isEmpty(searchChars)) {
2974             return INDEX_NOT_FOUND;
2975         }
2976         final Set<Integer> searchSetCodePoints = searchChars.codePoints()
2977                 .boxed().collect(Collectors.toSet());
2978         // advance character index from one interpreted codepoint to the next
2979         for (int curSeqCharIdx = 0; curSeqCharIdx < seq.length();) {
2980             final int curSeqCodePoint = Character.codePointAt(seq, curSeqCharIdx);
2981             if (!searchSetCodePoints.contains(curSeqCodePoint)) {
2982                 return curSeqCharIdx;
2983             }
2984             curSeqCharIdx += Character.charCount(curSeqCodePoint); // skip indices to paired low-surrogates
2985         }
2986         return INDEX_NOT_FOUND;
2987     }
2988 
2989     /**
2990      * Compares all CharSequences in an array and returns the index at which the CharSequences begin to differ.
2991      *
2992      * <p>
2993      * For example, {@code indexOfDifference(new String[] {"i am a machine", "i am a robot"}) -> 7}
2994      * </p>
2995      *
2996      * <pre>
2997      * StringUtils.indexOfDifference(null)                             = -1
2998      * StringUtils.indexOfDifference(new String[] {})                  = -1
2999      * StringUtils.indexOfDifference(new String[] {"abc"})             = -1
3000      * StringUtils.indexOfDifference(new String[] {null, null})        = -1
3001      * StringUtils.indexOfDifference(new String[] {"", ""})            = -1
3002      * StringUtils.indexOfDifference(new String[] {"", null})          = 0
3003      * StringUtils.indexOfDifference(new String[] {"abc", null, null}) = 0
3004      * StringUtils.indexOfDifference(new String[] {null, null, "abc"}) = 0
3005      * StringUtils.indexOfDifference(new String[] {"", "abc"})         = 0
3006      * StringUtils.indexOfDifference(new String[] {"abc", ""})         = 0
3007      * StringUtils.indexOfDifference(new String[] {"abc", "abc"})      = -1
3008      * StringUtils.indexOfDifference(new String[] {"abc", "a"})        = 1
3009      * StringUtils.indexOfDifference(new String[] {"ab", "abxyz"})     = 2
3010      * StringUtils.indexOfDifference(new String[] {"abcde", "abxyz"})  = 2
3011      * StringUtils.indexOfDifference(new String[] {"abcde", "xyz"})    = 0
3012      * StringUtils.indexOfDifference(new String[] {"xyz", "abcde"})    = 0
3013      * StringUtils.indexOfDifference(new String[] {"i am a machine", "i am a robot"}) = 7
3014      * </pre>
3015      *
3016      * @param css array of CharSequences, entries may be null.
3017      * @return The index where the strings begin to differ; -1 if they are all equal.
3018      * @since 2.4
3019      * @since 3.0 Changed signature from indexOfDifference(String...) to indexOfDifference(CharSequence...)
3020      */
3021     public static int indexOfDifference(final CharSequence... css) {
3022         if (ArrayUtils.getLength(css) <= 1) {
3023             return INDEX_NOT_FOUND;
3024         }
3025         boolean anyStringNull = false;
3026         boolean allStringsNull = true;
3027         final int arrayLen = css.length;
3028         int shortestStrLen = Integer.MAX_VALUE;
3029         int longestStrLen = 0;
3030         // find the min and max string lengths; this avoids checking to make
3031         // sure we are not exceeding the length of the string each time through
3032         // the bottom loop.
3033         for (final CharSequence cs : css) {
3034             if (cs == null) {
3035                 anyStringNull = true;
3036                 shortestStrLen = 0;
3037             } else {
3038                 allStringsNull = false;
3039                 shortestStrLen = Math.min(cs.length(), shortestStrLen);
3040                 longestStrLen = Math.max(cs.length(), longestStrLen);
3041             }
3042         }
3043         // handle lists containing all nulls or all empty strings
3044         if (allStringsNull || longestStrLen == 0 && !anyStringNull) {
3045             return INDEX_NOT_FOUND;
3046         }
3047         // handle lists containing some nulls or some empty strings
3048         if (shortestStrLen == 0) {
3049             return 0;
3050         }
3051         // find the position with the first difference across all strings
3052         int firstDiff = -1;
3053         for (int stringPos = 0; stringPos < shortestStrLen; stringPos++) {
3054             final char comparisonChar = css[0].charAt(stringPos);
3055             for (int arrayPos = 1; arrayPos < arrayLen; arrayPos++) {
3056                 if (css[arrayPos].charAt(stringPos) != comparisonChar) {
3057                     firstDiff = stringPos;
3058                     break;
3059                 }
3060             }
3061             if (firstDiff != -1) {
3062                 break;
3063             }
3064         }
3065         if (firstDiff > 0 && Character.isLowSurrogate(css[0].charAt(firstDiff))
3066                 && Character.isHighSurrogate(css[0].charAt(firstDiff - 1))) {
3067             // the difference splits a surrogate pair whose high half is common; report the start of the
3068             // pair so getCommonPrefix never slices it in half and leaves a stray high surrogate.
3069             firstDiff--;
3070         }
3071         if (firstDiff == -1 && shortestStrLen != longestStrLen) {
3072             // we compared all of the characters up to the length of the
3073             // shortest string and didn't find a match, but the string lengths
3074             // vary, so return the length of the shortest string.
3075             return shortestStrLen;
3076         }
3077         return firstDiff;
3078     }
3079 
3080     /**
3081      * Compares two CharSequences, and returns the index at which the CharSequences begin to differ.
3082      *
3083      * <p>
3084      * For example, {@code indexOfDifference("i am a machine", "i am a robot") -> 7}
3085      * </p>
3086      *
3087      * <pre>
3088      * StringUtils.indexOfDifference(null, null)       = -1
3089      * StringUtils.indexOfDifference("", "")           = -1
3090      * StringUtils.indexOfDifference("", "abc")        = 0
3091      * StringUtils.indexOfDifference("abc", "")        = 0
3092      * StringUtils.indexOfDifference("abc", "abc")     = -1
3093      * StringUtils.indexOfDifference("ab", "abxyz")    = 2
3094      * StringUtils.indexOfDifference("abcde", "abxyz") = 2
3095      * StringUtils.indexOfDifference("abcde", "xyz")   = 0
3096      * </pre>
3097      *
3098      * @param cs1 The first CharSequence, may be null.
3099      * @param cs2 The second CharSequence, may be null.
3100      * @return The index where cs1 and cs2 begin to differ; -1 if they are equal.
3101      * @since 2.0
3102      * @since 3.0 Changed signature from indexOfDifference(String, String) to indexOfDifference(CharSequence, CharSequence)
3103      */
3104     public static int indexOfDifference(final CharSequence cs1, final CharSequence cs2) {
3105         if (cs1 == cs2) {
3106             return INDEX_NOT_FOUND;
3107         }
3108         if (cs1 == null || cs2 == null) {
3109             return 0;
3110         }
3111         int i;
3112         for (i = 0; i < cs1.length() && i < cs2.length(); ++i) {
3113             if (cs1.charAt(i) != cs2.charAt(i)) {
3114                 break;
3115             }
3116         }
3117         if (i > 0 && i < cs1.length() && i < cs2.length() && Character.isHighSurrogate(cs1.charAt(i - 1))
3118                 && (Character.isLowSurrogate(cs1.charAt(i)) || Character.isLowSurrogate(cs2.charAt(i)))) {
3119             // the difference splits a surrogate pair whose high half is common; report the start of the
3120             // pair so difference does not return a string that begins with a stray low surrogate.
3121             i--;
3122         }
3123         if (i < cs2.length() || i < cs1.length()) {
3124             return i;
3125         }
3126         return INDEX_NOT_FOUND;
3127     }
3128 
3129     /**
3130      * Case insensitive find of the first index within a CharSequence.
3131      *
3132      * <p>
3133      * A {@code null} CharSequence will return {@code -1}. A negative start position is treated as zero. An empty ("") search CharSequence always matches. A
3134      * start position greater than the string length only matches an empty search CharSequence.
3135      * </p>
3136      *
3137      * <pre>
3138      * StringUtils.indexOfIgnoreCase(null, *)          = -1
3139      * StringUtils.indexOfIgnoreCase(*, null)          = -1
3140      * StringUtils.indexOfIgnoreCase("", "")           = 0
3141      * StringUtils.indexOfIgnoreCase(" ", " ")         = 0
3142      * StringUtils.indexOfIgnoreCase("aabaabaa", "a")  = 0
3143      * StringUtils.indexOfIgnoreCase("aabaabaa", "b")  = 2
3144      * StringUtils.indexOfIgnoreCase("aabaabaa", "ab") = 1
3145      * </pre>
3146      *
3147      * @param str       The CharSequence to check, may be null.
3148      * @param searchStr The CharSequence to find, may be null.
3149      * @return The first index of the search CharSequence, -1 if no match or {@code null} string input.
3150      * @since 2.5
3151      * @since 3.0 Changed signature from indexOfIgnoreCase(String, String) to indexOfIgnoreCase(CharSequence, CharSequence)
3152      * @deprecated Use {@link Strings#indexOf(CharSequence, CharSequence) Strings.CI.indexOf(CharSequence, CharSequence)}.
3153      */
3154     @Deprecated
3155     public static int indexOfIgnoreCase(final CharSequence str, final CharSequence searchStr) {
3156         return Strings.CI.indexOf(str, searchStr);
3157     }
3158 
3159     /**
3160      * Case insensitive find of the first index within a CharSequence from the specified position.
3161      *
3162      * <p>
3163      * A {@code null} CharSequence will return {@code -1}. A negative start position is treated as zero. An empty ("") search CharSequence always matches. A
3164      * start position greater than the string length only matches an empty search CharSequence.
3165      * </p>
3166      *
3167      * <pre>
3168      * StringUtils.indexOfIgnoreCase(null, *, *)          = -1
3169      * StringUtils.indexOfIgnoreCase(*, null, *)          = -1
3170      * StringUtils.indexOfIgnoreCase("", "", 0)           = 0
3171      * StringUtils.indexOfIgnoreCase("aabaabaa", "A", 0)  = 0
3172      * StringUtils.indexOfIgnoreCase("aabaabaa", "B", 0)  = 2
3173      * StringUtils.indexOfIgnoreCase("aabaabaa", "AB", 0) = 1
3174      * StringUtils.indexOfIgnoreCase("aabaabaa", "B", 3)  = 5
3175      * StringUtils.indexOfIgnoreCase("aabaabaa", "B", 9)  = -1
3176      * StringUtils.indexOfIgnoreCase("aabaabaa", "B", -1) = 2
3177      * StringUtils.indexOfIgnoreCase("aabaabaa", "", 2)   = 2
3178      * StringUtils.indexOfIgnoreCase("abc", "", 9)        = -1
3179      * </pre>
3180      *
3181      * @param str       The CharSequence to check, may be null.
3182      * @param searchStr The CharSequence to find, may be null.
3183      * @param startPos  The start position, negative treated as zero.
3184      * @return The first index of the search CharSequence (always &ge; startPos), -1 if no match or {@code null} string input.
3185      * @since 2.5
3186      * @since 3.0 Changed signature from indexOfIgnoreCase(String, String, int) to indexOfIgnoreCase(CharSequence, CharSequence, int)
3187      * @deprecated Use {@link Strings#indexOf(CharSequence, CharSequence, int) Strings.CI.indexOf(CharSequence, CharSequence, int)}.
3188      */
3189     @Deprecated
3190     public static int indexOfIgnoreCase(final CharSequence str, final CharSequence searchStr, final int startPos) {
3191         return Strings.CI.indexOf(str, searchStr, startPos);
3192     }
3193 
3194     /**
3195      * Tests if all of the CharSequences are empty (""), null or whitespace only.
3196      *
3197      * <p>
3198      * Whitespace is defined by {@link Character#isWhitespace(char)}.
3199      * </p>
3200      *
3201      * <pre>
3202      * StringUtils.isAllBlank(null)             = true
3203      * StringUtils.isAllBlank(null, "foo")      = false
3204      * StringUtils.isAllBlank(null, null)       = true
3205      * StringUtils.isAllBlank("", "bar")        = false
3206      * StringUtils.isAllBlank("bob", "")        = false
3207      * StringUtils.isAllBlank("  bob  ", null)  = false
3208      * StringUtils.isAllBlank(" ", "bar")       = false
3209      * StringUtils.isAllBlank("foo", "bar")     = false
3210      * StringUtils.isAllBlank(new String[] {})  = true
3211      * </pre>
3212      *
3213      * @param css The CharSequences to check, may be null or empty.
3214      * @return {@code true} if all of the CharSequences are empty or null or whitespace only.
3215      * @since 3.6
3216      */
3217     public static boolean isAllBlank(final CharSequence... css) {
3218         if (ArrayUtils.isEmpty(css)) {
3219             return true;
3220         }
3221         for (final CharSequence cs : css) {
3222             if (isNotBlank(cs)) {
3223                 return false;
3224             }
3225         }
3226         return true;
3227     }
3228 
3229     /**
3230      * Tests if all of the CharSequences are empty ("") or null.
3231      *
3232      * <pre>
3233      * StringUtils.isAllEmpty(null)             = true
3234      * StringUtils.isAllEmpty(null, "")         = true
3235      * StringUtils.isAllEmpty(new String[] {})  = true
3236      * StringUtils.isAllEmpty(null, "foo")      = false
3237      * StringUtils.isAllEmpty("", "bar")        = false
3238      * StringUtils.isAllEmpty("bob", "")        = false
3239      * StringUtils.isAllEmpty("  bob  ", null)  = false
3240      * StringUtils.isAllEmpty(" ", "bar")       = false
3241      * StringUtils.isAllEmpty("foo", "bar")     = false
3242      * </pre>
3243      *
3244      * @param css The CharSequences to check, may be null or empty.
3245      * @return {@code true} if all of the CharSequences are empty or null.
3246      * @since 3.6
3247      */
3248     public static boolean isAllEmpty(final CharSequence... css) {
3249         if (ArrayUtils.isEmpty(css)) {
3250             return true;
3251         }
3252         for (final CharSequence cs : css) {
3253             if (isNotEmpty(cs)) {
3254                 return false;
3255             }
3256         }
3257         return true;
3258     }
3259 
3260     /**
3261      * Tests if the CharSequence contains only lowercase characters.
3262      *
3263      * <p>
3264      * {@code null} will return {@code false}. An empty CharSequence (length()=0) will return {@code false}.
3265      * </p>
3266      *
3267      * <pre>
3268      * StringUtils.isAllLowerCase(null)   = false
3269      * StringUtils.isAllLowerCase("")     = false
3270      * StringUtils.isAllLowerCase("  ")   = false
3271      * StringUtils.isAllLowerCase("abc")  = true
3272      * StringUtils.isAllLowerCase("abC")  = false
3273      * StringUtils.isAllLowerCase("ab c") = false
3274      * StringUtils.isAllLowerCase("ab1c") = false
3275      * StringUtils.isAllLowerCase("ab/c") = false
3276      * </pre>
3277      *
3278      * @param cs The CharSequence to check, may be null.
3279      * @return {@code true} if only contains lowercase characters, and is non-null.
3280      * @since 2.5
3281      * @since 3.0 Changed signature from isAllLowerCase(String) to isAllLowerCase(CharSequence)
3282      */
3283     public static boolean isAllLowerCase(final CharSequence cs) {
3284         if (isEmpty(cs)) {
3285             return false;
3286         }
3287         final int sz = cs.length();
3288         for (int i = 0; i < sz;) {
3289             final int codePoint = Character.codePointAt(cs, i);
3290             if (!Character.isLowerCase(codePoint)) {
3291                 return false;
3292             }
3293             i += Character.charCount(codePoint);
3294         }
3295         return true;
3296     }
3297 
3298     /**
3299      * Tests if the CharSequence contains only uppercase characters.
3300      *
3301      * <p>
3302      * {@code null} will return {@code false}.
3303      * An empty String (length()=0) will return {@code false}.
3304      * </p>
3305      *
3306      * <pre>
3307      * StringUtils.isAllUpperCase(null)   = false
3308      * StringUtils.isAllUpperCase("")     = false
3309      * StringUtils.isAllUpperCase("  ")   = false
3310      * StringUtils.isAllUpperCase("ABC")  = true
3311      * StringUtils.isAllUpperCase("aBC")  = false
3312      * StringUtils.isAllUpperCase("A C")  = false
3313      * StringUtils.isAllUpperCase("A1C")  = false
3314      * StringUtils.isAllUpperCase("A/C")  = false
3315      * </pre>
3316      *
3317      * @param cs The CharSequence to check, may be null.
3318      * @return {@code true} if only contains uppercase characters, and is non-null.
3319      * @since 2.5
3320      * @since 3.0 Changed signature from isAllUpperCase(String) to isAllUpperCase(CharSequence)
3321      */
3322     public static boolean isAllUpperCase(final CharSequence cs) {
3323         if (isEmpty(cs)) {
3324             return false;
3325         }
3326         final int sz = cs.length();
3327         for (int i = 0; i < sz;) {
3328             final int codePoint = Character.codePointAt(cs, i);
3329             if (!Character.isUpperCase(codePoint)) {
3330                 return false;
3331             }
3332             i += Character.charCount(codePoint);
3333         }
3334         return true;
3335     }
3336 
3337     /**
3338      * Tests if the CharSequence contains only Unicode letters.
3339      *
3340      * <p>
3341      * {@code null} will return {@code false}. An empty CharSequence (length()=0) will return {@code false}.
3342      * </p>
3343      *
3344      * <pre>
3345      * StringUtils.isAlpha(null)   = false
3346      * StringUtils.isAlpha("")     = false
3347      * StringUtils.isAlpha("  ")   = false
3348      * StringUtils.isAlpha("abc")  = true
3349      * StringUtils.isAlpha("ab2c") = false
3350      * StringUtils.isAlpha("ab-c") = false
3351      * </pre>
3352      *
3353      * @param cs The CharSequence to check, may be null.
3354      * @return {@code true} if only contains letters, and is non-null.
3355      * @since 3.0 Changed signature from isAlpha(String) to isAlpha(CharSequence)
3356      * @since 3.0 Changed "" to return false and not true
3357      */
3358     public static boolean isAlpha(final CharSequence cs) {
3359         if (isEmpty(cs)) {
3360             return false;
3361         }
3362         final int sz = cs.length();
3363         for (int i = 0; i < sz;) {
3364             final int codePoint = Character.codePointAt(cs, i);
3365             if (!Character.isLetter(codePoint)) {
3366                 return false;
3367             }
3368             i += Character.charCount(codePoint);
3369         }
3370         return true;
3371     }
3372 
3373     /**
3374      * Tests if the CharSequence contains only Unicode letters or digits.
3375      *
3376      * <p>
3377      * {@code null} will return {@code false}. An empty CharSequence (length()=0) will return {@code false}.
3378      * </p>
3379      *
3380      * <pre>
3381      * StringUtils.isAlphanumeric(null)   = false
3382      * StringUtils.isAlphanumeric("")     = false
3383      * StringUtils.isAlphanumeric("  ")   = false
3384      * StringUtils.isAlphanumeric("abc")  = true
3385      * StringUtils.isAlphanumeric("ab c") = false
3386      * StringUtils.isAlphanumeric("ab2c") = true
3387      * StringUtils.isAlphanumeric("ab-c") = false
3388      * </pre>
3389      *
3390      * @param cs The CharSequence to check, may be null.
3391      * @return {@code true} if only contains letters or digits, and is non-null.
3392      * @since 3.0 Changed signature from isAlphanumeric(String) to isAlphanumeric(CharSequence)
3393      * @since 3.0 Changed "" to return false and not true
3394      */
3395     public static boolean isAlphanumeric(final CharSequence cs) {
3396         if (isEmpty(cs)) {
3397             return false;
3398         }
3399         final int sz = cs.length();
3400         for (int i = 0; i < sz;) {
3401             final int codePoint = Character.codePointAt(cs, i);
3402             if (!Character.isLetterOrDigit(codePoint)) {
3403                 return false;
3404             }
3405             i += Character.charCount(codePoint);
3406         }
3407         return true;
3408     }
3409 
3410     /**
3411      * Tests if the CharSequence contains only Unicode letters, digits or space ({@code ' '}).
3412      *
3413      * <p>
3414      * {@code null} will return {@code false}. An empty CharSequence (length()=0) will return {@code true}.
3415      * </p>
3416      *
3417      * <pre>
3418      * StringUtils.isAlphanumericSpace(null)   = false
3419      * StringUtils.isAlphanumericSpace("")     = true
3420      * StringUtils.isAlphanumericSpace("  ")   = true
3421      * StringUtils.isAlphanumericSpace("abc")  = true
3422      * StringUtils.isAlphanumericSpace("ab c") = true
3423      * StringUtils.isAlphanumericSpace("ab2c") = true
3424      * StringUtils.isAlphanumericSpace("ab-c") = false
3425      * </pre>
3426      *
3427      * @param cs The CharSequence to check, may be null.
3428      * @return {@code true} if only contains letters, digits or space, and is non-null.
3429      * @since 3.0 Changed signature from isAlphanumericSpace(String) to isAlphanumericSpace(CharSequence)
3430      */
3431     public static boolean isAlphanumericSpace(final CharSequence cs) {
3432         if (cs == null) {
3433             return false;
3434         }
3435         final int sz = cs.length();
3436         for (int i = 0; i < sz;) {
3437             final int codePoint = Character.codePointAt(cs, i);
3438             if (codePoint != ' ' && !Character.isLetterOrDigit(codePoint)) {
3439                 return false;
3440             }
3441             i += Character.charCount(codePoint);
3442         }
3443         return true;
3444     }
3445 
3446     /**
3447      * Tests if the CharSequence contains only Unicode letters and space (' ').
3448      *
3449      * <p>
3450      * {@code null} will return {@code false} An empty CharSequence (length()=0) will return {@code true}.
3451      * </p>
3452      *
3453      * <pre>
3454      * StringUtils.isAlphaSpace(null)   = false
3455      * StringUtils.isAlphaSpace("")     = true
3456      * StringUtils.isAlphaSpace("  ")   = true
3457      * StringUtils.isAlphaSpace("abc")  = true
3458      * StringUtils.isAlphaSpace("ab c") = true
3459      * StringUtils.isAlphaSpace("ab2c") = false
3460      * StringUtils.isAlphaSpace("ab-c") = false
3461      * </pre>
3462      *
3463      * @param cs The CharSequence to check, may be null.
3464      * @return {@code true} if only contains letters and space, and is non-null.
3465      * @since 3.0 Changed signature from isAlphaSpace(String) to isAlphaSpace(CharSequence)
3466      */
3467     public static boolean isAlphaSpace(final CharSequence cs) {
3468         if (cs == null) {
3469             return false;
3470         }
3471         final int sz = cs.length();
3472         for (int i = 0; i < sz;) {
3473             final int codePoint = Character.codePointAt(cs, i);
3474             if (codePoint != ' ' && !Character.isLetter(codePoint)) {
3475                 return false;
3476             }
3477             i += Character.charCount(codePoint);
3478         }
3479         return true;
3480     }
3481 
3482     /**
3483      * Tests if any of the CharSequences are {@link #isBlank(CharSequence) blank} (whitespaces, empty ({@code ""}), or {@code null}).
3484      *
3485      * <p>
3486      * Whitespace is defined by {@link Character#isWhitespace(char)}.
3487      * </p>
3488      *
3489      * <pre>
3490      * StringUtils.isAnyBlank((String) null)    = true
3491      * StringUtils.isAnyBlank((String[]) null)  = false
3492      * StringUtils.isAnyBlank(null, "foo")      = true
3493      * StringUtils.isAnyBlank(null, null)       = true
3494      * StringUtils.isAnyBlank("", "bar")        = true
3495      * StringUtils.isAnyBlank("bob", "")        = true
3496      * StringUtils.isAnyBlank("  bob  ", null)  = true
3497      * StringUtils.isAnyBlank(" ", "bar")       = true
3498      * StringUtils.isAnyBlank(new String[] {})  = false
3499      * StringUtils.isAnyBlank(new String[]{""}) = true
3500      * StringUtils.isAnyBlank("foo", "bar")     = false
3501      * </pre>
3502      *
3503      * @param css The CharSequences to check, may be null or empty.
3504      * @return {@code true} if any of the CharSequences are {@link #isBlank(CharSequence) blank} (whitespaces, empty ({@code ""}), or {@code null}).
3505      * @see #isBlank(CharSequence)
3506      * @since 3.2
3507      */
3508     public static boolean isAnyBlank(final CharSequence... css) {
3509         if (ArrayUtils.isEmpty(css)) {
3510             return false;
3511         }
3512         for (final CharSequence cs : css) {
3513             if (isBlank(cs)) {
3514                 return true;
3515             }
3516         }
3517         return false;
3518     }
3519 
3520     /**
3521      * Tests if any of the CharSequences are empty ("") or null.
3522      *
3523      * <pre>
3524      * StringUtils.isAnyEmpty((String) null)    = true
3525      * StringUtils.isAnyEmpty((String[]) null)  = false
3526      * StringUtils.isAnyEmpty(null, "foo")      = true
3527      * StringUtils.isAnyEmpty("", "bar")        = true
3528      * StringUtils.isAnyEmpty("bob", "")        = true
3529      * StringUtils.isAnyEmpty("  bob  ", null)  = true
3530      * StringUtils.isAnyEmpty(" ", "bar")       = false
3531      * StringUtils.isAnyEmpty("foo", "bar")     = false
3532      * StringUtils.isAnyEmpty(new String[]{})   = false
3533      * StringUtils.isAnyEmpty(new String[]{""}) = true
3534      * </pre>
3535      *
3536      * @param css  The CharSequences to check, may be null or empty.
3537      * @return {@code true} if any of the CharSequences are empty or null.
3538      * @since 3.2
3539      */
3540     public static boolean isAnyEmpty(final CharSequence... css) {
3541         if (ArrayUtils.isEmpty(css)) {
3542             return false;
3543         }
3544         for (final CharSequence cs : css) {
3545             if (isEmpty(cs)) {
3546                 return true;
3547             }
3548         }
3549         return false;
3550     }
3551 
3552     /**
3553      * Tests if the CharSequence contains only ASCII printable characters.
3554      *
3555      * <p>
3556      * {@code null} will return {@code false}. An empty CharSequence (length()=0) will return {@code true}.
3557      * </p>
3558      *
3559      * <pre>
3560      * StringUtils.isAsciiPrintable(null)     = false
3561      * StringUtils.isAsciiPrintable("")       = true
3562      * StringUtils.isAsciiPrintable(" ")      = true
3563      * StringUtils.isAsciiPrintable("Ceki")   = true
3564      * StringUtils.isAsciiPrintable("ab2c")   = true
3565      * StringUtils.isAsciiPrintable("!ab-c~") = true
3566      * StringUtils.isAsciiPrintable("\u0020") = true
3567      * StringUtils.isAsciiPrintable("\u0021") = true
3568      * StringUtils.isAsciiPrintable("\u007e") = true
3569      * StringUtils.isAsciiPrintable("\u007f") = false
3570      * StringUtils.isAsciiPrintable("Ceki G\u00fclc\u00fc") = false
3571      * </pre>
3572      *
3573      * @param cs The CharSequence to check, may be null.
3574      * @return {@code true} if every character is in the range 32 through 126.
3575      * @since 2.1
3576      * @since 3.0 Changed signature from isAsciiPrintable(String) to isAsciiPrintable(CharSequence)
3577      */
3578     public static boolean isAsciiPrintable(final CharSequence cs) {
3579         if (cs == null) {
3580             return false;
3581         }
3582         final int sz = cs.length();
3583         for (int i = 0; i < sz; i++) {
3584             if (!CharUtils.isAsciiPrintable(cs.charAt(i))) {
3585                 return false;
3586             }
3587         }
3588         return true;
3589     }
3590 
3591     /**
3592      * Tests if a CharSequence is empty ({@code "")}, null, or contains only whitespace as defined by {@link Character#isWhitespace(char)}.
3593      *
3594      * <pre>
3595      * StringUtils.isBlank(null)      = true
3596      * StringUtils.isBlank("")        = true
3597      * StringUtils.isBlank(" ")       = true
3598      * StringUtils.isBlank("bob")     = false
3599      * StringUtils.isBlank("  bob  ") = false
3600      * </pre>
3601      *
3602      * @param cs The CharSequence to check, may be null.
3603      * @return {@code true} if the CharSequence is null, empty or whitespace only.
3604      * @since 2.0
3605      * @since 3.0 Changed signature from isBlank(String) to isBlank(CharSequence)
3606      */
3607     public static boolean isBlank(final CharSequence cs) {
3608         final int strLen = length(cs);
3609         for (int i = 0; i < strLen; i++) {
3610             if (!Character.isWhitespace(cs.charAt(i))) {
3611                 return false;
3612             }
3613         }
3614         return true;
3615     }
3616 
3617     /**
3618      * Tests if a CharSequence is empty ("") or null.
3619      *
3620      * <pre>
3621      * StringUtils.isEmpty(null)      = true
3622      * StringUtils.isEmpty("")        = true
3623      * StringUtils.isEmpty(" ")       = false
3624      * StringUtils.isEmpty("bob")     = false
3625      * StringUtils.isEmpty("  bob  ") = false
3626      * </pre>
3627      *
3628      * <p>
3629      * NOTE: This method changed in Lang version 2.0. It no longer trims the CharSequence. That functionality is available in isBlank().
3630      * </p>
3631      *
3632      * @param cs The CharSequence to check, may be null.
3633      * @return {@code true} if the CharSequence is empty or null.
3634      * @since 3.0 Changed signature from isEmpty(String) to isEmpty(CharSequence)
3635      */
3636     public static boolean isEmpty(final CharSequence cs) {
3637         return cs == null || cs.length() == 0;
3638     }
3639 
3640     /**
3641      * Tests if the CharSequence contains mixed casing of both uppercase and lowercase characters.
3642      *
3643      * <p>
3644      * {@code null} will return {@code false}. An empty CharSequence ({@code length()=0}) will return {@code false}.
3645      * </p>
3646      *
3647      * <pre>
3648      * StringUtils.isMixedCase(null)    = false
3649      * StringUtils.isMixedCase("")      = false
3650      * StringUtils.isMixedCase(" ")     = false
3651      * StringUtils.isMixedCase("ABC")   = false
3652      * StringUtils.isMixedCase("abc")   = false
3653      * StringUtils.isMixedCase("aBc")   = true
3654      * StringUtils.isMixedCase("A c")   = true
3655      * StringUtils.isMixedCase("A1c")   = true
3656      * StringUtils.isMixedCase("a/C")   = true
3657      * StringUtils.isMixedCase("aC\t")  = true
3658      * </pre>
3659      *
3660      * @param cs The CharSequence to check, may be null.
3661      * @return {@code true} if the CharSequence contains both uppercase and lowercase characters.
3662      * @since 3.5
3663      */
3664     public static boolean isMixedCase(final CharSequence cs) {
3665         if (isEmpty(cs) || cs.length() == 1) {
3666             return false;
3667         }
3668         boolean containsUppercase = false;
3669         boolean containsLowercase = false;
3670         final int sz = cs.length();
3671         for (int i = 0; i < sz;) {
3672             final int codePoint = Character.codePointAt(cs, i);
3673             if (Character.isUpperCase(codePoint)) {
3674                 containsUppercase = true;
3675             } else if (Character.isLowerCase(codePoint)) {
3676                 containsLowercase = true;
3677             }
3678             if (containsUppercase && containsLowercase) {
3679                 return true;
3680             }
3681             i += Character.charCount(codePoint);
3682         }
3683         return false;
3684     }
3685 
3686     /**
3687      * Tests if none of the CharSequences are empty (""), null or whitespace only.
3688      *
3689      * <p>
3690      * Whitespace is defined by {@link Character#isWhitespace(char)}.
3691      * </p>
3692      *
3693      * <pre>
3694      * StringUtils.isNoneBlank((String) null)    = false
3695      * StringUtils.isNoneBlank((String[]) null)  = true
3696      * StringUtils.isNoneBlank(null, "foo")      = false
3697      * StringUtils.isNoneBlank(null, null)       = false
3698      * StringUtils.isNoneBlank("", "bar")        = false
3699      * StringUtils.isNoneBlank("bob", "")        = false
3700      * StringUtils.isNoneBlank("  bob  ", null)  = false
3701      * StringUtils.isNoneBlank(" ", "bar")       = false
3702      * StringUtils.isNoneBlank(new String[] {})  = true
3703      * StringUtils.isNoneBlank(new String[]{""}) = false
3704      * StringUtils.isNoneBlank("foo", "bar")     = true
3705      * </pre>
3706      *
3707      * @param css The CharSequences to check, may be null or empty.
3708      * @return {@code true} if none of the CharSequences are empty or null or whitespace only.
3709      * @since 3.2
3710      */
3711     public static boolean isNoneBlank(final CharSequence... css) {
3712         return !isAnyBlank(css);
3713     }
3714 
3715     /**
3716      * Tests if none of the CharSequences are empty ("") or null.
3717      *
3718      * <pre>
3719      * StringUtils.isNoneEmpty((String) null)    = false
3720      * StringUtils.isNoneEmpty((String[]) null)  = true
3721      * StringUtils.isNoneEmpty(null, "foo")      = false
3722      * StringUtils.isNoneEmpty("", "bar")        = false
3723      * StringUtils.isNoneEmpty("bob", "")        = false
3724      * StringUtils.isNoneEmpty("  bob  ", null)  = false
3725      * StringUtils.isNoneEmpty(new String[] {})  = true
3726      * StringUtils.isNoneEmpty(new String[]{""}) = false
3727      * StringUtils.isNoneEmpty(" ", "bar")       = true
3728      * StringUtils.isNoneEmpty("foo", "bar")     = true
3729      * </pre>
3730      *
3731      * @param css  The CharSequences to check, may be null or empty.
3732      * @return {@code true} if none of the CharSequences are empty or null.
3733      * @since 3.2
3734      */
3735     public static boolean isNoneEmpty(final CharSequence... css) {
3736         return !isAnyEmpty(css);
3737     }
3738 
3739     /**
3740      * Tests if a CharSequence is not {@link #isBlank(CharSequence) blank} (whitespaces, empty ({@code ""}), or {@code null}).
3741      *
3742      * <p>
3743      * Whitespace is defined by {@link Character#isWhitespace(char)}.
3744      * </p>
3745      *
3746      * <pre>
3747      * StringUtils.isNotBlank(null)      = false
3748      * StringUtils.isNotBlank("")        = false
3749      * StringUtils.isNotBlank(" ")       = false
3750      * StringUtils.isNotBlank("bob")     = true
3751      * StringUtils.isNotBlank("  bob  ") = true
3752      * </pre>
3753      *
3754      * @param cs The CharSequence to check, may be null.
3755      * @return {@code true} if the CharSequence is not {@link #isBlank(CharSequence) blank} (whitespaces, empty ({@code ""}), or {@code null}).
3756      * @see #isBlank(CharSequence)
3757      * @since 2.0
3758      * @since 3.0 Changed signature from isNotBlank(String) to isNotBlank(CharSequence)
3759      */
3760     public static boolean isNotBlank(final CharSequence cs) {
3761         return !isBlank(cs);
3762     }
3763 
3764     /**
3765      * Tests if a CharSequence is not empty ("") and not null.
3766      *
3767      * <pre>
3768      * StringUtils.isNotEmpty(null)      = false
3769      * StringUtils.isNotEmpty("")        = false
3770      * StringUtils.isNotEmpty(" ")       = true
3771      * StringUtils.isNotEmpty("bob")     = true
3772      * StringUtils.isNotEmpty("  bob  ") = true
3773      * </pre>
3774      *
3775      * @param cs  The CharSequence to check, may be null.
3776      * @return {@code true} if the CharSequence is not empty and not null.
3777      * @since 3.0 Changed signature from isNotEmpty(String) to isNotEmpty(CharSequence)
3778      */
3779     public static boolean isNotEmpty(final CharSequence cs) {
3780         return !isEmpty(cs);
3781     }
3782 
3783     /**
3784      * Tests if the CharSequence contains only Unicode digits. A decimal point is not a Unicode digit and returns false.
3785      *
3786      * <p>
3787      * {@code null} will return {@code false}. An empty CharSequence (length()=0) will return {@code false}.
3788      * </p>
3789      *
3790      * <p>
3791      * Note that the method does not allow for a leading sign, either positive or negative. Also, if a String passes the numeric test, it may still generate a
3792      * NumberFormatException when parsed by Integer.parseInt or Long.parseLong, e.g. if the value is outside the range for int or long respectively.
3793      * </p>
3794      *
3795      * <pre>
3796      * StringUtils.isNumeric(null)   = false
3797      * StringUtils.isNumeric("")     = false
3798      * StringUtils.isNumeric("  ")   = false
3799      * StringUtils.isNumeric("123")  = true
3800      * StringUtils.isNumeric("\u0967\u0968\u0969")  = true
3801      * StringUtils.isNumeric("12 3") = false
3802      * StringUtils.isNumeric("ab2c") = false
3803      * StringUtils.isNumeric("12-3") = false
3804      * StringUtils.isNumeric("12.3") = false
3805      * StringUtils.isNumeric("-123") = false
3806      * StringUtils.isNumeric("+123") = false
3807      * </pre>
3808      *
3809      * @param cs The CharSequence to check, may be null.
3810      * @return {@code true} if only contains digits, and is non-null.
3811      * @since 3.0 Changed signature from isNumeric(String) to isNumeric(CharSequence)
3812      * @since 3.0 Changed "" to return false and not true
3813      */
3814     public static boolean isNumeric(final CharSequence cs) {
3815         if (isEmpty(cs)) {
3816             return false;
3817         }
3818         final int sz = cs.length();
3819         for (int i = 0; i < sz;) {
3820             final int codePoint = Character.codePointAt(cs, i);
3821             if (!Character.isDigit(codePoint)) {
3822                 return false;
3823             }
3824             i += Character.charCount(codePoint);
3825         }
3826         return true;
3827     }
3828 
3829     /**
3830      * Tests if the CharSequence contains only Unicode digits or space ({@code ' '}). A decimal point is not a Unicode digit and returns false.
3831      *
3832      * <p>
3833      * {@code null} will return {@code false}. An empty CharSequence (length()=0) will return {@code true}.
3834      * </p>
3835      *
3836      * <pre>
3837      * StringUtils.isNumericSpace(null)   = false
3838      * StringUtils.isNumericSpace("")     = true
3839      * StringUtils.isNumericSpace("  ")   = true
3840      * StringUtils.isNumericSpace("123")  = true
3841      * StringUtils.isNumericSpace("12 3") = true
3842      * StringUtils.isNumericSpace("\u0967\u0968\u0969")   = true
3843      * StringUtils.isNumericSpace("\u0967\u0968 \u0969")  = true
3844      * StringUtils.isNumericSpace("ab2c") = false
3845      * StringUtils.isNumericSpace("12-3") = false
3846      * StringUtils.isNumericSpace("12.3") = false
3847      * </pre>
3848      *
3849      * @param cs The CharSequence to check, may be null.
3850      * @return {@code true} if only contains digits or space, and is non-null.
3851      * @since 3.0 Changed signature from isNumericSpace(String) to isNumericSpace(CharSequence)
3852      */
3853     public static boolean isNumericSpace(final CharSequence cs) {
3854         if (cs == null) {
3855             return false;
3856         }
3857         final int sz = cs.length();
3858         for (int i = 0; i < sz;) {
3859             final int codePoint = Character.codePointAt(cs, i);
3860             if (codePoint != ' ' && !Character.isDigit(codePoint)) {
3861                 return false;
3862             }
3863             i += Character.charCount(codePoint);
3864         }
3865         return true;
3866     }
3867 
3868     /**
3869      * Tests if the CharSequence contains only whitespace.
3870      *
3871      * <p>
3872      * Whitespace is defined by {@link Character#isWhitespace(char)}.
3873      * </p>
3874      *
3875      * <p>
3876      * {@code null} will return {@code false}. An empty CharSequence (length()=0) will return {@code true}.
3877      * </p>
3878      *
3879      * <pre>
3880      * StringUtils.isWhitespace(null)   = false
3881      * StringUtils.isWhitespace("")     = true
3882      * StringUtils.isWhitespace("  ")   = true
3883      * StringUtils.isWhitespace("abc")  = false
3884      * StringUtils.isWhitespace("ab2c") = false
3885      * StringUtils.isWhitespace("ab-c") = false
3886      * </pre>
3887      *
3888      * @param cs The CharSequence to check, may be null.
3889      * @return {@code true} if only contains whitespace, and is non-null.
3890      * @since 2.0
3891      * @since 3.0 Changed signature from isWhitespace(String) to isWhitespace(CharSequence)
3892      */
3893     public static boolean isWhitespace(final CharSequence cs) {
3894         if (cs == null) {
3895             return false;
3896         }
3897         final int sz = cs.length();
3898         for (int i = 0; i < sz; i++) {
3899             if (!Character.isWhitespace(cs.charAt(i))) {
3900                 return false;
3901             }
3902         }
3903         return true;
3904     }
3905 
3906     /**
3907      * Joins the elements of the provided array into a single String containing the provided list of elements.
3908      *
3909      * <p>
3910      * No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.
3911      * </p>
3912      *
3913      * <pre>
3914      * StringUtils.join(null, *)             = null
3915      * StringUtils.join([], *)               = ""
3916      * StringUtils.join([null], *)           = ""
3917      * StringUtils.join([false, false], ';') = "false;false"
3918      * </pre>
3919      *
3920      * @param array     The array of values to join together, may be null.
3921      * @param delimiter The separator character to use.
3922      * @return The joined String, {@code null} if null array input.
3923      * @since 3.12.0
3924      */
3925     public static String join(final boolean[] array, final char delimiter) {
3926         if (array == null) {
3927             return null;
3928         }
3929         return join(array, delimiter, 0, array.length);
3930     }
3931 
3932     /**
3933      * Joins the elements of the provided array into a single String containing the provided list of elements.
3934      *
3935      * <p>
3936      * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
3937      * by empty strings.
3938      * </p>
3939      *
3940      * <pre>
3941      * StringUtils.join(null, *)                  = null
3942      * StringUtils.join([], *)                    = ""
3943      * StringUtils.join([null], *)                = ""
3944      * StringUtils.join([true, false, true], ';') = "true;false;true"
3945      * </pre>
3946      *
3947      * @param array
3948      *            the array of values to join together, may be null.
3949      * @param delimiter
3950      *            the separator character to use.
3951      * @param startIndex
3952      *            the first index to start joining from. It is an error to pass in a start index past the end of the
3953      *            array.
3954      * @param endIndex
3955      *            the index to stop joining from (exclusive). It is an error to pass in an end index past the end of
3956      *            the array.
3957      * @return The joined String, {@code null} if null array input.
3958      * @since 3.12.0
3959      */
3960     public static String join(final boolean[] array, final char delimiter, final int startIndex, final int endIndex) {
3961         // See StringUtilsJoinBenchmark
3962         if (array == null) {
3963             return null;
3964         }
3965         checkFromToIndex(startIndex, endIndex, array.length);
3966         final int count = endIndex - startIndex;
3967         if (count <= 0) {
3968             return EMPTY;
3969         }
3970         final byte maxElementChars = 5; // "false"
3971         final StringBuilder stringBuilder = capacity(count, maxElementChars);
3972         stringBuilder.append(array[startIndex]);
3973         for (int i = startIndex + 1; i < endIndex; i++) {
3974             stringBuilder.append(delimiter).append(array[i]);
3975         }
3976         return stringBuilder.toString();
3977     }
3978 
3979     /**
3980      * Joins the elements of the provided array into a single String containing the provided list of elements.
3981      *
3982      * <p>
3983      * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
3984      * by empty strings.
3985      * </p>
3986      *
3987      * <pre>
3988      * StringUtils.join(null, *)         = null
3989      * StringUtils.join([], *)           = ""
3990      * StringUtils.join([null], *)       = ""
3991      * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
3992      * StringUtils.join([1, 2, 3], null) = "123"
3993      * </pre>
3994      *
3995      * @param array
3996      *            the array of values to join together, may be null.
3997      * @param delimiter
3998      *            the separator character to use.
3999      * @return The joined String, {@code null} if null array input.
4000      * @since 3.2
4001      */
4002     public static String join(final byte[] array, final char delimiter) {
4003         if (array == null) {
4004             return null;
4005         }
4006         return join(array, delimiter, 0, array.length);
4007     }
4008 
4009     /**
4010      * Joins the elements of the provided array into a single String containing the provided list of elements.
4011      *
4012      * <p>
4013      * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
4014      * by empty strings.
4015      * </p>
4016      *
4017      * <pre>
4018      * StringUtils.join(null, *)         = null
4019      * StringUtils.join([], *)           = ""
4020      * StringUtils.join([null], *)       = ""
4021      * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
4022      * StringUtils.join([1, 2, 3], null) = "123"
4023      * </pre>
4024      *
4025      * @param array
4026      *            the array of values to join together, may be null.
4027      * @param delimiter
4028      *            the separator character to use.
4029      * @param startIndex
4030      *            the first index to start joining from. It is an error to pass in a start index past the end of the
4031      *            array.
4032      * @param endIndex
4033      *            the index to stop joining from (exclusive). It is an error to pass in an end index past the end of
4034      *            the array.
4035      * @return The joined String, {@code null} if null array input.
4036      * @since 3.2
4037      */
4038     public static String join(final byte[] array, final char delimiter, final int startIndex, final int endIndex) {
4039         // See StringUtilsJoinBenchmark
4040         if (array == null) {
4041             return null;
4042         }
4043         checkFromToIndex(startIndex, endIndex, array.length);
4044         final int count = endIndex - startIndex;
4045         if (count <= 0) {
4046             return EMPTY;
4047         }
4048         final byte maxElementChars = 4; // "-128"
4049         final StringBuilder stringBuilder = capacity(count, maxElementChars);
4050         stringBuilder.append(array[startIndex]);
4051         for (int i = startIndex + 1; i < endIndex; i++) {
4052             stringBuilder.append(delimiter).append(array[i]);
4053         }
4054         return stringBuilder.toString();
4055     }
4056 
4057     /**
4058      * Joins the elements of the provided array into a single String containing the provided list of elements.
4059      *
4060      * <p>
4061      * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
4062      * by empty strings.
4063      * </p>
4064      *
4065      * <pre>
4066      * StringUtils.join(null, *)         = null
4067      * StringUtils.join([], *)           = ""
4068      * StringUtils.join([null], *)       = ""
4069      * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
4070      * StringUtils.join([1, 2, 3], null) = "123"
4071      * </pre>
4072      *
4073      * @param array
4074      *            the array of values to join together, may be null.
4075      * @param delimiter
4076      *            the separator character to use.
4077      * @return The joined String, {@code null} if null array input.
4078      * @since 3.2
4079      */
4080     public static String join(final char[] array, final char delimiter) {
4081         if (array == null) {
4082             return null;
4083         }
4084         return join(array, delimiter, 0, array.length);
4085     }
4086 
4087     /**
4088      * Joins the elements of the provided array into a single String containing the provided list of elements.
4089      *
4090      * <p>
4091      * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
4092      * by empty strings.
4093      * </p>
4094      *
4095      * <pre>
4096      * StringUtils.join(null, *)         = null
4097      * StringUtils.join([], *)           = ""
4098      * StringUtils.join([null], *)       = ""
4099      * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
4100      * StringUtils.join([1, 2, 3], null) = "123"
4101      * </pre>
4102      *
4103      * @param array
4104      *            the array of values to join together, may be null.
4105      * @param delimiter
4106      *            the separator character to use.
4107      * @param startIndex
4108      *            the first index to start joining from. It is an error to pass in a start index past the end of the
4109      *            array.
4110      * @param endIndex
4111      *            the index to stop joining from (exclusive). It is an error to pass in an end index past the end of
4112      *            the array.
4113      * @return The joined String, {@code null} if null array input.
4114      * @since 3.2
4115      */
4116     public static String join(final char[] array, final char delimiter, final int startIndex, final int endIndex) {
4117         // See StringUtilsJoinBenchmark
4118         if (array == null) {
4119             return null;
4120         }
4121         checkFromToIndex(startIndex, endIndex, array.length);
4122         final int count = endIndex - startIndex;
4123         if (count <= 0) {
4124             return EMPTY;
4125         }
4126         final byte maxElementChars = 1;
4127         final StringBuilder stringBuilder = capacity(count, maxElementChars);
4128         stringBuilder.append(array[startIndex]);
4129         for (int i = startIndex + 1; i < endIndex; i++) {
4130             stringBuilder.append(delimiter).append(array[i]);
4131         }
4132         return stringBuilder.toString();
4133     }
4134 
4135     /**
4136      * Joins the elements of the provided array into a single String containing the provided list of elements.
4137      *
4138      * <p>
4139      * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
4140      * by empty strings.
4141      * </p>
4142      *
4143      * <pre>
4144      * StringUtils.join(null, *)          = null
4145      * StringUtils.join([], *)            = ""
4146      * StringUtils.join([null], *)        = ""
4147      * StringUtils.join([1, 2, 3], ';')   = "1;2;3"
4148      * StringUtils.join([1, 2, 3], null)  = "123"
4149      * </pre>
4150      *
4151      * @param array
4152      *            the array of values to join together, may be null.
4153      * @param delimiter
4154      *            the separator character to use.
4155      * @return The joined String, {@code null} if null array input.
4156      * @since 3.2
4157      */
4158     public static String join(final double[] array, final char delimiter) {
4159         if (array == null) {
4160             return null;
4161         }
4162         return join(array, delimiter, 0, array.length);
4163     }
4164 
4165     /**
4166      * Joins the elements of the provided array into a single String containing the provided list of elements.
4167      *
4168      * <p>
4169      * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
4170      * by empty strings.
4171      * </p>
4172      *
4173      * <pre>
4174      * StringUtils.join(null, *)          = null
4175      * StringUtils.join([], *)            = ""
4176      * StringUtils.join([null], *)        = ""
4177      * StringUtils.join([1, 2, 3], ';')   = "1;2;3"
4178      * StringUtils.join([1, 2, 3], null)  = "123"
4179      * </pre>
4180      *
4181      * @param array
4182      *            the array of values to join together, may be null.
4183      * @param delimiter
4184      *            the separator character to use.
4185      * @param startIndex
4186      *            the first index to start joining from. It is an error to pass in a start index past the end of the
4187      *            array.
4188      * @param endIndex
4189      *            the index to stop joining from (exclusive). It is an error to pass in an end index past the end of
4190      *            the array.
4191      * @return The joined String, {@code null} if null array input.
4192      * @since 3.2
4193      */
4194     public static String join(final double[] array, final char delimiter, final int startIndex, final int endIndex) {
4195         // See StringUtilsJoinBenchmark
4196         if (array == null) {
4197             return null;
4198         }
4199         checkFromToIndex(startIndex, endIndex, array.length);
4200         final int count = endIndex - startIndex;
4201         if (count <= 0) {
4202             return EMPTY;
4203         }
4204         final byte maxElementChars = 22; // "1.7976931348623157E308"
4205         final StringBuilder stringBuilder = capacity(count, maxElementChars);
4206         stringBuilder.append(array[startIndex]);
4207         for (int i = startIndex + 1; i < endIndex; i++) {
4208             stringBuilder.append(delimiter).append(array[i]);
4209         }
4210         return stringBuilder.toString();
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         // See StringUtilsJoinBenchmark
4274         if (array == null) {
4275             return null;
4276         }
4277         checkFromToIndex(startIndex, endIndex, array.length);
4278         final int count = endIndex - startIndex;
4279         if (count <= 0) {
4280             return EMPTY;
4281         }
4282         final byte maxElementChars = 12; // "3.4028235E38"
4283         final StringBuilder stringBuilder = capacity(count, maxElementChars);
4284         stringBuilder.append(array[startIndex]);
4285         for (int i = startIndex + 1; i < endIndex; i++) {
4286             stringBuilder.append(delimiter).append(array[i]);
4287         }
4288         return stringBuilder.toString();
4289     }
4290 
4291     /**
4292      * Joins the elements of the provided array into a single String containing the provided list of elements.
4293      *
4294      * <p>
4295      * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
4296      * by empty strings.
4297      * </p>
4298      *
4299      * <pre>
4300      * StringUtils.join(null, *)          = null
4301      * StringUtils.join([], *)            = ""
4302      * StringUtils.join([null], *)        = ""
4303      * StringUtils.join([1, 2, 3], ';')   = "1;2;3"
4304      * StringUtils.join([1, 2, 3], null)  = "123"
4305      * </pre>
4306      *
4307      * @param array
4308      *            the array of values to join together, may be null.
4309      * @param separator
4310      *            the separator character to use.
4311      * @return The joined String, {@code null} if null array input.
4312      * @since 3.2
4313      */
4314     public static String join(final int[] array, final char separator) {
4315         if (array == null) {
4316             return null;
4317         }
4318         return join(array, separator, 0, array.length);
4319     }
4320 
4321     /**
4322      * Joins the elements of the provided array into a single String containing the provided list of elements.
4323      *
4324      * <p>
4325      * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
4326      * by empty strings.
4327      * </p>
4328      *
4329      * <pre>
4330      * StringUtils.join(null, *)          = null
4331      * StringUtils.join([], *)            = ""
4332      * StringUtils.join([null], *)        = ""
4333      * StringUtils.join([1, 2, 3], ';')   = "1;2;3"
4334      * StringUtils.join([1, 2, 3], null)  = "123"
4335      * </pre>
4336      *
4337      * @param array
4338      *            the array of values to join together, may be null.
4339      * @param delimiter
4340      *            the separator character to use.
4341      * @param startIndex
4342      *            the first index to start joining from. It is an error to pass in a start index past the end of the
4343      *            array.
4344      * @param endIndex
4345      *            the index to stop joining from (exclusive). It is an error to pass in an end index past the end of
4346      *            the array.
4347      * @return The joined String, {@code null} if null array input.
4348      * @since 3.2
4349      */
4350     public static String join(final int[] array, final char delimiter, final int startIndex, final int endIndex) {
4351         // See StringUtilsJoinBenchmark
4352         if (array == null) {
4353             return null;
4354         }
4355         checkFromToIndex(startIndex, endIndex, array.length);
4356         final int count = endIndex - startIndex;
4357         if (count <= 0) {
4358             return EMPTY;
4359         }
4360         final byte maxElementChars = 11; // "-2147483648"
4361         final StringBuilder stringBuilder = capacity(count, maxElementChars);
4362         stringBuilder.append(array[startIndex]);
4363         for (int i = startIndex + 1; i < endIndex; i++) {
4364             stringBuilder.append(delimiter).append(array[i]);
4365         }
4366         return stringBuilder.toString();
4367     }
4368 
4369     /**
4370      * Joins the elements of the provided {@link Iterable} into a single String containing the provided elements.
4371      *
4372      * <p>
4373      * No delimiter is added before or after the list. Null objects or empty strings within the iteration are represented by empty strings.
4374      * </p>
4375      *
4376      * <p>
4377      * See the examples here: {@link #join(Object[],char)}.
4378      * </p>
4379      *
4380      * @param iterable  The {@link Iterable} providing the values to join together, may be null.
4381      * @param separator The separator character to use.
4382      * @return The joined String, {@code null} if null iterator input.
4383      * @since 2.3
4384      */
4385     public static String join(final Iterable<?> iterable, final char separator) {
4386         return iterable != null ? join(iterable.iterator(), separator) : null;
4387     }
4388 
4389     /**
4390      * Joins the elements of the provided {@link Iterable} into a single String containing the provided elements.
4391      *
4392      * <p>
4393      * No delimiter is added before or after the list. A {@code null} separator is the same as an empty String ("").
4394      * </p>
4395      *
4396      * <p>
4397      * See the examples here: {@link #join(Object[],String)}.
4398      * </p>
4399      *
4400      * @param iterable  The {@link Iterable} providing the values to join together, may be null.
4401      * @param separator The separator character to use, null treated as "".
4402      * @return The joined String, {@code null} if null iterator input.
4403      * @since 2.3
4404      */
4405     public static String join(final Iterable<?> iterable, final String separator) {
4406         return iterable != null ? join(iterable.iterator(), separator) : null;
4407     }
4408 
4409     /**
4410      * Joins the elements of the provided {@link Iterator} into a single String containing the provided elements.
4411      *
4412      * <p>
4413      * No delimiter is added before or after the list. Null objects or empty strings within the iteration are represented by empty strings.
4414      * </p>
4415      *
4416      * <p>
4417      * See the examples here: {@link #join(Object[],char)}.
4418      * </p>
4419      *
4420      * @param iterator  The {@link Iterator} of values to join together, may be null.
4421      * @param separator The separator character to use.
4422      * @return The joined String, {@code null} if null iterator input.
4423      * @since 2.0
4424      */
4425     public static String join(final Iterator<?> iterator, final char separator) {
4426         // handle null, zero and one elements before building a buffer
4427         if (iterator == null) {
4428             return null;
4429         }
4430         if (!iterator.hasNext()) {
4431             return EMPTY;
4432         }
4433         return Streams.of(iterator).collect(LangCollectors.joining(ObjectUtils.toString(String.valueOf(separator)), EMPTY, EMPTY, ObjectUtils::toString));
4434     }
4435 
4436     /**
4437      * Joins the elements of the provided {@link Iterator} into a single String containing the provided elements.
4438      *
4439      * <p>
4440      * No delimiter is added before or after the list. A {@code null} separator is the same as an empty String ("").
4441      * </p>
4442      *
4443      * <p>
4444      * See the examples here: {@link #join(Object[],String)}.
4445      * </p>
4446      *
4447      * @param iterator  The {@link Iterator} of values to join together, may be null.
4448      * @param separator The separator character to use, null treated as "".
4449      * @return The joined String, {@code null} if null iterator input.
4450      */
4451     public static String join(final Iterator<?> iterator, final String separator) {
4452         // handle null, zero and one elements before building a buffer
4453         if (iterator == null) {
4454             return null;
4455         }
4456         if (!iterator.hasNext()) {
4457             return EMPTY;
4458         }
4459         return Streams.of(iterator).collect(LangCollectors.joining(ObjectUtils.toString(separator), EMPTY, EMPTY, ObjectUtils::toString));
4460     }
4461 
4462     /**
4463      * Joins the elements of the provided {@link List} into a single String containing the provided list of elements.
4464      *
4465      * <p>
4466      * No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.
4467      * </p>
4468      *
4469      * <pre>
4470      * StringUtils.join(null, *)               = null
4471      * StringUtils.join([], *)                 = ""
4472      * StringUtils.join([null], *)             = ""
4473      * StringUtils.join(["a", "b", "c"], ';')  = "a;b;c"
4474      * StringUtils.join(["a", "b", "c"], null) = "abc"
4475      * StringUtils.join([null, "", "a"], ';')  = ";;a"
4476      * </pre>
4477      *
4478      * @param list       The {@link List} of values to join together, may be null.
4479      * @param separator  The separator character to use.
4480      * @param startIndex The first index to start joining from. It is an error to pass in a start index past the end of the list.
4481      * @param endIndex   The index to stop joining from (exclusive). It is an error to pass in an end index past the end of the list.
4482      * @return The joined String, {@code null} if null list input.
4483      * @since 3.8
4484      */
4485     public static String join(final List<?> list, final char separator, final int startIndex, final int endIndex) {
4486         if (list == null) {
4487             return null;
4488         }
4489         final int noOfItems = endIndex - startIndex;
4490         if (noOfItems <= 0) {
4491             return EMPTY;
4492         }
4493         final List<?> subList = list.subList(startIndex, endIndex);
4494         return join(subList.iterator(), separator);
4495     }
4496 
4497     /**
4498      * Joins the elements of the provided {@link List} into a single String containing the provided list of elements.
4499      *
4500      * <p>
4501      * No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.
4502      * </p>
4503      *
4504      * <pre>
4505      * StringUtils.join(null, *)               = null
4506      * StringUtils.join([], *)                 = ""
4507      * StringUtils.join([null], *)             = ""
4508      * StringUtils.join(["a", "b", "c"], ';')  = "a;b;c"
4509      * StringUtils.join(["a", "b", "c"], null) = "abc"
4510      * StringUtils.join([null, "", "a"], ';')  = ";;a"
4511      * </pre>
4512      *
4513      * @param list       The {@link List} of values to join together, may be null.
4514      * @param separator  The separator character to use.
4515      * @param startIndex The first index to start joining from. It is an error to pass in a start index past the end of the list.
4516      * @param endIndex   The index to stop joining from (exclusive). It is an error to pass in an end index past the end of the list.
4517      * @return The joined String, {@code null} if null list input.
4518      * @since 3.8
4519      */
4520     public static String join(final List<?> list, final String separator, final int startIndex, final int endIndex) {
4521         if (list == null) {
4522             return null;
4523         }
4524         final int noOfItems = endIndex - startIndex;
4525         if (noOfItems <= 0) {
4526             return EMPTY;
4527         }
4528         final List<?> subList = list.subList(startIndex, endIndex);
4529         return join(subList.iterator(), separator);
4530     }
4531 
4532     /**
4533      * Joins the elements of the provided array into a single String containing the provided list of elements.
4534      *
4535      * <p>
4536      * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
4537      * by empty strings.
4538      * </p>
4539      *
4540      * <pre>
4541      * StringUtils.join(null, *)               = null
4542      * StringUtils.join([], *)                 = ""
4543      * StringUtils.join([null], *)             = ""
4544      * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
4545      * StringUtils.join([1, 2, 3], null) = "123"
4546      * </pre>
4547      *
4548      * @param array
4549      *            the array of values to join together, may be null.
4550      * @param separator
4551      *            the separator character to use.
4552      * @return The joined String, {@code null} if null array input.
4553      * @since 3.2
4554      */
4555     public static String join(final long[] array, final char separator) {
4556         if (array == null) {
4557             return null;
4558         }
4559         return join(array, separator, 0, array.length);
4560     }
4561 
4562     /**
4563      * Joins the elements of the provided array into a single String containing the provided list of elements.
4564      *
4565      * <p>
4566      * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
4567      * by empty strings.
4568      * </p>
4569      *
4570      * <pre>
4571      * StringUtils.join(null, *)               = null
4572      * StringUtils.join([], *)                 = ""
4573      * StringUtils.join([null], *)             = ""
4574      * StringUtils.join([1, 2, 3], ';')  = "1;2;3"
4575      * StringUtils.join([1, 2, 3], null) = "123"
4576      * </pre>
4577      *
4578      * @param array
4579      *            the array of values to join together, may be null.
4580      * @param delimiter
4581      *            the separator character to use.
4582      * @param startIndex
4583      *            the first index to start joining from. It is an error to pass in a start index past the end of the
4584      *            array.
4585      * @param endIndex
4586      *            the index to stop joining from (exclusive). It is an error to pass in an end index past the end of
4587      *            the array.
4588      * @return The joined String, {@code null} if null array input.
4589      * @since 3.2
4590      */
4591     public static String join(final long[] array, final char delimiter, final int startIndex, final int endIndex) {
4592         // See StringUtilsJoinBenchmark
4593         if (array == null) {
4594             return null;
4595         }
4596         checkFromToIndex(startIndex, endIndex, array.length);
4597         final int count = endIndex - startIndex;
4598         if (count <= 0) {
4599             return EMPTY;
4600         }
4601         final byte maxElementChars = 20; // "-9223372036854775808"
4602         final StringBuilder stringBuilder = capacity(count, maxElementChars);
4603         stringBuilder.append(array[startIndex]);
4604         for (int i = startIndex + 1; i < endIndex; i++) {
4605             stringBuilder.append(delimiter).append(array[i]);
4606         }
4607         return stringBuilder.toString();
4608     }
4609 
4610     /**
4611      * Joins the elements of the provided array into a single String containing the provided list of elements.
4612      *
4613      * <p>
4614      * No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.
4615      * </p>
4616      *
4617      * <pre>
4618      * StringUtils.join(null, *)               = null
4619      * StringUtils.join([], *)                 = ""
4620      * StringUtils.join([null], *)             = ""
4621      * StringUtils.join(["a", "b", "c"], ';')  = "a;b;c"
4622      * StringUtils.join(["a", "b", "c"], null) = "abc"
4623      * StringUtils.join([null, "", "a"], ';')  = ";;a"
4624      * </pre>
4625      *
4626      * @param array     The array of values to join together, may be null.
4627      * @param delimiter The separator character to use.
4628      * @return The joined String, {@code null} if null array input.
4629      * @since 2.0
4630      */
4631     public static String join(final Object[] array, final char delimiter) {
4632         if (array == null) {
4633             return null;
4634         }
4635         return join(array, delimiter, 0, array.length);
4636     }
4637 
4638     /**
4639      * Joins the elements of the provided array into a single String containing the provided list of elements.
4640      *
4641      * <p>
4642      * No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.
4643      * </p>
4644      *
4645      * <pre>
4646      * StringUtils.join(null, *)               = null
4647      * StringUtils.join([], *)                 = ""
4648      * StringUtils.join([null], *)             = ""
4649      * StringUtils.join(["a", "b", "c"], ';')  = "a;b;c"
4650      * StringUtils.join(["a", "b", "c"], null) = "abc"
4651      * StringUtils.join([null, "", "a"], ';')  = ";;a"
4652      * </pre>
4653      *
4654      * @param array      The array of values to join together, may be null.
4655      * @param delimiter  The separator character to use.
4656      * @param startIndex The first index to start joining from. It is an error to pass in a start index past the end of the array.
4657      * @param endIndex   The index to stop joining from (exclusive). It is an error to pass in an end index past the end of the array.
4658      * @return The joined String, {@code null} if null array input.
4659      * @since 2.0
4660      */
4661     public static String join(final Object[] array, final char delimiter, final int startIndex, final int endIndex) {
4662         return join(array, String.valueOf(delimiter), startIndex, endIndex);
4663     }
4664 
4665     /**
4666      * Joins the elements of the provided array into a single String containing the provided list of elements.
4667      *
4668      * <p>
4669      * No delimiter is added before or after the list. A {@code null} separator is the same as an empty String (""). Null objects or empty strings within the
4670      * array are represented by empty strings.
4671      * </p>
4672      *
4673      * <pre>
4674      * StringUtils.join(null, *)                = null
4675      * StringUtils.join([], *)                  = ""
4676      * StringUtils.join([null], *)              = ""
4677      * StringUtils.join(["a", "b", "c"], "--")  = "a--b--c"
4678      * StringUtils.join(["a", "b", "c"], null)  = "abc"
4679      * StringUtils.join(["a", "b", "c"], "")    = "abc"
4680      * StringUtils.join([null, "", "a"], ',')   = ",,a"
4681      * </pre>
4682      *
4683      * @param array     The array of values to join together, may be null.
4684      * @param delimiter The separator character to use, null treated as "".
4685      * @return The joined String, {@code null} if null array input.
4686      */
4687     public static String join(final Object[] array, final String delimiter) {
4688         return array != null ? join(array, ObjectUtils.toString(delimiter), 0, array.length) : null;
4689     }
4690 
4691     /**
4692      * Joins the elements of the provided array into a single String containing the provided list of elements.
4693      *
4694      * <p>
4695      * No delimiter is added before or after the list. A {@code null} separator is the same as an empty String (""). Null objects or empty strings within the
4696      * array are represented by empty strings.
4697      * </p>
4698      *
4699      * <pre>
4700      * StringUtils.join(null, *, *, *)                = null
4701      * StringUtils.join([], *, *, *)                  = ""
4702      * StringUtils.join([null], *, *, *)              = ""
4703      * StringUtils.join(["a", "b", "c"], "--", 0, 3)  = "a--b--c"
4704      * StringUtils.join(["a", "b", "c"], "--", 1, 3)  = "b--c"
4705      * StringUtils.join(["a", "b", "c"], "--", 2, 3)  = "c"
4706      * StringUtils.join(["a", "b", "c"], "--", 2, 2)  = ""
4707      * StringUtils.join(["a", "b", "c"], null, 0, 3)  = "abc"
4708      * StringUtils.join(["a", "b", "c"], "", 0, 3)    = "abc"
4709      * StringUtils.join([null, "", "a"], ',', 0, 3)   = ",,a"
4710      * </pre>
4711      *
4712      * @param array      The array of values to join together, may be null.
4713      * @param delimiter  The separator character to use, null treated as "".
4714      * @param startIndex The first index to start joining from.
4715      * @param endIndex   The index to stop joining from (exclusive).
4716      * @return The joined String, {@code null} if null array input; or the empty string if {@code endIndex - startIndex <= 0}. The number of joined entries is
4717      *         given by {@code endIndex - startIndex}.
4718      * @throws ArrayIndexOutOfBoundsException Thrown if<br> {@code startIndex < 0} or <br> {@code startIndex >= array.length()} or <br> {@code endIndex < 0} or
4719      *         <br> {@code endIndex > array.length()}.
4720      */
4721     public static String join(final Object[] array, final String delimiter, final int startIndex, final int endIndex) {
4722         return array != null ? Streams.of(array).skip(startIndex).limit(Math.max(0, endIndex - startIndex))
4723                 .collect(LangCollectors.joining(delimiter, EMPTY, EMPTY, ObjectUtils::toString)) : null;
4724     }
4725 
4726     /**
4727      * Joins the elements of the provided array into a single String containing the provided list of elements.
4728      *
4729      * <p>
4730      * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
4731      * by empty strings.
4732      * </p>
4733      *
4734      * <pre>
4735      * StringUtils.join(null, *)          = null
4736      * StringUtils.join([], *)            = ""
4737      * StringUtils.join([null], *)        = ""
4738      * StringUtils.join([1, 2, 3], ';')   = "1;2;3"
4739      * StringUtils.join([1, 2, 3], null)  = "123"
4740      * </pre>
4741      *
4742      * @param array
4743      *            the array of values to join together, may be null.
4744      * @param delimiter
4745      *            the separator character to use.
4746      * @return The joined String, {@code null} if null array input.
4747      * @since 3.2
4748      */
4749     public static String join(final short[] array, final char delimiter) {
4750         if (array == null) {
4751             return null;
4752         }
4753         return join(array, delimiter, 0, array.length);
4754     }
4755 
4756     /**
4757      * Joins the elements of the provided array into a single String containing the provided list of elements.
4758      *
4759      * <p>
4760      * No delimiter is added before or after the list. Null objects or empty strings within the array are represented
4761      * by empty strings.
4762      * </p>
4763      *
4764      * <pre>
4765      * StringUtils.join(null, *)          = null
4766      * StringUtils.join([], *)            = ""
4767      * StringUtils.join([null], *)        = ""
4768      * StringUtils.join([1, 2, 3], ';')   = "1;2;3"
4769      * StringUtils.join([1, 2, 3], null)  = "123"
4770      * </pre>
4771      *
4772      * @param array
4773      *            the array of values to join together, may be null.
4774      * @param delimiter
4775      *            the separator character to use.
4776      * @param startIndex
4777      *            the first index to start joining from. It is an error to pass in a start index past the end of the
4778      *            array.
4779      * @param endIndex
4780      *            the index to stop joining from (exclusive). It is an error to pass in an end index past the end of
4781      *            the array.
4782      * @return The joined String, {@code null} if null array input.
4783      * @since 3.2
4784      */
4785     public static String join(final short[] array, final char delimiter, final int startIndex, final int endIndex) {
4786         // See StringUtilsJoinBenchmark
4787         if (array == null) {
4788             return null;
4789         }
4790         checkFromToIndex(startIndex, endIndex, array.length);
4791         final int count = endIndex - startIndex;
4792         if (count <= 0) {
4793             return EMPTY;
4794         }
4795         final byte maxElementChars = 6; // "-32768"
4796         final StringBuilder stringBuilder = capacity(count, maxElementChars);
4797         stringBuilder.append(array[startIndex]);
4798         for (int i = startIndex + 1; i < endIndex; i++) {
4799             stringBuilder.append(delimiter).append(array[i]);
4800         }
4801         return stringBuilder.toString();
4802     }
4803 
4804     /**
4805      * Joins the elements of the provided array into a single String containing the provided list of elements.
4806      *
4807      * <p>
4808      * No separator is added to the joined String. Null objects or empty strings within the array are represented by empty strings.
4809      * </p>
4810      *
4811      * <pre>
4812      * StringUtils.join(null)            = null
4813      * StringUtils.join([])              = ""
4814      * StringUtils.join([null])          = ""
4815      * StringUtils.join("a", "b", "c")   = "abc"
4816      * StringUtils.join(null, "", "a")   = "a"
4817      * </pre>
4818      *
4819      * @param <T>      the specific type of values to join together.
4820      * @param elements The values to join together, may be null.
4821      * @return The joined String, {@code null} if null array input.
4822      * @since 2.0
4823      * @since 3.0 Changed signature to use varargs
4824      */
4825     @SafeVarargs
4826     public static <T> String join(final T... elements) {
4827         return join(elements, null);
4828     }
4829 
4830     /**
4831      * Joins the elements of the provided varargs into a single String containing the provided elements.
4832      *
4833      * <p>
4834      * No delimiter is added before or after the list. {@code null} elements and separator are treated as empty Strings ("").
4835      * </p>
4836      *
4837      * <pre>
4838      * StringUtils.joinWith(",", "a", "b")        = "a,b"
4839      * StringUtils.joinWith(",", "a", "b","")     = "a,b,"
4840      * StringUtils.joinWith(",", "a", null, "b")  = "a,,b"
4841      * StringUtils.joinWith(null, "a", "b")       = "ab"
4842      * </pre>
4843      *
4844      * @param delimiter The separator character to use, null treated as "".
4845      * @param array     The varargs providing the values to join together. {@code null} elements are treated as "".
4846      * @return The joined String.
4847      * @throws IllegalArgumentException Thrown if a null varargs is provided.
4848      * @since 3.5
4849      */
4850     public static String joinWith(final String delimiter, final Object... array) {
4851         if (array == null) {
4852             throw new IllegalArgumentException("Object varargs must not be null");
4853         }
4854         return join(array, delimiter);
4855     }
4856 
4857     /**
4858      * Finds the last index within a CharSequence, handling {@code null}. This method uses {@link String#lastIndexOf(String)} if possible.
4859      *
4860      * <p>
4861      * A {@code null} CharSequence will return {@code -1}.
4862      * </p>
4863      *
4864      * <pre>
4865      * StringUtils.lastIndexOf(null, *)          = -1
4866      * StringUtils.lastIndexOf(*, null)          = -1
4867      * StringUtils.lastIndexOf("", "")           = 0
4868      * StringUtils.lastIndexOf("aabaabaa", "a")  = 7
4869      * StringUtils.lastIndexOf("aabaabaa", "b")  = 5
4870      * StringUtils.lastIndexOf("aabaabaa", "ab") = 4
4871      * StringUtils.lastIndexOf("aabaabaa", "")   = 8
4872      * </pre>
4873      *
4874      * @param seq       The CharSequence to check, may be null.
4875      * @param searchSeq The CharSequence to find, may be null.
4876      * @return The last index of the search String, -1 if no match or {@code null} string input.
4877      * @since 2.0
4878      * @since 3.0 Changed signature from lastIndexOf(String, String) to lastIndexOf(CharSequence, CharSequence)
4879      * @deprecated Use {@link Strings#lastIndexOf(CharSequence, CharSequence) Strings.CS.lastIndexOf(CharSequence, CharSequence)}.
4880      */
4881     @Deprecated
4882     public static int lastIndexOf(final CharSequence seq, final CharSequence searchSeq) {
4883         return Strings.CS.lastIndexOf(seq, searchSeq);
4884     }
4885 
4886     /**
4887      * Finds the last index within a CharSequence, handling {@code null}. This method uses {@link String#lastIndexOf(String, int)} if possible.
4888      *
4889      * <p>
4890      * A {@code null} CharSequence will return {@code -1}. A negative start position returns {@code -1}. An empty ("") search CharSequence always matches unless
4891      * the start position is negative. A start position greater than the string length searches the whole string. The search starts at the startPos and works
4892      * backwards; matches starting after the start position are ignored.
4893      * </p>
4894      *
4895      * <pre>
4896      * StringUtils.lastIndexOf(null, *, *)          = -1
4897      * StringUtils.lastIndexOf(*, null, *)          = -1
4898      * StringUtils.lastIndexOf("aabaabaa", "a", 8)  = 7
4899      * StringUtils.lastIndexOf("aabaabaa", "b", 8)  = 5
4900      * StringUtils.lastIndexOf("aabaabaa", "ab", 8) = 4
4901      * StringUtils.lastIndexOf("aabaabaa", "b", 9)  = 5
4902      * StringUtils.lastIndexOf("aabaabaa", "b", -1) = -1
4903      * StringUtils.lastIndexOf("aabaabaa", "a", 0)  = 0
4904      * StringUtils.lastIndexOf("aabaabaa", "b", 0)  = -1
4905      * StringUtils.lastIndexOf("aabaabaa", "b", 1)  = -1
4906      * StringUtils.lastIndexOf("aabaabaa", "b", 2)  = 2
4907      * StringUtils.lastIndexOf("aabaabaa", "ba", 2)  = 2
4908      * </pre>
4909      *
4910      * @param seq       The CharSequence to check, may be null.
4911      * @param searchSeq The CharSequence to find, may be null.
4912      * @param startPos  The start position, negative treated as zero.
4913      * @return The last index of the search CharSequence (always &le; startPos), -1 if no match or {@code null} string input.
4914      * @since 2.0
4915      * @since 3.0 Changed signature from lastIndexOf(String, String, int) to lastIndexOf(CharSequence, CharSequence, int)
4916      * @deprecated Use {@link Strings#lastIndexOf(CharSequence, CharSequence, int) Strings.CS.lastIndexOf(CharSequence, CharSequence, int)}.
4917      */
4918     @Deprecated
4919     public static int lastIndexOf(final CharSequence seq, final CharSequence searchSeq, final int startPos) {
4920         return Strings.CS.lastIndexOf(seq, searchSeq, startPos);
4921     }
4922 
4923     /**
4924      * Returns the index within {@code seq} of the last occurrence of the specified character. For values of {@code searchChar} in the range from 0 to 0xFFFF
4925      * (inclusive), the index (in Unicode code units) returned is the largest value <em>k</em> such that:
4926      *
4927      * <pre>
4928      * this.charAt(<em>k</em>) == searchChar
4929      * </pre>
4930      *
4931      * <p>
4932      * is true. For other values of {@code searchChar}, it is the largest value <em>k</em> such that:
4933      * </p>
4934      *
4935      * <pre>
4936      * this.codePointAt(<em>k</em>) == searchChar
4937      * </pre>
4938      *
4939      * <p>
4940      * is true. In either case, if no such character occurs in this string, then {@code -1} is returned. Furthermore, a {@code null} or empty ("")
4941      * {@link CharSequence} will return {@code -1}. The {@code seq} {@link CharSequence} object is searched backwards starting at the last character.
4942      * </p>
4943      *
4944      * <pre>
4945      * StringUtils.lastIndexOf(null, *)         = -1
4946      * StringUtils.lastIndexOf("", *)           = -1
4947      * StringUtils.lastIndexOf("aabaabaa", 'a') = 7
4948      * StringUtils.lastIndexOf("aabaabaa", 'b') = 5
4949      * </pre>
4950      *
4951      * @param seq        The {@link CharSequence} to check, may be null.
4952      * @param searchChar The character to find.
4953      * @return The last index of the search character, -1 if no match or {@code null} string input.
4954      * @since 2.0
4955      * @since 3.0 Changed signature from lastIndexOf(String, int) to lastIndexOf(CharSequence, int)
4956      * @since 3.6 Updated {@link CharSequenceUtils} call to behave more like {@link String}
4957      */
4958     public static int lastIndexOf(final CharSequence seq, final int searchChar) {
4959         if (isEmpty(seq)) {
4960             return INDEX_NOT_FOUND;
4961         }
4962         return CharSequenceUtils.lastIndexOf(seq, searchChar, seq.length());
4963     }
4964 
4965     /**
4966      * Returns the index within {@code seq} of the last occurrence of the specified character, searching backward starting at the specified index. For values of
4967      * {@code searchChar} in the range from 0 to 0xFFFF (inclusive), the index returned is the largest value <em>k</em> such that:
4968      *
4969      * <pre>
4970      * (this.charAt(<em>k</em>) == searchChar) &amp;&amp; (<em>k</em> &lt;= startPos)
4971      * </pre>
4972      *
4973      * <p>
4974      * is true. For other values of {@code searchChar}, it is the largest value <em>k</em> such that:
4975      * </p>
4976      *
4977      * <pre>
4978      * (this.codePointAt(<em>k</em>) == searchChar) &amp;&amp; (<em>k</em> &lt;= startPos)
4979      * </pre>
4980      *
4981      * <p>
4982      * is true. In either case, if no such character occurs in {@code seq} at or before position {@code startPos}, then {@code -1} is returned. Furthermore, a
4983      * {@code null} or empty ("") {@link CharSequence} will return {@code -1}. A start position greater than the string length searches the whole string. The
4984      * search starts at the {@code startPos} and works backwards; matches starting after the start position are ignored.
4985      * </p>
4986      *
4987      * <p>
4988      * All indices are specified in {@code char} values (Unicode code units).
4989      * </p>
4990      *
4991      * <pre>
4992      * StringUtils.lastIndexOf(null, *, *)          = -1
4993      * StringUtils.lastIndexOf("", *,  *)           = -1
4994      * StringUtils.lastIndexOf("aabaabaa", 'b', 8)  = 5
4995      * StringUtils.lastIndexOf("aabaabaa", 'b', 4)  = 2
4996      * StringUtils.lastIndexOf("aabaabaa", 'b', 0)  = -1
4997      * StringUtils.lastIndexOf("aabaabaa", 'b', 9)  = 5
4998      * StringUtils.lastIndexOf("aabaabaa", 'b', -1) = -1
4999      * StringUtils.lastIndexOf("aabaabaa", 'a', 0)  = 0
5000      * </pre>
5001      *
5002      * @param seq        The CharSequence to check, may be null.
5003      * @param searchChar The character to find.
5004      * @param startPos   The start position.
5005      * @return The last index of the search character (always &le; startPos), -1 if no match or {@code null} string input.
5006      * @since 2.0
5007      * @since 3.0 Changed signature from lastIndexOf(String, int, int) to lastIndexOf(CharSequence, int, int)
5008      */
5009     public static int lastIndexOf(final CharSequence seq, final int searchChar, final int startPos) {
5010         if (isEmpty(seq)) {
5011             return INDEX_NOT_FOUND;
5012         }
5013         return CharSequenceUtils.lastIndexOf(seq, searchChar, startPos);
5014     }
5015 
5016     /**
5017      * Finds the latest index of any substring in a set of potential substrings.
5018      *
5019      * <p>
5020      * A {@code null} CharSequence will return {@code -1}. A {@code null} search array will return {@code -1}. A {@code null} or zero length search array entry
5021      * will be ignored, but a search array containing "" will return the length of {@code str} if {@code str} is not null. This method uses
5022      * {@link String#indexOf(String)} if possible
5023      * </p>
5024      *
5025      * <pre>
5026      * StringUtils.lastIndexOfAny(null, *)                    = -1
5027      * StringUtils.lastIndexOfAny(*, null)                    = -1
5028      * StringUtils.lastIndexOfAny(*, [])                      = -1
5029      * StringUtils.lastIndexOfAny(*, [null])                  = -1
5030      * StringUtils.lastIndexOfAny("zzabyycdxx", ["ab", "cd"]) = 6
5031      * StringUtils.lastIndexOfAny("zzabyycdxx", ["cd", "ab"]) = 6
5032      * StringUtils.lastIndexOfAny("zzabyycdxx", ["mn", "op"]) = -1
5033      * StringUtils.lastIndexOfAny("zzabyycdxx", ["mn", "op"]) = -1
5034      * StringUtils.lastIndexOfAny("zzabyycdxx", ["mn", ""])   = 10
5035      * </pre>
5036      *
5037      * @param str        The CharSequence to check, may be null.
5038      * @param searchStrs The CharSequences to search for, may be null.
5039      * @return The last index of any of the CharSequences, -1 if no match.
5040      * @since 3.0 Changed signature from lastIndexOfAny(String, String[]) to lastIndexOfAny(CharSequence, CharSequence)
5041      */
5042     public static int lastIndexOfAny(final CharSequence str, final CharSequence... searchStrs) {
5043         if (str == null || searchStrs == null) {
5044             return INDEX_NOT_FOUND;
5045         }
5046         int ret = INDEX_NOT_FOUND;
5047         int tmp;
5048         for (final CharSequence search : searchStrs) {
5049             if (search == null) {
5050                 continue;
5051             }
5052             tmp = CharSequenceUtils.lastIndexOf(str, search, str.length());
5053             if (tmp > ret) {
5054                 ret = tmp;
5055             }
5056         }
5057         return ret;
5058     }
5059 
5060     /**
5061      * Case insensitive find of the last index within a CharSequence.
5062      *
5063      * <p>
5064      * A {@code null} CharSequence will return {@code -1}. A negative start position returns {@code -1}. An empty ("") search CharSequence always matches unless
5065      * the start position is negative. A start position greater than the string length searches the whole string.
5066      * </p>
5067      *
5068      * <pre>
5069      * StringUtils.lastIndexOfIgnoreCase(null, *)          = -1
5070      * StringUtils.lastIndexOfIgnoreCase(*, null)          = -1
5071      * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "A")  = 7
5072      * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B")  = 5
5073      * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "AB") = 4
5074      * </pre>
5075      *
5076      * @param str       The CharSequence to check, may be null.
5077      * @param searchStr The CharSequence to find, may be null.
5078      * @return The first index of the search CharSequence, -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      * @deprecated Use {@link Strings#lastIndexOf(CharSequence, CharSequence) Strings.CI.lastIndexOf(CharSequence, CharSequence)}.
5082      */
5083     @Deprecated
5084     public static int lastIndexOfIgnoreCase(final CharSequence str, final CharSequence searchStr) {
5085         return Strings.CI.lastIndexOf(str, searchStr);
5086     }
5087 
5088     /**
5089      * Case insensitive find of the last index within a CharSequence from the specified position.
5090      *
5091      * <p>
5092      * A {@code null} CharSequence will return {@code -1}. A negative start position returns {@code -1}. An empty ("") search CharSequence always matches unless
5093      * the start position is negative. A start position greater than the string length searches the whole string. The search starts at the startPos and works
5094      * backwards; matches starting after the start position are ignored.
5095      * </p>
5096      *
5097      * <pre>
5098      * StringUtils.lastIndexOfIgnoreCase(null, *, *)          = -1
5099      * StringUtils.lastIndexOfIgnoreCase(*, null, *)          = -1
5100      * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "A", 8)  = 7
5101      * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B", 8)  = 5
5102      * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "AB", 8) = 4
5103      * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B", 9)  = 5
5104      * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B", -1) = -1
5105      * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "A", 0)  = 0
5106      * StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B", 0)  = -1
5107      * </pre>
5108      *
5109      * @param str       The CharSequence to check, may be null.
5110      * @param searchStr The CharSequence to find, may be null.
5111      * @param startPos  The start position.
5112      * @return The last index of the search CharSequence (always &le; startPos), -1 if no match or {@code null} input.
5113      * @since 2.5
5114      * @since 3.0 Changed signature from lastIndexOfIgnoreCase(String, String, int) to lastIndexOfIgnoreCase(CharSequence, CharSequence, int)
5115      * @deprecated Use {@link Strings#lastIndexOf(CharSequence, CharSequence, int) Strings.CI.lastIndexOf(CharSequence, CharSequence, int)}.
5116      */
5117     @Deprecated
5118     public static int lastIndexOfIgnoreCase(final CharSequence str, final CharSequence searchStr, final int startPos) {
5119         return Strings.CI.lastIndexOf(str, searchStr, startPos);
5120     }
5121 
5122     /**
5123      * Finds the n-th last index within a String, handling {@code null}. This method uses {@link String#lastIndexOf(String)}.
5124      *
5125      * <p>
5126      * A {@code null} String will return {@code -1}.
5127      * </p>
5128      *
5129      * <pre>
5130      * StringUtils.lastOrdinalIndexOf(null, *, *)          = -1
5131      * StringUtils.lastOrdinalIndexOf(*, null, *)          = -1
5132      * StringUtils.lastOrdinalIndexOf("", "", *)           = 0
5133      * StringUtils.lastOrdinalIndexOf("aabaabaa", "a", 1)  = 7
5134      * StringUtils.lastOrdinalIndexOf("aabaabaa", "a", 2)  = 6
5135      * StringUtils.lastOrdinalIndexOf("aabaabaa", "b", 1)  = 5
5136      * StringUtils.lastOrdinalIndexOf("aabaabaa", "b", 2)  = 2
5137      * StringUtils.lastOrdinalIndexOf("aabaabaa", "ab", 1) = 4
5138      * StringUtils.lastOrdinalIndexOf("aabaabaa", "ab", 2) = 1
5139      * StringUtils.lastOrdinalIndexOf("aabaabaa", "", 1)   = 8
5140      * StringUtils.lastOrdinalIndexOf("aabaabaa", "", 2)   = 8
5141      * </pre>
5142      *
5143      * <p>
5144      * Note that 'tail(CharSequence str, int n)' may be implemented as:
5145      * </p>
5146      *
5147      * <pre>
5148      * str.substring(lastOrdinalIndexOf(str, "\n", n) + 1)
5149      * </pre>
5150      *
5151      * @param str       The CharSequence to check, may be null.
5152      * @param searchStr The CharSequence to find, may be null.
5153      * @param ordinal   The n-th last {@code searchStr} to find.
5154      * @return The n-th last index of the search CharSequence, {@code -1} ({@code INDEX_NOT_FOUND}) if no match or {@code null} string input.
5155      * @since 2.5
5156      * @since 3.0 Changed signature from lastOrdinalIndexOf(String, String, int) to lastOrdinalIndexOf(CharSequence, CharSequence, int)
5157      */
5158     public static int lastOrdinalIndexOf(final CharSequence str, final CharSequence searchStr, final int ordinal) {
5159         return ordinalIndexOf(str, searchStr, ordinal, true);
5160     }
5161 
5162     /**
5163      * Gets the leftmost {@code len} characters of a String.
5164      *
5165      * <p>
5166      * If {@code len} characters are not available, or the String is {@code null}, the String will be returned without an exception. An empty String is returned
5167      * if len is negative.
5168      * </p>
5169      *
5170      * <pre>
5171      * StringUtils.left(null, *)    = null
5172      * StringUtils.left(*, -ve)     = ""
5173      * StringUtils.left("", *)      = ""
5174      * StringUtils.left("abc", 0)   = ""
5175      * StringUtils.left("abc", 2)   = "ab"
5176      * StringUtils.left("abc", 4)   = "abc"
5177      * </pre>
5178      *
5179      * @param str The String to get the leftmost characters from, may be null.
5180      * @param len The length of the required String.
5181      * @return The leftmost characters, {@code null} if null String input.
5182      */
5183     public static String left(final String str, final int len) {
5184         if (str == null) {
5185             return null;
5186         }
5187         if (len < 0) {
5188             return EMPTY;
5189         }
5190         if (str.length() <= len) {
5191             return str;
5192         }
5193         int cut = len;
5194         // keep the cut off the middle of a surrogate pair so the result is never left holding a lone surrogate
5195         if (splitsSurrogatePair(str, cut)) {
5196             cut--;
5197         }
5198         return str.substring(0, cut);
5199     }
5200 
5201     /**
5202      * Left pad a String with spaces (' ').
5203      *
5204      * <p>
5205      * The String is padded to the size of {@code size}.
5206      * </p>
5207      *
5208      * <pre>
5209      * StringUtils.leftPad(null, *)   = null
5210      * StringUtils.leftPad("", 3)     = "   "
5211      * StringUtils.leftPad("bat", 3)  = "bat"
5212      * StringUtils.leftPad("bat", 5)  = "  bat"
5213      * StringUtils.leftPad("bat", 1)  = "bat"
5214      * StringUtils.leftPad("bat", -1) = "bat"
5215      * </pre>
5216      *
5217      * @param str  The String to pad out, may be null.
5218      * @param size The size to pad to.
5219      * @return left padded String or original String if no padding is necessary, {@code null} if null String input.
5220      */
5221     public static String leftPad(final String str, final int size) {
5222         return leftPad(str, size, ' ');
5223     }
5224 
5225     /**
5226      * Left pad a String with a specified character.
5227      *
5228      * <p>
5229      * Pad to a size of {@code size}.
5230      * </p>
5231      *
5232      * <pre>
5233      * StringUtils.leftPad(null, *, *)     = null
5234      * StringUtils.leftPad("", 3, 'z')     = "zzz"
5235      * StringUtils.leftPad("bat", 3, 'z')  = "bat"
5236      * StringUtils.leftPad("bat", 5, 'z')  = "zzbat"
5237      * StringUtils.leftPad("bat", 1, 'z')  = "bat"
5238      * StringUtils.leftPad("bat", -1, 'z') = "bat"
5239      * </pre>
5240      *
5241      * @param str     The String to pad out, may be null.
5242      * @param size    The size to pad to.
5243      * @param padChar The character to pad with.
5244      * @return left padded String or original String if no padding is necessary, {@code null} if null String input.
5245      * @since 2.0
5246      */
5247     public static String leftPad(final String str, final int size, final char padChar) {
5248         if (str == null || size <= str.length()) {
5249             return str;
5250         }
5251         final int pads = size - str.length();
5252         if (pads <= 0) {
5253             return str; // returns original String when possible
5254         }
5255         if (pads > PAD_LIMIT) {
5256             return leftPad(str, size, String.valueOf(padChar));
5257         }
5258         return repeat(padChar, pads).concat(str);
5259     }
5260 
5261     /**
5262      * Left pad a String with a specified String.
5263      *
5264      * <p>
5265      * Pad to a size of {@code size}. If the requested padding length would split a Unicode surrogate pair in {@code padStr},
5266      * the padding is shortened by one {@code char} to avoid introducing an unpaired surrogate by splitting the pair. In that case, the
5267      * returned String has a length of {@code size - 1}.
5268      * </p>
5269      *
5270      * <pre>
5271      * StringUtils.leftPad(null, *, *)      = null
5272      * StringUtils.leftPad("", 3, "z")      = "zzz"
5273      * StringUtils.leftPad("bat", 3, "yz")  = "bat"
5274      * StringUtils.leftPad("bat", 5, "yz")  = "yzbat"
5275      * StringUtils.leftPad("bat", 8, "yz")  = "yzyzybat"
5276      * StringUtils.leftPad("bat", 1, "yz")  = "bat"
5277      * StringUtils.leftPad("bat", -1, "yz") = "bat"
5278      * StringUtils.leftPad("bat", 5, null)  = "  bat"
5279      * StringUtils.leftPad("bat", 5, "")    = "  bat"
5280      * StringUtils.leftPad("a", 2, "\uD83D\uDE00")    = "a"
5281      * StringUtils.leftPad("a", 3, "\uD83D\uDE00")    = "\uD83D\uDE00a"
5282      * </pre>
5283      *
5284      * @param str    The String to pad out, may be null.
5285      * @param size   The size to pad to.
5286      * @param padStr The String to pad with, null or empty treated as single space.
5287      * @return left padded String or original String if no padding is necessary, {@code null} if null String input.
5288      */
5289     public static String leftPad(final String str, final int size, String padStr) {
5290         if (str == null || size <= str.length()) {
5291             return str;
5292         }
5293         if (isEmpty(padStr)) {
5294             padStr = SPACE;
5295         }
5296         final int padLen = padStr.length();
5297         final int strLen = str.length();
5298         int pads = size - strLen;
5299         if (pads <= 0) {
5300             return str; // returns original String when possible
5301         }
5302         if (padLen == 1 && pads <= PAD_LIMIT) {
5303             return leftPad(str, size, padStr.charAt(0));
5304         }
5305         // Keep the padding boundary off the middle of a surrogate pair to avoid introducing a lone surrogate.
5306         if (splitsSurrogatePair(padStr, pads % padLen)) {
5307             pads--;
5308         }
5309         if (pads <= 0) {
5310             return str;
5311         }
5312         if (pads == padLen) {
5313             return padStr.concat(str);
5314         }
5315         if (pads < padLen) {
5316             return padStr.substring(0, pads).concat(str);
5317         }
5318         final char[] padding = new char[pads];
5319         final char[] padChars = padStr.toCharArray();
5320         for (int i = 0; i < pads; i++) {
5321             padding[i] = padChars[i % padLen];
5322         }
5323         return new String(padding).concat(str);
5324     }
5325 
5326     /**
5327      * Gets a CharSequence length or {@code 0} if the CharSequence is {@code null}.
5328      *
5329      * @param cs A CharSequence or {@code null}.
5330      * @return CharSequence length or {@code 0} if the CharSequence is {@code null}.
5331      * @since 2.4
5332      * @since 3.0 Changed signature from length(String) to length(CharSequence)
5333      */
5334     public static int length(final CharSequence cs) {
5335         return cs == null ? 0 : cs.length();
5336     }
5337 
5338     /**
5339      * Converts a String to lower case as per {@link String#toLowerCase()}.
5340      *
5341      * <p>
5342      * A {@code null} input String returns {@code null}.
5343      * </p>
5344      *
5345      * <pre>
5346      * StringUtils.lowerCase(null)  = null
5347      * StringUtils.lowerCase("")    = ""
5348      * StringUtils.lowerCase("aBc") = "abc"
5349      * </pre>
5350      *
5351      * <p>
5352      * <strong>Note:</strong> As described in the documentation for {@link String#toLowerCase()}, the result of this method is affected by the current locale.
5353      * For platform-independent case transformations, the method {@link #lowerCase(String, Locale)} should be used with a specific locale (e.g.
5354      * {@link Locale#ENGLISH}).
5355      * </p>
5356      *
5357      * @param str The String to lower case, may be null.
5358      * @return The lower cased String, {@code null} if null String input.
5359      */
5360     public static String lowerCase(final String str) {
5361         if (str == null) {
5362             return null;
5363         }
5364         return str.toLowerCase();
5365     }
5366 
5367     /**
5368      * Converts a String to lower case as per {@link String#toLowerCase(Locale)}.
5369      *
5370      * <p>
5371      * A {@code null} input String returns {@code null}.
5372      * </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>
5451      * If {@code len} characters are not available, the remainder of the String will be returned without an exception. If the String is {@code null},
5452      * {@code null} will be returned. An empty String is returned if len is negative or exceeds the length of {@code str}.
5453      * </p>
5454      *
5455      * <pre>
5456      * StringUtils.mid(null, *, *)    = null
5457      * StringUtils.mid(*, *, -ve)     = ""
5458      * StringUtils.mid("", 0, *)      = ""
5459      * StringUtils.mid("abc", 0, 2)   = "ab"
5460      * StringUtils.mid("abc", 0, 4)   = "abc"
5461      * StringUtils.mid("abc", 2, 4)   = "c"
5462      * StringUtils.mid("abc", 4, 2)   = ""
5463      * StringUtils.mid("abc", -2, 2)  = "ab"
5464      * </pre>
5465      *
5466      * @param str The String to get the characters from, may be null.
5467      * @param pos The position to start from, negative treated as zero.
5468      * @param len The length of the required String.
5469      * @return The middle characters, {@code null} if null String input.
5470      */
5471     public static String mid(final String str, int pos, final int len) {
5472         if (str == null) {
5473             return null;
5474         }
5475         if (len < 0 || pos > str.length()) {
5476             return EMPTY;
5477         }
5478         if (pos < 0) {
5479             pos = 0;
5480         }
5481         int start = pos;
5482         // keep the start off the middle of a surrogate pair so the result is never left holding a lone surrogate
5483         if (splitsSurrogatePair(str, start)) {
5484             start++;
5485         }
5486         if (str.length() - pos <= len) {
5487             return str.substring(start);
5488         }
5489         int end = pos + len;
5490         // keep both cuts off the middle of a surrogate pair so the result is never left holding a lone surrogate
5491         if (splitsSurrogatePair(str, end)) {
5492             end--;
5493         }
5494         return str.substring(start, Math.max(start, end));
5495     }
5496 
5497     /**
5498      * Normalizes whitespace in a String.
5499      *
5500      * <p>Removes leading and trailing whitespace and replaces each remaining sequence of characters recognized by {@link Character#isWhitespace(char)}
5501      * with a single ordinary space ({@code U+0020}). This includes Unicode whitespace beyond the characters matched by the default regular expression
5502      * {@code \s}, such as EM SPACE ({@code U+2003}).</p>
5503      *
5504      * <p>Additionally, converts each non-breaking space ({@code U+00A0}) to an ordinary space, even though {@link Character#isWhitespace(char)} excludes it.
5505      * These conversions do not collapse adjacent spaces: for example, <code>"a&#92;u00A0&#92;u00A0b"</code> becomes {@code "a  b"}. Finally,
5506      * {@link String#trim()} removes
5507      * leading and trailing characters whose values are at most {@code U+0020}, including converted non-breaking spaces. Other non-breaking spaces, such as
5508      * FIGURE SPACE ({@code U+2007}) and NARROW NO-BREAK SPACE ({@code U+202F}), are preserved.</p>
5509      *
5510      * <p>This method was inspired by XPath's
5511      * <a href="https://www.w3.org/TR/xpath/#function-normalize-space">normalize-space</a> function, but does not reproduce its behavior.
5512      * XPath normalizes only XML
5513      * whitespace ({@code U+0020}, {@code U+0009}, {@code U+000D}, and {@code U+000A}) and preserves non-breaking spaces. This method additionally normalizes
5514      * Java whitespace, converts {@code U+00A0}, and trims leading and trailing control characters as described above.</p>
5515      *
5516      * @param str The source String to normalize whitespaces from, may be null.
5517      * @return The modified string with whitespace normalized, {@code null} if null String input.
5518      * @see Character#isWhitespace(char)
5519      * @see #trim(String)
5520      * @see <a href="https://www.w3.org/TR/xpath/#function-normalize-space">https://www.w3.org/TR/xpath/#function-normalize-space</a>
5521      * @since 3.0
5522      */
5523     public static String normalizeSpace(final String str) {
5524         // LANG-1020: Improved performance significantly by normalizing manually instead of using regex
5525         // See https://github.com/librucha/commons-lang-normalizespaces-benchmark for performance test
5526         if (isEmpty(str)) {
5527             return str;
5528         }
5529         final int size = str.length();
5530         final char[] newChars = new char[size];
5531         int count = 0;
5532         int whitespacesCount = 0;
5533         boolean startWhitespaces = true;
5534         for (int i = 0; i < size; i++) {
5535             final char actualChar = str.charAt(i);
5536             final boolean isWhitespace = Character.isWhitespace(actualChar);
5537             if (isWhitespace) {
5538                 if (whitespacesCount == 0 && !startWhitespaces) {
5539                     newChars[count++] = SPACE.charAt(0);
5540                 }
5541                 whitespacesCount++;
5542             } else {
5543                 startWhitespaces = false;
5544                 newChars[count++] = actualChar == 160 ? 32 : actualChar;
5545                 whitespacesCount = 0;
5546             }
5547         }
5548         if (startWhitespaces) {
5549             return EMPTY;
5550         }
5551         return new String(newChars, 0, count - (whitespacesCount > 0 ? 1 : 0)).trim();
5552     }
5553 
5554     /**
5555      * Finds the n-th index within a CharSequence, handling {@code null}. This method uses {@link String#indexOf(String)} if possible.
5556      * <p>
5557      * <strong>Note:</strong> The code starts looking for a match at the start of the target, incrementing the starting index by one after each successful match
5558      * (unless {@code searchStr} is an empty string, in which case the position is never incremented and {@code 0} is returned immediately). This means that
5559      * matches may overlap.
5560      * </p>
5561      * <p>
5562      * A {@code null} CharSequence will return {@code -1}.
5563      * </p>
5564      *
5565      * <pre>
5566      * StringUtils.ordinalIndexOf(null, *, *)          = -1
5567      * StringUtils.ordinalIndexOf(*, null, *)          = -1
5568      * StringUtils.ordinalIndexOf("", "", *)           = 0
5569      * StringUtils.ordinalIndexOf("aabaabaa", "a", 1)  = 0
5570      * StringUtils.ordinalIndexOf("aabaabaa", "a", 2)  = 1
5571      * StringUtils.ordinalIndexOf("aabaabaa", "b", 1)  = 2
5572      * StringUtils.ordinalIndexOf("aabaabaa", "b", 2)  = 5
5573      * StringUtils.ordinalIndexOf("aabaabaa", "ab", 1) = 1
5574      * StringUtils.ordinalIndexOf("aabaabaa", "ab", 2) = 4
5575      * StringUtils.ordinalIndexOf("aabaabaa", "", 1)   = 0
5576      * StringUtils.ordinalIndexOf("aabaabaa", "", 2)   = 0
5577      * </pre>
5578      *
5579      * <p>
5580      * Matches may overlap:
5581      * </p>
5582      *
5583      * <pre>
5584      * StringUtils.ordinalIndexOf("ababab", "aba", 1)   = 0
5585      * StringUtils.ordinalIndexOf("ababab", "aba", 2)   = 2
5586      * StringUtils.ordinalIndexOf("ababab", "aba", 3)   = -1
5587      *
5588      * StringUtils.ordinalIndexOf("abababab", "abab", 1) = 0
5589      * StringUtils.ordinalIndexOf("abababab", "abab", 2) = 2
5590      * StringUtils.ordinalIndexOf("abababab", "abab", 3) = 4
5591      * StringUtils.ordinalIndexOf("abababab", "abab", 4) = -1
5592      * </pre>
5593      *
5594      * <p>
5595      * Note that 'head(CharSequence str, int n)' may be implemented as:
5596      * </p>
5597      *
5598      * <pre>
5599      * str.substring(0, lastOrdinalIndexOf(str, "\n", n))
5600      * </pre>
5601      *
5602      * @param str       The CharSequence to check, may be null.
5603      * @param searchStr The CharSequence to find, may be null.
5604      * @param ordinal   The n-th {@code searchStr} to find.
5605      * @return The n-th index of the search CharSequence, {@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}. This method uses {@link String#indexOf(String)} if possible.
5615      * <p>
5616      * Note that matches may overlap.
5617      * <p>
5618      *
5619      * <p>
5620      * A {@code null} CharSequence will return {@code -1}.
5621      * </p>
5622      *
5623      * @param str       The CharSequence to check, may be null.
5624      * @param searchStr The CharSequence to find, may be null.
5625      * @param ordinal   The n-th {@code searchStr} to find, overlapping matches are allowed.
5626      * @param lastIndex true if lastOrdinalIndexOf() otherwise false if ordinalIndexOf().
5627      * @return The n-th index of the search CharSequence, {@code -1} ({@code INDEX_NOT_FOUND}) if no match or {@code null} string input.
5628      */
5629     // Shared code between ordinalIndexOf(String, String, int) and lastOrdinalIndexOf(String, String, int)
5630     private static int ordinalIndexOf(final CharSequence str, final CharSequence searchStr, final int ordinal, final boolean lastIndex) {
5631         if (str == null || searchStr == null || ordinal <= 0) {
5632             return INDEX_NOT_FOUND;
5633         }
5634         if (isEmpty(searchStr)) {
5635             return lastIndex ? str.length() : 0;
5636         }
5637         int found = 0;
5638         // set the initial index beyond the end of the string
5639         // this is to allow for the initial index decrement/increment
5640         int index = lastIndex ? str.length() : INDEX_NOT_FOUND;
5641         do {
5642             if (lastIndex) {
5643                 index = CharSequenceUtils.lastIndexOf(str, searchStr, index - 1); // step backwards through string
5644             } else {
5645                 index = CharSequenceUtils.indexOf(str, searchStr, index + 1); // step forwards through string
5646             }
5647             if (index < 0) {
5648                 return index;
5649             }
5650             found++;
5651         } while (found < ordinal);
5652         return index;
5653     }
5654 
5655     /**
5656      * Overlays part of a String with another String.
5657      *
5658      * <p>
5659      * A {@code null} string input returns {@code null}. A negative index is treated as zero. An index greater than the string length is treated as the string
5660      * length. The start index is always the smaller of the two indices.
5661      * </p>
5662      *
5663      * <pre>
5664      * StringUtils.overlay(null, *, *, *)            = null
5665      * StringUtils.overlay("", "abc", 0, 0)          = "abc"
5666      * StringUtils.overlay("abcdef", null, 2, 4)     = "abef"
5667      * StringUtils.overlay("abcdef", "", 2, 4)       = "abef"
5668      * StringUtils.overlay("abcdef", "", 4, 2)       = "abef"
5669      * StringUtils.overlay("abcdef", "zzzz", 2, 4)   = "abzzzzef"
5670      * StringUtils.overlay("abcdef", "zzzz", 4, 2)   = "abzzzzef"
5671      * StringUtils.overlay("abcdef", "zzzz", -1, 4)  = "zzzzef"
5672      * StringUtils.overlay("abcdef", "zzzz", 2, 8)   = "abzzzz"
5673      * StringUtils.overlay("abcdef", "zzzz", -2, -3) = "zzzzabcdef"
5674      * StringUtils.overlay("abcdef", "zzzz", 8, 10)  = "abcdefzzzz"
5675      * </pre>
5676      *
5677      * @param str     The String to do overlaying in, may be null.
5678      * @param overlay The String to overlay, may be null.
5679      * @param start   The position to start overlaying at.
5680      * @param end     The position to stop overlaying before.
5681      * @return overlaid String, {@code null} if null String input.
5682      * @since 2.0
5683      */
5684     public static String overlay(final String str, String overlay, int start, int end) {
5685         if (str == null) {
5686             return null;
5687         }
5688         if (overlay == null) {
5689             overlay = EMPTY;
5690         }
5691         final int len = str.length();
5692         if (start < 0) {
5693             start = 0;
5694         }
5695         if (start > len) {
5696             start = len;
5697         }
5698         if (end < 0) {
5699             end = 0;
5700         }
5701         if (end > len) {
5702             end = len;
5703         }
5704         if (start > end) {
5705             final int temp = start;
5706             start = end;
5707             end = temp;
5708         }
5709         // keep both cuts off the middle of a surrogate pair so the result is never left holding a lone surrogate
5710         if (splitsSurrogatePair(str, start)) {
5711             start--;
5712         }
5713         if (splitsSurrogatePair(str, end)) {
5714             end++;
5715         }
5716         return str.substring(0, start) + overlay + str.substring(end);
5717     }
5718 
5719     /**
5720      * Prepends the prefix to the start of the string if the string does not already start with any of the prefixes.
5721      *
5722      * <pre>
5723      * StringUtils.prependIfMissing(null, null) = null
5724      * StringUtils.prependIfMissing("abc", null) = "abc"
5725      * StringUtils.prependIfMissing("", "xyz") = "xyz"
5726      * StringUtils.prependIfMissing("abc", "xyz") = "xyzabc"
5727      * StringUtils.prependIfMissing("xyzabc", "xyz") = "xyzabc"
5728      * StringUtils.prependIfMissing("XYZabc", "xyz") = "xyzXYZabc"
5729      * </pre>
5730      * <p>
5731      * With additional prefixes,
5732      * </p>
5733      *
5734      * <pre>
5735      * StringUtils.prependIfMissing(null, null, null) = null
5736      * StringUtils.prependIfMissing("abc", null, null) = "abc"
5737      * StringUtils.prependIfMissing("", "xyz", null) = "xyz"
5738      * StringUtils.prependIfMissing("abc", "xyz", new CharSequence[]{null}) = "xyzabc"
5739      * StringUtils.prependIfMissing("abc", "xyz", "") = "abc"
5740      * StringUtils.prependIfMissing("abc", "xyz", "mno") = "xyzabc"
5741      * StringUtils.prependIfMissing("xyzabc", "xyz", "mno") = "xyzabc"
5742      * StringUtils.prependIfMissing("mnoabc", "xyz", "mno") = "mnoabc"
5743      * StringUtils.prependIfMissing("XYZabc", "xyz", "mno") = "xyzXYZabc"
5744      * StringUtils.prependIfMissing("MNOabc", "xyz", "mno") = "xyzMNOabc"
5745      * </pre>
5746      *
5747      * @param str      The string.
5748      * @param prefix   The prefix to prepend to the start of the string.
5749      * @param prefixes Additional prefixes that are valid.
5750      * @return A new String if prefix was prepended, the same string otherwise.
5751      * @since 3.2
5752      * @deprecated Use {@link Strings#prependIfMissing(String, CharSequence, CharSequence...) Strings.CS.prependIfMissing(String, CharSequence,
5753      *             CharSequence...)}.
5754      */
5755     @Deprecated
5756     public static String prependIfMissing(final String str, final CharSequence prefix, final CharSequence... prefixes) {
5757         return Strings.CS.prependIfMissing(str, prefix, prefixes);
5758     }
5759 
5760     /**
5761      * Prepends the prefix to the start of the string if the string does not already start, case-insensitive, with any of the prefixes.
5762      *
5763      * <pre>
5764      * StringUtils.prependIfMissingIgnoreCase(null, null) = null
5765      * StringUtils.prependIfMissingIgnoreCase("abc", null) = "abc"
5766      * StringUtils.prependIfMissingIgnoreCase("", "xyz") = "xyz"
5767      * StringUtils.prependIfMissingIgnoreCase("abc", "xyz") = "xyzabc"
5768      * StringUtils.prependIfMissingIgnoreCase("xyzabc", "xyz") = "xyzabc"
5769      * StringUtils.prependIfMissingIgnoreCase("XYZabc", "xyz") = "XYZabc"
5770      * </pre>
5771      * <p>
5772      * With additional prefixes,
5773      * </p>
5774      *
5775      * <pre>
5776      * StringUtils.prependIfMissingIgnoreCase(null, null, null) = null
5777      * StringUtils.prependIfMissingIgnoreCase("abc", null, null) = "abc"
5778      * StringUtils.prependIfMissingIgnoreCase("", "xyz", null) = "xyz"
5779      * StringUtils.prependIfMissingIgnoreCase("abc", "xyz", new CharSequence[]{null}) = "xyzabc"
5780      * StringUtils.prependIfMissingIgnoreCase("abc", "xyz", "") = "abc"
5781      * StringUtils.prependIfMissingIgnoreCase("abc", "xyz", "mno") = "xyzabc"
5782      * StringUtils.prependIfMissingIgnoreCase("xyzabc", "xyz", "mno") = "xyzabc"
5783      * StringUtils.prependIfMissingIgnoreCase("mnoabc", "xyz", "mno") = "mnoabc"
5784      * StringUtils.prependIfMissingIgnoreCase("XYZabc", "xyz", "mno") = "XYZabc"
5785      * StringUtils.prependIfMissingIgnoreCase("MNOabc", "xyz", "mno") = "MNOabc"
5786      * </pre>
5787      *
5788      * @param str      The string.
5789      * @param prefix   The prefix to prepend to the start of the string.
5790      * @param prefixes Additional prefixes that are valid (optional).
5791      * @return A new String if prefix was prepended, the same string otherwise.
5792      * @since 3.2
5793      * @deprecated Use {@link Strings#prependIfMissing(String, CharSequence, CharSequence...) Strings.CI.prependIfMissing(String, CharSequence,
5794      *             CharSequence...)}.
5795      */
5796     @Deprecated
5797     public static String prependIfMissingIgnoreCase(final String str, final CharSequence prefix, final CharSequence... prefixes) {
5798         return Strings.CI.prependIfMissing(str, prefix, prefixes);
5799     }
5800 
5801     /**
5802      * Removes all occurrences of a character from within the source string.
5803      *
5804      * <p>
5805      * A {@code null} source string will return {@code null}. An empty ("") source string will return the empty string.
5806      * </p>
5807      *
5808      * <pre>
5809      * StringUtils.remove(null, *)       = null
5810      * StringUtils.remove("", *)         = ""
5811      * StringUtils.remove("queued", 'u') = "qeed"
5812      * StringUtils.remove("queued", 'z') = "queued"
5813      * </pre>
5814      *
5815      * @param str    The source String to search, may be null.
5816      * @param remove The char to search for and remove, may be null.
5817      * @return The substring with the char removed if found, {@code null} if null String input.
5818      * @since 2.1
5819      */
5820     public static String remove(final String str, final char remove) {
5821         if (isEmpty(str) || str.indexOf(remove) == INDEX_NOT_FOUND) {
5822             return str;
5823         }
5824         final char[] chars = str.toCharArray();
5825         int pos = 0;
5826         for (int i = 0; i < chars.length; i++) {
5827             if (chars[i] != remove) {
5828                 chars[pos++] = chars[i];
5829             }
5830         }
5831         return new String(chars, 0, pos);
5832     }
5833 
5834     /**
5835      * Removes all occurrences of a substring from within the source string.
5836      *
5837      * <p>
5838      * A {@code null} source string will return {@code null}. An empty ("") source string will return the empty string. A {@code null} remove string will return
5839      * the source string. An empty ("") remove string will return the source string.
5840      * </p>
5841      *
5842      * <pre>
5843      * StringUtils.remove(null, *)        = null
5844      * StringUtils.remove("", *)          = ""
5845      * StringUtils.remove(*, null)        = *
5846      * StringUtils.remove(*, "")          = *
5847      * StringUtils.remove("queued", "ue") = "qd"
5848      * StringUtils.remove("queued", "zz") = "queued"
5849      * </pre>
5850      *
5851      * @param str    The source String to search, may be null.
5852      * @param remove The String to search for and remove, may be null.
5853      * @return The substring with the string removed if found, {@code null} if null String input.
5854      * @since 2.1
5855      * @deprecated Use {@link Strings#remove(String, String) Strings.CS.remove(String, String)}.
5856      */
5857     @Deprecated
5858     public static String remove(final String str, final String remove) {
5859         return Strings.CS.remove(str, remove);
5860     }
5861 
5862     /**
5863      * Removes each substring of the text String that matches the given regular expression.
5864      *
5865      * This method is a {@code null} safe equivalent to:
5866      * <ul>
5867      * <li>{@code text.replaceAll(regex, StringUtils.EMPTY)}</li>
5868      * <li>{@code Pattern.compile(regex).matcher(text).replaceAll(StringUtils.EMPTY)}</li>
5869      * </ul>
5870      *
5871      * <p>
5872      * A {@code null} reference passed to this method is a no-op.
5873      * </p>
5874      *
5875      * <p>
5876      * Unlike in the {@link #removePattern(String, String)} method, the {@link Pattern#DOTALL} option is NOT automatically added. To use the DOTALL option
5877      * prepend {@code "(?s)"} to the regex. DOTALL is also known as single-line mode in Perl.
5878      * </p>
5879      *
5880      * <pre>{@code
5881      * StringUtils.removeAll(null, *)      = null
5882      * StringUtils.removeAll("any", (String) null)  = "any"
5883      * StringUtils.removeAll("any", "")    = "any"
5884      * StringUtils.removeAll("any", ".*")  = ""
5885      * StringUtils.removeAll("any", ".+")  = ""
5886      * StringUtils.removeAll("abc", ".?")  = ""
5887      * StringUtils.removeAll("A<__>\n<__>B", "<.*>")      = "A\nB"
5888      * StringUtils.removeAll("A<__>\n<__>B", "(?s)<.*>")  = "AB"
5889      * StringUtils.removeAll("ABCabc123abc", "[a-z]")     = "ABC123"
5890      * }</pre>
5891      *
5892      * @param text  text to remove from, may be null.
5893      * @param regex The regular expression to which this string is to be matched.
5894      * @return The text with any removes processed, {@code null} if null String input.
5895      * @throws java.util.regex.PatternSyntaxException Thrown if the regular expression's syntax is invalid.
5896      * @see #replaceAll(String, String, String)
5897      * @see #removePattern(String, String)
5898      * @see String#replaceAll(String, String)
5899      * @see java.util.regex.Pattern
5900      * @see java.util.regex.Pattern#DOTALL
5901      * @since 3.5
5902      * @deprecated Use {@link RegExUtils#removeAll(String, String)}.
5903      */
5904     @Deprecated
5905     public static String removeAll(final String text, final String regex) {
5906         return RegExUtils.removeAll(text, regex);
5907     }
5908 
5909     /**
5910      * Removes a substring only if it is at the end of a source string, otherwise returns the source string.
5911      *
5912      * <p>
5913      * A {@code null} source string will return {@code null}. An empty ("") source string will return the empty string. A {@code null} search string will return
5914      * the source string.
5915      * </p>
5916      *
5917      * <pre>
5918      * StringUtils.removeEnd(null, *)      = null
5919      * StringUtils.removeEnd("", *)        = ""
5920      * StringUtils.removeEnd(*, null)      = *
5921      * StringUtils.removeEnd("www.domain.com", ".com.")  = "www.domain.com"
5922      * StringUtils.removeEnd("www.domain.com", ".com")   = "www.domain"
5923      * StringUtils.removeEnd("www.domain.com", "domain") = "www.domain.com"
5924      * StringUtils.removeEnd("abc", "")    = "abc"
5925      * </pre>
5926      *
5927      * @param str    The source String to search, may be null.
5928      * @param remove The String to search for and remove, may be null.
5929      * @return The substring with the string removed if found, {@code null} if null String input.
5930      * @since 2.1
5931      * @deprecated Use {@link Strings#removeEnd(String, CharSequence) Strings.CS.removeEnd(String, CharSequence)}.
5932      */
5933     @Deprecated
5934     public static String removeEnd(final String str, final String remove) {
5935         return Strings.CS.removeEnd(str, remove);
5936     }
5937 
5938     /**
5939      * Case-insensitive removal of a substring if it is at the end of a source string, otherwise returns the source string.
5940      *
5941      * <p>
5942      * A {@code null} source string will return {@code null}. An empty ("") source string will return the empty string. A {@code null} search string will return
5943      * the source string.
5944      * </p>
5945      *
5946      * <pre>
5947      * StringUtils.removeEndIgnoreCase(null, *)      = null
5948      * StringUtils.removeEndIgnoreCase("", *)        = ""
5949      * StringUtils.removeEndIgnoreCase(*, null)      = *
5950      * StringUtils.removeEndIgnoreCase("www.domain.com", ".com.")  = "www.domain.com"
5951      * StringUtils.removeEndIgnoreCase("www.domain.com", ".com")   = "www.domain"
5952      * StringUtils.removeEndIgnoreCase("www.domain.com", "domain") = "www.domain.com"
5953      * StringUtils.removeEndIgnoreCase("abc", "")    = "abc"
5954      * StringUtils.removeEndIgnoreCase("www.domain.com", ".COM") = "www.domain"
5955      * StringUtils.removeEndIgnoreCase("www.domain.COM", ".com") = "www.domain"
5956      * </pre>
5957      *
5958      * @param str    The source String to search, may be null.
5959      * @param remove The String to search for (case-insensitive) and remove, may be null.
5960      * @return The substring with the string removed if found, {@code null} if null String input.
5961      * @since 2.4
5962      * @deprecated Use {@link Strings#removeEnd(String, CharSequence) Strings.CI.removeEnd(String, CharSequence)}.
5963      */
5964     @Deprecated
5965     public static String removeEndIgnoreCase(final String str, final String remove) {
5966         return Strings.CI.removeEnd(str, remove);
5967     }
5968 
5969     /**
5970      * Removes the first substring of the text string that matches the given regular expression.
5971      *
5972      * This method is a {@code null} safe equivalent to:
5973      * <ul>
5974      * <li>{@code text.replaceFirst(regex, StringUtils.EMPTY)}</li>
5975      * <li>{@code Pattern.compile(regex).matcher(text).replaceFirst(StringUtils.EMPTY)}</li>
5976      * </ul>
5977      *
5978      * <p>
5979      * A {@code null} reference passed to this method is a no-op.
5980      * </p>
5981      *
5982      * <p>
5983      * The {@link Pattern#DOTALL} option is NOT automatically added. To use the DOTALL option prepend {@code "(?s)"} to the regex. DOTALL is also known as
5984      * single-line mode in Perl.
5985      * </p>
5986      *
5987      * <pre>{@code
5988      * StringUtils.removeFirst(null, *)      = null
5989      * StringUtils.removeFirst("any", (String) null)  = "any"
5990      * StringUtils.removeFirst("any", "")    = "any"
5991      * StringUtils.removeFirst("any", ".*")  = ""
5992      * StringUtils.removeFirst("any", ".+")  = ""
5993      * StringUtils.removeFirst("abc", ".?")  = "bc"
5994      * StringUtils.removeFirst("A<__>\n<__>B", "<.*>")      = "A\n<__>B"
5995      * StringUtils.removeFirst("A<__>\n<__>B", "(?s)<.*>")  = "AB"
5996      * StringUtils.removeFirst("ABCabc123", "[a-z]")          = "ABCbc123"
5997      * StringUtils.removeFirst("ABCabc123abc", "[a-z]+")      = "ABC123abc"
5998      * }</pre>
5999      *
6000      * @param text  text to remove from, may be null.
6001      * @param regex The regular expression to which this string is to be matched.
6002      * @return The text with the first replacement processed, {@code null} if null String input.
6003      * @throws java.util.regex.PatternSyntaxException Thrown if the regular expression's syntax is invalid.
6004      * @see #replaceFirst(String, String, String)
6005      * @see String#replaceFirst(String, String)
6006      * @see java.util.regex.Pattern
6007      * @see java.util.regex.Pattern#DOTALL
6008      * @since 3.5
6009      * @deprecated Use {@link RegExUtils#replaceFirst(String, String, String) RegExUtils.replaceFirst(String, String, EMPTY)}.
6010      */
6011     @Deprecated
6012     public static String removeFirst(final String text, final String regex) {
6013         return replaceFirst(text, regex, EMPTY);
6014     }
6015 
6016     /**
6017      * Case-insensitive removal of all occurrences of a substring from within the source string.
6018      *
6019      * <p>
6020      * A {@code null} source string will return {@code null}. An empty ("") source string will return the empty string. A {@code null} remove string will return
6021      * the source string. An empty ("") remove string will return the source string.
6022      * </p>
6023      *
6024      * <pre>
6025      * StringUtils.removeIgnoreCase(null, *)        = null
6026      * StringUtils.removeIgnoreCase("", *)          = ""
6027      * StringUtils.removeIgnoreCase(*, null)        = *
6028      * StringUtils.removeIgnoreCase(*, "")          = *
6029      * StringUtils.removeIgnoreCase("queued", "ue") = "qd"
6030      * StringUtils.removeIgnoreCase("queued", "zz") = "queued"
6031      * StringUtils.removeIgnoreCase("quEUed", "UE") = "qd"
6032      * StringUtils.removeIgnoreCase("queued", "zZ") = "queued"
6033      * </pre>
6034      *
6035      * @param str    The source String to search, may be null.
6036      * @param remove The String to search for (case-insensitive) and remove, may be null.
6037      * @return The substring with the string removed if found, {@code null} if null String input.
6038      * @since 3.5
6039      * @deprecated Use {@link Strings#remove(String, String) Strings.CI.remove(String, String)}.
6040      */
6041     @Deprecated
6042     public static String removeIgnoreCase(final String str, final String remove) {
6043         return Strings.CI.remove(str, remove);
6044     }
6045 
6046     /**
6047      * Removes each substring of the source String that matches the given regular expression using the DOTALL option.
6048      *
6049      * This call is a {@code null} safe equivalent to:
6050      * <ul>
6051      * <li>{@code source.replaceAll(&quot;(?s)&quot; + regex, StringUtils.EMPTY)}</li>
6052      * <li>{@code Pattern.compile(regex, Pattern.DOTALL).matcher(source).replaceAll(StringUtils.EMPTY)}</li>
6053      * </ul>
6054      *
6055      * <p>
6056      * A {@code null} reference passed to this method is a no-op.
6057      * </p>
6058      *
6059      * <pre>{@code
6060      * StringUtils.removePattern(null, *)       = null
6061      * StringUtils.removePattern("any", (String) null)   = "any"
6062      * StringUtils.removePattern("A<__>\n<__>B", "<.*>")  = "AB"
6063      * StringUtils.removePattern("ABCabc123", "[a-z]")    = "ABC123"
6064      * }</pre>
6065      *
6066      * @param source The source string.
6067      * @param regex  The regular expression to which this string is to be matched.
6068      * @return The resulting {@link String}.
6069      * @see #replacePattern(String, String, String)
6070      * @see String#replaceAll(String, String)
6071      * @see Pattern#DOTALL
6072      * @since 3.2
6073      * @since 3.5 Changed {@code null} reference passed to this method is a no-op.
6074      * @deprecated Use {@link RegExUtils#removePattern(CharSequence, String)}.
6075      */
6076     @Deprecated
6077     public static String removePattern(final String source, final String regex) {
6078         return RegExUtils.removePattern(source, regex);
6079     }
6080 
6081     /**
6082      * Removes a char only if it is at the beginning of a source string, otherwise returns the source string.
6083      *
6084      * <p>
6085      * A {@code null} source string will return {@code null}. An empty ("") source string will return the empty string.
6086      * </p>
6087      *
6088      * <pre>
6089      * StringUtils.removeStart(null, *)      = null
6090      * StringUtils.removeStart("", *)        = ""
6091      * StringUtils.removeStart("/path", '/') = "path"
6092      * StringUtils.removeStart("path", '/')  = "path"
6093      * StringUtils.removeStart("path", '\0') = "path"
6094      * </pre>
6095      *
6096      * @param str    The source String to search, may be null.
6097      * @param remove The char to search for and remove.
6098      * @return The substring with the char removed if found, {@code null} if null String input.
6099      * @since 3.13.0
6100      */
6101     public static String removeStart(final String str, final char remove) {
6102         if (isEmpty(str)) {
6103             return str;
6104         }
6105         return str.charAt(0) == remove ? str.substring(1) : str;
6106     }
6107 
6108     /**
6109      * Removes a substring only if it is at the beginning of a source string, otherwise returns the source string.
6110      *
6111      * <p>
6112      * A {@code null} source string will return {@code null}. An empty ("") source string will return the empty string. A {@code null} search string will return
6113      * the source string.
6114      * </p>
6115      *
6116      * <pre>
6117      * StringUtils.removeStart(null, *)                    = null
6118      * StringUtils.removeStart("", *)                      = ""
6119      * StringUtils.removeStart(*, null)                    = *
6120      * StringUtils.removeStart("www.domain.com", "www.")   = "domain.com"
6121      * StringUtils.removeStart("domain.com", "www.")       = "domain.com"
6122      * StringUtils.removeStart("www.domain.com", "domain") = "www.domain.com"
6123      * StringUtils.removeStart("abc", "")                  = "abc"
6124      * </pre>
6125      *
6126      * @param str    The source String to search, may be null.
6127      * @param remove The String to search for and remove, may be null.
6128      * @return The substring with the string removed if found, {@code null} if null String input.
6129      * @since 2.1
6130      * @deprecated Use {@link Strings#removeStart(String, CharSequence) Strings.CS.removeStart(String, CharSequence)}.
6131      */
6132     @Deprecated
6133     public static String removeStart(final String str, final String remove) {
6134         return Strings.CS.removeStart(str, remove);
6135     }
6136 
6137     /**
6138      * Case-insensitive removal of a substring if it is at the beginning of a source string, otherwise returns the source string.
6139      *
6140      * <p>
6141      * A {@code null} source string will return {@code null}. An empty ("") source string will return the empty string. A {@code null} search string will return
6142      * the source string.
6143      * </p>
6144      *
6145      * <pre>
6146      * StringUtils.removeStartIgnoreCase(null, *)                    = null
6147      * StringUtils.removeStartIgnoreCase("", *)                      = ""
6148      * StringUtils.removeStartIgnoreCase(*, null)                    = *
6149      * StringUtils.removeStartIgnoreCase("www.domain.com", "www.")   = "domain.com"
6150      * StringUtils.removeStartIgnoreCase("www.domain.com", "WWW.")   = "domain.com"
6151      * StringUtils.removeStartIgnoreCase("domain.com", "www.")       = "domain.com"
6152      * StringUtils.removeStartIgnoreCase("www.domain.com", "domain") = "www.domain.com"
6153      * StringUtils.removeStartIgnoreCase("abc", "")                  = "abc"
6154      * </pre>
6155      *
6156      * @param str    The source String to search, may be null.
6157      * @param remove The String to search for (case-insensitive) and remove, may be null.
6158      * @return The substring with the string removed if found, {@code null} if null String input.
6159      * @since 2.4
6160      * @deprecated Use {@link Strings#removeStart(String, CharSequence) Strings.CI.removeStart(String, CharSequence)}.
6161      */
6162     @Deprecated
6163     public static String removeStartIgnoreCase(final String str, final String remove) {
6164         return Strings.CI.removeStart(str, remove);
6165     }
6166 
6167     /**
6168      * Returns padding using the specified delimiter repeated to a given length.
6169      *
6170      * <pre>
6171      * StringUtils.repeat('e', 0)  = ""
6172      * StringUtils.repeat('e', 3)  = "eee"
6173      * StringUtils.repeat('e', -2) = ""
6174      * </pre>
6175      *
6176      * <p>
6177      * Note: this method does not support padding with <a href="https://www.unicode.org/glossary/#supplementary_character">Unicode Supplementary Characters</a>
6178      * as they require a pair of {@code char}s to be represented. If you are needing to support full I18N of your applications consider using
6179      * {@link #repeat(String, int)} instead.
6180      * </p>
6181      *
6182      * @param repeat character to repeat.
6183      * @param count  number of times to repeat char, negative treated as zero.
6184      * @return String with repeated character.
6185      * @see #repeat(String, int)
6186      */
6187     public static String repeat(final char repeat, final int count) {
6188         if (count <= 0) {
6189             return EMPTY;
6190         }
6191         return new String(ArrayFill.fill(new char[count], repeat));
6192     }
6193 
6194     /**
6195      * Repeats a String {@code repeat} times to form a new String.
6196      *
6197      * <pre>
6198      * StringUtils.repeat(null, 2) = null
6199      * StringUtils.repeat("", 0)   = ""
6200      * StringUtils.repeat("", 2)   = ""
6201      * StringUtils.repeat("a", 3)  = "aaa"
6202      * StringUtils.repeat("ab", 2) = "abab"
6203      * StringUtils.repeat("a", -2) = ""
6204      * </pre>
6205      *
6206      * @param repeat The String to repeat, may be null.
6207      * @param count  number of times to repeat str, negative treated as zero.
6208      * @return A new String consisting of the original String repeated, {@code null} if null String input.
6209      */
6210     public static String repeat(final String repeat, final int count) {
6211         // Performance tuned for 2.0 (JDK1.4)
6212         if (repeat == null) {
6213             return null;
6214         }
6215         if (count <= 0) {
6216             return EMPTY;
6217         }
6218         final int inputLength = repeat.length();
6219         if (count == 1 || inputLength == 0) {
6220             return repeat;
6221         }
6222         if (inputLength == 1 && count <= PAD_LIMIT) {
6223             return repeat(repeat.charAt(0), count);
6224         }
6225         final int outputLength;
6226         try {
6227             outputLength = Math.multiplyExact(inputLength, count);
6228         } catch (final Exception e) {
6229             throw new IllegalArgumentException("The requested result is too large for a String.");
6230         }
6231         switch (inputLength) {
6232         case 1:
6233             return repeat(repeat.charAt(0), count);
6234         case 2:
6235             final char ch0 = repeat.charAt(0);
6236             final char ch1 = repeat.charAt(1);
6237             final char[] output2 = new char[outputLength];
6238             for (int i = count * 2 - 2; i >= 0; i--, i--) {
6239                 output2[i] = ch0;
6240                 output2[i + 1] = ch1;
6241             }
6242             return new String(output2);
6243         default:
6244             final StringBuilder buf = new StringBuilder(outputLength);
6245             for (int i = 0; i < count; i++) {
6246                 buf.append(repeat);
6247             }
6248             return buf.toString();
6249         }
6250     }
6251 
6252     /**
6253      * Repeats a String {@code repeat} times to form a new String, with a String separator injected each time.
6254      *
6255      * <pre>
6256      * StringUtils.repeat(null, null, 2) = null
6257      * StringUtils.repeat(null, "x", 2)  = null
6258      * StringUtils.repeat("", null, 0)   = ""
6259      * StringUtils.repeat("", "", 2)     = ""
6260      * StringUtils.repeat("", "x", 3)    = "xx"
6261      * StringUtils.repeat("?", ", ", 3)  = "?, ?, ?"
6262      * </pre>
6263      *
6264      * @param repeat    The String to repeat, may be null.
6265      * @param separator The String to inject, may be null.
6266      * @param count     number of times to repeat str, negative treated as zero.
6267      * @return A new String consisting of the original String repeated, {@code null} if null String input.
6268      * @since 2.5
6269      */
6270     public static String repeat(final String repeat, final String separator, final int count) {
6271         if (repeat == null || separator == null) {
6272             return repeat(repeat, count);
6273         }
6274         // given that repeat(String, int) is quite optimized, better to rely on it than try and splice this into it
6275         final String result = repeat(repeat + separator, count);
6276         return Strings.CS.removeEnd(result, separator);
6277     }
6278 
6279     /**
6280      * Replaces all occurrences of a String within another String.
6281      *
6282      * <p>
6283      * A {@code null} reference passed to this method is a no-op.
6284      * </p>
6285      *
6286      * <pre>
6287      * StringUtils.replace(null, *, *)        = null
6288      * StringUtils.replace("", *, *)          = ""
6289      * StringUtils.replace("any", null, *)    = "any"
6290      * StringUtils.replace("any", *, null)    = "any"
6291      * StringUtils.replace("any", "", *)      = "any"
6292      * StringUtils.replace("aba", "a", null)  = "aba"
6293      * StringUtils.replace("aba", "a", "")    = "b"
6294      * StringUtils.replace("aba", "a", "z")   = "zbz"
6295      * </pre>
6296      *
6297      * @param text         text to search and replace in, may be null.
6298      * @param searchString The String to search for, may be null.
6299      * @param replacement  The String to replace it with, may be null.
6300      * @return The text with any replacements processed, {@code null} if null String input.
6301      * @see #replace(String text, String searchString, String replacement, int max)
6302      * @deprecated Use {@link Strings#replace(String, String, String) Strings.CS.replace(String, String, String)}.
6303      */
6304     @Deprecated
6305     public static String replace(final String text, final String searchString, final String replacement) {
6306         return Strings.CS.replace(text, searchString, replacement);
6307     }
6308 
6309     /**
6310      * Replaces a String with another String inside a larger String, for the first {@code max} values of the search String.
6311      *
6312      * <p>
6313      * A {@code null} reference passed to this method is a no-op.
6314      * </p>
6315      *
6316      * <pre>
6317      * StringUtils.replace(null, *, *, *)         = null
6318      * StringUtils.replace("", *, *, *)           = ""
6319      * StringUtils.replace("any", null, *, *)     = "any"
6320      * StringUtils.replace("any", *, null, *)     = "any"
6321      * StringUtils.replace("any", "", *, *)       = "any"
6322      * StringUtils.replace("any", *, *, 0)        = "any"
6323      * StringUtils.replace("abaa", "a", null, -1) = "abaa"
6324      * StringUtils.replace("abaa", "a", "", -1)   = "b"
6325      * StringUtils.replace("abaa", "a", "z", 0)   = "abaa"
6326      * StringUtils.replace("abaa", "a", "z", 1)   = "zbaa"
6327      * StringUtils.replace("abaa", "a", "z", 2)   = "zbza"
6328      * StringUtils.replace("abaa", "a", "z", -1)  = "zbzz"
6329      * </pre>
6330      *
6331      * @param text         text to search and replace in, may be null.
6332      * @param searchString The String to search for, may be null.
6333      * @param replacement  The String to replace it with, may be null.
6334      * @param max          maximum number of values to replace, or {@code -1} if no maximum.
6335      * @return The text with any replacements processed, {@code null} if null String input.
6336      * @deprecated Use {@link Strings#replace(String, String, String, int) Strings.CS.replace(String, String, String, int)}.
6337      */
6338     @Deprecated
6339     public static String replace(final String text, final String searchString, final String replacement, final int max) {
6340         return Strings.CS.replace(text, searchString, replacement, max);
6341     }
6342 
6343     /**
6344      * Replaces each substring of the text String that matches the given regular expression with the given replacement.
6345      *
6346      * This method is a {@code null} safe equivalent to:
6347      * <ul>
6348      * <li>{@code text.replaceAll(regex, replacement)}</li>
6349      * <li>{@code Pattern.compile(regex).matcher(text).replaceAll(replacement)}</li>
6350      * </ul>
6351      *
6352      * <p>
6353      * A {@code null} reference passed to this method is a no-op.
6354      * </p>
6355      *
6356      * <p>
6357      * Unlike in the {@link #replacePattern(String, String, String)} method, the {@link Pattern#DOTALL} option is NOT automatically added. To use the DOTALL
6358      * option prepend {@code "(?s)"} to the regex. DOTALL is also known as single-line mode in Perl.
6359      * </p>
6360      *
6361      * <pre>{@code
6362      * StringUtils.replaceAll(null, *, *)                                         = null
6363      * StringUtils.replaceAll("any", (String) null, *)                            = "any"
6364      * StringUtils.replaceAll("any", *, null)                                     = "any"
6365      * StringUtils.replaceAll("", "", "zzz")                                      = "zzz"
6366      * StringUtils.replaceAll("", ".*", "zzz")                                    = "zzz"
6367      * StringUtils.replaceAll("", ".+", "zzz")                                    = ""
6368      * StringUtils.replaceAll("abc", "", "ZZ")                                    = "ZZaZZbZZcZZ"
6369      * StringUtils.replaceAll("<__>\n<__>", "<.*>", "z")                          = "z\nz"
6370      * StringUtils.replaceAll("<__>\n<__>", "(?s)<.*>", "z")                      = "z"
6371      * StringUtils.replaceAll("ABCabc123", "[a-z]", "_")                          = "ABC___123"
6372      * StringUtils.replaceAll("ABCabc123", "[^A-Z0-9]+", "_")                     = "ABC_123"
6373      * StringUtils.replaceAll("ABCabc123", "[^A-Z0-9]+", "")                      = "ABC123"
6374      * StringUtils.replaceAll("Lorem ipsum  dolor   sit", "( +)([a-z]+)", "_$2")  = "Lorem_ipsum_dolor_sit"
6375      * }</pre>
6376      *
6377      * @param text        text to search and replace in, may be null.
6378      * @param regex       The regular expression to which this string is to be matched.
6379      * @param replacement The string to be substituted for each match.
6380      * @return The text with any replacements processed, {@code null} if null String input.
6381      * @throws java.util.regex.PatternSyntaxException Thrown if the regular expression's syntax is invalid.
6382      * @see #replacePattern(String, String, String)
6383      * @see String#replaceAll(String, String)
6384      * @see java.util.regex.Pattern
6385      * @see java.util.regex.Pattern#DOTALL
6386      * @since 3.5
6387      * @deprecated Use {@link RegExUtils#replaceAll(String, String, String)}.
6388      */
6389     @Deprecated
6390     public static String replaceAll(final String text, final String regex, final String replacement) {
6391         return RegExUtils.replaceAll(text, regex, replacement);
6392     }
6393 
6394     /**
6395      * Replaces all occurrences of a character in a String with another. This is a null-safe version of {@link String#replace(char, char)}.
6396      *
6397      * <p>
6398      * A {@code null} string input returns {@code null}. An empty ("") string input returns an empty string.
6399      * </p>
6400      *
6401      * <pre>
6402      * StringUtils.replaceChars(null, *, *)        = null
6403      * StringUtils.replaceChars("", *, *)          = ""
6404      * StringUtils.replaceChars("abcba", 'b', 'y') = "aycya"
6405      * StringUtils.replaceChars("abcba", 'z', 'y') = "abcba"
6406      * </pre>
6407      *
6408      * @param str         String to replace characters in, may be null.
6409      * @param searchChar  The character to search for, may be null.
6410      * @param replaceChar The character to replace, may be null.
6411      * @return modified String, {@code null} if null string input.
6412      * @since 2.0
6413      */
6414     public static String replaceChars(final String str, final char searchChar, final char replaceChar) {
6415         if (str == null) {
6416             return null;
6417         }
6418         return str.replace(searchChar, replaceChar);
6419     }
6420 
6421     /**
6422      * Replaces multiple characters in a String in one go. This method can also be used to delete characters.
6423      *
6424      * <p>
6425      * For example:
6426      * </p>
6427      * <pre>
6428      * replaceChars(&quot;hello&quot;, &quot;ho&quot;, &quot;jy&quot;) = jelly.
6429      * </pre>
6430      *
6431      * <p>
6432      * A {@code null} string input returns {@code null}. An empty ("") string input returns an empty string. A null or empty set of search characters returns
6433      * the input string.
6434      * </p>
6435      *
6436      * <p>
6437      * The length of the search characters should normally equal the length of the replace characters. If the search characters is longer, then the extra search
6438      * characters are deleted. If the search characters is shorter, then the extra replace characters are ignored.
6439      * </p>
6440      *
6441      * <pre>
6442      * StringUtils.replaceChars(null, *, *)           = null
6443      * StringUtils.replaceChars("", *, *)             = ""
6444      * StringUtils.replaceChars("abc", null, *)       = "abc"
6445      * StringUtils.replaceChars("abc", "", *)         = "abc"
6446      * StringUtils.replaceChars("abc", "b", null)     = "ac"
6447      * StringUtils.replaceChars("abc", "b", "")       = "ac"
6448      * StringUtils.replaceChars("abcba", "bc", "yz")  = "ayzya"
6449      * StringUtils.replaceChars("abcba", "bc", "y")   = "ayya"
6450      * StringUtils.replaceChars("abcba", "bc", "yzx") = "ayzya"
6451      * </pre>
6452      *
6453      * @param str          String to replace characters in, may be null.
6454      * @param searchChars  A set of characters to search for, may be null.
6455      * @param replaceChars A set of characters to replace, may be null.
6456      * @return modified String, {@code null} if null string input.
6457      * @since 2.0
6458      */
6459     public static String replaceChars(final String str, final String searchChars, String replaceChars) {
6460         if (isEmpty(str) || isEmpty(searchChars)) {
6461             return str;
6462         }
6463         replaceChars = ObjectUtils.toString(replaceChars);
6464         boolean modified = false;
6465         final int replaceCharsLength = replaceChars.length();
6466         final int strLength = str.length();
6467         final StringBuilder buf = new StringBuilder(strLength);
6468         for (int i = 0; i < strLength; i++) {
6469             final char ch = str.charAt(i);
6470             final int index = searchChars.indexOf(ch);
6471             if (index >= 0) {
6472                 modified = true;
6473                 if (index < replaceCharsLength) {
6474                     buf.append(replaceChars.charAt(index));
6475                 }
6476             } else {
6477                 buf.append(ch);
6478             }
6479         }
6480         if (modified) {
6481             return buf.toString();
6482         }
6483         return str;
6484     }
6485 
6486     /**
6487      * Replaces all occurrences of Strings within another String.
6488      *
6489      * <p>
6490      * A {@code null} reference passed to this method is a no-op, or if any "search string" or "string to replace" is null, that replace will be ignored. This
6491      * will not repeat. For repeating replaces, call the overloaded method.
6492      * </p>
6493      *
6494      * <pre>
6495      *  StringUtils.replaceEach(null, *, *)                                                = null
6496      *  StringUtils.replaceEach("", *, *)                                                  = ""
6497      *  StringUtils.replaceEach("aba", null, null)                                         = "aba"
6498      *  StringUtils.replaceEach("aba", new String[0], null)                                = "aba"
6499      *  StringUtils.replaceEach("aba", null, new String[0])                                = "aba"
6500      *  StringUtils.replaceEach("aba", new String[]{"a"}, null)                            = "aba"
6501      *  StringUtils.replaceEach("aba", new String[]{"a"}, new String[]{""})                = "b"
6502      *  StringUtils.replaceEach("aba", new String[]{null}, new String[]{"a"})              = "aba"
6503      *  StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"w", "t"})  = "wcte"
6504      *  (example of how it does not repeat)
6505      *  StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "t"})  = "dcte"
6506      * </pre>
6507      *
6508      * @param text            text to search and replace in, no-op if null.
6509      * @param searchList      The Strings to search for, no-op if null.
6510      * @param replacementList The Strings to replace them with, no-op if null.
6511      * @return The text with any replacements processed, {@code null} if null String input.
6512      * @throws IllegalArgumentException Thrown if the lengths of the arrays are not the same (null is ok, and/or size 0).
6513      * @since 2.4
6514      */
6515     public static String replaceEach(final String text, final String[] searchList, final String[] replacementList) {
6516         return replaceEachOnce(text, searchList, replacementList);
6517     }
6518 
6519     /**
6520      * Replace all occurrences of Strings within another String, in a single pass. This is a private helper method for
6521      * {@link #replaceEachRepeatedly(String, String[], String[])} and {@link #replaceEach(String, String[], String[])}
6522      *
6523      * <p>
6524      * A {@code null} reference passed to this method is a no-op, or if any "search string" or "string to replace" is null, that replace will be ignored.
6525      * </p>
6526      *
6527      * <pre>
6528      *  StringUtils.replaceEachOnce(null, *, *)                                                = null
6529      *  StringUtils.replaceEachOnce("", *, *)                                                  = ""
6530      *  StringUtils.replaceEachOnce("aba", null, null)                                         = "aba"
6531      *  StringUtils.replaceEachOnce("aba", new String[0], null)                                = "aba"
6532      *  StringUtils.replaceEachOnce("aba", null, new String[0])                                = "aba"
6533      *  StringUtils.replaceEachOnce("aba", new String[]{"a"}, null)                            = "aba"
6534      *  StringUtils.replaceEachOnce("aba", new String[]{"a"}, new String[]{""})                = "b"
6535      *  StringUtils.replaceEachOnce("aba", new String[]{null}, new String[]{"a"})              = "aba"
6536      *  StringUtils.replaceEachOnce("abcde", new String[]{"ab", "d"}, new String[]{"w", "t"})  = "wcte"
6537      *  StringUtils.replaceEachOnce("abcde", new String[]{"ab", "d"}, new String[]{"d", "t"})  = "dcte"
6538      * </pre>
6539      *
6540      * <p>
6541      * When no replacement is performed, the {@code text} argument is returned unchanged (same reference); callers rely on this to detect convergence.
6542      * </p>
6543      *
6544      * @param text            text to search and replace in, no-op if null.
6545      * @param searchList      The Strings to search for, no-op if null.
6546      * @param replacementList The Strings to replace them with, no-op if null.
6547      * @return The text with any replacements processed, {@code null} if null String input.
6548      * @throws IllegalArgumentException Thrown if the lengths of the arrays are not the same (null is ok, and/or size 0).
6549      * @since 2.4
6550      */
6551     private static String replaceEachOnce(final String text, final String[] searchList, final String[] replacementList) {
6552 
6553         // Performance note: This creates very few new objects (one major goal)
6554         // let me know if there are performance requests, we can create a harness to measure
6555         if (isEmpty(text) || ArrayUtils.isEmpty(searchList) || ArrayUtils.isEmpty(replacementList)) {
6556             return text;
6557         }
6558 
6559         final int searchLength = searchList.length;
6560         final int replacementLength = replacementList.length;
6561 
6562         // make sure lengths are ok, these need to be equal
6563         if (searchLength != replacementLength) {
6564             throw new IllegalArgumentException("Search and Replace array lengths don't match: "
6565                 + searchLength
6566                 + " vs "
6567                 + replacementLength);
6568         }
6569 
6570         // keep track of which still have matches
6571         final boolean[] noMoreMatchesForReplIndex = new boolean[searchLength];
6572 
6573         // index on index that the match was found
6574         int textIndex = -1;
6575         int replaceIndex = -1;
6576         int tempIndex;
6577 
6578         // index of replace array that will replace the search string found
6579         // NOTE: logic duplicated below START
6580         for (int i = 0; i < searchLength; i++) {
6581             if (noMoreMatchesForReplIndex[i] || isEmpty(searchList[i]) || replacementList[i] == null) {
6582                 continue;
6583             }
6584             tempIndex = text.indexOf(searchList[i]);
6585 
6586             // see if we need to keep searching for this
6587             if (tempIndex == -1) {
6588                 noMoreMatchesForReplIndex[i] = true;
6589             } else if (textIndex == -1 || tempIndex < textIndex) {
6590                 textIndex = tempIndex;
6591                 replaceIndex = i;
6592             }
6593         }
6594         // NOTE: logic mostly below END
6595 
6596         // no search strings found, we are done
6597         if (textIndex == -1) {
6598             return text;
6599         }
6600 
6601         int start = 0;
6602 
6603         // get a good guess on the size of the result buffer so it doesn't have to double if it goes over a bit
6604         int increase = 0;
6605 
6606         // count the replacement text elements that are larger than their corresponding text being replaced
6607         for (int i = 0; i < searchList.length; i++) {
6608             if (searchList[i] == null || replacementList[i] == null) {
6609                 continue;
6610             }
6611             final int greater = replacementList[i].length() - searchList[i].length();
6612             if (greater > 0) {
6613                 increase += 3 * greater; // assume 3 matches
6614             }
6615         }
6616         // have upper-bound at 20% increase, then let Java take over
6617         increase = Math.min(increase, text.length() / 5);
6618 
6619         final StringBuilder buf = new StringBuilder(text.length() + increase);
6620 
6621         while (textIndex != -1) {
6622 
6623             for (int i = start; i < textIndex; i++) {
6624                 buf.append(text.charAt(i));
6625             }
6626             buf.append(replacementList[replaceIndex]);
6627 
6628             start = textIndex + searchList[replaceIndex].length();
6629 
6630             textIndex = -1;
6631             replaceIndex = -1;
6632             // find the next earliest match
6633             // NOTE: logic mostly duplicated above START
6634             for (int i = 0; i < searchLength; i++) {
6635                 if (noMoreMatchesForReplIndex[i] || isEmpty(searchList[i]) || replacementList[i] == null) {
6636                     continue;
6637                 }
6638                 tempIndex = text.indexOf(searchList[i], start);
6639 
6640                 // see if we need to keep searching for this
6641                 if (tempIndex == -1) {
6642                     noMoreMatchesForReplIndex[i] = true;
6643                 } else if (textIndex == -1 || tempIndex < textIndex) {
6644                     textIndex = tempIndex;
6645                     replaceIndex = i;
6646                 }
6647             }
6648             // NOTE: logic duplicated above END
6649 
6650         }
6651         final int textLength = text.length();
6652         for (int i = start; i < textLength; i++) {
6653             buf.append(text.charAt(i));
6654         }
6655         return buf.toString();
6656     }
6657 
6658     /**
6659      * Replaces all occurrences of Strings within another String.
6660      *
6661      * <p>
6662      * A {@code null} reference passed to this method is a no-op, or if any "search string" or "string to replace" is null, that replace will be ignored.
6663      * </p>
6664      *
6665      * <pre>
6666      *  StringUtils.replaceEachRepeatedly(null, *, *)                                                = null
6667      *  StringUtils.replaceEachRepeatedly("", *, *)                                                  = ""
6668      *  StringUtils.replaceEachRepeatedly("aba", null, null)                                         = "aba"
6669      *  StringUtils.replaceEachRepeatedly("aba", new String[0], null)                                = "aba"
6670      *  StringUtils.replaceEachRepeatedly("aba", null, new String[0])                                = "aba"
6671      *  StringUtils.replaceEachRepeatedly("aba", new String[]{"a"}, null)                            = "aba"
6672      *  StringUtils.replaceEachRepeatedly("aba", new String[]{"a"}, new String[]{""})                = "b"
6673      *  StringUtils.replaceEachRepeatedly("aba", new String[]{null}, new String[]{"a"})              = "aba"
6674      *  StringUtils.replaceEachRepeatedly("abcde", new String[]{"ab", "d"}, new String[]{"w", "t"})  = "wcte"
6675      *  (example of how it repeats)
6676      *  StringUtils.replaceEachRepeatedly("abcde", new String[]{"ab", "d"}, new String[]{"d", "t"})  = "tcte"
6677      *  StringUtils.replaceEachRepeatedly("abcde", new String[]{"ab", "d"}, new String[]{"d", "ab"}) = Throws {@link IllegalStateException}
6678      * </pre>
6679      *
6680      * @param text            text to search and replace in, no-op if null.
6681      * @param searchList      The Strings to search for, no-op if null.
6682      * @param replacementList The Strings to replace them with, no-op if null.
6683      * @return The text with any replacements processed, {@code null} if null String input.
6684      * @throws IllegalStateException    Thrown if the search is repeating and there is an endless loop due to outputs of one being inputs to another.
6685      * @throws IllegalArgumentException Thrown if the lengths of the arrays are not the same (null is ok, and/or size 0).
6686      * @since 2.4
6687      */
6688     public static String replaceEachRepeatedly(final String text, final String[] searchList, final String[] replacementList) {
6689         // The iteration budget is a fixed constant, deliberately independent of the caller-supplied
6690         // searchList length: deriving the budget from the input would let the input size choose the
6691         // recursion depth/amplification (formerly a real StackOverflowError on large search lists).
6692         String result = text;
6693         for (int timeToLive = DEFAULT_TTL; timeToLive >= 0; timeToLive--) {
6694             final String next = replaceEachOnce(result, searchList, replacementList);
6695             if (next == result) {
6696                 // No replacement was performed; converged.
6697                 return result;
6698             }
6699             result = next;
6700         }
6701         throw new IllegalStateException("Aborting to protect against StackOverflowError - " +
6702             "output of one loop is the input of another");
6703     }
6704 
6705     /**
6706      * Replaces the first substring of the text string that matches the given regular expression with the given replacement.
6707      *
6708      * This method is a {@code null} safe equivalent to:
6709      * <ul>
6710      * <li>{@code text.replaceFirst(regex, replacement)}</li>
6711      * <li>{@code Pattern.compile(regex).matcher(text).replaceFirst(replacement)}</li>
6712      * </ul>
6713      *
6714      * <p>
6715      * A {@code null} reference passed to this method is a no-op.
6716      * </p>
6717      *
6718      * <p>
6719      * The {@link Pattern#DOTALL} option is NOT automatically added. To use the DOTALL option prepend {@code "(?s)"} to the regex. DOTALL is also known as
6720      * single-line mode in Perl.
6721      * </p>
6722      *
6723      * <pre>{@code
6724      * StringUtils.replaceFirst(null, *, *)       = null
6725      * StringUtils.replaceFirst("any", (String) null, *)   = "any"
6726      * StringUtils.replaceFirst("any", *, null)   = "any"
6727      * StringUtils.replaceFirst("", "", "zzz")    = "zzz"
6728      * StringUtils.replaceFirst("", ".*", "zzz")  = "zzz"
6729      * StringUtils.replaceFirst("", ".+", "zzz")  = ""
6730      * StringUtils.replaceFirst("abc", "", "ZZ")  = "ZZabc"
6731      * StringUtils.replaceFirst("<__>\n<__>", "<.*>", "z")      = "z\n<__>"
6732      * StringUtils.replaceFirst("<__>\n<__>", "(?s)<.*>", "z")  = "z"
6733      * StringUtils.replaceFirst("ABCabc123", "[a-z]", "_")          = "ABC_bc123"
6734      * StringUtils.replaceFirst("ABCabc123abc", "[^A-Z0-9]+", "_")  = "ABC_123abc"
6735      * StringUtils.replaceFirst("ABCabc123abc", "[^A-Z0-9]+", "")   = "ABC123abc"
6736      * StringUtils.replaceFirst("Lorem ipsum  dolor   sit", "( +)([a-z]+)", "_$2")  = "Lorem_ipsum  dolor   sit"
6737      * }</pre>
6738      *
6739      * @param text        text to search and replace in, may be null.
6740      * @param regex       The regular expression to which this string is to be matched.
6741      * @param replacement The string to be substituted for the first match.
6742      * @return The text with the first replacement processed, {@code null} if null String input.
6743      * @throws java.util.regex.PatternSyntaxException Thrown if the regular expression's syntax is invalid.
6744      * @see String#replaceFirst(String, String)
6745      * @see java.util.regex.Pattern
6746      * @see java.util.regex.Pattern#DOTALL
6747      * @since 3.5
6748      * @deprecated Use {@link RegExUtils#replaceFirst(String, String, String)}.
6749      */
6750     @Deprecated
6751     public static String replaceFirst(final String text, final String regex, final String replacement) {
6752         return RegExUtils.replaceFirst(text, regex, replacement);
6753     }
6754 
6755     /**
6756      * Case insensitively replaces all occurrences of a String within another String.
6757      *
6758      * <p>
6759      * A {@code null} reference passed to this method is a no-op.
6760      * </p>
6761      *
6762      * <pre>
6763      * StringUtils.replaceIgnoreCase(null, *, *)        = null
6764      * StringUtils.replaceIgnoreCase("", *, *)          = ""
6765      * StringUtils.replaceIgnoreCase("any", null, *)    = "any"
6766      * StringUtils.replaceIgnoreCase("any", *, null)    = "any"
6767      * StringUtils.replaceIgnoreCase("any", "", *)      = "any"
6768      * StringUtils.replaceIgnoreCase("aba", "a", null)  = "aba"
6769      * StringUtils.replaceIgnoreCase("abA", "A", "")    = "b"
6770      * StringUtils.replaceIgnoreCase("aba", "A", "z")   = "zbz"
6771      * </pre>
6772      *
6773      * @param text         text to search and replace in, may be null.
6774      * @param searchString The String to search for (case-insensitive), may be null.
6775      * @param replacement  The String to replace it with, may be null.
6776      * @return The text with any replacements processed, {@code null} if null String input.
6777      * @see #replaceIgnoreCase(String text, String searchString, String replacement, int max)
6778      * @since 3.5
6779      * @deprecated Use {@link Strings#replace(String, String, String) Strings.CI.replace(String, String, String)}.
6780      */
6781     @Deprecated
6782     public static String replaceIgnoreCase(final String text, final String searchString, final String replacement) {
6783         return Strings.CI.replace(text, searchString, replacement);
6784     }
6785 
6786     /**
6787      * Case insensitively replaces a String with another String inside a larger String, for the first {@code max} values of the search String.
6788      *
6789      * <p>
6790      * A {@code null} reference passed to this method is a no-op.
6791      * </p>
6792      *
6793      * <pre>
6794      * StringUtils.replaceIgnoreCase(null, *, *, *)         = null
6795      * StringUtils.replaceIgnoreCase("", *, *, *)           = ""
6796      * StringUtils.replaceIgnoreCase("any", null, *, *)     = "any"
6797      * StringUtils.replaceIgnoreCase("any", *, null, *)     = "any"
6798      * StringUtils.replaceIgnoreCase("any", "", *, *)       = "any"
6799      * StringUtils.replaceIgnoreCase("any", *, *, 0)        = "any"
6800      * StringUtils.replaceIgnoreCase("abaa", "a", null, -1) = "abaa"
6801      * StringUtils.replaceIgnoreCase("abaa", "a", "", -1)   = "b"
6802      * StringUtils.replaceIgnoreCase("abaa", "a", "z", 0)   = "abaa"
6803      * StringUtils.replaceIgnoreCase("abaa", "A", "z", 1)   = "zbaa"
6804      * StringUtils.replaceIgnoreCase("abAa", "a", "z", 2)   = "zbza"
6805      * StringUtils.replaceIgnoreCase("abAa", "a", "z", -1)  = "zbzz"
6806      * </pre>
6807      *
6808      * @param text         text to search and replace in, may be null.
6809      * @param searchString The String to search for (case-insensitive), may be null.
6810      * @param replacement  The String to replace it with, may be null.
6811      * @param max          maximum number of values to replace, or {@code -1} if no maximum.
6812      * @return The text with any replacements processed, {@code null} if null String input.
6813      * @since 3.5
6814      * @deprecated Use {@link Strings#replace(String, String, String, int) Strings.CI.replace(String, String, String, int)}.
6815      */
6816     @Deprecated
6817     public static String replaceIgnoreCase(final String text, final String searchString, final String replacement, final int max) {
6818         return Strings.CI.replace(text, searchString, replacement, max);
6819     }
6820 
6821     /**
6822      * Replaces a String with another String inside a larger String, once.
6823      *
6824      * <p>
6825      * A {@code null} reference passed to this method is a no-op.
6826      * </p>
6827      *
6828      * <pre>
6829      * StringUtils.replaceOnce(null, *, *)        = null
6830      * StringUtils.replaceOnce("", *, *)          = ""
6831      * StringUtils.replaceOnce("any", null, *)    = "any"
6832      * StringUtils.replaceOnce("any", *, null)    = "any"
6833      * StringUtils.replaceOnce("any", "", *)      = "any"
6834      * StringUtils.replaceOnce("aba", "a", null)  = "aba"
6835      * StringUtils.replaceOnce("aba", "a", "")    = "ba"
6836      * StringUtils.replaceOnce("aba", "a", "z")   = "zba"
6837      * </pre>
6838      *
6839      * @param text         text to search and replace in, may be null.
6840      * @param searchString The String to search for, may be null.
6841      * @param replacement  The String to replace with, may be null.
6842      * @return The text with any replacements processed, {@code null} if null String input.
6843      * @see #replace(String text, String searchString, String replacement, int max)
6844      * @deprecated Use {@link Strings#replaceOnce(String, String, String) Strings.CS.replaceOnce(String, String, String)}.
6845      */
6846     @Deprecated
6847     public static String replaceOnce(final String text, final String searchString, final String replacement) {
6848         return Strings.CS.replaceOnce(text, searchString, replacement);
6849     }
6850 
6851     /**
6852      * Case insensitively replaces a String with another String inside a larger String, once.
6853      *
6854      * <p>
6855      * A {@code null} reference passed to this method is a no-op.
6856      * </p>
6857      *
6858      * <pre>
6859      * StringUtils.replaceOnceIgnoreCase(null, *, *)        = null
6860      * StringUtils.replaceOnceIgnoreCase("", *, *)          = ""
6861      * StringUtils.replaceOnceIgnoreCase("any", null, *)    = "any"
6862      * StringUtils.replaceOnceIgnoreCase("any", *, null)    = "any"
6863      * StringUtils.replaceOnceIgnoreCase("any", "", *)      = "any"
6864      * StringUtils.replaceOnceIgnoreCase("aba", "a", null)  = "aba"
6865      * StringUtils.replaceOnceIgnoreCase("aba", "a", "")    = "ba"
6866      * StringUtils.replaceOnceIgnoreCase("aba", "a", "z")   = "zba"
6867      * StringUtils.replaceOnceIgnoreCase("FoOFoofoo", "foo", "") = "Foofoo"
6868      * </pre>
6869      *
6870      * @param text         text to search and replace in, may be null.
6871      * @param searchString The String to search for (case-insensitive), may be null.
6872      * @param replacement  The String to replace with, may be null.
6873      * @return The text with any replacements processed, {@code null} if null String input.
6874      * @see #replaceIgnoreCase(String text, String searchString, String replacement, int max)
6875      * @since 3.5
6876      * @deprecated Use {@link Strings#replaceOnce(String, String, String) Strings.CI.replaceOnce(String, String, String)}.
6877      */
6878     @Deprecated
6879     public static String replaceOnceIgnoreCase(final String text, final String searchString, final String replacement) {
6880         return Strings.CI.replaceOnce(text, searchString, replacement);
6881     }
6882 
6883     /**
6884      * Replaces each substring of the source String that matches the given regular expression with the given replacement using the {@link Pattern#DOTALL}
6885      * option. DOTALL is also known as single-line mode in Perl.
6886      *
6887      * This call is a {@code null} safe equivalent to:
6888      * <ul>
6889      * <li>{@code source.replaceAll(&quot;(?s)&quot; + regex, replacement)}</li>
6890      * <li>{@code Pattern.compile(regex, Pattern.DOTALL).matcher(source).replaceAll(replacement)}</li>
6891      * </ul>
6892      *
6893      * <p>
6894      * A {@code null} reference passed to this method is a no-op.
6895      * </p>
6896      *
6897      * <pre>{@code
6898      * StringUtils.replacePattern(null, *, *)                                         = null
6899      * StringUtils.replacePattern("any", (String) null, *)                            = "any"
6900      * StringUtils.replacePattern("any", *, null)                                     = "any"
6901      * StringUtils.replacePattern("", "", "zzz")                                      = "zzz"
6902      * StringUtils.replacePattern("", ".*", "zzz")                                    = "zzz"
6903      * StringUtils.replacePattern("", ".+", "zzz")                                    = ""
6904      * StringUtils.replacePattern("<__>\n<__>", "<.*>", "z")                          = "z"
6905      * StringUtils.replacePattern("ABCabc123", "[a-z]", "_")                          = "ABC___123"
6906      * StringUtils.replacePattern("ABCabc123", "[^A-Z0-9]+", "_")                     = "ABC_123"
6907      * StringUtils.replacePattern("ABCabc123", "[^A-Z0-9]+", "")                      = "ABC123"
6908      * StringUtils.replacePattern("Lorem ipsum  dolor   sit", "( +)([a-z]+)", "_$2")  = "Lorem_ipsum_dolor_sit"
6909      * }</pre>
6910      *
6911      * @param source      The source string.
6912      * @param regex       The regular expression to which this string is to be matched.
6913      * @param replacement The string to be substituted for each match.
6914      * @return The resulting {@link String}.
6915      * @see #replaceAll(String, String, String)
6916      * @see String#replaceAll(String, String)
6917      * @see Pattern#DOTALL
6918      * @since 3.2
6919      * @since 3.5 Changed {@code null} reference passed to this method is a no-op.
6920      * @deprecated Use {@link RegExUtils#replacePattern(CharSequence, String, String)}.
6921      */
6922     @Deprecated
6923     public static String replacePattern(final String source, final String regex, final String replacement) {
6924         return RegExUtils.replacePattern(source, regex, replacement);
6925     }
6926 
6927     /**
6928      * Reverses a String as per {@link StringBuilder#reverse()}.
6929      *
6930      * <p>
6931      * A {@code null} String returns {@code null}.
6932      * </p>
6933      *
6934      * <pre>
6935      * StringUtils.reverse(null)  = null
6936      * StringUtils.reverse("")    = ""
6937      * StringUtils.reverse("bat") = "tab"
6938      * </pre>
6939      *
6940      * @param str The String to reverse, may be null.
6941      * @return The reversed String, {@code null} if null String input.
6942      */
6943     public static String reverse(final String str) {
6944         if (str == null) {
6945             return null;
6946         }
6947         return new StringBuilder(str).reverse().toString();
6948     }
6949 
6950     /**
6951      * Reverses a String that is delimited by a specific character.
6952      *
6953      * <p>
6954      * The Strings between the delimiters are not reversed. Thus java.lang.String becomes String.lang.java (if the delimiter is {@code '.'}).
6955      * </p>
6956      *
6957      * <pre>
6958      * StringUtils.reverseDelimited(null, *)      = null
6959      * StringUtils.reverseDelimited("", *)        = ""
6960      * StringUtils.reverseDelimited("a.b.c", 'x') = "a.b.c"
6961      * StringUtils.reverseDelimited("a.b.c", '.') = "c.b.a"
6962      * </pre>
6963      *
6964      * @param str           The String to reverse, may be null.
6965      * @param separatorChar The separator character to use.
6966      * @return The reversed String, {@code null} if null String input.
6967      * @since 2.0
6968      */
6969     public static String reverseDelimited(final String str, final char separatorChar) {
6970         final String[] strs = split(str, separatorChar);
6971         ArrayUtils.reverse(strs);
6972         return join(strs, separatorChar);
6973     }
6974 
6975     /**
6976      * Gets the rightmost {@code len} characters of a String.
6977      *
6978      * <p>
6979      * If {@code len} characters are not available, or the String is {@code null}, the String will be returned without an exception. An empty String is
6980      * returned if len is negative.
6981      * </p>
6982      *
6983      * <pre>
6984      * StringUtils.right(null, *)    = null
6985      * StringUtils.right(*, -ve)     = ""
6986      * StringUtils.right("", *)      = ""
6987      * StringUtils.right("abc", 0)   = ""
6988      * StringUtils.right("abc", 2)   = "bc"
6989      * StringUtils.right("abc", 4)   = "abc"
6990      * </pre>
6991      *
6992      * @param str The String to get the rightmost characters from, may be null.
6993      * @param len The length of the required String.
6994      * @return The rightmost characters, {@code null} if null String input.
6995      */
6996     public static String right(final String str, final int len) {
6997         if (str == null) {
6998             return null;
6999         }
7000         if (len < 0) {
7001             return EMPTY;
7002         }
7003         if (str.length() <= len) {
7004             return str;
7005         }
7006         int start = str.length() - len;
7007         // keep the cut off the middle of a surrogate pair so the result is never left holding a lone surrogate
7008         if (splitsSurrogatePair(str, start)) {
7009             start++;
7010         }
7011         return str.substring(start);
7012     }
7013 
7014     /**
7015      * Right pad a String with spaces (' ').
7016      *
7017      * <p>
7018      * The String is padded to the size of {@code size}.
7019      * </p>
7020      *
7021      * <pre>
7022      * StringUtils.rightPad(null, *)   = null
7023      * StringUtils.rightPad("", 3)     = "   "
7024      * StringUtils.rightPad("bat", 3)  = "bat"
7025      * StringUtils.rightPad("bat", 5)  = "bat  "
7026      * StringUtils.rightPad("bat", 1)  = "bat"
7027      * StringUtils.rightPad("bat", -1) = "bat"
7028      * </pre>
7029      *
7030      * @param str  The String to pad out, may be null.
7031      * @param size The size to pad to.
7032      * @return right padded String or original String if no padding is necessary, {@code null} if null String input.
7033      */
7034     public static String rightPad(final String str, final int size) {
7035         return rightPad(str, size, ' ');
7036     }
7037 
7038     /**
7039      * Right pad a String with a specified character.
7040      *
7041      * <p>
7042      * The String is padded to the size of {@code size}.
7043      * </p>
7044      *
7045      * <pre>
7046      * StringUtils.rightPad(null, *, *)     = null
7047      * StringUtils.rightPad("", 3, 'z')     = "zzz"
7048      * StringUtils.rightPad("bat", 3, 'z')  = "bat"
7049      * StringUtils.rightPad("bat", 5, 'z')  = "batzz"
7050      * StringUtils.rightPad("bat", 1, 'z')  = "bat"
7051      * StringUtils.rightPad("bat", -1, 'z') = "bat"
7052      * </pre>
7053      *
7054      * @param str     The String to pad out, may be null.
7055      * @param size    The size to pad to.
7056      * @param padChar The character to pad with.
7057      * @return right padded String or original String if no padding is necessary, {@code null} if null String input.
7058      * @since 2.0
7059      */
7060     public static String rightPad(final String str, final int size, final char padChar) {
7061         if (str == null || size <= str.length()) {
7062             return str;
7063         }
7064         final int pads = size - str.length();
7065         if (pads <= 0) {
7066             return str; // returns original String when possible
7067         }
7068         if (pads > PAD_LIMIT) {
7069             return rightPad(str, size, String.valueOf(padChar));
7070         }
7071         return str.concat(repeat(padChar, pads));
7072     }
7073 
7074     /**
7075      * Right pad a String with a specified String.
7076      *
7077      * <p>
7078      * The String is padded to the size of {@code size}. If the requested padding length would split a Unicode surrogate pair
7079      * in {@code padStr}, the padding is shortened by one {@code char} to avoid introducing an unpaired surrogate by splitting the pair.
7080      * In that case, the returned String has a length of {@code size - 1}.
7081      * </p>
7082      *
7083      * <pre>
7084      * StringUtils.rightPad(null, *, *)      = null
7085      * StringUtils.rightPad("", 3, "z")      = "zzz"
7086      * StringUtils.rightPad("bat", 3, "yz")  = "bat"
7087      * StringUtils.rightPad("bat", 5, "yz")  = "batyz"
7088      * StringUtils.rightPad("bat", 8, "yz")  = "batyzyzy"
7089      * StringUtils.rightPad("bat", 1, "yz")  = "bat"
7090      * StringUtils.rightPad("bat", -1, "yz") = "bat"
7091      * StringUtils.rightPad("bat", 5, null)  = "bat  "
7092      * StringUtils.rightPad("bat", 5, "")    = "bat  "
7093      * StringUtils.rightPad("a", 2, "\uD83D\uDE00")    = "a"
7094      * StringUtils.rightPad("a", 3, "\uD83D\uDE00")    = "a\uD83D\uDE00"
7095      * </pre>
7096      *
7097      * @param str    The String to pad out, may be null.
7098      * @param size   The size to pad to.
7099      * @param padStr The String to pad with, null or empty treated as single space.
7100      * @return right padded String or original String if no padding is necessary, {@code null} if null String input.
7101      */
7102     public static String rightPad(final String str, final int size, String padStr) {
7103         if (str == null || size <= str.length()) {
7104             return str;
7105         }
7106         if (isEmpty(padStr)) {
7107             padStr = SPACE;
7108         }
7109         final int padLen = padStr.length();
7110         final int strLen = str.length();
7111         int pads = size - strLen;
7112         if (pads <= 0) {
7113             return str; // returns original String when possible
7114         }
7115         if (padLen == 1 && pads <= PAD_LIMIT) {
7116             return rightPad(str, size, padStr.charAt(0));
7117         }
7118         // Keep the padding boundary off the middle of a surrogate pair to avoid introducing a lone surrogate.
7119         if (splitsSurrogatePair(padStr, pads % padLen)) {
7120             pads--;
7121         }
7122         if (pads <= 0) {
7123             return str;
7124         }
7125         if (pads == padLen) {
7126             return str.concat(padStr);
7127         }
7128         if (pads < padLen) {
7129             return str.concat(padStr.substring(0, pads));
7130         }
7131         final char[] padding = new char[pads];
7132         final char[] padChars = padStr.toCharArray();
7133         for (int i = 0; i < pads; i++) {
7134             padding[i] = padChars[i % padLen];
7135         }
7136         return str.concat(new String(padding));
7137     }
7138 
7139     /**
7140      * Rotate (circular shift) a String of {@code shift} characters.
7141      * <ul>
7142      * <li>If {@code shift > 0}, right circular shift (ex : ABCDEF =&gt; FABCDE)</li>
7143      * <li>If {@code shift < 0}, left circular shift (ex : ABCDEF =&gt; BCDEFA)</li>
7144      * </ul>
7145      *
7146      * <pre>
7147      * StringUtils.rotate(null, *)        = null
7148      * StringUtils.rotate("", *)          = ""
7149      * StringUtils.rotate("abcdefg", 0)   = "abcdefg"
7150      * StringUtils.rotate("abcdefg", 2)   = "fgabcde"
7151      * StringUtils.rotate("abcdefg", -2)  = "cdefgab"
7152      * StringUtils.rotate("abcdefg", 7)   = "abcdefg"
7153      * StringUtils.rotate("abcdefg", -7)  = "abcdefg"
7154      * StringUtils.rotate("abcdefg", 9)   = "fgabcde"
7155      * StringUtils.rotate("abcdefg", -9)  = "cdefgab"
7156      * </pre>
7157      *
7158      * @param str   The String to rotate, may be null.
7159      * @param shift number of time to shift (positive : right shift, negative : left shift).
7160      * @return The rotated String, or the original String if {@code shift == 0}, or {@code null} if null String input.
7161      * @since 3.5
7162      */
7163     public static String rotate(final String str, final int shift) {
7164         if (str == null) {
7165             return null;
7166         }
7167         final int strLen = str.length();
7168         if (shift == 0 || strLen == 0 || shift % strLen == 0) {
7169             return str;
7170         }
7171         final StringBuilder builder = new StringBuilder(strLen);
7172         final int offset = -(shift % strLen);
7173         builder.append(substring(str, offset));
7174         builder.append(substring(str, 0, offset));
7175         return builder.toString();
7176     }
7177 
7178     /**
7179      * Splits the provided text into an array, using whitespace as the separator. Whitespace is defined by {@link Character#isWhitespace(char)}.
7180      *
7181      * <p>
7182      * The separator is not included in the returned String array. Adjacent separators are treated as one separator. For more control over the split use the
7183      * StrTokenizer class.
7184      * </p>
7185      *
7186      * <p>
7187      * A {@code null} input String returns {@code null}.
7188      * </p>
7189      *
7190      * <pre>
7191      * StringUtils.split(null)       = null
7192      * StringUtils.split("")         = []
7193      * StringUtils.split("abc def")  = ["abc", "def"]
7194      * StringUtils.split("abc  def") = ["abc", "def"]
7195      * StringUtils.split(" abc ")    = ["abc"]
7196      * </pre>
7197      *
7198      * @param str The String to parse, may be null.
7199      * @return An array of parsed Strings, {@code null} if null String input.
7200      */
7201     public static String[] split(final String str) {
7202         return split(str, null, -1);
7203     }
7204 
7205     /**
7206      * Splits the provided text into an array, separator specified. This is an alternative to using StringTokenizer.
7207      *
7208      * <p>
7209      * The separator is not included in the returned String array. Adjacent separators are treated as one separator. For more control over the split use the
7210      * StrTokenizer class.
7211      * </p>
7212      *
7213      * <p>
7214      * A {@code null} input String returns {@code null}.
7215      * </p>
7216      *
7217      * <pre>
7218      * StringUtils.split(null, *)         = null
7219      * StringUtils.split("", *)           = []
7220      * StringUtils.split("a.b.c", '.')    = ["a", "b", "c"]
7221      * StringUtils.split("a..b.c", '.')   = ["a", "b", "c"]
7222      * StringUtils.split("a:b:c", '.')    = ["a:b:c"]
7223      * StringUtils.split("a b c", ' ')    = ["a", "b", "c"]
7224      * </pre>
7225      *
7226      * @param str           The String to parse, may be null.
7227      * @param separatorChar The character used as the delimiter.
7228      * @return An array of parsed Strings, {@code null} if null String input.
7229      * @since 2.0
7230      */
7231     public static String[] split(final String str, final char separatorChar) {
7232         return splitWorker(str, separatorChar, false);
7233     }
7234 
7235     /**
7236      * Splits the provided text into an array, separators specified. This is an alternative to using StringTokenizer.
7237      *
7238      * <p>
7239      * The separator is not included in the returned String array. Adjacent separators are treated as one separator. For more control over the split use the
7240      * StrTokenizer class.
7241      * </p>
7242      *
7243      * <p>
7244      * A {@code null} input String returns {@code null}. A {@code null} separatorChars splits on whitespace.
7245      * </p>
7246      *
7247      * <pre>
7248      * StringUtils.split(null, *)         = null
7249      * StringUtils.split("", *)           = []
7250      * StringUtils.split("abc def", null) = ["abc", "def"]
7251      * StringUtils.split("abc def", " ")  = ["abc", "def"]
7252      * StringUtils.split("abc  def", " ") = ["abc", "def"]
7253      * StringUtils.split("ab:cd:ef", ":") = ["ab", "cd", "ef"]
7254      * </pre>
7255      *
7256      * @param str            The String to parse, may be null.
7257      * @param separatorChars The characters used as the delimiters, {@code null} splits on whitespace.
7258      * @return An array of parsed Strings, {@code null} if null String input.
7259      */
7260     public static String[] split(final String str, final String separatorChars) {
7261         return splitWorker(str, separatorChars, -1, false);
7262     }
7263 
7264     /**
7265      * Splits the provided text into an array with a maximum length, separators specified.
7266      *
7267      * <p>
7268      * The separator is not included in the returned String array. Adjacent separators are treated as one separator.
7269      * </p>
7270      *
7271      * <p>
7272      * A {@code null} input String returns {@code null}. A {@code null} separatorChars splits on whitespace.
7273      * </p>
7274      *
7275      * <p>
7276      * If more than {@code max} delimited substrings are found, the last returned string includes all characters after the first {@code max - 1} returned
7277      * strings (including separator characters).
7278      * </p>
7279      *
7280      * <pre>
7281      * StringUtils.split(null, *, *)            = null
7282      * StringUtils.split("", *, *)              = []
7283      * StringUtils.split("ab cd ef", null, 0)   = ["ab", "cd", "ef"]
7284      * StringUtils.split("ab   cd ef", null, 0) = ["ab", "cd", "ef"]
7285      * StringUtils.split("ab:cd:ef", ":", 0)    = ["ab", "cd", "ef"]
7286      * StringUtils.split("ab:cd:ef", ":", 2)    = ["ab", "cd:ef"]
7287      * </pre>
7288      *
7289      * @param str            The String to parse, may be null.
7290      * @param separatorChars The characters used as the delimiters, {@code null} splits on whitespace.
7291      * @param max            The maximum number of elements to include in the array. A zero or negative value implies no limit.
7292      * @return An array of parsed Strings, {@code null} if null String input.
7293      */
7294     public static String[] split(final String str, final String separatorChars, final int max) {
7295         return splitWorker(str, separatorChars, max, false);
7296     }
7297 
7298     /**
7299      * Splits a String by Character type as returned by {@link Character#getType(int)}. Groups of contiguous characters of the same type are returned
7300      * as complete tokens.
7301      *
7302      * <pre>
7303      * StringUtils.splitByCharacterType(null)         = null
7304      * StringUtils.splitByCharacterType("")           = []
7305      * StringUtils.splitByCharacterType("ab de fg")   = ["ab", " ", "de", " ", "fg"]
7306      * StringUtils.splitByCharacterType("ab   de fg") = ["ab", "   ", "de", " ", "fg"]
7307      * StringUtils.splitByCharacterType("ab:cd:ef")   = ["ab", ":", "cd", ":", "ef"]
7308      * StringUtils.splitByCharacterType("number5")    = ["number", "5"]
7309      * StringUtils.splitByCharacterType("fooBar")     = ["foo", "B", "ar"]
7310      * StringUtils.splitByCharacterType("foo200Bar")  = ["foo", "200", "B", "ar"]
7311      * StringUtils.splitByCharacterType("ASFRules")   = ["ASFR", "ules"]
7312      * </pre>
7313      *
7314      * @param str The String to split, may be {@code null}.
7315      * @return An array of parsed Strings, {@code null} if null String input.
7316      * @see Character#getType(int)
7317      * @since 2.4
7318      */
7319     public static String[] splitByCharacterType(final String str) {
7320         return splitByCharacterType(str, false);
7321     }
7322 
7323     /**
7324      * Splits a String by Character type as returned by {@code java.lang.Character.getType(char)}. Groups of contiguous characters of the same type are returned
7325      * as complete tokens, with the following exception: if {@code camelCase} is {@code true}, the character of type {@link Character#UPPERCASE_LETTER}, if any,
7326      * immediately preceding a token of type {@link Character#LOWERCASE_LETTER} will belong to the following token rather than to the preceding, if any,
7327      * {@link Character#UPPERCASE_LETTER} token.
7328      *
7329      * @param str       The String to split, may be {@code null}.
7330      * @param camelCase whether to use so-called "camel-case" for letter types.
7331      * @return An array of parsed Strings, {@code null} if null String input.
7332      * @since 2.4
7333      */
7334     private static String[] splitByCharacterType(final String str, final boolean camelCase) {
7335         if (str == null) {
7336             return null;
7337         }
7338         if (str.isEmpty()) {
7339             return ArrayUtils.EMPTY_STRING_ARRAY;
7340         }
7341         final char[] c = str.toCharArray();
7342         final List<String> list = new ArrayList<>();
7343         int tokenStart = 0;
7344         int currentType = Character.getType(Character.codePointAt(c, tokenStart));
7345         for (int pos = tokenStart + Character.charCount(Character.codePointAt(c, tokenStart)); pos < c.length;) {
7346             final int codePoint = Character.codePointAt(c, pos);
7347             final int type = Character.getType(codePoint);
7348             final int count = Character.charCount(codePoint);
7349             if (type == currentType) {
7350                 pos += count;
7351                 continue;
7352             }
7353             if (camelCase && type == Character.LOWERCASE_LETTER && currentType == Character.UPPERCASE_LETTER) {
7354                 final int newTokenStart = pos - Character.charCount(Character.codePointBefore(c, pos));
7355                 if (newTokenStart != tokenStart) {
7356                     list.add(new String(c, tokenStart, newTokenStart - tokenStart));
7357                     tokenStart = newTokenStart;
7358                 }
7359             } else {
7360                 list.add(new String(c, tokenStart, pos - tokenStart));
7361                 tokenStart = pos;
7362             }
7363             currentType = type;
7364             pos += count;
7365         }
7366         list.add(new String(c, tokenStart, c.length - tokenStart));
7367         return list.toArray(ArrayUtils.EMPTY_STRING_ARRAY);
7368     }
7369 
7370     /**
7371      * Splits a String by Character type as returned by {@link Character#getType(int)}. Groups of contiguous characters of the same type are returned
7372      * as complete tokens, with the following exception: the character of type {@link Character#UPPERCASE_LETTER}, if any, immediately preceding a token of type
7373      * {@link Character#LOWERCASE_LETTER} will belong to the following token rather than to the preceding, if any, {@link Character#UPPERCASE_LETTER} token.
7374      *
7375      * <pre>
7376      * StringUtils.splitByCharacterTypeCamelCase(null)         = null
7377      * StringUtils.splitByCharacterTypeCamelCase("")           = []
7378      * StringUtils.splitByCharacterTypeCamelCase("ab de fg")   = ["ab", " ", "de", " ", "fg"]
7379      * StringUtils.splitByCharacterTypeCamelCase("ab   de fg") = ["ab", "   ", "de", " ", "fg"]
7380      * StringUtils.splitByCharacterTypeCamelCase("ab:cd:ef")   = ["ab", ":", "cd", ":", "ef"]
7381      * StringUtils.splitByCharacterTypeCamelCase("number5")    = ["number", "5"]
7382      * StringUtils.splitByCharacterTypeCamelCase("fooBar")     = ["foo", "Bar"]
7383      * StringUtils.splitByCharacterTypeCamelCase("foo200Bar")  = ["foo", "200", "Bar"]
7384      * StringUtils.splitByCharacterTypeCamelCase("ASFRules")   = ["ASF", "Rules"]
7385      * </pre>
7386      *
7387      * @param str The String to split, may be {@code null}.
7388      * @return An array of parsed Strings, {@code null} if null String input.
7389      * @see Character#getType(int)
7390      * @since 2.4
7391      */
7392     public static String[] splitByCharacterTypeCamelCase(final String str) {
7393         return splitByCharacterType(str, true);
7394     }
7395 
7396     /**
7397      * Splits the provided text into an array, separator string specified.
7398      *
7399      * <p>
7400      * The separator(s) will not be included in the returned String array. Adjacent separators are treated as one separator.
7401      * </p>
7402      *
7403      * <p>
7404      * A {@code null} input String returns {@code null}. A {@code null} separator splits on whitespace.
7405      * </p>
7406      *
7407      * <pre>
7408      * StringUtils.splitByWholeSeparator(null, *)               = null
7409      * StringUtils.splitByWholeSeparator("", *)                 = []
7410      * StringUtils.splitByWholeSeparator("ab de fg", null)      = ["ab", "de", "fg"]
7411      * StringUtils.splitByWholeSeparator("ab   de fg", null)    = ["ab", "de", "fg"]
7412      * StringUtils.splitByWholeSeparator("ab:cd:ef", ":")       = ["ab", "cd", "ef"]
7413      * StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-") = ["ab", "cd", "ef"]
7414      * </pre>
7415      *
7416      * @param str       The String to parse, may be null.
7417      * @param separator String containing the String to be used as a delimiter, {@code null} splits on whitespace.
7418      * @return An array of parsed Strings, {@code null} if null String was input.
7419      */
7420     public static String[] splitByWholeSeparator(final String str, final String separator) {
7421         return splitByWholeSeparatorWorker(str, separator, -1, false);
7422     }
7423 
7424     /**
7425      * Splits the provided text into an array, separator string specified. Returns a maximum of {@code max} substrings.
7426      *
7427      * <p>
7428      * The separator(s) will not be included in the returned String array. Adjacent separators are treated as one separator.
7429      * </p>
7430      *
7431      * <p>
7432      * A {@code null} input String returns {@code null}. A {@code null} separator splits on whitespace.
7433      * </p>
7434      *
7435      * <pre>
7436      * StringUtils.splitByWholeSeparator(null, *, *)               = null
7437      * StringUtils.splitByWholeSeparator("", *, *)                 = []
7438      * StringUtils.splitByWholeSeparator("ab de fg", null, 0)      = ["ab", "de", "fg"]
7439      * StringUtils.splitByWholeSeparator("ab   de fg", null, 0)    = ["ab", "de", "fg"]
7440      * StringUtils.splitByWholeSeparator("ab:cd:ef", ":", 2)       = ["ab", "cd:ef"]
7441      * StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-", 5) = ["ab", "cd", "ef"]
7442      * StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-", 2) = ["ab", "cd-!-ef"]
7443      * </pre>
7444      *
7445      * @param str       The String to parse, may be null.
7446      * @param separator String containing the String to be used as a delimiter, {@code null} splits on whitespace.
7447      * @param max       The maximum number of elements to include in the returned array. A zero or negative value implies no limit.
7448      * @return An array of parsed Strings, {@code null} if null String was input.
7449      */
7450     public static String[] splitByWholeSeparator(final String str, final String separator, final int max) {
7451         return splitByWholeSeparatorWorker(str, separator, max, false);
7452     }
7453 
7454     /**
7455      * Splits the provided text into an array, separator string specified.
7456      *
7457      * <p>
7458      * The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. For more control over the
7459      * split use the StrTokenizer class.
7460      * </p>
7461      *
7462      * <p>
7463      * A {@code null} input String returns {@code null}. A {@code null} separator splits on whitespace.
7464      * </p>
7465      *
7466      * <pre>
7467      * StringUtils.splitByWholeSeparatorPreserveAllTokens(null, *)               = null
7468      * StringUtils.splitByWholeSeparatorPreserveAllTokens("", *)                 = []
7469      * StringUtils.splitByWholeSeparatorPreserveAllTokens("ab de fg", null)      = ["ab", "de", "fg"]
7470      * StringUtils.splitByWholeSeparatorPreserveAllTokens("ab   de fg", null)    = ["ab", "", "", "de", "fg"]
7471      * StringUtils.splitByWholeSeparatorPreserveAllTokens("ab:cd:ef", ":")       = ["ab", "cd", "ef"]
7472      * StringUtils.splitByWholeSeparatorPreserveAllTokens("ab-!-cd-!-ef", "-!-") = ["ab", "cd", "ef"]
7473      * </pre>
7474      *
7475      * @param str       The String to parse, may be null.
7476      * @param separator String containing the String to be used as a delimiter, {@code null} splits on whitespace.
7477      * @return An array of parsed Strings, {@code null} if null String was input.
7478      * @since 2.4
7479      */
7480     public static String[] splitByWholeSeparatorPreserveAllTokens(final String str, final String separator) {
7481         return splitByWholeSeparatorWorker(str, separator, -1, true);
7482     }
7483 
7484     /**
7485      * Splits the provided text into an array, separator string specified. Returns a maximum of {@code max} substrings.
7486      *
7487      * <p>
7488      * The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. For more control over the
7489      * split use the StrTokenizer class.
7490      * </p>
7491      *
7492      * <p>
7493      * A {@code null} input String returns {@code null}. A {@code null} separator splits on whitespace.
7494      * </p>
7495      *
7496      * <pre>
7497      * StringUtils.splitByWholeSeparatorPreserveAllTokens(null, *, *)               = null
7498      * StringUtils.splitByWholeSeparatorPreserveAllTokens("", *, *)                 = []
7499      * StringUtils.splitByWholeSeparatorPreserveAllTokens("ab de fg", null, 0)      = ["ab", "de", "fg"]
7500      * StringUtils.splitByWholeSeparatorPreserveAllTokens("ab   de fg", null, 0)    = ["ab", "", "", "de", "fg"]
7501      * StringUtils.splitByWholeSeparatorPreserveAllTokens("ab:cd:ef", ":", 2)       = ["ab", "cd:ef"]
7502      * StringUtils.splitByWholeSeparatorPreserveAllTokens("ab-!-cd-!-ef", "-!-", 5) = ["ab", "cd", "ef"]
7503      * StringUtils.splitByWholeSeparatorPreserveAllTokens("ab-!-cd-!-ef", "-!-", 2) = ["ab", "cd-!-ef"]
7504      * </pre>
7505      *
7506      * @param str       The String to parse, may be null.
7507      * @param separator String containing the String to be used as a delimiter, {@code null} splits on whitespace.
7508      * @param max       The maximum number of elements to include in the returned array. A zero or negative value implies no limit.
7509      * @return An array of parsed Strings, {@code null} if null String was input.
7510      * @since 2.4
7511      */
7512     public static String[] splitByWholeSeparatorPreserveAllTokens(final String str, final String separator, final int max) {
7513         return splitByWholeSeparatorWorker(str, separator, max, true);
7514     }
7515 
7516     /**
7517      * Performs the logic for the {@code splitByWholeSeparatorPreserveAllTokens} methods.
7518      *
7519      * @param str               The String to parse, may be {@code null}.
7520      * @param separator         String containing the String to be used as a delimiter, {@code null} splits on whitespace.
7521      * @param max               The maximum number of elements to include in the returned array. A zero or negative value implies no limit.
7522      * @param preserveAllTokens if {@code true}, adjacent separators are treated as empty token separators; if {@code false}, adjacent separators are treated as
7523      *                          one separator.
7524      * @return An array of parsed Strings, {@code null} if null String input.
7525      * @since 2.4
7526      */
7527     private static String[] splitByWholeSeparatorWorker(final String str, final String separator, final int max, final boolean preserveAllTokens) {
7528         if (str == null) {
7529             return null;
7530         }
7531         final int len = str.length();
7532         if (len == 0) {
7533             return ArrayUtils.EMPTY_STRING_ARRAY;
7534         }
7535         if (separator == null || EMPTY.equals(separator)) {
7536             // Split on whitespace.
7537             return splitWorker(str, null, max, preserveAllTokens);
7538         }
7539         final int separatorLength = separator.length();
7540         final ArrayList<String> substrings = new ArrayList<>();
7541         int numberOfSubstrings = 0;
7542         int beg = 0;
7543         int end = 0;
7544         while (end < len) {
7545             end = str.indexOf(separator, beg);
7546             if (end > -1) {
7547                 if (end > beg) {
7548                     numberOfSubstrings += 1;
7549                     if (numberOfSubstrings == max) {
7550                         end = len;
7551                         substrings.add(str.substring(beg));
7552                     } else {
7553                         // The following is OK, because String.substring( beg, end ) excludes
7554                         // the character at the position 'end'.
7555                         substrings.add(str.substring(beg, end));
7556                         // Set the starting point for the next search.
7557                         // The following is equivalent to beg = end + (separatorLength - 1) + 1,
7558                         // which is the right calculation:
7559                         beg = end + separatorLength;
7560                     }
7561                 } else {
7562                     // We found a consecutive occurrence of the separator, so skip it.
7563                     if (preserveAllTokens) {
7564                         numberOfSubstrings += 1;
7565                         if (numberOfSubstrings == max) {
7566                             end = len;
7567                             substrings.add(str.substring(beg));
7568                         } else {
7569                             substrings.add(EMPTY);
7570                         }
7571                     }
7572                     beg = end + separatorLength;
7573                 }
7574             } else {
7575                 // String.substring( beg ) goes from 'beg' to the end of the String.
7576                 // beg == len means the String ended on a separator, so the trailing
7577                 // token is empty and must be dropped unless empty tokens are preserved.
7578                 if (preserveAllTokens || beg < len) {
7579                     substrings.add(str.substring(beg));
7580                 }
7581                 end = len;
7582             }
7583         }
7584         return substrings.toArray(ArrayUtils.EMPTY_STRING_ARRAY);
7585     }
7586 
7587     /**
7588      * Splits the provided text into an array, using whitespace as the separator, preserving all tokens, including empty tokens created by adjacent separators.
7589      * This is an alternative to using StringTokenizer. Whitespace is defined by {@link Character#isWhitespace(char)}.
7590      *
7591      * <p>
7592      * The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. For more control over the
7593      * split use the StrTokenizer class.
7594      * </p>
7595      *
7596      * <p>
7597      * A {@code null} input String returns {@code null}.
7598      * </p>
7599      *
7600      * <pre>
7601      * StringUtils.splitPreserveAllTokens(null)       = null
7602      * StringUtils.splitPreserveAllTokens("")         = []
7603      * StringUtils.splitPreserveAllTokens("abc def")  = ["abc", "def"]
7604      * StringUtils.splitPreserveAllTokens("abc  def") = ["abc", "", "def"]
7605      * StringUtils.splitPreserveAllTokens(" abc ")    = ["", "abc", ""]
7606      * </pre>
7607      *
7608      * @param str The String to parse, may be {@code null}.
7609      * @return An array of parsed Strings, {@code null} if null String input.
7610      * @since 2.1
7611      */
7612     public static String[] splitPreserveAllTokens(final String str) {
7613         return splitWorker(str, null, -1, true);
7614     }
7615 
7616     /**
7617      * Splits the provided text into an array, separator specified, preserving all tokens, including empty tokens created by adjacent separators. This is an
7618      * alternative to using StringTokenizer.
7619      *
7620      * <p>
7621      * The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. For more control over the
7622      * split use the StrTokenizer class.
7623      * </p>
7624      *
7625      * <p>
7626      * A {@code null} input String returns {@code null}.
7627      * </p>
7628      *
7629      * <pre>
7630      * StringUtils.splitPreserveAllTokens(null, *)         = null
7631      * StringUtils.splitPreserveAllTokens("", *)           = []
7632      * StringUtils.splitPreserveAllTokens("a.b.c", '.')    = ["a", "b", "c"]
7633      * StringUtils.splitPreserveAllTokens("a..b.c", '.')   = ["a", "", "b", "c"]
7634      * StringUtils.splitPreserveAllTokens("a:b:c", '.')    = ["a:b:c"]
7635      * StringUtils.splitPreserveAllTokens("a\tb\nc", null) = ["a", "b", "c"]
7636      * StringUtils.splitPreserveAllTokens("a b c", ' ')    = ["a", "b", "c"]
7637      * StringUtils.splitPreserveAllTokens("a b c ", ' ')   = ["a", "b", "c", ""]
7638      * StringUtils.splitPreserveAllTokens("a b c  ", ' ')  = ["a", "b", "c", "", ""]
7639      * StringUtils.splitPreserveAllTokens(" a b c", ' ')   = ["", "a", "b", "c"]
7640      * StringUtils.splitPreserveAllTokens("  a b c", ' ')  = ["", "", "a", "b", "c"]
7641      * StringUtils.splitPreserveAllTokens(" a b c ", ' ')  = ["", "a", "b", "c", ""]
7642      * </pre>
7643      *
7644      * @param str           The String to parse, may be {@code null}.
7645      * @param separatorChar The character used as the delimiter, {@code null} splits on whitespace.
7646      * @return An array of parsed Strings, {@code null} if null String input.
7647      * @since 2.1
7648      */
7649     public static String[] splitPreserveAllTokens(final String str, final char separatorChar) {
7650         return splitWorker(str, separatorChar, true);
7651     }
7652 
7653     /**
7654      * Splits the provided text into an array, separators specified, preserving all tokens, including empty tokens created by adjacent separators. This is an
7655      * alternative to using StringTokenizer.
7656      *
7657      * <p>
7658      * The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. For more control over the
7659      * split use the StrTokenizer class.
7660      * </p>
7661      *
7662      * <p>
7663      * A {@code null} input String returns {@code null}. A {@code null} separatorChars splits on whitespace.
7664      * </p>
7665      *
7666      * <pre>
7667      * StringUtils.splitPreserveAllTokens(null, *)           = null
7668      * StringUtils.splitPreserveAllTokens("", *)             = []
7669      * StringUtils.splitPreserveAllTokens("abc def", null)   = ["abc", "def"]
7670      * StringUtils.splitPreserveAllTokens("abc def", " ")    = ["abc", "def"]
7671      * StringUtils.splitPreserveAllTokens("abc  def", " ")   = ["abc", "", "def"]
7672      * StringUtils.splitPreserveAllTokens("ab:cd:ef", ":")   = ["ab", "cd", "ef"]
7673      * StringUtils.splitPreserveAllTokens("ab:cd:ef:", ":")  = ["ab", "cd", "ef", ""]
7674      * StringUtils.splitPreserveAllTokens("ab:cd:ef::", ":") = ["ab", "cd", "ef", "", ""]
7675      * StringUtils.splitPreserveAllTokens("ab::cd:ef", ":")  = ["ab", "", "cd", "ef"]
7676      * StringUtils.splitPreserveAllTokens(":cd:ef", ":")     = ["", "cd", "ef"]
7677      * StringUtils.splitPreserveAllTokens("::cd:ef", ":")    = ["", "", "cd", "ef"]
7678      * StringUtils.splitPreserveAllTokens(":cd:ef:", ":")    = ["", "cd", "ef", ""]
7679      * </pre>
7680      *
7681      * @param str            The String to parse, may be {@code null}.
7682      * @param separatorChars The characters used as the delimiters, {@code null} splits on whitespace.
7683      * @return An array of parsed Strings, {@code null} if null String input.
7684      * @since 2.1
7685      */
7686     public static String[] splitPreserveAllTokens(final String str, final String separatorChars) {
7687         return splitWorker(str, separatorChars, -1, true);
7688     }
7689 
7690     /**
7691      * Splits the provided text into an array with a maximum length, separators specified, preserving all tokens, including empty tokens created by adjacent
7692      * separators.
7693      *
7694      * <p>
7695      * The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. Adjacent separators are
7696      * treated as one separator.
7697      * </p>
7698      *
7699      * <p>
7700      * A {@code null} input String returns {@code null}. A {@code null} separatorChars splits on whitespace.
7701      * </p>
7702      *
7703      * <p>
7704      * If more than {@code max} delimited substrings are found, the last returned string includes all characters after the first {@code max - 1} returned
7705      * strings (including separator characters).
7706      * </p>
7707      *
7708      * <pre>
7709      * StringUtils.splitPreserveAllTokens(null, *, *)            = null
7710      * StringUtils.splitPreserveAllTokens("", *, *)              = []
7711      * StringUtils.splitPreserveAllTokens("ab de fg", null, 0)   = ["ab", "de", "fg"]
7712      * StringUtils.splitPreserveAllTokens("ab   de fg", null, 0) = ["ab", "", "", "de", "fg"]
7713      * StringUtils.splitPreserveAllTokens("ab:cd:ef", ":", 0)    = ["ab", "cd", "ef"]
7714      * StringUtils.splitPreserveAllTokens("ab:cd:ef", ":", 2)    = ["ab", "cd:ef"]
7715      * StringUtils.splitPreserveAllTokens("ab   de fg", null, 2) = ["ab", "  de fg"]
7716      * StringUtils.splitPreserveAllTokens("ab   de fg", null, 3) = ["ab", "", " de fg"]
7717      * StringUtils.splitPreserveAllTokens("ab   de fg", null, 4) = ["ab", "", "", "de fg"]
7718      * </pre>
7719      *
7720      * @param str            The String to parse, may be {@code null}.
7721      * @param separatorChars The characters used as the delimiters, {@code null} splits on whitespace.
7722      * @param max            The maximum number of elements to include in the array. A zero or negative value implies no limit.
7723      * @return An array of parsed Strings, {@code null} if null String input.
7724      * @since 2.1
7725      */
7726     public static String[] splitPreserveAllTokens(final String str, final String separatorChars, final int max) {
7727         return splitWorker(str, separatorChars, max, true);
7728     }
7729 
7730     /**
7731      * Tests whether a {@link String#substring} boundary at {@code index} would fall between the two halves of a surrogate pair, that is the char before
7732      * {@code index} is a high surrogate and the char at {@code index} is its low surrogate. Slicing there leaves a lone surrogate in the result.
7733      *
7734      * @param str   The String being sliced.
7735      * @param index A candidate substring boundary, in {@code char} units.
7736      * @return whether slicing at {@code index} would split a surrogate pair.
7737      */
7738     private static boolean splitsSurrogatePair(final String str, final int index) {
7739         return index > 0 && index < str.length() && Character.isHighSurrogate(str.charAt(index - 1)) && Character.isLowSurrogate(str.charAt(index));
7740     }
7741 
7742     /**
7743      * Performs the logic for the {@code split} and {@code splitPreserveAllTokens} methods that do not return a maximum array length.
7744      *
7745      * @param str               The String to parse, may be {@code null}.
7746      * @param separatorChar     The separate character.
7747      * @param preserveAllTokens if {@code true}, adjacent separators are treated as empty token separators; if {@code false}, adjacent separators are treated as
7748      *                          one separator.
7749      * @return An array of parsed Strings, {@code null} if null String input.
7750      */
7751     private static String[] splitWorker(final String str, final char separatorChar, final boolean preserveAllTokens) {
7752         // Performance tuned for 2.0 (JDK1.4)
7753         if (str == null) {
7754             return null;
7755         }
7756         final int len = str.length();
7757         if (len == 0) {
7758             return ArrayUtils.EMPTY_STRING_ARRAY;
7759         }
7760         final List<String> list = new ArrayList<>();
7761         int i = 0;
7762         int start = 0;
7763         boolean match = false;
7764         boolean lastMatch = false;
7765         while (i < len) {
7766             if (str.charAt(i) == separatorChar) {
7767                 if (match || preserveAllTokens) {
7768                     list.add(str.substring(start, i));
7769                     match = false;
7770                     lastMatch = true;
7771                 }
7772                 start = ++i;
7773                 continue;
7774             }
7775             lastMatch = false;
7776             match = true;
7777             i++;
7778         }
7779         if (match || preserveAllTokens && lastMatch) {
7780             list.add(str.substring(start, i));
7781         }
7782         return list.toArray(ArrayUtils.EMPTY_STRING_ARRAY);
7783     }
7784 
7785     /**
7786      * Performs the logic for the {@code split} and {@code splitPreserveAllTokens} methods that return a maximum array length.
7787      *
7788      * @param str               The String to parse, may be {@code null}.
7789      * @param separatorChars    The separate character.
7790      * @param max               The maximum number of elements to include in the array. A zero or negative value implies no limit.
7791      * @param preserveAllTokens if {@code true}, adjacent separators are treated as empty token separators; if {@code false}, adjacent separators are treated as
7792      *                          one separator.
7793      * @return An array of parsed Strings, {@code null} if null String input.
7794      */
7795     private static String[] splitWorker(final String str, final String separatorChars, final int max, final boolean preserveAllTokens) {
7796         // Performance tuned for 2.0 (JDK1.4)
7797         // Direct code is quicker than StringTokenizer.
7798         // Also, StringTokenizer uses isSpace() not isWhitespace()
7799         if (str == null) {
7800             return null;
7801         }
7802         final int len = str.length();
7803         if (len == 0) {
7804             return ArrayUtils.EMPTY_STRING_ARRAY;
7805         }
7806         final List<String> list = new ArrayList<>();
7807         int sizePlus1 = 1;
7808         int i = 0;
7809         int start = 0;
7810         boolean match = false;
7811         boolean lastMatch = false;
7812         if (separatorChars == null) {
7813             // Null separator means use whitespace
7814             while (i < len) {
7815                 if (Character.isWhitespace(str.charAt(i))) {
7816                     if (match || preserveAllTokens) {
7817                         lastMatch = true;
7818                         if (sizePlus1++ == max) {
7819                             i = len;
7820                             lastMatch = false;
7821                         }
7822                         list.add(str.substring(start, i));
7823                         match = false;
7824                     }
7825                     start = ++i;
7826                     continue;
7827                 }
7828                 lastMatch = false;
7829                 match = true;
7830                 i++;
7831             }
7832         } else if (separatorChars.length() == 1) {
7833             // Optimize 1 character case
7834             final char sep = separatorChars.charAt(0);
7835             while (i < len) {
7836                 if (str.charAt(i) == sep) {
7837                     if (match || preserveAllTokens) {
7838                         lastMatch = true;
7839                         if (sizePlus1++ == max) {
7840                             i = len;
7841                             lastMatch = false;
7842                         }
7843                         list.add(str.substring(start, i));
7844                         match = false;
7845                     }
7846                     start = ++i;
7847                     continue;
7848                 }
7849                 lastMatch = false;
7850                 match = true;
7851                 i++;
7852             }
7853         } else {
7854             // standard case
7855             while (i < len) {
7856                 if (separatorChars.indexOf(str.charAt(i)) >= 0) {
7857                     if (match || preserveAllTokens) {
7858                         lastMatch = true;
7859                         if (sizePlus1++ == max) {
7860                             i = len;
7861                             lastMatch = false;
7862                         }
7863                         list.add(str.substring(start, i));
7864                         match = false;
7865                     }
7866                     start = ++i;
7867                     continue;
7868                 }
7869                 lastMatch = false;
7870                 match = true;
7871                 i++;
7872             }
7873         }
7874         if (match || preserveAllTokens && lastMatch) {
7875             list.add(str.substring(start, i));
7876         }
7877         return list.toArray(ArrayUtils.EMPTY_STRING_ARRAY);
7878     }
7879 
7880     /**
7881      * Tests if a CharSequence starts with a specified prefix.
7882      *
7883      * <p>
7884      * {@code null}s are handled without exceptions. Two {@code null} references are considered to be equal. The comparison is case-sensitive.
7885      * </p>
7886      *
7887      * <pre>
7888      * StringUtils.startsWith(null, null)      = true
7889      * StringUtils.startsWith(null, "abc")     = false
7890      * StringUtils.startsWith("abcdef", null)  = false
7891      * StringUtils.startsWith("abcdef", "abc") = true
7892      * StringUtils.startsWith("ABCDEF", "abc") = false
7893      * </pre>
7894      *
7895      * @param str    The CharSequence to check, may be null.
7896      * @param prefix The prefix to find, may be null.
7897      * @return {@code true} if the CharSequence starts with the prefix, case-sensitive, or both {@code null}.
7898      * @see String#startsWith(String)
7899      * @since 2.4
7900      * @since 3.0 Changed signature from startsWith(String, String) to startsWith(CharSequence, CharSequence)
7901      * @deprecated Use {@link Strings#startsWith(CharSequence, CharSequence) Strings.CS.startsWith(CharSequence, CharSequence)}.
7902      */
7903     @Deprecated
7904     public static boolean startsWith(final CharSequence str, final CharSequence prefix) {
7905         return Strings.CS.startsWith(str, prefix);
7906     }
7907 
7908     /**
7909      * Tests if a CharSequence starts with any of the provided case-sensitive prefixes.
7910      *
7911      * <pre>
7912      * StringUtils.startsWithAny(null, null)      = false
7913      * StringUtils.startsWithAny(null, new String[] {"abc"})  = false
7914      * StringUtils.startsWithAny("abcxyz", null)     = false
7915      * StringUtils.startsWithAny("abcxyz", new String[] {""}) = true
7916      * StringUtils.startsWithAny("abcxyz", new String[] {"abc"}) = true
7917      * StringUtils.startsWithAny("abcxyz", new String[] {null, "xyz", "abc"}) = true
7918      * StringUtils.startsWithAny("abcxyz", null, "xyz", "ABCX") = false
7919      * StringUtils.startsWithAny("ABCXYZ", null, "xyz", "abc") = false
7920      * </pre>
7921      *
7922      * @param sequence      The CharSequence to check, may be null.
7923      * @param searchStrings The case-sensitive CharSequence prefixes, may be empty or contain {@code null}.
7924      * @return {@code true} if the input {@code sequence} is {@code null} AND no {@code searchStrings} are provided, or the input {@code sequence} begins with
7925      *         any of the provided case-sensitive {@code searchStrings}.
7926      * @see StringUtils#startsWith(CharSequence, CharSequence)
7927      * @since 2.5
7928      * @since 3.0 Changed signature from startsWithAny(String, String[]) to startsWithAny(CharSequence, CharSequence...)
7929      * @deprecated Use {@link Strings#startsWithAny(CharSequence, CharSequence...) Strings.CS.startsWithAny(CharSequence, CharSequence...)}.
7930      */
7931     @Deprecated
7932     public static boolean startsWithAny(final CharSequence sequence, final CharSequence... searchStrings) {
7933         return Strings.CS.startsWithAny(sequence, searchStrings);
7934     }
7935 
7936     /**
7937      * Case-insensitive check if a CharSequence starts with a specified prefix.
7938      *
7939      * <p>
7940      * {@code null}s are handled without exceptions. Two {@code null} references are considered to be equal. The comparison is case insensitive.
7941      * </p>
7942      *
7943      * <pre>
7944      * StringUtils.startsWithIgnoreCase(null, null)      = true
7945      * StringUtils.startsWithIgnoreCase(null, "abc")     = false
7946      * StringUtils.startsWithIgnoreCase("abcdef", null)  = false
7947      * StringUtils.startsWithIgnoreCase("abcdef", "abc") = true
7948      * StringUtils.startsWithIgnoreCase("ABCDEF", "abc") = true
7949      * </pre>
7950      *
7951      * @param str    The CharSequence to check, may be null.
7952      * @param prefix The prefix to find, may be null.
7953      * @return {@code true} if the CharSequence starts with the prefix, case-insensitive, or both {@code null}.
7954      * @see String#startsWith(String)
7955      * @since 2.4
7956      * @since 3.0 Changed signature from startsWithIgnoreCase(String, String) to startsWithIgnoreCase(CharSequence, CharSequence)
7957      * @deprecated Use {@link Strings#startsWith(CharSequence, CharSequence) Strings.CI.startsWith(CharSequence, CharSequence)}.
7958      */
7959     @Deprecated
7960     public static boolean startsWithIgnoreCase(final CharSequence str, final CharSequence prefix) {
7961         return Strings.CI.startsWith(str, prefix);
7962     }
7963 
7964     /**
7965      * Strips whitespace from the start and end of a String.
7966      *
7967      * <p>
7968      * This is similar to {@link #trim(String)} but removes whitespace. Whitespace is defined by {@link Character#isWhitespace(char)}.
7969      * </p>
7970      *
7971      * <p>
7972      * A {@code null} input String returns {@code null}.
7973      * </p>
7974      *
7975      * <pre>
7976      * StringUtils.strip(null)     = null
7977      * StringUtils.strip("")       = ""
7978      * StringUtils.strip("   ")    = ""
7979      * StringUtils.strip("abc")    = "abc"
7980      * StringUtils.strip("  abc")  = "abc"
7981      * StringUtils.strip("abc  ")  = "abc"
7982      * StringUtils.strip(" abc ")  = "abc"
7983      * StringUtils.strip(" ab c ") = "ab c"
7984      * </pre>
7985      *
7986      * @param str The String to remove whitespace from, may be null.
7987      * @return The stripped String, {@code null} if null String input.
7988      */
7989     public static String strip(final String str) {
7990         return strip(str, null);
7991     }
7992 
7993     /**
7994      * Strips any of a set of characters from the start and end of a String. This is similar to {@link String#trim()} but allows the characters to be stripped
7995      * to be controlled.
7996      *
7997      * <p>
7998      * A {@code null} input String returns {@code null}. An empty string ("") input returns the empty string.
7999      * </p>
8000      *
8001      * <p>
8002      * If the stripChars String is {@code null}, whitespace is stripped as defined by {@link Character#isWhitespace(char)}. Alternatively use
8003      * {@link #strip(String)}.
8004      * </p>
8005      *
8006      * <pre>
8007      * StringUtils.strip(null, *)          = null
8008      * StringUtils.strip("", *)            = ""
8009      * StringUtils.strip("abc", null)      = "abc"
8010      * StringUtils.strip("  abc", null)    = "abc"
8011      * StringUtils.strip("abc  ", null)    = "abc"
8012      * StringUtils.strip(" abc ", null)    = "abc"
8013      * StringUtils.strip("  abcyx", "xyz") = "  abc"
8014      * </pre>
8015      *
8016      * @param str        The String to remove characters from, may be null.
8017      * @param stripChars The characters to remove, null treated as whitespace.
8018      * @return The stripped String, {@code null} if null String input.
8019      */
8020     public static String strip(String str, final String stripChars) {
8021         str = stripStart(str, stripChars);
8022         return stripEnd(str, stripChars);
8023     }
8024 
8025     /**
8026      * Removes diacritics (~= accents) from a string. The case will not be altered.
8027      * <p>
8028      * For instance, '&agrave;' will be replaced by 'a'.
8029      * </p>
8030      * <p>
8031      * Decomposes ligatures and digraphs per the KD column in the <a href = "https://www.unicode.org/charts/normalization/">Unicode Normalization Chart.</a>
8032      * </p>
8033      * <p>
8034      * Be aware that this NFKD compatibility decomposition can map non-letter compatibility forms (fullwidth, small-form, math-symbol variants of {@code <},
8035      * {@code >}, {@code /}, and so on) to their ASCII counterparts.
8036      * </p>
8037      *
8038      * <pre>
8039      * StringUtils.stripAccents(null)         = null
8040      * StringUtils.stripAccents("")           = ""
8041      * StringUtils.stripAccents("control")    = "control"
8042      * StringUtils.stripAccents("&eacute;clair")     = "eclair"
8043      * StringUtils.stripAccents("\u1d43\u1d47\u1d9c\u00b9\u00b2\u00b3")     = "abc123"
8044      * StringUtils.stripAccents("\u00BC \u00BD \u00BE")      = "1⁄4 1⁄2 3⁄4"
8045      * </pre>
8046      * <p>
8047      * See also <a href="https://www.unicode.org/unicode/reports/tr15/tr15-23.html">Unicode Standard Annex #15 Unicode Normalization Forms</a>.
8048      * </p>
8049      *
8050      * @param input String to be stripped.
8051      * @return input text with diacritics removed.
8052      * @since 3.0
8053      */
8054     // See also Lucene's ASCIIFoldingFilter (Lucene 2.9) that replaces accented characters by their unaccented equivalent (and uncommitted bug fix:
8055     // https://issues.apache.org/jira/browse/LUCENE-1343?focusedCommentId=12858907&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#action_12858907).
8056     public static String stripAccents(final String input) {
8057         if (isEmpty(input)) {
8058             return input;
8059         }
8060         final StringBuilder decomposed = new StringBuilder(Normalizer.normalize(input, Normalizer.Form.NFKD));
8061         convertRemainingAccentCharacters(decomposed);
8062         final String stripped = STRIP_ACCENTS_PATTERN.matcher(decomposed).replaceAll(EMPTY);
8063         return Normalizer.normalize(stripped, Normalizer.Form.NFC);
8064     }
8065 
8066     /**
8067      * Strips whitespace from the start and end of every String in an array. Whitespace is defined by {@link Character#isWhitespace(char)}.
8068      *
8069      * <p>
8070      * A new array is returned each time, except for length zero. A {@code null} array will return {@code null}. An empty array will return itself. A
8071      * {@code null} array entry will be ignored.
8072      * </p>
8073      *
8074      * <pre>
8075      * StringUtils.stripAll(null)             = null
8076      * StringUtils.stripAll([])               = []
8077      * StringUtils.stripAll(["abc", "  abc"]) = ["abc", "abc"]
8078      * StringUtils.stripAll(["abc  ", null])  = ["abc", null]
8079      * </pre>
8080      *
8081      * @param strs The array to remove whitespace from, may be null.
8082      * @return The stripped Strings, {@code null} if null array input.
8083      */
8084     public static String[] stripAll(final String... strs) {
8085         return stripAll(strs, null);
8086     }
8087 
8088     /**
8089      * Strips any of a set of characters from the start and end of every String in an array.
8090      * <p>
8091      * Whitespace is defined by {@link Character#isWhitespace(char)}.
8092      * </p>
8093      *
8094      * <p>
8095      * A new array is returned each time, except for length zero. A {@code null} array will return {@code null}. An empty array will return itself. A
8096      * {@code null} array entry will be ignored. A {@code null} stripChars will strip whitespace as defined by {@link Character#isWhitespace(char)}.
8097      * </p>
8098      *
8099      * <pre>
8100      * StringUtils.stripAll(null, *)                = null
8101      * StringUtils.stripAll([], *)                  = []
8102      * StringUtils.stripAll(["abc", "  abc"], null) = ["abc", "abc"]
8103      * StringUtils.stripAll(["abc  ", null], null)  = ["abc", null]
8104      * StringUtils.stripAll(["abc  ", null], "yz")  = ["abc  ", null]
8105      * StringUtils.stripAll(["yabcz", null], "yz")  = ["abc", null]
8106      * </pre>
8107      *
8108      * @param strs       The array to remove characters from, may be null.
8109      * @param stripChars The characters to remove, null treated as whitespace.
8110      * @return The stripped Strings, {@code null} if null array input.
8111      */
8112     public static String[] stripAll(final String[] strs, final String stripChars) {
8113         final int strsLen = ArrayUtils.getLength(strs);
8114         if (strsLen == 0) {
8115             return strs;
8116         }
8117         return ArrayUtils.setAll(new String[strsLen], i -> strip(strs[i], stripChars));
8118     }
8119 
8120     /**
8121      * Strips any of a set of characters from the end of a String.
8122      *
8123      * <p>
8124      * A {@code null} input String returns {@code null}. An empty string ("") input returns the empty string.
8125      * </p>
8126      *
8127      * <p>
8128      * If the stripChars String is {@code null}, whitespace is stripped as defined by {@link Character#isWhitespace(char)}.
8129      * </p>
8130      *
8131      * <p>
8132      * The characters in {@code stripChars} are treated individually, not as a suffix. To remove a suffix as a whole,
8133      * use {@link Strings#removeEnd(String, CharSequence)} on {@link Strings#CS} instead.
8134      * </p>
8135      *
8136      * <pre>
8137      * StringUtils.stripEnd(null, *)          = null
8138      * StringUtils.stripEnd("", *)            = ""
8139      * StringUtils.stripEnd("abc", "")        = "abc"
8140      * StringUtils.stripEnd("abc", null)      = "abc"
8141      * StringUtils.stripEnd("  abc", null)    = "  abc"
8142      * StringUtils.stripEnd("abc  ", null)    = "abc"
8143      * StringUtils.stripEnd(" abc ", null)    = " abc"
8144      * StringUtils.stripEnd("  abcyx", "xyz") = "  abc"
8145      * StringUtils.stripEnd("120.00", ".0")   = "12"
8146      * StringUtils.stripEnd("85123116", "16") = "85123"
8147      * </pre>
8148      *
8149      * @param str        The String to remove characters from, may be null.
8150      * @param stripChars The set of characters to remove, null treated as whitespace.
8151      * @return The stripped String, {@code null} if null String input.
8152      */
8153     public static String stripEnd(final String str, final String stripChars) {
8154         int end = length(str);
8155         if (end == 0) {
8156             return str;
8157         }
8158         if (stripChars == null) {
8159             while (end != 0 && Character.isWhitespace(str.charAt(end - 1))) {
8160                 end--;
8161             }
8162         } else if (stripChars.isEmpty()) {
8163             return str;
8164         } else {
8165             while (end != 0) {
8166                 final int codePoint = str.codePointBefore(end);
8167                 if (stripChars.indexOf(codePoint) == INDEX_NOT_FOUND) {
8168                     break;
8169                 }
8170                 end -= Character.charCount(codePoint);
8171             }
8172         }
8173         return str.substring(0, end);
8174     }
8175 
8176     /**
8177      * Strips any of a set of characters from the start of a String.
8178      *
8179      * <p>
8180      * A {@code null} input String returns {@code null}. An empty string ("") input returns the empty string.
8181      * </p>
8182      *
8183      * <p>
8184      * If the stripChars String is {@code null}, whitespace is stripped as defined by {@link Character#isWhitespace(char)}.
8185      * </p>
8186      *
8187      * <pre>
8188      * StringUtils.stripStart(null, *)          = null
8189      * StringUtils.stripStart("", *)            = ""
8190      * StringUtils.stripStart("abc", "")        = "abc"
8191      * StringUtils.stripStart("abc", null)      = "abc"
8192      * StringUtils.stripStart("  abc", null)    = "abc"
8193      * StringUtils.stripStart("abc  ", null)    = "abc  "
8194      * StringUtils.stripStart(" abc ", null)    = "abc "
8195      * StringUtils.stripStart("yxabc  ", "xyz") = "abc  "
8196      * </pre>
8197      *
8198      * @param str        The String to remove characters from, may be null.
8199      * @param stripChars The characters to remove, null treated as whitespace.
8200      * @return The stripped String, {@code null} if null String input.
8201      */
8202     public static String stripStart(final String str, final String stripChars) {
8203         final int strLen = length(str);
8204         if (strLen == 0) {
8205             return str;
8206         }
8207         int start = 0;
8208         if (stripChars == null) {
8209             while (start != strLen && Character.isWhitespace(str.charAt(start))) {
8210                 start++;
8211             }
8212         } else if (stripChars.isEmpty()) {
8213             return str;
8214         } else {
8215             while (start != strLen) {
8216                 final int codePoint = str.codePointAt(start);
8217                 if (stripChars.indexOf(codePoint) == INDEX_NOT_FOUND) {
8218                     break;
8219                 }
8220                 start += Character.charCount(codePoint);
8221             }
8222         }
8223         return str.substring(start);
8224     }
8225 
8226     /**
8227      * Strips whitespace from the start and end of a String returning an empty String if {@code null} input.
8228      *
8229      * <p>
8230      * This is similar to {@link #trimToEmpty(String)} but removes whitespace. Whitespace is defined by {@link Character#isWhitespace(char)}.
8231      * </p>
8232      *
8233      * <pre>
8234      * StringUtils.stripToEmpty(null)     = ""
8235      * StringUtils.stripToEmpty("")       = ""
8236      * StringUtils.stripToEmpty("   ")    = ""
8237      * StringUtils.stripToEmpty("abc")    = "abc"
8238      * StringUtils.stripToEmpty("  abc")  = "abc"
8239      * StringUtils.stripToEmpty("abc  ")  = "abc"
8240      * StringUtils.stripToEmpty(" abc ")  = "abc"
8241      * StringUtils.stripToEmpty(" ab c ") = "ab c"
8242      * </pre>
8243      *
8244      * @param str The String to be stripped, may be null.
8245      * @return The trimmed String, or an empty String if {@code null} input.
8246      * @since 2.0
8247      */
8248     public static String stripToEmpty(final String str) {
8249         return str == null ? EMPTY : strip(str, null);
8250     }
8251 
8252     /**
8253      * Strips whitespace from the start and end of a String returning {@code null} if the String is empty ("") after the strip.
8254      *
8255      * <p>
8256      * This is similar to {@link #trimToNull(String)} but removes whitespace. Whitespace is defined by {@link Character#isWhitespace(char)}.
8257      * </p>
8258      *
8259      * <pre>
8260      * StringUtils.stripToNull(null)     = null
8261      * StringUtils.stripToNull("")       = null
8262      * StringUtils.stripToNull("   ")    = null
8263      * StringUtils.stripToNull("abc")    = "abc"
8264      * StringUtils.stripToNull("  abc")  = "abc"
8265      * StringUtils.stripToNull("abc  ")  = "abc"
8266      * StringUtils.stripToNull(" abc ")  = "abc"
8267      * StringUtils.stripToNull(" ab c ") = "ab c"
8268      * </pre>
8269      *
8270      * @param str The String to be stripped, may be null.
8271      * @return The stripped String, {@code null} if whitespace, empty or null String input.
8272      * @since 2.0
8273      */
8274     public static String stripToNull(String str) {
8275         if (str == null) {
8276             return null;
8277         }
8278         str = strip(str, null);
8279         return str.isEmpty() ? null : str; // NOSONARLINT str cannot be null here
8280     }
8281 
8282     /**
8283      * Gets a substring from the specified String avoiding exceptions.
8284      *
8285      * <p>
8286      * A negative start position can be used to start {@code n} characters from the end of the String.
8287      * </p>
8288      *
8289      * <p>
8290      * A {@code null} String will return {@code null}. An empty ("") String will return "".
8291      * </p>
8292      *
8293      * <pre>
8294      * StringUtils.substring(null, *)   = null
8295      * StringUtils.substring("", *)     = ""
8296      * StringUtils.substring("abc", 0)  = "abc"
8297      * StringUtils.substring("abc", 2)  = "c"
8298      * StringUtils.substring("abc", 4)  = ""
8299      * StringUtils.substring("abc", -2) = "bc"
8300      * StringUtils.substring("abc", -4) = "abc"
8301      * </pre>
8302      *
8303      * @param str   The String to get the substring from, may be null.
8304      * @param start The position to start from, negative means count back from the end of the String by this many characters.
8305      * @return substring from start position, {@code null} if null String input.
8306      */
8307     public static String substring(final String str, int start) {
8308         if (str == null) {
8309             return null;
8310         }
8311         // handle negatives, which means last n characters
8312         if (start < 0) {
8313             start = str.length() + start; // remember start is negative
8314         }
8315         if (start < 0) {
8316             start = 0;
8317         }
8318         if (start > str.length()) {
8319             return EMPTY;
8320         }
8321         return str.substring(start);
8322     }
8323 
8324     /**
8325      * Gets a substring from the specified String avoiding exceptions.
8326      *
8327      * <p>
8328      * A negative start position can be used to start/end {@code n} characters from the end of the String.
8329      * </p>
8330      *
8331      * <p>
8332      * The returned substring starts with the character in the {@code start} position and ends before the {@code end} position. All position counting is
8333      * zero-based -- i.e., to start at the beginning of the string use {@code start = 0}. Negative start and end positions can be used to specify offsets
8334      * relative to the end of the String.
8335      * </p>
8336      *
8337      * <p>
8338      * If {@code start} is not strictly to the left of {@code end}, "" is returned.
8339      * </p>
8340      *
8341      * <pre>
8342      * StringUtils.substring(null, *, *)    = null
8343      * StringUtils.substring("", * ,  *)    = "";
8344      * StringUtils.substring("abc", 0, 2)   = "ab"
8345      * StringUtils.substring("abc", 2, 0)   = ""
8346      * StringUtils.substring("abc", 2, 4)   = "c"
8347      * StringUtils.substring("abc", 4, 6)   = ""
8348      * StringUtils.substring("abc", 2, 2)   = ""
8349      * StringUtils.substring("abc", -2, -1) = "b"
8350      * StringUtils.substring("abc", -4, 2)  = "ab"
8351      * </pre>
8352      *
8353      * @param str   The String to get the substring from, may be null.
8354      * @param start The position to start from, negative means count back from the end of the String by this many characters.
8355      * @param end   The position to end at (exclusive), negative means count back from the end of the String by this many characters.
8356      * @return substring from start position to end position, {@code null} if null String input.
8357      */
8358     public static String substring(final String str, int start, int end) {
8359         if (str == null) {
8360             return null;
8361         }
8362         // handle negatives
8363         if (end < 0) {
8364             end = str.length() + end; // remember end is negative
8365         }
8366         if (start < 0) {
8367             start = str.length() + start; // remember start is negative
8368         }
8369         // check length next
8370         if (end > str.length()) {
8371             end = str.length();
8372         }
8373         // if start is greater than end, return ""
8374         if (start > end) {
8375             return EMPTY;
8376         }
8377         if (start < 0) {
8378             start = 0;
8379         }
8380         if (end < 0) {
8381             end = 0;
8382         }
8383         return str.substring(start, end);
8384     }
8385 
8386     /**
8387      * Gets the substring after the first occurrence of a separator. The separator is not returned.
8388      *
8389      * <p>
8390      * A {@code null} string input will return {@code null}. An empty ("") string input will return the empty string.
8391      * </p>
8392      *
8393      * <p>
8394      * If nothing is found, the empty string is returned.
8395      * </p>
8396      *
8397      * <pre>
8398      * StringUtils.substringAfter(null, *)      = null
8399      * StringUtils.substringAfter("", *)        = ""
8400      * StringUtils.substringAfter("abc", 'a')   = "bc"
8401      * StringUtils.substringAfter("abcba", 'b') = "cba"
8402      * StringUtils.substringAfter("abc", 'c')   = ""
8403      * StringUtils.substringAfter("abc", 'd')   = ""
8404      * StringUtils.substringAfter(" abc", 32)   = "abc"
8405      * </pre>
8406      *
8407      * @param str       The String to get a substring from, may be null.
8408      * @param find The character (Unicode code point) to find.
8409      * @return The substring after the first occurrence of the specified character, {@code null} if null String input.
8410      * @since 3.11
8411      */
8412     public static String substringAfter(final String str, final int find) {
8413         if (isEmpty(str)) {
8414             return str;
8415         }
8416         final int pos = str.indexOf(find);
8417         if (pos == INDEX_NOT_FOUND) {
8418             return EMPTY;
8419         }
8420         return str.substring(pos + Character.charCount(find));
8421     }
8422 
8423     /**
8424      * Gets the substring after the first occurrence of a separator. The separator is not returned.
8425      *
8426      * <p>
8427      * A {@code null} string input will return {@code null}. An empty ("") string input will return the empty string. A {@code null} separator will return the
8428      * empty string if the input string is not {@code null}.
8429      * </p>
8430      *
8431      * <p>
8432      * If nothing is found, the empty string is returned.
8433      * </p>
8434      *
8435      * <pre>
8436      * StringUtils.substringAfter(null, *)      = null
8437      * StringUtils.substringAfter("", *)        = ""
8438      * StringUtils.substringAfter(*, null)      = ""
8439      * StringUtils.substringAfter("abc", "a")   = "bc"
8440      * StringUtils.substringAfter("abcba", "b") = "cba"
8441      * StringUtils.substringAfter("abc", "c")   = ""
8442      * StringUtils.substringAfter("abc", "d")   = ""
8443      * StringUtils.substringAfter("abc", "")    = "abc"
8444      * </pre>
8445      *
8446      * @param str       The String to get a substring from, may be null.
8447      * @param find The String to find, may be null.
8448      * @return The substring after the first occurrence of the specified string, {@code null} if null String input.
8449      * @since 2.0
8450      */
8451     public static String substringAfter(final String str, final String find) {
8452         if (isEmpty(str)) {
8453             return str;
8454         }
8455         if (find == null) {
8456             return EMPTY;
8457         }
8458         final int pos = str.indexOf(find);
8459         if (pos == INDEX_NOT_FOUND) {
8460             return EMPTY;
8461         }
8462         return str.substring(pos + find.length());
8463     }
8464 
8465     /**
8466      * Gets the substring after the last occurrence of a separator. The separator is not returned.
8467      *
8468      * <p>
8469      * A {@code null} string input will return {@code null}. An empty ("") string input will return the empty string.
8470      * </p>
8471      *
8472      * <p>
8473      * If nothing is found, the empty string is returned.
8474      * </p>
8475      *
8476      * <pre>
8477      * StringUtils.substringAfterLast(null, *)      = null
8478      * StringUtils.substringAfterLast("", *)        = ""
8479      * StringUtils.substringAfterLast("abc", 'a')   = "bc"
8480      * StringUtils.substringAfterLast(" bc", 32)    = "bc"
8481      * StringUtils.substringAfterLast("abcba", 'b') = "a"
8482      * StringUtils.substringAfterLast("abc", 'c')   = ""
8483      * StringUtils.substringAfterLast("a", 'a')     = ""
8484      * StringUtils.substringAfterLast("a", 'z')     = ""
8485      * </pre>
8486      *
8487      * @param str       The String to get a substring from, may be null.
8488      * @param find The character (Unicode code point) to find.
8489      * @return The substring after the last occurrence of the specified character, {@code null} if null String input.
8490      * @since 3.11
8491      */
8492     public static String substringAfterLast(final String str, final int find) {
8493         if (isEmpty(str)) {
8494             return str;
8495         }
8496         final int pos = str.lastIndexOf(find);
8497         if (pos == INDEX_NOT_FOUND || pos == str.length() - Character.charCount(find)) {
8498             return EMPTY;
8499         }
8500         return str.substring(pos + Character.charCount(find));
8501     }
8502 
8503     /**
8504      * Gets the substring after the last occurrence of a separator. The separator is not returned.
8505      *
8506      * <p>
8507      * A {@code null} string input will return {@code null}. An empty ("") string input will return the empty string. An empty or {@code null} separator will
8508      * return the empty string if the input string is not {@code null}.
8509      * </p>
8510      *
8511      * <p>
8512      * If nothing is found, the empty string is returned.
8513      * </p>
8514      *
8515      * <pre>
8516      * StringUtils.substringAfterLast(null, *)      = null
8517      * StringUtils.substringAfterLast("", *)        = ""
8518      * StringUtils.substringAfterLast(*, "")        = ""
8519      * StringUtils.substringAfterLast(*, null)      = ""
8520      * StringUtils.substringAfterLast("abc", "a")   = "bc"
8521      * StringUtils.substringAfterLast("abcba", "b") = "a"
8522      * StringUtils.substringAfterLast("abc", "c")   = ""
8523      * StringUtils.substringAfterLast("a", "a")     = ""
8524      * StringUtils.substringAfterLast("a", "z")     = ""
8525      * </pre>
8526      *
8527      * @param str       The String to get a substring from, may be null.
8528      * @param find The String to find, may be null.
8529      * @return The substring after the last occurrence of the specified string, {@code null} if null String input.
8530      * @since 2.0
8531      */
8532     public static String substringAfterLast(final String str, final String find) {
8533         if (isEmpty(str)) {
8534             return str;
8535         }
8536         if (isEmpty(find)) {
8537             return EMPTY;
8538         }
8539         final int pos = str.lastIndexOf(find);
8540         if (pos == INDEX_NOT_FOUND || pos == str.length() - find.length()) {
8541             return EMPTY;
8542         }
8543         return str.substring(pos + find.length());
8544     }
8545 
8546     /**
8547      * Gets the substring before the first occurrence of a separator. The separator is not returned.
8548      *
8549      * <p>
8550      * A {@code null} string input will return {@code null}. An empty ("") string input will return the empty string.
8551      * </p>
8552      *
8553      * <p>
8554      * If nothing is found, the string input is returned.
8555      * </p>
8556      *
8557      * <pre>
8558      * StringUtils.substringBefore(null, *)      = null
8559      * StringUtils.substringBefore("", *)        = ""
8560      * StringUtils.substringBefore("abc", 'a')   = ""
8561      * StringUtils.substringBefore("abcba", 'b') = "a"
8562      * StringUtils.substringBefore("abc", 'c')   = "ab"
8563      * StringUtils.substringBefore("abc", 'd')   = "abc"
8564      * </pre>
8565      *
8566      * @param str       The String to get a substring from, may be null.
8567      * @param find The character (Unicode code point) to find.
8568      * @return The substring before the first occurrence of the specified character, {@code null} if null String input.
8569      * @since 3.12.0
8570      */
8571     public static String substringBefore(final String str, final int find) {
8572         if (isEmpty(str)) {
8573             return str;
8574         }
8575         final int pos = str.indexOf(find);
8576         if (pos == INDEX_NOT_FOUND) {
8577             return str;
8578         }
8579         return str.substring(0, pos);
8580     }
8581 
8582     /**
8583      * Gets the substring before the first occurrence of a separator. The separator is not returned.
8584      *
8585      * <p>
8586      * A {@code null} string input will return {@code null}. An empty ("") string input will return the empty string. A {@code null} separator will return the
8587      * input string.
8588      * </p>
8589      *
8590      * <p>
8591      * If nothing is found, the string input is returned.
8592      * </p>
8593      *
8594      * <pre>
8595      * StringUtils.substringBefore(null, *)      = null
8596      * StringUtils.substringBefore("", *)        = ""
8597      * StringUtils.substringBefore("abc", "a")   = ""
8598      * StringUtils.substringBefore("abcba", "b") = "a"
8599      * StringUtils.substringBefore("abc", "c")   = "ab"
8600      * StringUtils.substringBefore("abc", "d")   = "abc"
8601      * StringUtils.substringBefore("abc", "")    = ""
8602      * StringUtils.substringBefore("abc", null)  = "abc"
8603      * </pre>
8604      *
8605      * @param str       The String to get a substring from, may be null.
8606      * @param find The String to find, may be null.
8607      * @return The substring before the first occurrence of the specified string, {@code null} if null String input.
8608      * @since 2.0
8609      */
8610     public static String substringBefore(final String str, final String find) {
8611         if (isEmpty(str) || find == null) {
8612             return str;
8613         }
8614         if (find.isEmpty()) {
8615             return EMPTY;
8616         }
8617         final int pos = str.indexOf(find);
8618         if (pos == INDEX_NOT_FOUND) {
8619             return str;
8620         }
8621         return str.substring(0, pos);
8622     }
8623 
8624     /**
8625      * Gets the substring before the last occurrence of a separator. The separator is not returned.
8626      *
8627      * <p>
8628      * A {@code null} string input will return {@code null}. An empty ("") string input will return the empty string. An empty or {@code null} separator will
8629      * return the input string.
8630      * </p>
8631      *
8632      * <p>
8633      * If nothing is found, the string input is returned.
8634      * </p>
8635      *
8636      * <pre>
8637      * StringUtils.substringBeforeLast(null, *)      = null
8638      * StringUtils.substringBeforeLast("", *)        = ""
8639      * StringUtils.substringBeforeLast("abcba", "b") = "abc"
8640      * StringUtils.substringBeforeLast("abc", "c")   = "ab"
8641      * StringUtils.substringBeforeLast("a", "a")     = ""
8642      * StringUtils.substringBeforeLast("a", "z")     = "a"
8643      * StringUtils.substringBeforeLast("a", null)    = "a"
8644      * StringUtils.substringBeforeLast("a", "")      = "a"
8645      * </pre>
8646      *
8647      * @param str       The String to get a substring from, may be null.
8648      * @param find The String to find, may be null.
8649      * @return The substring before the last occurrence of the specified string, {@code null} if null String input.
8650      * @since 2.0
8651      */
8652     public static String substringBeforeLast(final String str, final String find) {
8653         if (isEmpty(str) || isEmpty(find)) {
8654             return str;
8655         }
8656         final int pos = str.lastIndexOf(find);
8657         if (pos == INDEX_NOT_FOUND) {
8658             return str;
8659         }
8660         return str.substring(0, pos);
8661     }
8662 
8663     /**
8664      * Gets the String that is nested in between two instances of the same String.
8665      *
8666      * <p>
8667      * A {@code null} input String returns {@code null}. A {@code null} tag returns {@code null}.
8668      * </p>
8669      *
8670      * <pre>
8671      * StringUtils.substringBetween(null, *)            = null
8672      * StringUtils.substringBetween("", "")             = ""
8673      * StringUtils.substringBetween("", "tag")          = null
8674      * StringUtils.substringBetween("tagabctag", null)  = null
8675      * StringUtils.substringBetween("tagabctag", "")    = ""
8676      * StringUtils.substringBetween("tagabctag", "tag") = "abc"
8677      * </pre>
8678      *
8679      * @param str The String containing the substring, may be null.
8680      * @param tag The String before and after the substring, may be null.
8681      * @return The substring, {@code null} if no match.
8682      * @since 2.0
8683      */
8684     public static String substringBetween(final String str, final String tag) {
8685         return substringBetween(str, tag, tag);
8686     }
8687 
8688     /**
8689      * Gets the String that is nested in between two Strings. Only the first match is returned.
8690      *
8691      * <p>
8692      * A {@code null} input String returns {@code null}. A {@code null} open/close returns {@code null} (no match). An empty ("") open and close returns an
8693      * empty string.
8694      * </p>
8695      *
8696      * <pre>
8697      * StringUtils.substringBetween("wx[b]yz", "[", "]") = "b"
8698      * StringUtils.substringBetween(null, *, *)          = null
8699      * StringUtils.substringBetween(*, null, *)          = null
8700      * StringUtils.substringBetween(*, *, null)          = null
8701      * StringUtils.substringBetween("", "", "")          = ""
8702      * StringUtils.substringBetween("", "", "]")         = null
8703      * StringUtils.substringBetween("", "[", "]")        = null
8704      * StringUtils.substringBetween("yabcz", "", "")     = ""
8705      * StringUtils.substringBetween("yabcz", "y", "z")   = "abc"
8706      * StringUtils.substringBetween("yabczyabcz", "y", "z")   = "abc"
8707      * </pre>
8708      *
8709      * @param str   The String containing the substring, may be null.
8710      * @param open  The String before the substring, may be null.
8711      * @param close The String after the substring, may be null.
8712      * @return The substring, {@code null} if no match.
8713      * @since 2.0
8714      */
8715     public static String substringBetween(final String str, final String open, final String close) {
8716         if (!ObjectUtils.allNotNull(str, open, close)) {
8717             return null;
8718         }
8719         final int start = str.indexOf(open);
8720         if (start != INDEX_NOT_FOUND) {
8721             final int end = str.indexOf(close, start + open.length());
8722             if (end != INDEX_NOT_FOUND) {
8723                 return str.substring(start + open.length(), end);
8724             }
8725         }
8726         return null;
8727     }
8728 
8729     /**
8730      * Searches a String for substrings delimited by a start and end tag, returning all matching substrings in an array.
8731      *
8732      * <p>
8733      * A {@code null} input String returns {@code null}. A {@code null} open/close returns {@code null} (no match). An empty ("") open/close returns
8734      * {@code null} (no match).
8735      * </p>
8736      *
8737      * <pre>
8738      * StringUtils.substringsBetween("[a][b][c]", "[", "]") = ["a","b","c"]
8739      * StringUtils.substringsBetween(null, *, *)            = null
8740      * StringUtils.substringsBetween(*, null, *)            = null
8741      * StringUtils.substringsBetween(*, *, null)            = null
8742      * StringUtils.substringsBetween("", "[", "]")          = []
8743      * </pre>
8744      *
8745      * @param str   The String containing the substrings, null returns null, empty returns empty.
8746      * @param open  The String identifying the start of the substring, empty returns null.
8747      * @param close The String identifying the end of the substring, empty returns null.
8748      * @return A String Array of substrings, or {@code null} if no match.
8749      * @since 2.3
8750      */
8751     public static String[] substringsBetween(final String str, final String open, final String close) {
8752         if (str == null || isEmpty(open) || isEmpty(close)) {
8753             return null;
8754         }
8755         final int strLen = str.length();
8756         if (strLen == 0) {
8757             return ArrayUtils.EMPTY_STRING_ARRAY;
8758         }
8759         final int closeLen = close.length();
8760         final int openLen = open.length();
8761         final List<String> list = new ArrayList<>();
8762         int pos = 0;
8763         while (pos < strLen - closeLen) {
8764             int start = str.indexOf(open, pos);
8765             if (start < 0) {
8766                 break;
8767             }
8768             start += openLen;
8769             final int end = str.indexOf(close, start);
8770             if (end < 0) {
8771                 break;
8772             }
8773             list.add(str.substring(start, end));
8774             pos = end + closeLen;
8775         }
8776         if (list.isEmpty()) {
8777             return null;
8778         }
8779         return list.toArray(ArrayUtils.EMPTY_STRING_ARRAY);
8780     }
8781 
8782     /**
8783      * Swaps the case of a String changing upper and title case to lower case, and lower case to upper case.
8784      *
8785      * <ul>
8786      * <li>Upper case character converts to Lower case</li>
8787      * <li>Title case character converts to Lower case</li>
8788      * <li>Lower case character converts to Upper case</li>
8789      * </ul>
8790      *
8791      * <p>
8792      * For a word based algorithm, see {@link org.apache.commons.text.WordUtils#swapCase(String)}. A {@code null} input String returns {@code null}.
8793      * </p>
8794      *
8795      * <pre>
8796      * StringUtils.swapCase(null)                 = null
8797      * StringUtils.swapCase("")                   = ""
8798      * StringUtils.swapCase("The dog has a BONE") = "tHE DOG HAS A bone"
8799      * </pre>
8800      *
8801      * <p>
8802      * NOTE: This method changed in Lang version 2.0. It no longer performs a word based algorithm. If you only use ASCII, you will notice no change. That
8803      * functionality is available in org.apache.commons.lang3.text.WordUtils.
8804      * </p>
8805      *
8806      * @param str The String to swap case, may be null.
8807      * @return The changed String, {@code null} if null String input.
8808      */
8809     public static String swapCase(final String str) {
8810         if (isEmpty(str)) {
8811             return str;
8812         }
8813         final int strLen = str.length();
8814         final int[] newCodePoints = new int[strLen]; // cannot be longer than the char array
8815         int outOffset = 0;
8816         for (int i = 0; i < strLen;) {
8817             final int oldCodepoint = str.codePointAt(i);
8818             final int newCodePoint;
8819             if (Character.isUpperCase(oldCodepoint) || Character.isTitleCase(oldCodepoint)) {
8820                 newCodePoint = Character.toLowerCase(oldCodepoint);
8821             } else if (Character.isLowerCase(oldCodepoint)) {
8822                 newCodePoint = Character.toUpperCase(oldCodepoint);
8823             } else {
8824                 newCodePoint = oldCodepoint;
8825             }
8826             newCodePoints[outOffset++] = newCodePoint;
8827             i += Character.charCount(newCodePoint);
8828         }
8829         return new String(newCodePoints, 0, outOffset);
8830     }
8831 
8832     /**
8833      * Converts a {@link CharSequence} into an array of code points.
8834      *
8835      * <p>
8836      * Valid pairs of surrogate code units will be converted into a single supplementary code point. Isolated surrogate code units (i.e. a high surrogate not
8837      * followed by a low surrogate or a low surrogate not preceded by a high surrogate) will be returned as-is.
8838      * </p>
8839      *
8840      * <pre>
8841      * StringUtils.toCodePoints(null)   =  null
8842      * StringUtils.toCodePoints("")     =  []  // empty array
8843      * </pre>
8844      *
8845      * @param cs The character sequence to convert.
8846      * @return An array of code points.
8847      * @since 3.6
8848      */
8849     public static int[] toCodePoints(final CharSequence cs) {
8850         if (cs == null) {
8851             return null;
8852         }
8853         if (isEmpty(cs)) {
8854             return ArrayUtils.EMPTY_INT_ARRAY;
8855         }
8856         return cs.toString().codePoints().toArray();
8857     }
8858 
8859     /**
8860      * Converts a {@code byte[]} to a String using the specified character encoding.
8861      *
8862      * @param bytes   The byte array to read from.
8863      * @param charset The encoding to use, if null then use the platform default.
8864      * @return A new String.
8865      * @throws NullPointerException Thrown if {@code bytes} is null.
8866      * @since 3.2
8867      * @since 3.3 No longer throws {@link UnsupportedEncodingException}.
8868      */
8869     public static String toEncodedString(final byte[] bytes, final Charset charset) {
8870         return new String(bytes, Charsets.toCharset(charset));
8871     }
8872 
8873     /**
8874      * Converts the given source String as a lower-case using the {@link Locale#ROOT} locale in a null-safe manner.
8875      *
8876      * @param source A source String or null.
8877      * @return The given source String as a lower-case using the {@link Locale#ROOT} locale or null.
8878      * @since 3.10
8879      */
8880     public static String toRootLowerCase(final String source) {
8881         return source == null ? null : source.toLowerCase(Locale.ROOT);
8882     }
8883 
8884     /**
8885      * Converts the given source String as an upper-case using the {@link Locale#ROOT} locale in a null-safe manner.
8886      *
8887      * @param source A source String or null.
8888      * @return The given source String as an upper-case using the {@link Locale#ROOT} locale or null.
8889      * @since 3.10
8890      */
8891     public static String toRootUpperCase(final String source) {
8892         return source == null ? null : source.toUpperCase(Locale.ROOT);
8893     }
8894 
8895     /**
8896      * Converts a {@code byte[]} to a String using the specified character encoding.
8897      *
8898      * @param bytes       The byte array to read from.
8899      * @param charsetName The encoding to use, if null then use the platform default.
8900      * @return A new String.
8901      * @throws NullPointerException Thrown if the input is null.
8902      * @since 3.1
8903      * @deprecated Use {@link StringUtils#toEncodedString(byte[], Charset)} instead of String constants in your code.
8904      */
8905     @Deprecated
8906     public static String toString(final byte[] bytes, final String charsetName) {
8907         return new String(bytes, Charsets.toCharset(charsetName));
8908     }
8909 
8910     /**
8911      * Removes control characters plus space (char &lt;= 32) from both ends of this String, handling {@code null} by returning {@code null}.
8912      *
8913      * <p>
8914      * The String is trimmed using {@link String#trim()}. Trim removes start and end characters &lt;= 32. To strip whitespace use {@link #strip(String)}.
8915      * </p>
8916      *
8917      * <p>
8918      * To trim your choice of characters, use the {@link #strip(String, String)} methods.
8919      * </p>
8920      *
8921      * <pre>
8922      * StringUtils.trim(null)          = null
8923      * StringUtils.trim("")            = ""
8924      * StringUtils.trim("     ")       = ""
8925      * StringUtils.trim("abc")         = "abc"
8926      * StringUtils.trim("    abc    ") = "abc"
8927      * </pre>
8928      *
8929      * @param str The String to be trimmed, may be null.
8930      * @return The trimmed string, {@code null} if null String input.
8931      */
8932     public static String trim(final String str) {
8933         return str == null ? null : str.trim();
8934     }
8935 
8936     /**
8937      * Removes {@link CharUtils#isAsciiControl(char) ASCII control characters} (char &lt;= 31 or char == 127) from both ends of this String, handling
8938      * {@code null} by returning {@code null}.
8939      *
8940      * <p>
8941      * To trim your choice of characters, use the {@link #strip(String, String)} methods.
8942      * </p>
8943      *
8944      * <pre>{@code
8945      * StringUtils.trimAsciiControl(null)          = null
8946      * StringUtils.trimAsciiControl("")            = ""
8947      * StringUtils.trimAsciiControl("abc\u0000")   = "abc"
8948      * StringUtils.trimAsciiControl("abc")         = "abc"
8949      * StringUtils.trimAsciiControl(" abc ")       = " abc "
8950      * }</pre>
8951      *
8952      * @param str The String to be trimmed, may be null.
8953      * @return The trimmed string, {@code null} if null String input.
8954      * @since 3.21.0
8955      */
8956     public static String trimAsciiControl(final String str) {
8957         if (str == null) {
8958             return null;
8959         }
8960         int len = str.length();
8961         int st = 0;
8962         while (st < len && CharUtils.isAsciiControl(str.charAt(st))) {
8963             st++;
8964         }
8965         while (st < len && CharUtils.isAsciiControl(str.charAt(len - 1))) {
8966             len--;
8967         }
8968         return st > 0 || len < str.length() ? str.substring(st, len) : str;
8969     }
8970 
8971     /**
8972      * Removes control characters (char &lt;= 32) from both ends of this String returning an empty String ("") if the String is empty ("") after the trim or if
8973      * it is {@code null}.
8974      *
8975      * <p>
8976      * The String is trimmed using {@link String#trim()}. Trim removes start and end characters &lt;= 32. To strip whitespace use {@link #stripToEmpty(String)}.
8977      * </p>
8978      *
8979      * <pre>
8980      * StringUtils.trimToEmpty(null)          = ""
8981      * StringUtils.trimToEmpty("")            = ""
8982      * StringUtils.trimToEmpty("     ")       = ""
8983      * StringUtils.trimToEmpty("abc")         = "abc"
8984      * StringUtils.trimToEmpty("    abc    ") = "abc"
8985      * </pre>
8986      *
8987      * @param str The String to be trimmed, may be null.
8988      * @return The trimmed String, or an empty String if {@code null} input.
8989      * @since 2.0
8990      */
8991     public static String trimToEmpty(final String str) {
8992         return str == null ? EMPTY : str.trim();
8993     }
8994 
8995     /**
8996      * Removes control characters (char &lt;= 32) from both ends of this String returning {@code null} if the String is empty ("") after the trim or if it is
8997      * {@code null}.
8998      *
8999      * <p>
9000      * The String is trimmed using {@link String#trim()}. Trim removes start and end characters &lt;= 32. To strip whitespace use {@link #stripToNull(String)}.
9001      * </p>
9002      *
9003      * <pre>
9004      * StringUtils.trimToNull(null)          = null
9005      * StringUtils.trimToNull("")            = null
9006      * StringUtils.trimToNull("     ")       = null
9007      * StringUtils.trimToNull("abc")         = "abc"
9008      * StringUtils.trimToNull("    abc    ") = "abc"
9009      * </pre>
9010      *
9011      * @param str The String to be trimmed, may be null.
9012      * @return The trimmed String, {@code null} if only chars &lt;= 32, empty or null String input.
9013      * @since 2.0
9014      */
9015     public static String trimToNull(final String str) {
9016         final String ts = trim(str);
9017         return isEmpty(ts) ? null : ts;
9018     }
9019 
9020     /**
9021      * Truncates a String. This will turn "Now is the time for all good men" into "Now is the time for".
9022      *
9023      * <p>
9024      * Specifically:
9025      * </p>
9026      * <ul>
9027      * <li>If {@code str} is less than {@code maxWidth} characters long, return it.</li>
9028      * <li>Else truncate it to {@code substring(str, 0, maxWidth)}.</li>
9029      * <li>If {@code maxWidth} is less than {@code 0}, throw an {@link IllegalArgumentException}.</li>
9030      * <li>In no case will it return a String of length greater than {@code maxWidth}.</li>
9031      * </ul>
9032      *
9033      * <pre>
9034      * StringUtils.truncate(null, 0)       = null
9035      * StringUtils.truncate(null, 2)       = null
9036      * StringUtils.truncate("", 4)         = ""
9037      * StringUtils.truncate("abcdefg", 4)  = "abcd"
9038      * StringUtils.truncate("abcdefg", 6)  = "abcdef"
9039      * StringUtils.truncate("abcdefg", 7)  = "abcdefg"
9040      * StringUtils.truncate("abcdefg", 8)  = "abcdefg"
9041      * StringUtils.truncate("abcdefg", -1) = throws an IllegalArgumentException
9042      * </pre>
9043      *
9044      * @param str      The String to truncate, may be null.
9045      * @param maxWidth maximum length of result String, must be non-negative.
9046      * @return truncated String, {@code null} if null String input.
9047      * @throws IllegalArgumentException Thrown if {@code maxWidth} is less than {@code 0}.
9048      * @since 3.5
9049      */
9050     public static String truncate(final String str, final int maxWidth) {
9051         return truncate(str, 0, maxWidth);
9052     }
9053 
9054     /**
9055      * Truncates a String. This will turn "Now is the time for all good men" into "is the time for all".
9056      *
9057      * <p>
9058      * Works like {@code truncate(String, int)}, but allows you to specify a "left edge" offset.
9059      * </p>
9060      *
9061      * <p>
9062      * Specifically:
9063      * </p>
9064      * <ul>
9065      * <li>If {@code str} is less than {@code maxWidth} characters long, return it.</li>
9066      * <li>Else truncate it to {@code substring(str, offset, maxWidth)}.</li>
9067      * <li>If {@code maxWidth} is less than {@code 0}, throw an {@link IllegalArgumentException}.</li>
9068      * <li>If {@code offset} is less than {@code 0}, throw an {@link IllegalArgumentException}.</li>
9069      * <li>In no case will it return a String of length greater than {@code maxWidth}.</li>
9070      * </ul>
9071      *
9072      * <pre>
9073      * StringUtils.truncate(null, 0, 0) = null
9074      * StringUtils.truncate(null, 2, 4) = null
9075      * StringUtils.truncate("", 0, 10) = ""
9076      * StringUtils.truncate("", 2, 10) = ""
9077      * StringUtils.truncate("abcdefghij", 0, 3) = "abc"
9078      * StringUtils.truncate("abcdefghij", 5, 6) = "fghij"
9079      * StringUtils.truncate("raspberry peach", 10, 15) = "peach"
9080      * StringUtils.truncate("abcdefghijklmno", 0, 10) = "abcdefghij"
9081      * StringUtils.truncate("abcdefghijklmno", -1, 10) = throws an IllegalArgumentException
9082      * StringUtils.truncate("abcdefghijklmno", Integer.MIN_VALUE, 10) = throws an IllegalArgumentException
9083      * StringUtils.truncate("abcdefghijklmno", Integer.MIN_VALUE, Integer.MAX_VALUE) = throws an IllegalArgumentException
9084      * StringUtils.truncate("abcdefghijklmno", 0, Integer.MAX_VALUE) = "abcdefghijklmno"
9085      * StringUtils.truncate("abcdefghijklmno", 1, 10) = "bcdefghijk"
9086      * StringUtils.truncate("abcdefghijklmno", 2, 10) = "cdefghijkl"
9087      * StringUtils.truncate("abcdefghijklmno", 3, 10) = "defghijklm"
9088      * StringUtils.truncate("abcdefghijklmno", 4, 10) = "efghijklmn"
9089      * StringUtils.truncate("abcdefghijklmno", 5, 10) = "fghijklmno"
9090      * StringUtils.truncate("abcdefghijklmno", 5, 5) = "fghij"
9091      * StringUtils.truncate("abcdefghijklmno", 5, 3) = "fgh"
9092      * StringUtils.truncate("abcdefghijklmno", 10, 3) = "klm"
9093      * StringUtils.truncate("abcdefghijklmno", 10, Integer.MAX_VALUE) = "klmno"
9094      * StringUtils.truncate("abcdefghijklmno", 13, 1) = "n"
9095      * StringUtils.truncate("abcdefghijklmno", 13, Integer.MAX_VALUE) = "no"
9096      * StringUtils.truncate("abcdefghijklmno", 14, 1) = "o"
9097      * StringUtils.truncate("abcdefghijklmno", 14, Integer.MAX_VALUE) = "o"
9098      * StringUtils.truncate("abcdefghijklmno", 15, 1) = ""
9099      * StringUtils.truncate("abcdefghijklmno", 15, Integer.MAX_VALUE) = ""
9100      * StringUtils.truncate("abcdefghijklmno", Integer.MAX_VALUE, Integer.MAX_VALUE) = ""
9101      * StringUtils.truncate("abcdefghij", 3, -1) = throws an IllegalArgumentException
9102      * StringUtils.truncate("abcdefghij", -2, 4) = throws an IllegalArgumentException
9103      * </pre>
9104      *
9105      * @param str      The String to truncate, may be null.
9106      * @param offset   left edge of source String.
9107      * @param maxWidth maximum length of result String, must be non-negative.
9108      * @return truncated String, {@code null} if null String input.
9109      * @throws IllegalArgumentException Thrown if {@code offset} or {@code maxWidth} is less than {@code 0}.
9110      * @since 3.5
9111      */
9112     public static String truncate(final String str, final int offset, final int maxWidth) {
9113         if (offset < 0) {
9114             throw new IllegalArgumentException("offset cannot be negative");
9115         }
9116         if (maxWidth < 0) {
9117             throw new IllegalArgumentException("maxWidth cannot be negative");
9118         }
9119         if (str == null) {
9120             return null;
9121         }
9122         final int len = str.length();
9123         int start = Math.min(offset, len);
9124         int end = Math.min(offset > len - maxWidth ? len : offset + maxWidth, len);
9125         // keep both edges off the middle of a surrogate pair so the result is never left holding a lone surrogate
9126         if (splitsSurrogatePair(str, start)) {
9127             start++;
9128         }
9129         if (splitsSurrogatePair(str, end)) {
9130             end--;
9131         }
9132         return str.substring(start, Math.max(start, end));
9133     }
9134 
9135     /**
9136      * Uncapitalizes a String, changing the first character to lower case as per {@link Character#toLowerCase(int)}. No other characters are changed.
9137      *
9138      * <p>
9139      * For a word based algorithm, see {@link org.apache.commons.text.WordUtils#uncapitalize(String)}. A {@code null} input String returns {@code null}.
9140      * </p>
9141      *
9142      * <pre>
9143      * StringUtils.uncapitalize(null)  = null
9144      * StringUtils.uncapitalize("")    = ""
9145      * StringUtils.uncapitalize("cat") = "cat"
9146      * StringUtils.uncapitalize("Cat") = "cat"
9147      * StringUtils.uncapitalize("CAT") = "cAT"
9148      * </pre>
9149      *
9150      * @param str The String to uncapitalize, may be null.
9151      * @return The uncapitalized String, {@code null} if null String input.
9152      * @see org.apache.commons.text.WordUtils#uncapitalize(String)
9153      * @see #capitalize(String)
9154      * @since 2.0
9155      */
9156     public static String uncapitalize(final String str) {
9157         final int strLen = length(str);
9158         if (strLen == 0) {
9159             return str;
9160         }
9161         final int firstCodePoint = str.codePointAt(0);
9162         final int newCodePoint = Character.toLowerCase(firstCodePoint);
9163         if (firstCodePoint == newCodePoint) {
9164             // already uncapitalized
9165             return str;
9166         }
9167         final int[] newCodePoints = str.codePoints().toArray();
9168         newCodePoints[0] = newCodePoint; // copy the first code point
9169         return new String(newCodePoints, 0, newCodePoints.length);
9170     }
9171 
9172     /**
9173      * Unwraps a given string from a character.
9174      *
9175      * <pre>
9176      * StringUtils.unwrap(null, null)         = null
9177      * StringUtils.unwrap(null, '\0')         = null
9178      * StringUtils.unwrap(null, '1')          = null
9179      * StringUtils.unwrap("a", 'a')           = "a"
9180      * StringUtils.unwrap("aa", 'a')           = ""
9181      * StringUtils.unwrap("\'abc\'", '\'')    = "abc"
9182      * StringUtils.unwrap("AABabcBAA", 'A')   = "ABabcBA"
9183      * StringUtils.unwrap("A", '#')           = "A"
9184      * StringUtils.unwrap("#A", '#')          = "#A"
9185      * StringUtils.unwrap("A#", '#')          = "A#"
9186      * </pre>
9187      *
9188      * @param str      The String to be unwrapped, can be null.
9189      * @param wrapChar The character used to unwrap.
9190      * @return unwrapped String or the original string if it is not quoted properly with the wrapChar.
9191      * @since 3.6
9192      */
9193     public static String unwrap(final String str, final char wrapChar) {
9194         if (isEmpty(str) || wrapChar == CharUtils.NUL || str.length() == 1) {
9195             return str;
9196         }
9197         if (str.charAt(0) == wrapChar && str.charAt(str.length() - 1) == wrapChar) {
9198             final int startIndex = 0;
9199             final int endIndex = str.length() - 1;
9200             return str.substring(startIndex + 1, endIndex);
9201         }
9202         return str;
9203     }
9204 
9205     /**
9206      * Unwraps a given string from another string.
9207      *
9208      * <pre>
9209      * StringUtils.unwrap(null, null)         = null
9210      * StringUtils.unwrap(null, "")           = null
9211      * StringUtils.unwrap(null, "1")          = null
9212      * StringUtils.unwrap("a", "a")           = "a"
9213      * StringUtils.unwrap("aa", "a")          = ""
9214      * StringUtils.unwrap("\'abc\'", "\'")    = "abc"
9215      * StringUtils.unwrap("\"abc\"", "\"")    = "abc"
9216      * StringUtils.unwrap("AABabcBAA", "AA")  = "BabcB"
9217      * StringUtils.unwrap("A", "#")           = "A"
9218      * StringUtils.unwrap("#A", "#")          = "#A"
9219      * StringUtils.unwrap("A#", "#")          = "A#"
9220      * </pre>
9221      *
9222      * @param str       The String to be unwrapped, can be null.
9223      * @param wrapToken The String used to unwrap.
9224      * @return unwrapped String or the original string if it is not quoted properly with the wrapToken.
9225      * @since 3.6
9226      */
9227     public static String unwrap(final String str, final String wrapToken) {
9228         if (isEmpty(str) || isEmpty(wrapToken) || str.length() < 2 * wrapToken.length()) {
9229             return str;
9230         }
9231         if (Strings.CS.startsWith(str, wrapToken) && Strings.CS.endsWith(str, wrapToken)) {
9232             return str.substring(wrapToken.length(), str.lastIndexOf(wrapToken));
9233         }
9234         return str;
9235     }
9236 
9237     /**
9238      * Converts a String to upper case as per {@link String#toUpperCase()}.
9239      *
9240      * <p>
9241      * A {@code null} input String returns {@code null}.
9242      * </p>
9243      *
9244      * <pre>
9245      * StringUtils.upperCase(null)  = null
9246      * StringUtils.upperCase("")    = ""
9247      * StringUtils.upperCase("aBc") = "ABC"
9248      * </pre>
9249      *
9250      * <p>
9251      * <strong>Note:</strong> As described in the documentation for {@link String#toUpperCase()}, the result of this method is affected by the current locale.
9252      * For platform-independent case transformations, the method {@link #upperCase(String, Locale)} should be used with a specific locale (e.g.
9253      * {@link Locale#ENGLISH}).
9254      * </p>
9255      *
9256      * @param str The String to upper case, may be null.
9257      * @return The upper-cased String, {@code null} if null String input.
9258      */
9259     public static String upperCase(final String str) {
9260         if (str == null) {
9261             return null;
9262         }
9263         return str.toUpperCase();
9264     }
9265 
9266     /**
9267      * Converts a String to upper case as per {@link String#toUpperCase(Locale)}.
9268      *
9269      * <p>
9270      * A {@code null} input String returns {@code null}.
9271      * </p>
9272      *
9273      * <pre>
9274      * StringUtils.upperCase(null, Locale.ENGLISH)  = null
9275      * StringUtils.upperCase("", Locale.ENGLISH)    = ""
9276      * StringUtils.upperCase("aBc", Locale.ENGLISH) = "ABC"
9277      * </pre>
9278      *
9279      * @param str    The String to upper case, may be null.
9280      * @param locale The locale that defines the case transformation rules, must not be null.
9281      * @return The upper-cased String, {@code null} if null String input.
9282      * @since 2.5
9283      */
9284     public static String upperCase(final String str, final Locale locale) {
9285         if (str == null) {
9286             return null;
9287         }
9288         return str.toUpperCase(LocaleUtils.toLocale(locale));
9289     }
9290 
9291     /**
9292      * Returns the string representation of the {@code char} array or null.
9293      *
9294      * @param value The character array.
9295      * @return A String or null.
9296      * @see String#valueOf(char[])
9297      * @since 3.9
9298      */
9299     public static String valueOf(final char[] value) {
9300         return value == null ? null : String.valueOf(value);
9301     }
9302 
9303     /**
9304      * Wraps a string with a char.
9305      *
9306      * <pre>
9307      * StringUtils.wrap(null, *)        = null
9308      * StringUtils.wrap("", *)          = ""
9309      * StringUtils.wrap("ab", '\0')     = "ab"
9310      * StringUtils.wrap("ab", 'x')      = "xabx"
9311      * StringUtils.wrap("ab", '\'')     = "'ab'"
9312      * StringUtils.wrap("\"ab\"", '\"') = "\"\"ab\"\""
9313      * </pre>
9314      *
9315      * @param str      The string to be wrapped, may be {@code null}.
9316      * @param wrapWith The char that will wrap {@code str}.
9317      * @return The wrapped string, or {@code null} if {@code str == null}.
9318      * @since 3.4
9319      */
9320     public static String wrap(final String str, final char wrapWith) {
9321         if (isEmpty(str) || wrapWith == CharUtils.NUL) {
9322             return str;
9323         }
9324         return wrapWith + str + wrapWith;
9325     }
9326 
9327     /**
9328      * Wraps a String with another String.
9329      *
9330      * <p>
9331      * A {@code null} input String returns {@code null}.
9332      * </p>
9333      *
9334      * <pre>
9335      * StringUtils.wrap(null, *)         = null
9336      * StringUtils.wrap("", *)           = ""
9337      * StringUtils.wrap("ab", null)      = "ab"
9338      * StringUtils.wrap("ab", "x")       = "xabx"
9339      * StringUtils.wrap("ab", "\"")      = "\"ab\""
9340      * StringUtils.wrap("\"ab\"", "\"")  = "\"\"ab\"\""
9341      * StringUtils.wrap("ab", "'")       = "'ab'"
9342      * StringUtils.wrap("'abcd'", "'")   = "''abcd''"
9343      * StringUtils.wrap("\"abcd\"", "'") = "'\"abcd\"'"
9344      * StringUtils.wrap("'abcd'", "\"")  = "\"'abcd'\""
9345      * </pre>
9346      *
9347      * @param str      The String to be wrapper, may be null.
9348      * @param wrapWith The String that will wrap str.
9349      * @return wrapped String, {@code null} if null String input.
9350      * @since 3.4
9351      */
9352     public static String wrap(final String str, final String wrapWith) {
9353         if (isEmpty(str) || isEmpty(wrapWith)) {
9354             return str;
9355         }
9356         return wrapWith.concat(str).concat(wrapWith);
9357     }
9358 
9359     /**
9360      * Wraps a string with a char if that char is missing from the start or end of the given string.
9361      *
9362      * <p>
9363      * A new {@link String} will not be created if {@code str} is already wrapped.
9364      * </p>
9365      *
9366      * <pre>
9367      * StringUtils.wrapIfMissing(null, *)        = null
9368      * StringUtils.wrapIfMissing("", *)          = ""
9369      * StringUtils.wrapIfMissing("ab", '\0')     = "ab"
9370      * StringUtils.wrapIfMissing("ab", 'x')      = "xabx"
9371      * StringUtils.wrapIfMissing("ab", '\'')     = "'ab'"
9372      * StringUtils.wrapIfMissing("\"ab\"", '\"') = "\"ab\""
9373      * StringUtils.wrapIfMissing("/", '/')  = "/"
9374      * StringUtils.wrapIfMissing("a/b/c", '/')  = "/a/b/c/"
9375      * StringUtils.wrapIfMissing("/a/b/c", '/')  = "/a/b/c/"
9376      * StringUtils.wrapIfMissing("a/b/c/", '/')  = "/a/b/c/"
9377      * </pre>
9378      *
9379      * @param str      The string to be wrapped, may be {@code null}.
9380      * @param wrapWith The char that will wrap {@code str}.
9381      * @return The wrapped string, or {@code null} if {@code str == null}.
9382      * @since 3.5
9383      */
9384     public static String wrapIfMissing(final String str, final char wrapWith) {
9385         if (isEmpty(str) || wrapWith == CharUtils.NUL) {
9386             return str;
9387         }
9388         final boolean wrapStart = str.charAt(0) != wrapWith;
9389         final boolean wrapEnd = str.charAt(str.length() - 1) != wrapWith;
9390         if (!wrapStart && !wrapEnd) {
9391             return str;
9392         }
9393         final StringBuilder builder = new StringBuilder(str.length() + 2);
9394         if (wrapStart) {
9395             builder.append(wrapWith);
9396         }
9397         builder.append(str);
9398         if (wrapEnd) {
9399             builder.append(wrapWith);
9400         }
9401         return builder.toString();
9402     }
9403 
9404     /**
9405      * Wraps a string with a string if that string is missing from the start or end of the given string.
9406      *
9407      * <p>
9408      * A new {@link String} will not be created if {@code str} is already wrapped.
9409      * </p>
9410      *
9411      * <pre>
9412      * StringUtils.wrapIfMissing(null, *)         = null
9413      * StringUtils.wrapIfMissing("", *)           = ""
9414      * StringUtils.wrapIfMissing("ab", null)      = "ab"
9415      * StringUtils.wrapIfMissing("ab", "x")       = "xabx"
9416      * StringUtils.wrapIfMissing("ab", "\"")      = "\"ab\""
9417      * StringUtils.wrapIfMissing("\"ab\"", "\"")  = "\"ab\""
9418      * StringUtils.wrapIfMissing("ab", "'")       = "'ab'"
9419      * StringUtils.wrapIfMissing("'abcd'", "'")   = "'abcd'"
9420      * StringUtils.wrapIfMissing("\"abcd\"", "'") = "'\"abcd\"'"
9421      * StringUtils.wrapIfMissing("'abcd'", "\"")  = "\"'abcd'\""
9422      * StringUtils.wrapIfMissing("/", "/")  = "/"
9423      * StringUtils.wrapIfMissing("a/b/c", "/")  = "/a/b/c/"
9424      * StringUtils.wrapIfMissing("/a/b/c", "/")  = "/a/b/c/"
9425      * StringUtils.wrapIfMissing("a/b/c/", "/")  = "/a/b/c/"
9426      * </pre>
9427      *
9428      * @param str      The string to be wrapped, may be {@code null}.
9429      * @param wrapWith The string that will wrap {@code str}.
9430      * @return The wrapped string, or {@code null} if {@code str == null}.
9431      * @since 3.5
9432      */
9433     public static String wrapIfMissing(final String str, final String wrapWith) {
9434         if (isEmpty(str) || isEmpty(wrapWith)) {
9435             return str;
9436         }
9437         final boolean wrapStart = !str.startsWith(wrapWith);
9438         final boolean wrapEnd = !str.endsWith(wrapWith);
9439         if (!wrapStart && !wrapEnd) {
9440             return str;
9441         }
9442         final StringBuilder builder = new StringBuilder(str.length() + wrapWith.length() + wrapWith.length());
9443         if (wrapStart) {
9444             builder.append(wrapWith);
9445         }
9446         builder.append(str);
9447         if (wrapEnd) {
9448             builder.append(wrapWith);
9449         }
9450         return builder.toString();
9451     }
9452 
9453     /**
9454      * {@link StringUtils} instances should NOT be constructed in standard programming. Instead, the class should be used as {@code StringUtils.trim(" foo ");}.
9455      *
9456      * <p>
9457      * This constructor is public to permit tools that require a JavaBean instance to operate.
9458      * </p>
9459      *
9460      * @deprecated TODO Make private in 4.0.
9461      */
9462     @Deprecated
9463     public StringUtils() {
9464         // empty
9465     }
9466 
9467 }