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 * http://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.lang;
18
19 import java.util.ArrayList;
20 import java.util.Collection;
21 import java.util.Iterator;
22 import java.util.List;
23
24 /**
25 * <p>Operations on {@link java.lang.String} that are
26 * <code>null</code> safe.</p>
27 *
28 * <ul>
29 * <li><b>IsEmpty/IsBlank</b>
30 * - checks if a String contains text</li>
31 * <li><b>Trim/Strip</b>
32 * - removes leading and trailing whitespace</li>
33 * <li><b>Equals</b>
34 * - compares two strings null-safe</li>
35 * <li><b>startsWith</b>
36 * - check if a String starts with a prefix null-safe</li>
37 * <li><b>endsWith</b>
38 * - check if a String ends with a suffix null-safe</li>
39 * <li><b>IndexOf/LastIndexOf/Contains</b>
40 * - null-safe index-of checks
41 * <li><b>IndexOfAny/LastIndexOfAny/IndexOfAnyBut/LastIndexOfAnyBut</b>
42 * - index-of any of a set of Strings</li>
43 * <li><b>ContainsOnly/ContainsNone/ContainsAny</b>
44 * - does String contains only/none/any of these characters</li>
45 * <li><b>Substring/Left/Right/Mid</b>
46 * - null-safe substring extractions</li>
47 * <li><b>SubstringBefore/SubstringAfter/SubstringBetween</b>
48 * - substring extraction relative to other strings</li>
49 * <li><b>Split/Join</b>
50 * - splits a String into an array of substrings and vice versa</li>
51 * <li><b>Remove/Delete</b>
52 * - removes part of a String</li>
53 * <li><b>Replace/Overlay</b>
54 * - Searches a String and replaces one String with another</li>
55 * <li><b>Chomp/Chop</b>
56 * - removes the last part of a String</li>
57 * <li><b>LeftPad/RightPad/Center/Repeat</b>
58 * - pads a String</li>
59 * <li><b>UpperCase/LowerCase/SwapCase/Capitalize/Uncapitalize</b>
60 * - changes the case of a String</li>
61 * <li><b>CountMatches</b>
62 * - counts the number of occurrences of one String in another</li>
63 * <li><b>IsAlpha/IsNumeric/IsWhitespace/IsAsciiPrintable</b>
64 * - checks the characters in a String</li>
65 * <li><b>DefaultString</b>
66 * - protects against a null input String</li>
67 * <li><b>Reverse/ReverseDelimited</b>
68 * - reverses a String</li>
69 * <li><b>Abbreviate</b>
70 * - abbreviates a string using ellipsis</li>
71 * <li><b>Difference</b>
72 * - compares Strings and reports on their differences</li>
73 * <li><b>LevensteinDistance</b>
74 * - the number of changes needed to change one String into another</li>
75 * </ul>
76 *
77 * <p>The <code>StringUtils</code> class defines certain words related to
78 * String handling.</p>
79 *
80 * <ul>
81 * <li>null - <code>null</code></li>
82 * <li>empty - a zero-length string (<code>""</code>)</li>
83 * <li>space - the space character (<code>' '</code>, char 32)</li>
84 * <li>whitespace - the characters defined by {@link Character#isWhitespace(char)}</li>
85 * <li>trim - the characters <= 32 as in {@link String#trim()}</li>
86 * </ul>
87 *
88 * <p><code>StringUtils</code> handles <code>null</code> input Strings quietly.
89 * That is to say that a <code>null</code> input will return <code>null</code>.
90 * Where a <code>boolean</code> or <code>int</code> is being returned
91 * details vary by method.</p>
92 *
93 * <p>A side effect of the <code>null</code> handling is that a
94 * <code>NullPointerException</code> should be considered a bug in
95 * <code>StringUtils</code> (except for deprecated methods).</p>
96 *
97 * <p>Methods in this class give sample code to explain their operation.
98 * The symbol <code>*</code> is used to indicate any input including <code>null</code>.</p>
99 *
100 * @see java.lang.String
101 * @author <a href="http://jakarta.apache.org/turbine/">Apache Jakarta Turbine</a>
102 * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
103 * @author Daniel L. Rall
104 * @author <a href="mailto:gcoladonato@yahoo.com">Greg Coladonato</a>
105 * @author <a href="mailto:ed@apache.org">Ed Korthof</a>
106 * @author <a href="mailto:rand_mcneely@yahoo.com">Rand McNeely</a>
107 * @author Stephen Colebourne
108 * @author <a href="mailto:fredrik@westermarck.com">Fredrik Westermarck</a>
109 * @author Holger Krauth
110 * @author <a href="mailto:alex@purpletech.com">Alexander Day Chaffee</a>
111 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
112 * @author Arun Mammen Thomas
113 * @author Gary Gregory
114 * @author Phil Steitz
115 * @author Al Chou
116 * @author Michael Davey
117 * @author Reuben Sivan
118 * @author Chris Hyzer
119 * @author Scott Johnson
120 * @since 1.0
121 * @version $Id: StringUtils.java 635447 2008-03-10 06:27:09Z bayard $
122 */
123 public class StringUtils {
124 // Performance testing notes (JDK 1.4, Jul03, scolebourne)
125 // Whitespace:
126 // Character.isWhitespace() is faster than WHITESPACE.indexOf()
127 // where WHITESPACE is a string of all whitespace characters
128 //
129 // Character access:
130 // String.charAt(n) versus toCharArray(), then array[n]
131 // String.charAt(n) is about 15% worse for a 10K string
132 // They are about equal for a length 50 string
133 // String.charAt(n) is about 4 times better for a length 3 string
134 // String.charAt(n) is best bet overall
135 //
136 // Append:
137 // String.concat about twice as fast as StringBuffer.append
138 // (not sure who tested this)
139
140 /**
141 * The empty String <code>""</code>.
142 * @since 2.0
143 */
144 public static final String EMPTY = "";
145
146 /**
147 * Represents a failed index search.
148 * @since 2.1
149 */
150 public static final int INDEX_NOT_FOUND = -1;
151
152 /**
153 * <p>The maximum size to which the padding constant(s) can expand.</p>
154 */
155 private static final int PAD_LIMIT = 8192;
156
157 /**
158 * <p><code>StringUtils</code> instances should NOT be constructed in
159 * standard programming. Instead, the class should be used as
160 * <code>StringUtils.trim(" foo ");</code>.</p>
161 *
162 * <p>This constructor is public to permit tools that require a JavaBean
163 * instance to operate.</p>
164 */
165 public StringUtils() {
166 super();
167 }
168
169 // Empty checks
170 //-----------------------------------------------------------------------
171 /**
172 * <p>Checks if a String is empty ("") or null.</p>
173 *
174 * <pre>
175 * StringUtils.isEmpty(null) = true
176 * StringUtils.isEmpty("") = true
177 * StringUtils.isEmpty(" ") = false
178 * StringUtils.isEmpty("bob") = false
179 * StringUtils.isEmpty(" bob ") = false
180 * </pre>
181 *
182 * <p>NOTE: This method changed in Lang version 2.0.
183 * It no longer trims the String.
184 * That functionality is available in isBlank().</p>
185 *
186 * @param str the String to check, may be null
187 * @return <code>true</code> if the String is empty or null
188 */
189 public static boolean isEmpty(String str) {
190 return str == null || str.length() == 0;
191 }
192
193 /**
194 * <p>Checks if a String is not empty ("") and not null.</p>
195 *
196 * <pre>
197 * StringUtils.isNotEmpty(null) = false
198 * StringUtils.isNotEmpty("") = false
199 * StringUtils.isNotEmpty(" ") = true
200 * StringUtils.isNotEmpty("bob") = true
201 * StringUtils.isNotEmpty(" bob ") = true
202 * </pre>
203 *
204 * @param str the String to check, may be null
205 * @return <code>true</code> if the String is not empty and not null
206 */
207 public static boolean isNotEmpty(String str) {
208 return !StringUtils.isEmpty(str);
209 }
210
211 /**
212 * <p>Checks if a String is whitespace, empty ("") or null.</p>
213 *
214 * <pre>
215 * StringUtils.isBlank(null) = true
216 * StringUtils.isBlank("") = true
217 * StringUtils.isBlank(" ") = true
218 * StringUtils.isBlank("bob") = false
219 * StringUtils.isBlank(" bob ") = false
220 * </pre>
221 *
222 * @param str the String to check, may be null
223 * @return <code>true</code> if the String is null, empty or whitespace
224 * @since 2.0
225 */
226 public static boolean isBlank(String str) {
227 int strLen;
228 if (str == null || (strLen = str.length()) == 0) {
229 return true;
230 }
231 for (int i = 0; i < strLen; i++) {
232 if ((Character.isWhitespace(str.charAt(i)) == false)) {
233 return false;
234 }
235 }
236 return true;
237 }
238
239 /**
240 * <p>Checks if a String is not empty (""), not null and not whitespace only.</p>
241 *
242 * <pre>
243 * StringUtils.isNotBlank(null) = false
244 * StringUtils.isNotBlank("") = false
245 * StringUtils.isNotBlank(" ") = false
246 * StringUtils.isNotBlank("bob") = true
247 * StringUtils.isNotBlank(" bob ") = true
248 * </pre>
249 *
250 * @param str the String to check, may be null
251 * @return <code>true</code> if the String is
252 * not empty and not null and not whitespace
253 * @since 2.0
254 */
255 public static boolean isNotBlank(String str) {
256 return !StringUtils.isBlank(str);
257 }
258
259 // Trim
260 //-----------------------------------------------------------------------
261 /**
262 * <p>Removes control characters (char <= 32) from both
263 * ends of this String, handling <code>null</code> by returning
264 * an empty String ("").</p>
265 *
266 * <pre>
267 * StringUtils.clean(null) = ""
268 * StringUtils.clean("") = ""
269 * StringUtils.clean("abc") = "abc"
270 * StringUtils.clean(" abc ") = "abc"
271 * StringUtils.clean(" ") = ""
272 * </pre>
273 *
274 * @see java.lang.String#trim()
275 * @param str the String to clean, may be null
276 * @return the trimmed text, never <code>null</code>
277 * @deprecated Use the clearer named {@link #trimToEmpty(String)}.
278 * Method will be removed in Commons Lang 3.0.
279 */
280 public static String clean(String str) {
281 return str == null ? EMPTY : str.trim();
282 }
283
284 /**
285 * <p>Removes control characters (char <= 32) from both
286 * ends of this String, handling <code>null</code> by returning
287 * <code>null</code>.</p>
288 *
289 * <p>The String is trimmed using {@link String#trim()}.
290 * Trim removes start and end characters <= 32.
291 * To strip whitespace use {@link #strip(String)}.</p>
292 *
293 * <p>To trim your choice of characters, use the
294 * {@link #strip(String, String)} methods.</p>
295 *
296 * <pre>
297 * StringUtils.trim(null) = null
298 * StringUtils.trim("") = ""
299 * StringUtils.trim(" ") = ""
300 * StringUtils.trim("abc") = "abc"
301 * StringUtils.trim(" abc ") = "abc"
302 * </pre>
303 *
304 * @param str the String to be trimmed, may be null
305 * @return the trimmed string, <code>null</code> if null String input
306 */
307 public static String trim(String str) {
308 return str == null ? null : str.trim();
309 }
310
311 /**
312 * <p>Removes control characters (char <= 32) from both
313 * ends of this String returning <code>null</code> if the String is
314 * empty ("") after the trim or if it is <code>null</code>.
315 *
316 * <p>The String is trimmed using {@link String#trim()}.
317 * Trim removes start and end characters <= 32.
318 * To strip whitespace use {@link #stripToNull(String)}.</p>
319 *
320 * <pre>
321 * StringUtils.trimToNull(null) = null
322 * StringUtils.trimToNull("") = null
323 * StringUtils.trimToNull(" ") = null
324 * StringUtils.trimToNull("abc") = "abc"
325 * StringUtils.trimToNull(" abc ") = "abc"
326 * </pre>
327 *
328 * @param str the String to be trimmed, may be null
329 * @return the trimmed String,
330 * <code>null</code> if only chars <= 32, empty or null String input
331 * @since 2.0
332 */
333 public static String trimToNull(String str) {
334 String ts = trim(str);
335 return isEmpty(ts) ? null : ts;
336 }
337
338 /**
339 * <p>Removes control characters (char <= 32) from both
340 * ends of this String returning an empty String ("") if the String
341 * is empty ("") after the trim or if it is <code>null</code>.
342 *
343 * <p>The String is trimmed using {@link String#trim()}.
344 * Trim removes start and end characters <= 32.
345 * To strip whitespace use {@link #stripToEmpty(String)}.</p>
346 *
347 * <pre>
348 * StringUtils.trimToEmpty(null) = ""
349 * StringUtils.trimToEmpty("") = ""
350 * StringUtils.trimToEmpty(" ") = ""
351 * StringUtils.trimToEmpty("abc") = "abc"
352 * StringUtils.trimToEmpty(" abc ") = "abc"
353 * </pre>
354 *
355 * @param str the String to be trimmed, may be null
356 * @return the trimmed String, or an empty String if <code>null</code> input
357 * @since 2.0
358 */
359 public static String trimToEmpty(String str) {
360 return str == null ? EMPTY : str.trim();
361 }
362
363 // Stripping
364 //-----------------------------------------------------------------------
365 /**
366 * <p>Strips whitespace from the start and end of a String.</p>
367 *
368 * <p>This is similar to {@link #trim(String)} but removes whitespace.
369 * Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
370 *
371 * <p>A <code>null</code> input String returns <code>null</code>.</p>
372 *
373 * <pre>
374 * StringUtils.strip(null) = null
375 * StringUtils.strip("") = ""
376 * StringUtils.strip(" ") = ""
377 * StringUtils.strip("abc") = "abc"
378 * StringUtils.strip(" abc") = "abc"
379 * StringUtils.strip("abc ") = "abc"
380 * StringUtils.strip(" abc ") = "abc"
381 * StringUtils.strip(" ab c ") = "ab c"
382 * </pre>
383 *
384 * @param str the String to remove whitespace from, may be null
385 * @return the stripped String, <code>null</code> if null String input
386 */
387 public static String strip(String str) {
388 return strip(str, null);
389 }
390
391 /**
392 * <p>Strips whitespace from the start and end of a String returning
393 * <code>null</code> if the String is empty ("") after the strip.</p>
394 *
395 * <p>This is similar to {@link #trimToNull(String)} but removes whitespace.
396 * Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
397 *
398 * <pre>
399 * StringUtils.stripToNull(null) = null
400 * StringUtils.stripToNull("") = null
401 * StringUtils.stripToNull(" ") = null
402 * StringUtils.stripToNull("abc") = "abc"
403 * StringUtils.stripToNull(" abc") = "abc"
404 * StringUtils.stripToNull("abc ") = "abc"
405 * StringUtils.stripToNull(" abc ") = "abc"
406 * StringUtils.stripToNull(" ab c ") = "ab c"
407 * </pre>
408 *
409 * @param str the String to be stripped, may be null
410 * @return the stripped String,
411 * <code>null</code> if whitespace, empty or null String input
412 * @since 2.0
413 */
414 public static String stripToNull(String str) {
415 if (str == null) {
416 return null;
417 }
418 str = strip(str, null);
419 return str.length() == 0 ? null : str;
420 }
421
422 /**
423 * <p>Strips whitespace from the start and end of a String returning
424 * an empty String if <code>null</code> input.</p>
425 *
426 * <p>This is similar to {@link #trimToEmpty(String)} but removes whitespace.
427 * Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
428 *
429 * <pre>
430 * StringUtils.stripToEmpty(null) = ""
431 * StringUtils.stripToEmpty("") = ""
432 * StringUtils.stripToEmpty(" ") = ""
433 * StringUtils.stripToEmpty("abc") = "abc"
434 * StringUtils.stripToEmpty(" abc") = "abc"
435 * StringUtils.stripToEmpty("abc ") = "abc"
436 * StringUtils.stripToEmpty(" abc ") = "abc"
437 * StringUtils.stripToEmpty(" ab c ") = "ab c"
438 * </pre>
439 *
440 * @param str the String to be stripped, may be null
441 * @return the trimmed String, or an empty String if <code>null</code> input
442 * @since 2.0
443 */
444 public static String stripToEmpty(String str) {
445 return str == null ? EMPTY : strip(str, null);
446 }
447
448 /**
449 * <p>Strips any of a set of characters from the start and end of a String.
450 * This is similar to {@link String#trim()} but allows the characters
451 * to be stripped to be controlled.</p>
452 *
453 * <p>A <code>null</code> input String returns <code>null</code>.
454 * An empty string ("") input returns the empty string.</p>
455 *
456 * <p>If the stripChars String is <code>null</code>, whitespace is
457 * stripped as defined by {@link Character#isWhitespace(char)}.
458 * Alternatively use {@link #strip(String)}.</p>
459 *
460 * <pre>
461 * StringUtils.strip(null, *) = null
462 * StringUtils.strip("", *) = ""
463 * StringUtils.strip("abc", null) = "abc"
464 * StringUtils.strip(" abc", null) = "abc"
465 * StringUtils.strip("abc ", null) = "abc"
466 * StringUtils.strip(" abc ", null) = "abc"
467 * StringUtils.strip(" abcyx", "xyz") = " abc"
468 * </pre>
469 *
470 * @param str the String to remove characters from, may be null
471 * @param stripChars the characters to remove, null treated as whitespace
472 * @return the stripped String, <code>null</code> if null String input
473 */
474 public static String strip(String str, String stripChars) {
475 if (isEmpty(str)) {
476 return str;
477 }
478 str = stripStart(str, stripChars);
479 return stripEnd(str, stripChars);
480 }
481
482 /**
483 * <p>Strips any of a set of characters from the start of a String.</p>
484 *
485 * <p>A <code>null</code> input String returns <code>null</code>.
486 * An empty string ("") input returns the empty string.</p>
487 *
488 * <p>If the stripChars String is <code>null</code>, whitespace is
489 * stripped as defined by {@link Character#isWhitespace(char)}.</p>
490 *
491 * <pre>
492 * StringUtils.stripStart(null, *) = null
493 * StringUtils.stripStart("", *) = ""
494 * StringUtils.stripStart("abc", "") = "abc"
495 * StringUtils.stripStart("abc", null) = "abc"
496 * StringUtils.stripStart(" abc", null) = "abc"
497 * StringUtils.stripStart("abc ", null) = "abc "
498 * StringUtils.stripStart(" abc ", null) = "abc "
499 * StringUtils.stripStart("yxabc ", "xyz") = "abc "
500 * </pre>
501 *
502 * @param str the String to remove characters from, may be null
503 * @param stripChars the characters to remove, null treated as whitespace
504 * @return the stripped String, <code>null</code> if null String input
505 */
506 public static String stripStart(String str, String stripChars) {
507 int strLen;
508 if (str == null || (strLen = str.length()) == 0) {
509 return str;
510 }
511 int start = 0;
512 if (stripChars == null) {
513 while ((start != strLen) && Character.isWhitespace(str.charAt(start))) {
514 start++;
515 }
516 } else if (stripChars.length() == 0) {
517 return str;
518 } else {
519 while ((start != strLen) && (stripChars.indexOf(str.charAt(start)) != -1)) {
520 start++;
521 }
522 }
523 return str.substring(start);
524 }
525
526 /**
527 * <p>Strips any of a set of characters from the end of a String.</p>
528 *
529 * <p>A <code>null</code> input String returns <code>null</code>.
530 * An empty string ("") input returns the empty string.</p>
531 *
532 * <p>If the stripChars String is <code>null</code>, whitespace is
533 * stripped as defined by {@link Character#isWhitespace(char)}.</p>
534 *
535 * <pre>
536 * StringUtils.stripEnd(null, *) = null
537 * StringUtils.stripEnd("", *) = ""
538 * StringUtils.stripEnd("abc", "") = "abc"
539 * StringUtils.stripEnd("abc", null) = "abc"
540 * StringUtils.stripEnd(" abc", null) = " abc"
541 * StringUtils.stripEnd("abc ", null) = "abc"
542 * StringUtils.stripEnd(" abc ", null) = " abc"
543 * StringUtils.stripEnd(" abcyx", "xyz") = " abc"
544 * </pre>
545 *
546 * @param str the String to remove characters from, may be null
547 * @param stripChars the characters to remove, null treated as whitespace
548 * @return the stripped String, <code>null</code> if null String input
549 */
550 public static String stripEnd(String str, String stripChars) {
551 int end;
552 if (str == null || (end = str.length()) == 0) {
553 return str;
554 }
555
556 if (stripChars == null) {
557 while ((end != 0) && Character.isWhitespace(str.charAt(end - 1))) {
558 end--;
559 }
560 } else if (stripChars.length() == 0) {
561 return str;
562 } else {
563 while ((end != 0) && (stripChars.indexOf(str.charAt(end - 1)) != -1)) {
564 end--;
565 }
566 }
567 return str.substring(0, end);
568 }
569
570 // StripAll
571 //-----------------------------------------------------------------------
572 /**
573 * <p>Strips whitespace from the start and end of every String in an array.
574 * Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
575 *
576 * <p>A new array is returned each time, except for length zero.
577 * A <code>null</code> array will return <code>null</code>.
578 * An empty array will return itself.
579 * A <code>null</code> array entry will be ignored.</p>
580 *
581 * <pre>
582 * StringUtils.stripAll(null) = null
583 * StringUtils.stripAll([]) = []
584 * StringUtils.stripAll(["abc", " abc"]) = ["abc", "abc"]
585 * StringUtils.stripAll(["abc ", null]) = ["abc", null]
586 * </pre>
587 *
588 * @param strs the array to remove whitespace from, may be null
589 * @return the stripped Strings, <code>null</code> if null array input
590 */
591 public static String[] stripAll(String[] strs) {
592 return stripAll(strs, null);
593 }
594
595 /**
596 * <p>Strips any of a set of characters from the start and end of every
597 * String in an array.</p>
598 * Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
599 *
600 * <p>A new array is returned each time, except for length zero.
601 * A <code>null</code> array will return <code>null</code>.
602 * An empty array will return itself.
603 * A <code>null</code> array entry will be ignored.
604 * A <code>null</code> stripChars will strip whitespace as defined by
605 * {@link Character#isWhitespace(char)}.</p>
606 *
607 * <pre>
608 * StringUtils.stripAll(null, *) = null
609 * StringUtils.stripAll([], *) = []
610 * StringUtils.stripAll(["abc", " abc"], null) = ["abc", "abc"]
611 * StringUtils.stripAll(["abc ", null], null) = ["abc", null]
612 * StringUtils.stripAll(["abc ", null], "yz") = ["abc ", null]
613 * StringUtils.stripAll(["yabcz", null], "yz") = ["abc", null]
614 * </pre>
615 *
616 * @param strs the array to remove characters from, may be null
617 * @param stripChars the characters to remove, null treated as whitespace
618 * @return the stripped Strings, <code>null</code> if null array input
619 */
620 public static String[] stripAll(String[] strs, String stripChars) {
621 int strsLen;
622 if (strs == null || (strsLen = strs.length) == 0) {
623 return strs;
624 }
625 String[] newArr = new String[strsLen];
626 for (int i = 0; i < strsLen; i++) {
627 newArr[i] = strip(strs[i], stripChars);
628 }
629 return newArr;
630 }
631
632 // Equals
633 //-----------------------------------------------------------------------
634 /**
635 * <p>Compares two Strings, returning <code>true</code> if they are equal.</p>
636 *
637 * <p><code>null</code>s are handled without exceptions. Two <code>null</code>
638 * references are considered to be equal. The comparison is case sensitive.</p>
639 *
640 * <pre>
641 * StringUtils.equals(null, null) = true
642 * StringUtils.equals(null, "abc") = false
643 * StringUtils.equals("abc", null) = false
644 * StringUtils.equals("abc", "abc") = true
645 * StringUtils.equals("abc", "ABC") = false
646 * </pre>
647 *
648 * @see java.lang.String#equals(Object)
649 * @param str1 the first String, may be null
650 * @param str2 the second String, may be null
651 * @return <code>true</code> if the Strings are equal, case sensitive, or
652 * both <code>null</code>
653 */
654 public static boolean equals(String str1, String str2) {
655 return str1 == null ? str2 == null : str1.equals(str2);
656 }
657
658 /**
659 * <p>Compares two Strings, returning <code>true</code> if they are equal ignoring
660 * the case.</p>
661 *
662 * <p><code>null</code>s are handled without exceptions. Two <code>null</code>
663 * references are considered equal. Comparison is case insensitive.</p>
664 *
665 * <pre>
666 * StringUtils.equalsIgnoreCase(null, null) = true
667 * StringUtils.equalsIgnoreCase(null, "abc") = false
668 * StringUtils.equalsIgnoreCase("abc", null) = false
669 * StringUtils.equalsIgnoreCase("abc", "abc") = true
670 * StringUtils.equalsIgnoreCase("abc", "ABC") = true
671 * </pre>
672 *
673 * @see java.lang.String#equalsIgnoreCase(String)
674 * @param str1 the first String, may be null
675 * @param str2 the second String, may be null
676 * @return <code>true</code> if the Strings are equal, case insensitive, or
677 * both <code>null</code>
678 */
679 public static boolean equalsIgnoreCase(String str1, String str2) {
680 return str1 == null ? str2 == null : str1.equalsIgnoreCase(str2);
681 }
682
683 // IndexOf
684 //-----------------------------------------------------------------------
685 /**
686 * <p>Finds the first index within a String, handling <code>null</code>.
687 * This method uses {@link String#indexOf(int)}.</p>
688 *
689 * <p>A <code>null</code> or empty ("") String will return <code>-1</code>.</p>
690 *
691 * <pre>
692 * StringUtils.indexOf(null, *) = -1
693 * StringUtils.indexOf("", *) = -1
694 * StringUtils.indexOf("aabaabaa", 'a') = 0
695 * StringUtils.indexOf("aabaabaa", 'b') = 2
696 * </pre>
697 *
698 * @param str the String to check, may be null
699 * @param searchChar the character to find
700 * @return the first index of the search character,
701 * -1 if no match or <code>null</code> string input
702 * @since 2.0
703 */
704 public static int indexOf(String str, char searchChar) {
705 if (isEmpty(str)) {
706 return -1;
707 }
708 return str.indexOf(searchChar);
709 }
710
711 /**
712 * <p>Finds the first index within a String from a start position,
713 * handling <code>null</code>.
714 * This method uses {@link String#indexOf(int, int)}.</p>
715 *
716 * <p>A <code>null</code> or empty ("") String will return <code>-1</code>.
717 * A negative start position is treated as zero.
718 * A start position greater than the string length returns <code>-1</code>.</p>
719 *
720 * <pre>
721 * StringUtils.indexOf(null, *, *) = -1
722 * StringUtils.indexOf("", *, *) = -1
723 * StringUtils.indexOf("aabaabaa", 'b', 0) = 2
724 * StringUtils.indexOf("aabaabaa", 'b', 3) = 5
725 * StringUtils.indexOf("aabaabaa", 'b', 9) = -1
726 * StringUtils.indexOf("aabaabaa", 'b', -1) = 2
727 * </pre>
728 *
729 * @param str the String to check, may be null
730 * @param searchChar the character to find
731 * @param startPos the start position, negative treated as zero
732 * @return the first index of the search character,
733 * -1 if no match or <code>null</code> string input
734 * @since 2.0
735 */
736 public static int indexOf(String str, char searchChar, int startPos) {
737 if (isEmpty(str)) {
738 return -1;
739 }
740 return str.indexOf(searchChar, startPos);
741 }
742
743 /**
744 * <p>Finds the first index within a String, handling <code>null</code>.
745 * This method uses {@link String#indexOf(String)}.</p>
746 *
747 * <p>A <code>null</code> String will return <code>-1</code>.</p>
748 *
749 * <pre>
750 * StringUtils.indexOf(null, *) = -1
751 * StringUtils.indexOf(*, null) = -1
752 * StringUtils.indexOf("", "") = 0
753 * StringUtils.indexOf("aabaabaa", "a") = 0
754 * StringUtils.indexOf("aabaabaa", "b") = 2
755 * StringUtils.indexOf("aabaabaa", "ab") = 1
756 * StringUtils.indexOf("aabaabaa", "") = 0
757 * </pre>
758 *
759 * @param str the String to check, may be null
760 * @param searchStr the String to find, may be null
761 * @return the first index of the search String,
762 * -1 if no match or <code>null</code> string input
763 * @since 2.0
764 */
765 public static int indexOf(String str, String searchStr) {
766 if (str == null || searchStr == null) {
767 return -1;
768 }
769 return str.indexOf(searchStr);
770 }
771
772 /**
773 * <p>Finds the n-th index within a String, handling <code>null</code>.
774 * This method uses {@link String#indexOf(String)}.</p>
775 *
776 * <p>A <code>null</code> String will return <code>-1</code>.</p>
777 *
778 * <pre>
779 * StringUtils.ordinalIndexOf(null, *, *) = -1
780 * StringUtils.ordinalIndexOf(*, null, *) = -1
781 * StringUtils.ordinalIndexOf("", "", *) = 0
782 * StringUtils.ordinalIndexOf("aabaabaa", "a", 1) = 0
783 * StringUtils.ordinalIndexOf("aabaabaa", "a", 2) = 1
784 * StringUtils.ordinalIndexOf("aabaabaa", "b", 1) = 2
785 * StringUtils.ordinalIndexOf("aabaabaa", "b", 2) = 5
786 * StringUtils.ordinalIndexOf("aabaabaa", "ab", 1) = 1
787 * StringUtils.ordinalIndexOf("aabaabaa", "ab", 2) = 4
788 * StringUtils.ordinalIndexOf("aabaabaa", "", 1) = 0
789 * StringUtils.ordinalIndexOf("aabaabaa", "", 2) = 0
790 * </pre>
791 *
792 * @param str the String to check, may be null
793 * @param searchStr the String to find, may be null
794 * @param ordinal the n-th <code>searchStr</code> to find
795 * @return the n-th index of the search String,
796 * <code>-1</code> (<code>INDEX_NOT_FOUND</code>) if no match or <code>null</code> string input
797 * @since 2.1
798 */
799 public static int ordinalIndexOf(String str, String searchStr, int ordinal) {
800 if (str == null || searchStr == null || ordinal <= 0) {
801 return INDEX_NOT_FOUND;
802 }
803 if (searchStr.length() == 0) {
804 return 0;
805 }
806 int found = 0;
807 int index = INDEX_NOT_FOUND;
808 do {
809 index = str.indexOf(searchStr, index + 1);
810 if (index < 0) {
811 return index;
812 }
813 found++;
814 } while (found < ordinal);
815 return index;
816 }
817
818 /**
819 * <p>Finds the first index within a String, handling <code>null</code>.
820 * This method uses {@link String#indexOf(String, int)}.</p>
821 *
822 * <p>A <code>null</code> String will return <code>-1</code>.
823 * A negative start position is treated as zero.
824 * An empty ("") search String always matches.
825 * A start position greater than the string length only matches
826 * an empty search String.</p>
827 *
828 * <pre>
829 * StringUtils.indexOf(null, *, *) = -1
830 * StringUtils.indexOf(*, null, *) = -1
831 * StringUtils.indexOf("", "", 0) = 0
832 * StringUtils.indexOf("aabaabaa", "a", 0) = 0
833 * StringUtils.indexOf("aabaabaa", "b", 0) = 2
834 * StringUtils.indexOf("aabaabaa", "ab", 0) = 1
835 * StringUtils.indexOf("aabaabaa", "b", 3) = 5
836 * StringUtils.indexOf("aabaabaa", "b", 9) = -1
837 * StringUtils.indexOf("aabaabaa", "b", -1) = 2
838 * StringUtils.indexOf("aabaabaa", "", 2) = 2
839 * StringUtils.indexOf("abc", "", 9) = 3
840 * </pre>
841 *
842 * @param str the String to check, may be null
843 * @param searchStr the String to find, may be null
844 * @param startPos the start position, negative treated as zero
845 * @return the first index of the search String,
846 * -1 if no match or <code>null</code> string input
847 * @since 2.0
848 */
849 public static int indexOf(String str, String searchStr, int startPos) {
850 if (str == null || searchStr == null) {
851 return -1;
852 }
853 // JDK1.2/JDK1.3 have a bug, when startPos > str.length for "", hence
854 if (searchStr.length() == 0 && startPos >= str.length()) {
855 return str.length();
856 }
857 return str.indexOf(searchStr, startPos);
858 }
859
860 // LastIndexOf
861 //-----------------------------------------------------------------------
862 /**
863 * <p>Finds the last index within a String, handling <code>null</code>.
864 * This method uses {@link String#lastIndexOf(int)}.</p>
865 *
866 * <p>A <code>null</code> or empty ("") String will return <code>-1</code>.</p>
867 *
868 * <pre>
869 * StringUtils.lastIndexOf(null, *) = -1
870 * StringUtils.lastIndexOf("", *) = -1
871 * StringUtils.lastIndexOf("aabaabaa", 'a') = 7
872 * StringUtils.lastIndexOf("aabaabaa", 'b') = 5
873 * </pre>
874 *
875 * @param str the String to check, may be null
876 * @param searchChar the character to find
877 * @return the last index of the search character,
878 * -1 if no match or <code>null</code> string input
879 * @since 2.0
880 */
881 public static int lastIndexOf(String str, char searchChar) {
882 if (isEmpty(str)) {
883 return -1;
884 }
885 return str.lastIndexOf(searchChar);
886 }
887
888 /**
889 * <p>Finds the last index within a String from a start position,
890 * handling <code>null</code>.
891 * This method uses {@link String#lastIndexOf(int, int)}.</p>
892 *
893 * <p>A <code>null</code> or empty ("") String will return <code>-1</code>.
894 * A negative start position returns <code>-1</code>.
895 * A start position greater than the string length searches the whole string.</p>
896 *
897 * <pre>
898 * StringUtils.lastIndexOf(null, *, *) = -1
899 * StringUtils.lastIndexOf("", *, *) = -1
900 * StringUtils.lastIndexOf("aabaabaa", 'b', 8) = 5
901 * StringUtils.lastIndexOf("aabaabaa", 'b', 4) = 2
902 * StringUtils.lastIndexOf("aabaabaa", 'b', 0) = -1
903 * StringUtils.lastIndexOf("aabaabaa", 'b', 9) = 5
904 * StringUtils.lastIndexOf("aabaabaa", 'b', -1) = -1
905 * StringUtils.lastIndexOf("aabaabaa", 'a', 0) = 0
906 * </pre>
907 *
908 * @param str the String to check, may be null
909 * @param searchChar the character to find
910 * @param startPos the start position
911 * @return the last index of the search character,
912 * -1 if no match or <code>null</code> string input
913 * @since 2.0
914 */
915 public static int lastIndexOf(String str, char searchChar, int startPos) {
916 if (isEmpty(str)) {
917 return -1;
918 }
919 return str.lastIndexOf(searchChar, startPos);
920 }
921
922 /**
923 * <p>Finds the last index within a String, handling <code>null</code>.
924 * This method uses {@link String#lastIndexOf(String)}.</p>
925 *
926 * <p>A <code>null</code> String will return <code>-1</code>.</p>
927 *
928 * <pre>
929 * StringUtils.lastIndexOf(null, *) = -1
930 * StringUtils.lastIndexOf(*, null) = -1
931 * StringUtils.lastIndexOf("", "") = 0
932 * StringUtils.lastIndexOf("aabaabaa", "a") = 0
933 * StringUtils.lastIndexOf("aabaabaa", "b") = 2
934 * StringUtils.lastIndexOf("aabaabaa", "ab") = 1
935 * StringUtils.lastIndexOf("aabaabaa", "") = 8
936 * </pre>
937 *
938 * @param str the String to check, may be null
939 * @param searchStr the String to find, may be null
940 * @return the last index of the search String,
941 * -1 if no match or <code>null</code> string input
942 * @since 2.0
943 */
944 public static int lastIndexOf(String str, String searchStr) {
945 if (str == null || searchStr == null) {
946 return -1;
947 }
948 return str.lastIndexOf(searchStr);
949 }
950
951 /**
952 * <p>Finds the first index within a String, handling <code>null</code>.
953 * This method uses {@link String#lastIndexOf(String, int)}.</p>
954 *
955 * <p>A <code>null</code> String will return <code>-1</code>.
956 * A negative start position returns <code>-1</code>.
957 * An empty ("") search String always matches unless the start position is negative.
958 * A start position greater than the string length searches the whole string.</p>
959 *
960 * <pre>
961 * StringUtils.lastIndexOf(null, *, *) = -1
962 * StringUtils.lastIndexOf(*, null, *) = -1
963 * StringUtils.lastIndexOf("aabaabaa", "a", 8) = 7
964 * StringUtils.lastIndexOf("aabaabaa", "b", 8) = 5
965 * StringUtils.lastIndexOf("aabaabaa", "ab", 8) = 4
966 * StringUtils.lastIndexOf("aabaabaa", "b", 9) = 5
967 * StringUtils.lastIndexOf("aabaabaa", "b", -1) = -1
968 * StringUtils.lastIndexOf("aabaabaa", "a", 0) = 0
969 * StringUtils.lastIndexOf("aabaabaa", "b", 0) = -1
970 * </pre>
971 *
972 * @param str the String to check, may be null
973 * @param searchStr the String to find, may be null
974 * @param startPos the start position, negative treated as zero
975 * @return the first index of the search String,
976 * -1 if no match or <code>null</code> string input
977 * @since 2.0
978 */
979 public static int lastIndexOf(String str, String searchStr, int startPos) {
980 if (str == null || searchStr == null) {
981 return -1;
982 }
983 return str.lastIndexOf(searchStr, startPos);
984 }
985
986 // Contains
987 //-----------------------------------------------------------------------
988 /**
989 * <p>Checks if String contains a search character, handling <code>null</code>.
990 * This method uses {@link String#indexOf(int)}.</p>
991 *
992 * <p>A <code>null</code> or empty ("") String will return <code>false</code>.</p>
993 *
994 * <pre>
995 * StringUtils.contains(null, *) = false
996 * StringUtils.contains("", *) = false
997 * StringUtils.contains("abc", 'a') = true
998 * StringUtils.contains("abc", 'z') = false
999 * </pre>
1000 *
1001 * @param str the String to check, may be null
1002 * @param searchChar the character to find
1003 * @return true if the String contains the search character,
1004 * false if not or <code>null</code> string input
1005 * @since 2.0
1006 */
1007 public static boolean contains(String str, char searchChar) {
1008 if (isEmpty(str)) {
1009 return false;
1010 }
1011 return str.indexOf(searchChar) >= 0;
1012 }
1013
1014 /**
1015 * <p>Checks if String contains a search String, handling <code>null</code>.
1016 * This method uses {@link String#indexOf(String)}.</p>
1017 *
1018 * <p>A <code>null</code> String will return <code>false</code>.</p>
1019 *
1020 * <pre>
1021 * StringUtils.contains(null, *) = false
1022 * StringUtils.contains(*, null) = false
1023 * StringUtils.contains("", "") = true
1024 * StringUtils.contains("abc", "") = true
1025 * StringUtils.contains("abc", "a") = true
1026 * StringUtils.contains("abc", "z") = false
1027 * </pre>
1028 *
1029 * @param str the String to check, may be null
1030 * @param searchStr the String to find, may be null
1031 * @return true if the String contains the search String,
1032 * false if not or <code>null</code> string input
1033 * @since 2.0
1034 */
1035 public static boolean contains(String str, String searchStr) {
1036 if (str == null || searchStr == null) {
1037 return false;
1038 }
1039 return str.indexOf(searchStr) >= 0;
1040 }
1041
1042 /**
1043 * <p>Checks if String contains a search String irrespective of case,
1044 * handling <code>null</code>. This method uses
1045 * {@link #contains(String, String)}.</p>
1046 *
1047 * <p>A <code>null</code> String will return <code>false</code>.</p>
1048 *
1049 * <pre>
1050 * StringUtils.contains(null, *) = false
1051 * StringUtils.contains(*, null) = false
1052 * StringUtils.contains("", "") = true
1053 * StringUtils.contains("abc", "") = true
1054 * StringUtils.contains("abc", "a") = true
1055 * StringUtils.contains("abc", "z") = false
1056 * StringUtils.contains("abc", "A") = true
1057 * StringUtils.contains("abc", "Z") = false
1058 * </pre>
1059 *
1060 * @param str the String to check, may be null
1061 * @param searchStr the String to find, may be null
1062 * @return true if the String contains the search String irrespective of
1063 * case or false if not or <code>null</code> string input
1064 */
1065 public static boolean containsIgnoreCase(String str, String searchStr) {
1066 if (str == null || searchStr == null) {
1067 return false;
1068 }
1069 return contains(str.toUpperCase(), searchStr.toUpperCase());
1070 }
1071
1072 // IndexOfAny chars
1073 //-----------------------------------------------------------------------
1074 /**
1075 * <p>Search a String to find the first index of any
1076 * character in the given set of characters.</p>
1077 *
1078 * <p>A <code>null</code> String will return <code>-1</code>.
1079 * A <code>null</code> or zero length search array will return <code>-1</code>.</p>
1080 *
1081 * <pre>
1082 * StringUtils.indexOfAny(null, *) = -1
1083 * StringUtils.indexOfAny("", *) = -1
1084 * StringUtils.indexOfAny(*, null) = -1
1085 * StringUtils.indexOfAny(*, []) = -1
1086 * StringUtils.indexOfAny("zzabyycdxx",['z','a']) = 0
1087 * StringUtils.indexOfAny("zzabyycdxx",['b','y']) = 3
1088 * StringUtils.indexOfAny("aba", ['z']) = -1
1089 * </pre>
1090 *
1091 * @param str the String to check, may be null
1092 * @param searchChars the chars to search for, may be null
1093 * @return the index of any of the chars, -1 if no match or null input
1094 * @since 2.0
1095 */
1096 public static int indexOfAny(String str, char[] searchChars) {
1097 if (isEmpty(str) || ArrayUtils.isEmpty(searchChars)) {
1098 return -1;
1099 }
1100 for (int i = 0; i < str.length(); i++) {
1101 char ch = str.charAt(i);
1102 for (int j = 0; j < searchChars.length; j++) {
1103 if (searchChars[j] == ch) {
1104 return i;
1105 }
1106 }
1107 }
1108 return -1;
1109 }
1110
1111 /**
1112 * <p>Search a String to find the first index of any
1113 * character in the given set of characters.</p>
1114 *
1115 * <p>A <code>null</code> String will return <code>-1</code>.
1116 * A <code>null</code> search string will return <code>-1</code>.</p>
1117 *
1118 * <pre>
1119 * StringUtils.indexOfAny(null, *) = -1
1120 * StringUtils.indexOfAny("", *) = -1
1121 * StringUtils.indexOfAny(*, null) = -1
1122 * StringUtils.indexOfAny(*, "") = -1
1123 * StringUtils.indexOfAny("zzabyycdxx", "za") = 0
1124 * StringUtils.indexOfAny("zzabyycdxx", "by") = 3
1125 * StringUtils.indexOfAny("aba","z") = -1
1126 * </pre>
1127 *
1128 * @param str the String to check, may be null
1129 * @param searchChars the chars to search for, may be null
1130 * @return the index of any of the chars, -1 if no match or null input
1131 * @since 2.0
1132 */
1133 public static int indexOfAny(String str, String searchChars) {
1134 if (isEmpty(str) || isEmpty(searchChars)) {
1135 return -1;
1136 }
1137 return indexOfAny(str, searchChars.toCharArray());
1138 }
1139
1140 // ContainsAny
1141 //-----------------------------------------------------------------------
1142 /**
1143 * <p>Checks if the String contains any character in the given
1144 * set of characters.</p>
1145 *
1146 * <p>A <code>null</code> String will return <code>false</code>.
1147 * A <code>null</code> or zero length search array will return <code>false</code>.</p>
1148 *
1149 * <pre>
1150 * StringUtils.containsAny(null, *) = false
1151 * StringUtils.containsAny("", *) = false
1152 * StringUtils.containsAny(*, null) = false
1153 * StringUtils.containsAny(*, []) = false
1154 * StringUtils.containsAny("zzabyycdxx",['z','a']) = true
1155 * StringUtils.containsAny("zzabyycdxx",['b','y']) = true
1156 * StringUtils.containsAny("aba", ['z']) = false
1157 * </pre>
1158 *
1159 * @param str the String to check, may be null
1160 * @param se