KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > lang > StringUtils


1 /*
2  * Copyright 2002-2005 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */

16 package org.apache.commons.lang;
17
18 import java.util.ArrayList JavaDoc;
19 import java.util.Iterator JavaDoc;
20 import java.util.List JavaDoc;
21
22 /**
23  * <p>Operations on {@link java.lang.String} that are
24  * <code>null</code> safe.</p>
25  *
26  * <ul>
27  * <li><b>IsEmpty/IsBlank</b>
28  * - checks if a String contains text</li>
29  * <li><b>Trim/Strip</b>
30  * - removes leading and trailing whitespace</li>
31  * <li><b>Equals</b>
32  * - compares two strings null-safe</li>
33  * <li><b>IndexOf/LastIndexOf/Contains</b>
34  * - null-safe index-of checks
35  * <li><b>IndexOfAny/LastIndexOfAny/IndexOfAnyBut/LastIndexOfAnyBut</b>
36  * - index-of any of a set of Strings</li>
37  * <li><b>ContainsOnly/ContainsNone</b>
38  * - does String contains only/none of these characters</li>
39  * <li><b>Substring/Left/Right/Mid</b>
40  * - null-safe substring extractions</li>
41  * <li><b>SubstringBefore/SubstringAfter/SubstringBetween</b>
42  * - substring extraction relative to other strings</li>
43  * <li><b>Split/Join</b>
44  * - splits a String into an array of substrings and vice versa</li>
45  * <li><b>Remove/Delete</b>
46  * - removes part of a String</li>
47  * <li><b>Replace/Overlay</b>
48  * - Searches a String and replaces one String with another</li>
49  * <li><b>Chomp/Chop</b>
50  * - removes the last part of a String</li>
51  * <li><b>LeftPad/RightPad/Center/Repeat</b>
52  * - pads a String</li>
53  * <li><b>UpperCase/LowerCase/SwapCase/Capitalize/Uncapitalize</b>
54  * - changes the case of a String</li>
55  * <li><b>CountMatches</b>
56  * - counts the number of occurrences of one String in another</li>
57  * <li><b>IsAlpha/IsNumeric/IsWhitespace/IsAsciiPrintable</b>
58  * - checks the characters in a String</li>
59  * <li><b>DefaultString</b>
60  * - protects against a null input String</li>
61  * <li><b>Reverse/ReverseDelimited</b>
62  * - reverses a String</li>
63  * <li><b>Abbreviate</b>
64  * - abbreviates a string using ellipsis</li>
65  * <li><b>Difference</b>
66  * - compares two Strings and reports on their differences</li>
67  * <li><b>LevensteinDistance</b>
68  * - the number of changes needed to change one String into another</li>
69  * </ul>
70  *
71  * <p>The <code>StringUtils</code> class defines certain words related to
72  * String handling.</p>
73  *
74  * <ul>
75  * <li>null - <code>null</code></li>
76  * <li>empty - a zero-length string (<code>""</code>)</li>
77  * <li>space - the space character (<code>' '</code>, char 32)</li>
78  * <li>whitespace - the characters defined by {@link Character#isWhitespace(char)}</li>
79  * <li>trim - the characters &lt;= 32 as in {@link String#trim()}</li>
80  * </ul>
81  *
82  * <p><code>StringUtils</code> handles <code>null</code> input Strings quietly.
83  * That is to say that a <code>null</code> input will return <code>null</code>.
84  * Where a <code>boolean</code> or <code>int</code> is being returned
85  * details vary by method.</p>
86  *
87  * <p>A side effect of the <code>null</code> handling is that a
88  * <code>NullPointerException</code> should be considered a bug in
89  * <code>StringUtils</code> (except for deprecated methods).</p>
90  *
91  * <p>Methods in this class give sample code to explain their operation.
92  * The symbol <code>*</code> is used to indicate any input including <code>null</code>.</p>
93  *
94  * @see java.lang.String
95  * @author <a HREF="http://jakarta.apache.org/turbine/">Apache Jakarta Turbine</a>
96  * @author GenerationJavaCore
97  * @author <a HREF="mailto:jon@latchkey.com">Jon S. Stevens</a>
98  * @author <a HREF="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
99  * @author <a HREF="mailto:gcoladonato@yahoo.com">Greg Coladonato</a>
100  * @author <a HREF="mailto:bayard@generationjava.com">Henri Yandell</a>
101  * @author <a HREF="mailto:ed@apache.org">Ed Korthof</a>
102  * @author <a HREF="mailto:rand_mcneely@yahoo.com">Rand McNeely</a>
103  * @author Stephen Colebourne
104  * @author <a HREF="mailto:fredrik@westermarck.com">Fredrik Westermarck</a>
105  * @author Holger Krauth
106  * @author <a HREF="mailto:alex@purpletech.com">Alexander Day Chaffee</a>
107  * @author <a HREF="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
108  * @author Arun Mammen Thomas
109  * @author Gary Gregory
110  * @author Phil Steitz
111  * @author Al Chou
112  * @author Michael Davey
113  * @since 1.0
114  * @version $Id: StringUtils.java 161243 2005-04-14 04:30:28Z ggregory $
115  */

116 public class StringUtils {
117     // Performance testing notes (JDK 1.4, Jul03, scolebourne)
118
// Whitespace:
119
// Character.isWhitespace() is faster than WHITESPACE.indexOf()
120
// where WHITESPACE is a string of all whitespace characters
121
//
122
// Character access:
123
// String.charAt(n) versus toCharArray(), then array[n]
124
// String.charAt(n) is about 15% worse for a 10K string
125
// They are about equal for a length 50 string
126
// String.charAt(n) is about 4 times better for a length 3 string
127
// String.charAt(n) is best bet overall
128
//
129
// Append:
130
// String.concat about twice as fast as StringBuffer.append
131
// (not sure who tested this)
132

133     /**
134      * The empty String <code>""</code>.
135      * @since 2.0
136      */

137     public static final String JavaDoc EMPTY = "";
138
139     /**
140      * Represents a failed index search.
141      * @since 2.1
142      */

143     public static final int INDEX_NOT_FOUND = -1;
144
145     /**
146      * <p>The maximum size to which the padding constant(s) can expand.</p>
147      */

148     private static final int PAD_LIMIT = 8192;
149
150     /**
151      * <p>An array of <code>String</code>s used for padding.</p>
152      *
153      * <p>Used for efficient space padding. The length of each String expands as needed.</p>
154      */

155     private static final String JavaDoc[] PADDING = new String JavaDoc[Character.MAX_VALUE];
156
157     static {
158         // space padding is most common, start with 64 chars
159
PADDING[32] = " ";
160     }
161
162     /**
163      * <p><code>StringUtils</code> instances should NOT be constructed in
164      * standard programming. Instead, the class should be used as
165      * <code>StringUtils.trim(" foo ");</code>.</p>
166      *
167      * <p>This constructor is public to permit tools that require a JavaBean
168      * instance to operate.</p>
169      */

170     public StringUtils() {
171         // no init.
172
}
173
174     // Empty checks
175
//-----------------------------------------------------------------------
176
/**
177      * <p>Checks if a String is empty ("") or null.</p>
178      *
179      * <pre>
180      * StringUtils.isEmpty(null) = true
181      * StringUtils.isEmpty("") = true
182      * StringUtils.isEmpty(" ") = false
183      * StringUtils.isEmpty("bob") = false
184      * StringUtils.isEmpty(" bob ") = false
185      * </pre>
186      *
187      * <p>NOTE: This method changed in Lang version 2.0.
188      * It no longer trims the String.
189      * That functionality is available in isBlank().</p>
190      *
191      * @param str the String to check, may be null
192      * @return <code>true</code> if the String is empty or null
193      */

194     public static boolean isEmpty(String JavaDoc str) {
195         return str == null || str.length() == 0;
196     }
197
198     /**
199      * <p>Checks if a String is not empty ("") and not null.</p>
200      *
201      * <pre>
202      * StringUtils.isNotEmpty(null) = false
203      * StringUtils.isNotEmpty("") = false
204      * StringUtils.isNotEmpty(" ") = true
205      * StringUtils.isNotEmpty("bob") = true
206      * StringUtils.isNotEmpty(" bob ") = true
207      * </pre>
208      *
209      * @param str the String to check, may be null
210      * @return <code>true</code> if the String is not empty and not null
211      */

212     public static boolean isNotEmpty(String JavaDoc str) {
213         return str != null && str.length() > 0;
214     }
215
216     /**
217      * <p>Checks if a String is whitespace, empty ("") or null.</p>
218      *
219      * <pre>
220      * StringUtils.isBlank(null) = true
221      * StringUtils.isBlank("") = true
222      * StringUtils.isBlank(" ") = true
223      * StringUtils.isBlank("bob") = false
224      * StringUtils.isBlank(" bob ") = false
225      * </pre>
226      *
227      * @param str the String to check, may be null
228      * @return <code>true</code> if the String is null, empty or whitespace
229      * @since 2.0
230      */

231     public static boolean isBlank(String JavaDoc str) {
232         int strLen;
233         if (str == null || (strLen = str.length()) == 0) {
234             return true;
235         }
236         for (int i = 0; i < strLen; i++) {
237             if ((Character.isWhitespace(str.charAt(i)) == false)) {
238                 return false;
239             }
240         }
241         return true;
242     }
243
244     /**
245      * <p>Checks if a String is not empty (""), not null and not whitespace only.</p>
246      *
247      * <pre>
248      * StringUtils.isNotBlank(null) = false
249      * StringUtils.isNotBlank("") = false
250      * StringUtils.isNotBlank(" ") = false
251      * StringUtils.isNotBlank("bob") = true
252      * StringUtils.isNotBlank(" bob ") = true
253      * </pre>
254      *
255      * @param str the String to check, may be null
256      * @return <code>true</code> if the String is
257      * not empty and not null and not whitespace
258      * @since 2.0
259      */

260     public static boolean isNotBlank(String JavaDoc str) {
261         int strLen;
262         if (str == null || (strLen = str.length()) == 0) {
263             return false;
264         }
265         for (int i = 0; i < strLen; i++) {
266             if ((Character.isWhitespace(str.charAt(i)) == false)) {
267                 return true;
268             }
269         }
270         return false;
271     }
272
273     // Trim
274
//-----------------------------------------------------------------------
275
/**
276      * <p>Removes control characters (char &lt;= 32) from both
277      * ends of this String, handling <code>null</code> by returning
278      * an empty String ("").</p>
279      *
280      * <pre>
281      * StringUtils.clean(null) = ""
282      * StringUtils.clean("") = ""
283      * StringUtils.clean("abc") = "abc"
284      * StringUtils.clean(" abc ") = "abc"
285      * StringUtils.clean(" ") = ""
286      * </pre>
287      *
288      * @see java.lang.String#trim()
289      * @param str the String to clean, may be null
290      * @return the trimmed text, never <code>null</code>
291      * @deprecated Use the clearer named {@link #trimToEmpty(String)}.
292      * Method will be removed in Commons Lang 3.0.
293      */

294     public static String JavaDoc clean(String JavaDoc str) {
295         return str == null ? EMPTY : str.trim();
296     }
297
298     /**
299      * <p>Removes control characters (char &lt;= 32) from both
300      * ends of this String, handling <code>null</code> by returning
301      * <code>null</code>.</p>
302      *
303      * <p>The String is trimmed using {@link String#trim()}.
304      * Trim removes start and end characters &lt;= 32.
305      * To strip whitespace use {@link #strip(String)}.</p>
306      *
307      * <p>To trim your choice of characters, use the
308      * {@link #strip(String, String)} methods.</p>
309      *
310      * <pre>
311      * StringUtils.trim(null) = null
312      * StringUtils.trim("") = ""
313      * StringUtils.trim(" ") = ""
314      * StringUtils.trim("abc") = "abc"
315      * StringUtils.trim(" abc ") = "abc"
316      * </pre>
317      *
318      * @param str the String to be trimmed, may be null
319      * @return the trimmed string, <code>null</code> if null String input
320      */

321     public static String JavaDoc trim(String JavaDoc str) {
322         return str == null ? null : str.trim();
323     }
324
325     /**
326      * <p>Removes control characters (char &lt;= 32) from both
327      * ends of this String returning <code>null</code> if the String is
328      * empty ("") after the trim or if it is <code>null</code>.
329      *
330      * <p>The String is trimmed using {@link String#trim()}.
331      * Trim removes start and end characters &lt;= 32.
332      * To strip whitespace use {@link #stripToNull(String)}.</p>
333      *
334      * <pre>
335      * StringUtils.trimToNull(null) = null
336      * StringUtils.trimToNull("") = null
337      * StringUtils.trimToNull(" ") = null
338      * StringUtils.trimToNull("abc") = "abc"
339      * StringUtils.trimToNull(" abc ") = "abc"
340      * </pre>
341      *
342      * @param str the String to be trimmed, may be null
343      * @return the trimmed String,
344      * <code>null</code> if only chars &lt;= 32, empty or null String input
345      * @since 2.0
346      */

347     public static String JavaDoc trimToNull(String JavaDoc str) {
348         String JavaDoc ts = trim(str);
349         return isEmpty(ts) ? null : ts;
350     }
351
352     /**
353      * <p>Removes control characters (char &lt;= 32) from both
354      * ends of this String returning an empty String ("") if the String
355      * is empty ("") after the trim or if it is <code>null</code>.
356      *
357      * <p>The String is trimmed using {@link String#trim()}.
358      * Trim removes start and end characters &lt;= 32.
359      * To strip whitespace use {@link #stripToEmpty(String)}.</p>
360      *
361      * <pre>
362      * StringUtils.trimToEmpty(null) = ""
363      * StringUtils.trimToEmpty("") = ""
364      * StringUtils.trimToEmpty(" ") = ""
365      * StringUtils.trimToEmpty("abc") = "abc"
366      * StringUtils.trimToEmpty(" abc ") = "abc"
367      * </pre>
368      *
369      * @param str the String to be trimmed, may be null
370      * @return the trimmed String, or an empty String if <code>null</code> input
371      * @since 2.0
372      */

373     public static String JavaDoc trimToEmpty(String JavaDoc str) {
374         return str == null ? EMPTY : str.trim();
375     }
376
377     // Stripping
378
//-----------------------------------------------------------------------
379
/**
380      * <p>Strips whitespace from the start and end of a String.</p>
381      *
382      * <p>This is similar to {@link #trim(String)} but removes whitespace.
383      * Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
384      *
385      * <p>A <code>null</code> input String returns <code>null</code>.</p>
386      *
387      * <pre>
388      * StringUtils.strip(null) = null
389      * StringUtils.strip("") = ""
390      * StringUtils.strip(" ") = ""
391      * StringUtils.strip("abc") = "abc"
392      * StringUtils.strip(" abc") = "abc"
393      * StringUtils.strip("abc ") = "abc"
394      * StringUtils.strip(" abc ") = "abc"
395      * StringUtils.strip(" ab c ") = "ab c"
396      * </pre>
397      *
398      * @param str the String to remove whitespace from, may be null
399      * @return the stripped String, <code>null</code> if null String input
400      */

401     public static String JavaDoc strip(String JavaDoc str) {
402         return strip(str, null);
403     }
404
405     /**
406      * <p>Strips whitespace from the start and end of a String returning
407      * <code>null</code> if the String is empty ("") after the strip.</p>
408      *
409      * <p>This is similar to {@link #trimToNull(String)} but removes whitespace.
410      * Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
411      *
412      * <pre>
413      * StringUtils.strip(null) = null
414      * StringUtils.strip("") = null
415      * StringUtils.strip(" ") = null
416      * StringUtils.strip("abc") = "abc"
417      * StringUtils.strip(" abc") = "abc"
418      * StringUtils.strip("abc ") = "abc"
419      * StringUtils.strip(" abc ") = "abc"
420      * StringUtils.strip(" ab c ") = "ab c"
421      * </pre>
422      *
423      * @param str the String to be stripped, may be null
424      * @return the stripped String,
425      * <code>null</code> if whitespace, empty or null String input
426      * @since 2.0
427      */

428     public static String JavaDoc stripToNull(String JavaDoc str) {
429         if (str == null) {
430             return null;
431         }
432         str = strip(str, null);
433         return str.length() == 0 ? null : str;
434     }
435
436     /**
437      * <p>Strips whitespace from the start and end of a String returning
438      * an empty String if <code>null</code> input.</p>
439      *
440      * <p>This is similar to {@link #trimToEmpty(String)} but removes whitespace.
441      * Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
442      *
443      * <pre>
444      * StringUtils.strip(null) = ""
445      * StringUtils.strip("") = ""
446      * StringUtils.strip(" ") = ""
447      * StringUtils.strip("abc") = "abc"
448      * StringUtils.strip(" abc") = "abc"
449      * StringUtils.strip("abc ") = "abc"
450      * StringUtils.strip(" abc ") = "abc"
451      * StringUtils.strip(" ab c ") = "ab c"
452      * </pre>
453      *
454      * @param str the String to be stripped, may be null
455      * @return the trimmed String, or an empty String if <code>null</code> input
456      * @since 2.0
457      */

458     public static String JavaDoc stripToEmpty(String JavaDoc str) {
459         return str == null ? EMPTY : strip(str, null);
460     }
461
462     /**
463      * <p>Strips any of a set of characters from the start and end of a String.
464      * This is similar to {@link String#trim()} but allows the characters
465      * to be stripped to be controlled.</p>
466      *
467      * <p>A <code>null</code> input String returns <code>null</code>.
468      * An empty string ("") input returns the empty string.</p>
469      *
470      * <p>If the stripChars String is <code>null</code>, whitespace is
471      * stripped as defined by {@link Character#isWhitespace(char)}.
472      * Alternatively use {@link #strip(String)}.</p>
473      *
474      * <pre>
475      * StringUtils.strip(null, *) = null
476      * StringUtils.strip("", *) = ""
477      * StringUtils.strip("abc", null) = "abc"
478      * StringUtils.strip(" abc", null) = "abc"
479      * StringUtils.strip("abc ", null) = "abc"
480      * StringUtils.strip(" abc ", null) = "abc"
481      * StringUtils.strip(" abcyx", "xyz") = " abc"
482      * </pre>
483      *
484      * @param str the String to remove characters from, may be null
485      * @param stripChars the characters to remove, null treated as whitespace
486      * @return the stripped String, <code>null</code> if null String input
487      */

488     public static String JavaDoc strip(String JavaDoc str, String JavaDoc stripChars) {
489         if (isEmpty(str)) {
490             return str;
491         }
492         str = stripStart(str, stripChars);
493         return stripEnd(str, stripChars);
494     }
495
496     /**
497      * <p>Strips any of a set of characters from the start of a String.</p>
498      *
499      * <p>A <code>null</code> input String returns <code>null</code>.
500      * An empty string ("") input returns the empty string.</p>
501      *
502      * <p>If the stripChars String is <code>null</code>, whitespace is
503      * stripped as defined by {@link Character#isWhitespace(char)}.</p>
504      *
505      * <pre>
506      * StringUtils.stripStart(null, *) = null
507      * StringUtils.stripStart("", *) = ""
508      * StringUtils.stripStart("abc", "") = "abc"
509      * StringUtils.stripStart("abc", null) = "abc"
510      * StringUtils.stripStart(" abc", null) = "abc"
511      * StringUtils.stripStart("abc ", null) = "abc "
512      * StringUtils.stripStart(" abc ", null) = "abc "
513      * StringUtils.stripStart("yxabc ", "xyz") = "abc "
514      * </pre>
515      *
516      * @param str the String to remove characters from, may be null
517      * @param stripChars the characters to remove, null treated as whitespace
518      * @return the stripped String, <code>null</code> if null String input
519      */

520     public static String JavaDoc stripStart(String JavaDoc str, String JavaDoc stripChars) {
521         int strLen;
522         if (str == null || (strLen = str.length()) == 0) {
523             return str;
524         }
525         int start = 0;
526         if (stripChars == null) {
527             while ((start != strLen) && Character.isWhitespace(str.charAt(start))) {
528                 start++;
529             }
530         } else if (stripChars.length() == 0) {
531             return str;
532         } else {
533             while ((start != strLen) && (stripChars.indexOf(str.charAt(start)) != -1)) {
534                 start++;
535             }
536         }
537         return str.substring(start);
538     }
539
540     /**
541      * <p>Strips any of a set of characters from the end of a String.</p>
542      *
543      * <p>A <code>null</code> input String returns <code>null</code>.
544      * An empty string ("") input returns the empty string.</p>
545      *
546      * <p>If the stripChars String is <code>null</code>, whitespace is
547      * stripped as defined by {@link Character#isWhitespace(char)}.</p>
548      *
549      * <pre>
550      * StringUtils.stripEnd(null, *) = null
551      * StringUtils.stripEnd("", *) = ""
552      * StringUtils.stripEnd("abc", "") = "abc"
553      * StringUtils.stripEnd("abc", null) = "abc"
554      * StringUtils.stripEnd(" abc", null) = " abc"
555      * StringUtils.stripEnd("abc ", null) = "abc"
556      * StringUtils.stripEnd(" abc ", null) = " abc"
557      * StringUtils.stripEnd(" abcyx", "xyz") = " abc"
558      * </pre>
559      *
560      * @param str the String to remove characters from, may be null
561      * @param stripChars the characters to remove, null treated as whitespace
562      * @return the stripped String, <code>null</code> if null String input
563      */

564     public static String JavaDoc stripEnd(String JavaDoc str, String JavaDoc stripChars) {
565         int end;
566         if (str == null || (end = str.length()) == 0) {
567             return str;
568         }
569
570         if (stripChars == null) {
571             while ((end != 0) && Character.isWhitespace(str.charAt(end - 1))) {
572                 end--;
573             }
574         } else if (stripChars.length() == 0) {
575             return str;
576         } else {
577             while ((end != 0) && (stripChars.indexOf(str.charAt(end - 1)) != -1)) {
578                 end--;
579             }
580         }
581         return str.substring(0, end);
582     }
583
584     // StripAll
585
//-----------------------------------------------------------------------
586
/**
587      * <p>Strips whitespace from the start and end of every String in an array.
588      * Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
589      *
590      * <p>A new array is returned each time, except for length zero.
591      * A <code>null</code> array will return <code>null</code>.
592      * An empty array will return itself.
593      * A <code>null</code> array entry will be ignored.</p>
594      *
595      * <pre>
596      * StringUtils.stripAll(null) = null
597      * StringUtils.stripAll([]) = []
598      * StringUtils.stripAll(["abc", " abc"]) = ["abc", "abc"]
599      * StringUtils.stripAll(["abc ", null]) = ["abc", null]
600      * </pre>
601      *
602      * @param strs the array to remove whitespace from, may be null
603      * @return the stripped Strings, <code>null</code> if null array input
604      */

605     public static String JavaDoc[] stripAll(String JavaDoc[] strs) {
606         return stripAll(strs, null);
607     }
608
609     /**
610      * <p>Strips any of a set of characters from the start and end of every
611      * String in an array.</p>
612      * Whitespace is defined by {@link Character#isWhitespace(char)}.</p>
613      *
614      * <p>A new array is returned each time, except for length zero.
615      * A <code>null</code> array will return <code>null</code>.
616      * An empty array will return itself.
617      * A <code>null</code> array entry will be ignored.
618      * A <code>null</code> stripChars will strip whitespace as defined by
619      * {@link Character#isWhitespace(char)}.</p>
620      *
621      * <pre>
622      * StringUtils.stripAll(null, *) = null
623      * StringUtils.stripAll([], *) = []
624      * StringUtils.stripAll(["abc", " abc"], null) = ["abc", "abc"]
625      * StringUtils.stripAll(["abc ", null], null) = ["abc", null]
626      * StringUtils.stripAll(["abc ", null], "yz") = ["abc ", null]
627      * StringUtils.stripAll(["yabcz", null], "yz") = ["abc", null]
628      * </pre>
629      *
630      * @param strs the array to remove characters from, may be null
631      * @param stripChars the characters to remove, null treated as whitespace
632      * @return the stripped Strings, <code>null</code> if null array input
633      */

634     public static String JavaDoc[] stripAll(String JavaDoc[] strs, String JavaDoc stripChars) {
635         int strsLen;
636         if (strs == null || (strsLen = strs.length) == 0) {
637             return strs;
638         }
639         String JavaDoc[] newArr = new String JavaDoc[strsLen];
640         for (int i = 0; i < strsLen; i++) {
641             newArr[i] = strip(strs[i], stripChars);
642         }
643         return newArr;
644     }
645
646     // Equals
647
//-----------------------------------------------------------------------
648
/**
649      * <p>Compares two Strings, returning <code>true</code> if they are equal.</p>
650      *
651      * <p><code>null</code>s are handled without exceptions. Two <code>null</code>
652      * references are considered to be equal. The comparison is case sensitive.</p>
653      *
654      * <pre>
655      * StringUtils.equals(null, null) = true
656      * StringUtils.equals(null, "abc") = false
657      * StringUtils.equals("abc", null) = false
658      * StringUtils.equals("abc", "abc") = true
659      * StringUtils.equals("abc", "ABC") = false
660      * </pre>
661      *
662      * @see java.lang.String#equals(Object)
663      * @param str1 the first String, may be null
664      * @param str2 the second String, may be null
665      * @return <code>true</code> if the Strings are equal, case sensitive, or
666      * both <code>null</code>
667      */

668     public static boolean equals(String JavaDoc str1, String JavaDoc str2) {
669         return str1 == null ? str2 == null : str1.equals(str2);
670     }
671
672     /**
673      * <p>Compares two Strings, returning <code>true</code> if they are equal ignoring
674      * the case.</p>
675      *
676      * <p><code>null</code>s are handled without exceptions. Two <code>null</code>
677      * references are considered equal. Comparison is case insensitive.</p>
678      *
679      * <pre>
680      * StringUtils.equalsIgnoreCase(null, null) = true
681      * StringUtils.equalsIgnoreCase(null, "abc") = false
682      * StringUtils.equalsIgnoreCase("abc", null) = false
683      * StringUtils.equalsIgnoreCase("abc", "abc") = true
684      * StringUtils.equalsIgnoreCase("abc", "ABC") = true
685      * </pre>
686      *
687      * @see java.lang.String#equalsIgnoreCase(String)
688      * @param str1 the first String, may be null
689      * @param str2 the second String, may be null
690      * @return <code>true</code> if the Strings are equal, case insensitive, or
691      * both <code>null</code>
692      */

693     public static boolean equalsIgnoreCase(String JavaDoc str1, String JavaDoc str2) {
694         return str1 == null ? str2 == null : str1.equalsIgnoreCase(str2);
695     }
696
697     // IndexOf
698
//-----------------------------------------------------------------------
699
/**
700      * <p>Finds the first index within a String, handling <code>null</code>.
701      * This method uses {@link String#indexOf(int)}.</p>
702      *
703      * <p>A <code>null</code> or empty ("") String will return <code>-1</code>.</p>
704      *
705      * <pre>
706      * StringUtils.indexOf(null, *) = -1
707      * StringUtils.indexOf("", *) = -1
708      * StringUtils.indexOf("aabaabaa", 'a') = 0
709      * StringUtils.indexOf("aabaabaa", 'b') = 2
710      * </pre>
711      *
712      * @param str the String to check, may be null
713      * @param searchChar the character to find
714      * @return the first index of the search character,
715      * -1 if no match or <code>null</code> string input
716      * @since 2.0
717      */

718     public static int indexOf(String JavaDoc str, char searchChar) {
719         if (isEmpty(str)) {
720             return -1;
721         }
722         return str.indexOf(searchChar);
723     }
724
725     /**
726      * <p>Finds the first index within a String from a start position,
727      * handling <code>null</code>.
728      * This method uses {@link String#indexOf(int, int)}.</p>
729      *
730      * <p>A <code>null</code> or empty ("") String will return <code>-1</code>.
731      * A negative start position is treated as zero.
732      * A start position greater than the string length returns <code>-1</code>.</p>
733      *
734      * <pre>
735      * StringUtils.indexOf(null, *, *) = -1
736      * StringUtils.indexOf("", *, *) = -1
737      * StringUtils.indexOf("aabaabaa", 'b', 0) = 2
738      * StringUtils.indexOf("aabaabaa", 'b', 3) = 5
739      * StringUtils.indexOf("aabaabaa", 'b', 9) = -1
740      * StringUtils.indexOf("aabaabaa", 'b', -1) = 2
741      * </pre>
742      *
743      * @param str the String to check, may be null
744      * @param searchChar the character to find
745      * @param startPos the start position, negative treated as zero
746      * @return the first index of the search character,
747      * -1 if no match or <code>null</code> string input
748      * @since 2.0
749      */

750     public static int indexOf(String JavaDoc str, char searchChar, int startPos) {
751         if (isEmpty(str)) {
752             return -1;
753         }
754         return str.indexOf(searchChar, startPos);
755     }
756
757     /**
758      * <p>Finds the first index within a String, handling <code>null</code>.
759      * This method uses {@link String#indexOf(String)}.</p>
760      *
761      * <p>A <code>null</code> String will return <code>-1</code>.</p>
762      *
763      * <pre>
764      * StringUtils.indexOf(null, *) = -1
765      * StringUtils.indexOf(*, null) = -1
766      * StringUtils.indexOf("", "") = 0
767      * StringUtils.indexOf("aabaabaa", "a") = 0
768      * StringUtils.indexOf("aabaabaa", "b") = 2
769      * StringUtils.indexOf("aabaabaa", "ab") = 1
770      * StringUtils.indexOf("aabaabaa", "") = 0
771      * </pre>
772      *
773      * @param str the String to check, may be null
774      * @param searchStr the String to find, may be null
775      * @return the first index of the search String,
776      * -1 if no match or <code>null</code> string input
777      * @since 2.0
778      */

779     public static int indexOf(String JavaDoc str, String JavaDoc searchStr) {
780         if (str == null || searchStr == null) {
781             return -1;
782         }
783         return str.indexOf(searchStr);
784     }
785
786     /**
787      * <p>Finds the n-th index within a String, handling <code>null</code>.
788      * This method uses {@link String#indexOf(String)}.</p>
789      *
790      * <p>A <code>null</code> String will return <code>-1</code>.</p>
791      *
792      * <pre>
793      * StringUtils.ordinalIndexOf(null, *, *) = -1
794      * StringUtils.ordinalIndexOf(*, null, *) = -1
795      * StringUtils.ordinalIndexOf("", "", *) = 0
796      * StringUtils.ordinalIndexOf("aabaabaa", "a", 1) = 0
797      * StringUtils.ordinalIndexOf("aabaabaa", "a", 2) = 1
798      * StringUtils.ordinalIndexOf("aabaabaa", "b", 1) = 2
799      * StringUtils.ordinalIndexOf("aabaabaa", "b", 2) = 5
800      * StringUtils.ordinalIndexOf("aabaabaa", "ab", 1) = 1
801      * StringUtils.ordinalIndexOf("aabaabaa", "ab", 2) = 4
802      * StringUtils.ordinalIndexOf("aabaabaa", "", 1) = 0
803      * StringUtils.ordinalIndexOf("aabaabaa", "", 2) = 0
804      * </pre>
805      *
806      * @param str the String to check, may be null
807      * @param searchStr the String to find, may be null
808      * @param ordinal the n-th <code>searchStr</code> to find
809      * @return the n-th index of the search String,
810      * <code>-1</code> (<code>INDEX_NOT_FOUND</code>) if no match or <code>null</code> string input
811      * @since 2.1
812      */

813     public static int ordinalIndexOf(String JavaDoc str, String JavaDoc searchStr, int ordinal) {
814         if (str == null || searchStr == null || ordinal <= 0) {
815             return INDEX_NOT_FOUND;
816         }
817         if (searchStr.length() == 0) {
818             return 0;
819         }
820         int found = 0;
821         int index = INDEX_NOT_FOUND;
822         do {
823             index = str.indexOf(searchStr, index + 1);
824             if (index < 0) {
825                 return index;
826             }
827             found++;
828         } while (found < ordinal);
829         return index;
830     }
831
832     /**
833      * <p>Finds the first index within a String, handling <code>null</code>.
834      * This method uses {@link String#indexOf(String, int)}.</p>
835      *
836      * <p>A <code>null</code> String will return <code>-1</code>.
837      * A negative start position is treated as zero.
838      * An empty ("") search String always matches.
839      * A start position greater than the string length only matches
840      * an empty search String.</p>
841      *
842      * <pre>
843      * StringUtils.indexOf(null, *, *) = -1
844      * StringUtils.indexOf(*, null, *) = -1
845      * StringUtils.indexOf("", "", 0) = 0
846      * StringUtils.indexOf("aabaabaa", "a", 0) = 0
847      * StringUtils.indexOf("aabaabaa", "b", 0) = 2
848      * StringUtils.indexOf("aabaabaa", "ab", 0) = 1
849      * StringUtils.indexOf("aabaabaa", "b", 3) = 5
850      * StringUtils.indexOf("aabaabaa", "b", 9) = -1
851      * StringUtils.indexOf("aabaabaa", "b", -1) = 2
852      * StringUtils.indexOf("aabaabaa", "", 2) = 2
853      * StringUtils.indexOf("abc", "", 9) = 3
854      * </pre>
855      *
856      * @param str the String to check, may be null
857      * @param searchStr the String to find, may be null
858      * @param startPos the start position, negative treated as zero
859      * @return the first index of the search String,
860      * -1 if no match or <code>null</code> string input
861      * @since 2.0
862      */

863     public static int indexOf(String JavaDoc str, String JavaDoc searchStr, int startPos) {
864         if (str == null || searchStr == null) {
865             return -1;
866         }
867         // JDK1.2/JDK1.3 have a bug, when startPos > str.length for "", hence
868
if (searchStr.length() == 0 && startPos >= str.length()) {
869             return str.length();
870         }
871         return str.indexOf(searchStr, startPos);
872     }
873
874     // LastIndexOf
875
//-----------------------------------------------------------------------
876
/**
877      * <p>Finds the last index within a String, handling <code>null</code>.
878      * This method uses {@link String#lastIndexOf(int)}.</p>
879      *
880      * <p>A <code>null</code> or empty ("") String will return <code>-1</code>.</p>
881      *
882      * <pre>
883      * StringUtils.lastIndexOf(null, *) = -1
884      * StringUtils.lastIndexOf("", *) = -1
885      * StringUtils.lastIndexOf("aabaabaa", 'a') = 7
886      * StringUtils.lastIndexOf("aabaabaa", 'b') = 5
887      * </pre>
888      *
889      * @param str the String to check, may be null
890      * @param searchChar the character to find
891      * @return the last index of the search character,
892      * -1 if no match or <code>null</code> string input
893      * @since 2.0
894      */

895     public static int lastIndexOf(String JavaDoc str, char searchChar) {
896         if (isEmpty(str)) {
897             return -1;
898         }
899         return str.lastIndexOf(searchChar);
900     }
901
902     /**
903      * <p>Finds the last index within a String from a start position,
904      * handling <code>null</code>.
905      * This method uses {@link String#lastIndexOf(int, int)}.</p>
906      *
907      * <p>A <code>null</code> or empty ("") String will return <code>-1</code>.
908      * A negative start position returns <code>-1</code>.
909      * A start position greater than the string length searches the whole string.</p>
910      *
911      * <pre>
912      * StringUtils.lastIndexOf(null, *, *) = -1
913      * StringUtils.lastIndexOf("", *, *) = -1
914      * StringUtils.lastIndexOf("aabaabaa", 'b', 8) = 5
915      * StringUtils.lastIndexOf("aabaabaa", 'b', 4) = 2
916      * StringUtils.lastIndexOf("aabaabaa", 'b', 0) = -1
917      * StringUtils.lastIndexOf("aabaabaa", 'b', 9) = 5
918      * StringUtils.lastIndexOf("aabaabaa", 'b', -1) = -1
919      * StringUtils.lastIndexOf("aabaabaa", 'a', 0) = 0
920      * </pre>
921      *
922      * @param str the String to check, may be null
923      * @param searchChar the character to find
924      * @param startPos the start position
925      * @return the last index of the search character,
926      * -1 if no match or <code>null</code> string input
927      * @since 2.0
928      */

929     public static int lastIndexOf(String JavaDoc str, char searchChar, int startPos) {
930         if (isEmpty(str)) {
931             return -1;
932         }
933         return str.lastIndexOf(searchChar, startPos);
934     }
935
936     /**
937      * <p>Finds the last index within a String, handling <code>null</code>.
938      * This method uses {@link String#lastIndexOf(String)}.</p>
939      *
940      * <p>A <code>null</code> String will return <code>-1</code>.</p>
941      *
942      * <pre>
943      * StringUtils.lastIndexOf(null, *) = -1
944      * StringUtils.lastIndexOf(*, null) = -1
945      * StringUtils.lastIndexOf("", "") = 0
946      * StringUtils.lastIndexOf("aabaabaa", "a") = 0
947      * StringUtils.lastIndexOf("aabaabaa", "b") = 2
948      * StringUtils.lastIndexOf("aabaabaa", "ab") = 1
949      * StringUtils.lastIndexOf("aabaabaa", "") = 8
950      * </pre>
951      *
952      * @param str the String to check, may be null
953      * @param searchStr the String to find, may be null
954      * @return the last index of the search String,
955      * -1 if no match or <code>null</code> string input
956      * @since 2.0
957      */

958     public static int lastIndexOf(String JavaDoc str, String JavaDoc searchStr) {
959         if (str == null || searchStr == null) {
960             return -1;
961         }
962         return str.lastIndexOf(searchStr);
963     }
964
965     /**
966      * <p>Finds the first index within a String, handling <code>null</code>.
967      * This method uses {@link String#lastIndexOf(String, int)}.</p>
968      *
969      * <p>A <code>null</code> String will return <code>-1</code>.
970      * A negative start position returns <code>-1</code>.
971      * An empty ("") search String always matches unless the start position is negative.
972      * A start position greater than the string length searches the whole string.</p>
973      *
974      * <pre>
975      * StringUtils.lastIndexOf(null, *, *) = -1
976      * StringUtils.lastIndexOf(*, null, *) = -1
977      * StringUtils.lastIndexOf("aabaabaa", "a", 8) = 7
978      * StringUtils.lastIndexOf("aabaabaa", "b", 8) = 5
979      * StringUtils.lastIndexOf("aabaabaa", "ab", 8) = 4
980      * StringUtils.lastIndexOf("aabaabaa", "b", 9) = 5
981      * StringUtils.lastIndexOf("aabaabaa", "b", -1) = -1
982      * String