|
Operations on String that are null safe.
The StringUtils class defines certain words related to String handling.
StringUtils handles null input Strings quietly. That is to say that a null input will return null. Where a boolean or int is being returned, details vary by method. A side effect of the null handling is that a NullPointerException should be considered a bug in StringUtils (except for deprecated methods). Methods in this class give sample code to explain their operation. The symbol * is used to indicate any input including null. Field Detailpublic static final java.lang.String EMPTY The empty String "". See Also: Constant Field Values Constructor Detailpublic StringUtils() StringUtils instances should NOT be constructed in standard programming. Instead, the class should be used as StringUtils.trim("foo");. This constructor is public to permit tools that require a JavaBean instance to operate. Method Detailpublic static boolean isEmpty(java.lang.String str) Checks if a String is empty ("") or null. StringUtils.isEmpty(null) = true StringUtils.isEmpty("") = true StringUtils.isEmpty(" ") = false StringUtils.isEmpty("bob") = false StringUtils.isEmpty(" bob ") = false NOTE: This method changed in Lang version 2.0. It no longer trims the String. That functionality is available in isBlank(). Parameters: strthe String to check, may be null Returns: true if the String is empty or null public static boolean isNotEmpty(java.lang.String str) Checks if a String is not empty ("") and not null. StringUtils.isNotEmpty(null) = false StringUtils.isNotEmpty("") = false StringUtils.isNotEmpty(" ") = true StringUtils.isNotEmpty("bob") = true StringUtils.isNotEmpty(" bob ") = true Parameters: strthe String to check, may be null Returns: true if the String is not empty and not null public static boolean isBlank(java.lang.String str) Checks if a String is whitespace, empty ("") or null. StringUtils.isBlank(null) = true StringUtils.isBlank("") = true StringUtils.isBlank(" ") = true StringUtils.isBlank("bob") = false StringUtils.isBlank(" bob ") = false Parameters: strthe String to check, may be null Returns: true if the String is null, empty or whitespace public static boolean isNotBlank(java.lang.String str) Checks if a String is not empty (""), not null and not whitespace only. StringUtils.isNotBlank(null) = false StringUtils.isNotBlank("") = false StringUtils.isNotBlank(" ") = false StringUtils.isNotBlank("bob") = true StringUtils.isNotBlank(" bob ") = true Parameters: strthe String to check, may be null Returns: true if the String is not empty and not null and not whitespace public static java.lang.String trim(java.lang.String str) Removes control characters (char <= 32) from both ends of this String, handling null by returning null. The String is trimmed using String.trim(). trim removes start and end characters <= 32. To strip whitespace use strip(String). To trim your choice of characters, use the strip(String, String) methods. StringUtils.trim(null) = null StringUtils.trim("") = "" StringUtils.trim(" ") = "" StringUtils.trim("abc") = "abc" StringUtils.trim(" abc ") = "abc" Parameters: strthe String to be trimmed, may be null Returns: the trimmed string, null if null String input public static java.lang.String trimToNull(java.lang.String str) Removes control characters (char <= 32) from both ends of this String returning null if the String is empty ("") after the trim or if it is null. The String is trimmed using String.trim(). trim removes start and end characters <= 32. To strip whitespace use stripToNull(String). StringUtils.trimToNull(null) = null StringUtils.trimToNull("") = null StringUtils.trimToNull(" ") = null StringUtils.trimToNull("abc") = "abc" StringUtils.trimToNull(" abc ") = "abc" Parameters: strthe String to be trimmed, may be null Returns: the trimmed String, null if only chars <= 32, empty or null String input public static java.lang.String trimToEmpty(java.lang.String str) Removes control characters (char <= 32) from both ends of this String returning an empty String ("") if the String is empty ("") after the trim or if it is null. The String is trimmed using String.trim(). trim removes start and end characters <= 32. To strip whitespace use stripToEmpty(String). StringUtils.trimToEmpty(null) = "" StringUtils.trimToEmpty("") = "" StringUtils.trimToEmpty(" ") = "" StringUtils.trimToEmpty("abc") = "abc" StringUtils.trimToEmpty(" abc ") = "abc" Parameters: strthe String to be trimmed, may be null Returns: the trimmed String, or an empty String if null input public static java.lang.String strip(java.lang.String str) Strips whitespace from the start and end of a String. This is similar to TRim(String) but removes whitespace. Whitespace is defined by Character.isWhitespace(char). A null input String returns null. StringUtils.strip(null) = null StringUtils.strip("") = "" StringUtils.strip(" ") = "" StringUtils.strip("abc") = "abc" StringUtils.strip(" abc") = "abc" StringUtils.strip("abc ") = "abc" StringUtils.strip(" abc ") = "abc" StringUtils.strip(" ab c ") = "ab c" Parameters: strthe String to remove whitespace from, may be null Returns: the stripped String, null if null String input public static java.lang.String stripToNull(java.lang.String str) Strips whitespace from the start and end of a String returning null if the String is empty ("") after the strip. This is similar to trimToNull(String) but removes whitespace. Whitespace is defined by Character.isWhitespace(char). StringUtils.strip(null) = null StringUtils.strip("") = null StringUtils.strip(" ") = null StringUtils.strip("abc") = "abc" StringUtils.strip(" abc") = "abc" StringUtils.strip("abc ") = "abc" StringUtils.strip(" abc ") = "abc" StringUtils.strip(" ab c ") = "ab c" Parameters: strthe String to be stripped, may be null Returns: the stripped String, null if whitespace, empty or null String input public static java.lang.String stripToEmpty(java.lang.String str) Strips whitespace from the start and end of a String returning an empty String if null input. This is similar to trimToEmpty(String) but removes whitespace. Whitespace is defined by Character.isWhitespace(char). StringUtils.strip(null) = "" StringUtils.strip("") = "" StringUtils.strip(" ") = "" StringUtils.strip("abc") = "abc" StringUtils.strip(" abc") = "abc" StringUtils.strip("abc ") = "abc" StringUtils.strip(" abc ") = "abc" StringUtils.strip(" ab c ") = "ab c" Parameters: strthe String to be stripped, may be null Returns: the trimmed String, or an empty String if null input public static java.lang.String strip(java.lang.String str, java.lang.String stripChars) Strips any of a set of characters from the start and end of a String. This is similar to String.trim() but allows the characters to be stripped to be controlled. A null input String returns null. An empty string ("") input returns the empty string. If the stripChars String is null, whitespace is stripped as defined by Character.isWhitespace(char). Alternatively use strip(String). StringUtils.strip(null, *) = null StringUtils.strip("", *) = "" StringUtils.strip("abc", null) = "abc" StringUtils.strip(" abc", null) = "abc" StringUtils.strip("abc ", null) = "abc" StringUtils.strip(" abc ", null) = "abc" StringUtils.strip(" abcyx", "xyz") = " abc" Parameters: strthe String to remove characters from, may be null stripCharsthe characters to remove, null TReated as whitespace Returns: the stripped String, null if null String input public static java.lang.String stripStart(java.lang.String str, java.lang.String stripChars) Strips any of a set of characters from the start of a String. A null input String returns null. An empty string ("") input returns the empty string. If the stripChars String is null, whitespace is stripped as defined by Character.isWhitespace(char). StringUtils.stripStart(null, *) = null StringUtils.stripStart("", *) = "" StringUtils.stripStart("abc", "") = "abc" StringUtils.stripStart("abc", null) = "abc" StringUtils.stripStart(" abc", null) = "abc" StringUtils.stripStart("abc ", null) = "abc " StringUtils.stripStart(" abc ", null) = "abc " StringUtils.stripStart("yxabc ", "xyz") = "abc " Parameters: strthe String to remove characters from, may be null stripCharsthe characters to remove, null treated as whitespace Returns: the stripped String, null if null String input public static java.lang.String stripEnd(java.lang.String str, java.lang.String stripChars) Strips any of a set of characters from the end of a String. A null input String returns null. An empty string ("") input returns the empty string. If the stripChars String is null, whitespace is stripped as defined by Character.isWhitespace(char). StringUtils.stripEnd(null, *) = null StringUtils.stripEnd("", *) = "" StringUtils.stripEnd("abc", "") = "abc" StringUtils.stripEnd("abc", null) = "abc" StringUtils.stripEnd(" abc", null) = " abc" StringUtils.stripEnd("abc ", null) = "abc" StringUtils.stripEnd(" abc ", null) = " abc" StringUtils.stripEnd(" abcyx", "xyz") = " abc" Parameters: strthe String to remove characters from, may be null stripCharsthe characters to remove, null treated as whitespace Returns: the stripped String, null if null String input public static java.lang.String[] stripAll(java.lang.String[] strs) Strips whitespace from the start and end of every String in an array. Whitespace is defined by Character.isWhitespace(char). A new array is returned each time, except for length zero. A null array will return null. An empty array will return itself. A null array entry will be ignored. StringUtils.stripAll(null) = null StringUtils.stripAll([]) = [] StringUtils.stripAll(["abc", " abc"]) = ["abc", "abc"] StringUtils.stripAll(["abc ", null]) = ["abc", null] Parameters: strsthe array to remove whitespace from, may be null Returns: the stripped Strings, null if null array input
Strips any of a set of characters from the start and end of every String in an array. Whitespace is defined by Character.isWhitespace(char). A new array is returned each time, except for length zero. A null array will return null. An empty array will return itself. A null array entry will be ignored. A null stripChars will strip whitespace as defined by Character.isWhitespace(char). StringUtils.stripAll(null, *) = null StringUtils.stripAll([], *) = [] StringUtils.stripAll(["abc", " abc"], null) = ["abc", "abc"] StringUtils.stripAll(["abc ", null], null) = ["abc", null] StringUtils.stripAll(["abc ", null], "yz") = ["abc ", null] StringUtils.stripAll(["yabcz", null], "yz") = ["abc", null] Parameters: strsthe array to remove characters from, may be null stripCharsthe characters to remove, null treated as whitespace Returns: the stripped Strings, null if null array input public static boolean equals(java.lang.String str1, java.lang.String str2) Compares two Strings, returning true if they are equal. nulls are handled without exceptions. Two null references are considered to be equal. The comparison is case sensitive. StringUtils.equals(null, null) = true StringUtils.equals(null, "abc") = false StringUtils.equals("abc", null) = false StringUtils.equals("abc", "abc") = true StringUtils.equals("abc", "ABC") = false Parameters: str1the first String, may be null str2the second String, may be null Returns: true if the Strings are equal, case sensitive, or both null See Also: String.equals(Object) public static boolean equalsIgnoreCase(java.lang.String str1, java.lang.String str2) Compares two Strings, returning true if they are equal ignoring the case. nulls are handled without exceptions. Two null references are considered equal. Comparison is case insensitive. StringUtils.equalsIgnoreCase(null, null) = true StringUtils.equalsIgnoreCase(null, "abc") = false StringUtils.equalsIgnoreCase("abc", null) = false StringUtils.equalsIgnoreCase("abc", "abc") = true StringUtils.equalsIgnoreCase("abc", "ABC") = true Parameters: str1the first String, may be null str2the second String, may be null Returns: true if the Strings are equal, case insensitive, or both null See Also: String.equalsIgnoreCase(String) public static int indexOf(java.lang.String str, char searchChar) Finds the first index within a String, handling null. This method uses String.indexOf(int). A null or empty ("") String will return -1. StringUtils.indexOf(null, *) = -1 StringUtils.indexOf("", *) = -1 StringUtils.indexOf("aabaabaa", 'a') = 0 StringUtils.indexOf("aabaabaa", 'b') = 2 Parameters: strthe String to check, may be null searchCharthe character to find Returns: the first index of the search character, -1 if no match or null string input public static int indexOf(java.lang.String str, char searchChar, int startPos) Finds the first index within a String from a start position, handling null. This method uses String.indexOf(int, int). A null or empty ("") String will return -1. A negative start position is treated as zero. A start position greater than the string length returns -1. StringUtils.indexOf(null, *, *) = -1 StringUtils.indexOf("", *, *) = -1 StringUtils.indexOf("aabaabaa", 'b', 0) = 2 StringUtils.indexOf("aabaabaa", 'b', 3) = 5 StringUtils.indexOf("aabaabaa", 'b', 9) = -1 StringUtils.indexOf("aabaabaa", 'b', -1) = 2 Parameters: strthe String to check, may be null searchCharthe character to find startPosthe start position, negative treated as zero Returns: the first index of the search character, -1 if no match or null string input public static int indexOf(java.lang.String str, java.lang.String searchStr) Finds the first index within a String, handling null. This method uses String.indexOf(String). A null String will return -1. StringUtils.indexOf(null, *) = -1 StringUtils.indexOf(*, null) = -1 StringUtils.indexOf("", "") = 0 StringUtils.indexOf("aabaabaa", "a") = 0 StringUtils.indexOf("aabaabaa", "b") = 2 StringUtils.indexOf("aabaabaa", "ab") = 1 StringUtils.indexOf("aabaabaa", "") = 0 Parameters: strthe String to check, may be null searchStrthe String to find, may be null Returns: the first index of the search String, -1 if no match or null string input public static int indexOf(java.lang.String str, java.lang.String searchStr, int startPos) Finds the first index within a String, handling null. This method uses String.indexOf(String, int). A null String will return -1. A negative start position is treated as zero. An empty ("") search String always matches. A start position greater than the string length only matches an empty search String. StringUtils.indexOf(null, *, *) = -1 StringUtils.indexOf(*, null, *) = -1 StringUtils.indexOf("", "", 0) = 0 StringUtils.indexOf("aabaabaa", "a", 0) = 0 StringUtils.indexOf("aabaabaa", "b", 0) = 2 StringUtils.indexOf("aabaabaa", "ab", 0) = 1 StringUtils.indexOf("aabaabaa", "b", 3) = 5 StringUtils.indexOf("aabaabaa", "b", 9) = -1 StringUtils.indexOf("aabaabaa", "b", -1) = 2 StringUtils.indexOf("aabaabaa", "", 2) = 2 StringUtils.indexOf("abc", "", 9) = 3 Parameters: strthe String to check, may be null searchStrthe String to find, may be null startPosthe start position, negative treated as zero Returns: the first index of the search String, -1 if no match or null string input public static int lastIndexOf(java.lang.String str, char searchChar) Finds the last index within a String, handling null. This method uses String.lastIndexOf(int). A null or empty ("") String will return -1. StringUtils.lastIndexOf(null, *) = -1 StringUtils.lastIndexOf("", *) = -1 StringUtils.lastIndexOf("aabaabaa", 'a') = 7 StringUtils.lastIndexOf("aabaabaa", 'b') = 5 Parameters: strthe String to check, may be null searchCharthe character to find Returns: the last index of the search character, -1 if no match or null string input public static int lastIndexOf(java.lang.String str, char searchChar, int startPos) Finds the last index within a String from a start position, handling null. This method uses String.lastIndexOf(int, int). A null or empty ("") String will return -1. A negative start position returns -1. A start position greater than the string length searches the whole string. StringUtils.lastIndexOf(null, *, *) = -1 StringUtils.lastIndexOf("", *, *) = -1 StringUtils.lastIndexOf("aabaabaa", 'b', 8) = 5 StringUtils.lastIndexOf("aabaabaa", 'b', 4) = 2 StringUtils.lastIndexOf("aabaabaa", 'b', 0) = -1 StringUtils.lastIndexOf("aabaabaa", 'b', 9) = 5 StringUtils.lastIndexOf("aabaabaa", 'b', -1) = -1 StringUtils.lastIndexOf("aabaabaa", 'a', 0) = 0 Parameters: strthe String to check, may be null searchCharthe character to find startPosthe start position Returns: the last index of the search character, -1 if no match or null string input public static int lastIndexOf(java.lang.String str, java.lang.String searchStr) Finds the last index within a String, handling null. This method uses String.lastIndexOf(String). A null String will return -1. StringUtils.lastIndexOf(null, *) = -1 StringUtils.lastIndexOf(*, null) = -1 StringUtils.lastIndexOf("", "") = 0 StringUtils.lastIndexOf("aabaabaa", "a") = 0 StringUtils.lastIndexOf("aabaabaa", "b") = 2 StringUtils.lastIndexOf("aabaabaa", "ab") = 1 StringUtils.lastIndexOf("aabaabaa", "") = 8 Parameters: strthe String to check, may be null searchStrthe String to find, may be null Returns: the last index of the search String, -1 if no match or null string input public static int lastIndexOf(java.lang.String str, java.lang.String searchStr, int startPos) Finds the first index within a String, handling null. This method uses String.lastIndexOf(String, int). A null String will return -1. A negative start position returns -1. An empty ("") search String always matches unless the start position is negative. A start position greater than the string length searches the whole string. StringUtils.lastIndexOf(null, *, *) = -1 StringUtils.lastIndexOf(*, null, *) = -1 StringUtils.lastIndexOf("aabaabaa", "a", 8) = 7 StringUtils.lastIndexOf("aabaabaa", "b", 8) = 5 StringUtils.lastIndexOf("aabaabaa", "ab", 8) = 4 StringUtils.lastIndexOf("aabaabaa", "b", 9) = 5 StringUtils.lastIndexOf("aabaabaa", "b", -1) = -1 StringUtils.lastIndexOf("aabaabaa", "a", 0) = 0 StringUtils.lastIndexOf("aabaabaa", "b", 0) = -1 Parameters: strthe String to check, may be null searchStrthe String to find, may be null startPosthe start position, negative treated as zero Returns: the first index of the search String, -1 if no match or null string input public static boolean contains(java.lang.String str, char searchChar) Checks if String contains a search character, handling null. This method uses String.indexOf(int). A null or empty ("") String will return false. StringUtils.contains(null, *) = false StringUtils.contains("", *) = false StringUtils.contains("abc", 'a') = true StringUtils.contains("abc", 'z') = false Parameters: strthe String to check, may be null searchCharthe character to find Returns: true if the String contains the search character, false if not or null string input public static boolean contains(java.lang.String str, java.lang.String searchStr) Find the first index within a String, handling null. This method uses String.indexOf(int). A null String will return false. StringUtils.contains(null, *) = false StringUtils.contains(*, null) = false StringUtils.contains("", "") = true StringUtils.contains("abc", "") = true StringUtils.contains("abc", "a") = true StringUtils.contains("abc", "z") = false Parameters: strthe String to check, may be null searchStrthe String to find, may be null Returns: true if the String contains the search character, false if not or null string input public static int indexOfAny(java.lang.String str, char[] searchChars) Search a String to find the first index of any character in the given set of characters. A null String will return -1. A null or zero length search array will return -1. StringUtils.indexOfAny(null, *) = -1 StringUtils.indexOfAny("", *) = -1 StringUtils.indexOfAny(*, null) = -1 StringUtils.indexOfAny(*, []) = -1 StringUtils.indexOfAny("zzabyycdxx",['z','a']) = 0 StringUtils.indexOfAny("zzabyycdxx",['b','y']) = 3 StringUtils.indexOfAny("aba", ['z']) = -1 Parameters: strthe String to check, may be null searchCharsthe chars to search for, may be null Returns: the index of any of the chars, -1 if no match or null input public static int indexOfAny(java.lang.String str, java.lang.String searchChars) Search a String to find the first index of any character in the given set of characters. A null String will return -1. A null search string will return -1. StringUtils.indexOfAny(null, *) = -1 StringUtils.indexOfAny("", *) = -1 StringUtils.indexOfAny(*, null) = -1 StringUtils.indexOfAny(*, "") = -1 StringUtils.indexOfAny("zzabyycdxx", "za") = 0 StringUtils.indexOfAny("zzabyycdxx", "by") = 3 StringUtils.indexOfAny("aba","z") = -1 Parameters: strthe String to check, may be null searchCharsthe chars to search for, may be null Returns: the index of any of the chars, -1 if no match or null input public static int indexOfAnyBut(java.lang.String str, char[] searchChars) Search a String to find the first index of any character not in the given set of characters. A null String will return -1. A null or zero length search array will return -1. StringUtils.indexOfAnyBut(null, *) = -1 StringUtils.indexOfAnyBut("", *) = -1 StringUtils.indexOfAnyBut(*, null) = -1 StringUtils.indexOfAnyBut(*, []) = -1 StringUtils.indexOfAnyBut("zzabyycdxx",'za') = 3 StringUtils.indexOfAnyBut("zzabyycdxx", '') = 0 StringUtils.indexOfAnyBut("aba", 'ab') = -1 Parameters: strthe String to check, may be null searchCharsthe chars to search for, may be null Returns: the index of any of the chars, -1 if no match or null input public static int indexOfAnyBut(java.lang.String str, java.lang.String searchChars) Search a String to find the first index of any character not in the given set of characters. A null String will return -1. A null search string will return -1. StringUtils.indexOfAnyBut(null, *) = -1 StringUtils.indexOfAnyBut("", *) = -1 StringUtils.indexOfAnyBut(*, null) = -1 StringUtils.indexOfAnyBut(*, "") = -1 StringUtils.indexOfAnyBut("zzabyycdxx", "za") = 3 StringUtils.indexOfAnyBut("zzabyycdxx", "") = 0 StringUtils.indexOfAnyBut("aba","ab") = -1 Parameters: strthe String to check, may be null searchCharsthe chars to search for, may be null Returns: the index of any of the chars, -1 if no match or null input public static boolean containsOnly(java.lang.String str, char[] valid) Checks if the String contains only certain characters. A null String will return false. A null valid character array will return false. An empty String ("") always returns true. StringUtils.containsOnly(null, *) = false StringUtils.containsOnly(*, null) = false StringUtils.containsOnly("", *) = true StringUtils.containsOnly("ab", '') = false StringUtils.containsOnly("abab", 'abc') = true StringUtils.containsOnly("ab1", 'abc') = false StringUtils.containsOnly("abz", 'abc') = false Parameters: strthe String to check, may be null validan array of valid chars, may be null Returns: true if it only contains valid chars and is non-null public static boolean containsOnly(java.lang.String str, java.lang.String validChars) Checks if the String contains only certain characters. A null String will return false. A null valid character String will return false. An empty String ("") always returns true. StringUtils.containsOnly(null, *) = false StringUtils.containsOnly(*, null) = false StringUtils.containsOnly("", *) = true StringUtils.containsOnly("ab", "") = false StringUtils.containsOnly("abab", "abc") = true StringUtils.containsOnly("ab1", "abc") = false StringUtils.containsOnly("abz", "abc") = false Parameters: strthe String to check, may be null validCharsa String of valid chars, may be null Returns: true if it only contains valid chars and is non-null public static boolean containsNone(java.lang.String str, char[] invalidChars) Checks that the String does not contain certain characters. A null String will return true. A null invalid character array will return true. An empty String ("") always returns true. StringUtils.containsNone(null, *) = true StringUtils.containsNone(*, null) = true StringUtils.containsNone("", *) = true StringUtils.containsNone("ab", '') = true StringUtils.containsNone("abab", 'xyz') = true StringUtils.containsNone("ab1", 'xyz') = true StringUtils.containsNone("abz", 'xyz') = false Parameters: strthe String to check, may be null invalidCharsan array of invalid chars, may be null Returns: true if it contains none of the invalid chars, or is null public static boolean containsNone(java.lang.String str, java.lang.String invalidChars) Checks that the String does not contain certain characters. A null String will return true. A null invalid character array will return true. An empty String ("") always returns true. StringUtils.containsNone(null, *) = true StringUtils.containsNone(*, null) = true StringUtils.containsNone("", *) = true StringUtils.containsNone("ab", "") = true StringUtils.containsNone("abab", "xyz") = true StringUtils.containsNone("ab1", "xyz") = true StringUtils.containsNone("abz", "xyz") = false Parameters: strthe String to check, may be null invalidCharsa String of invalid chars, may be null Returns: TRue if it contains none of the invalid chars, or is null public static int indexOfAny(java.lang.String str, java.lang.String[] searchStrs) Find the first index of any of a set of potential substrings. A null String will return -1. A null or zero length search array will return -1. A null search array entry will be ignored, but a search array containing "" will return 0 if str is not null. This method uses String.indexOf(String). StringUtils.indexOfAny(null, *) = -1 StringUtils.indexOfAny(*, null) = -1 StringUtils.indexOfAny(*, []) = -1 StringUtils.indexOfAny("zzabyycdxx", ["ab","cd"]) = 2 StringUtils.indexOfAny("zzabyycdxx", ["cd","ab"]) = 2 StringUtils.indexOfAny("zzabyycdxx", ["mn","op"]) = -1 StringUtils.indexOfAny("zzabyycdxx", ["zab","aby"]) = 1 StringUtils.indexOfAny("zzabyycdxx", [""]) = 0 StringUtils.indexOfAny("", [""]) = 0 StringUtils.indexOfAny("", ["a"]) = -1 Parameters: strthe String to check, may be null searchStrsthe Strings to search for, may be null Returns: the first index of any of the searchStrs in str, -1 if no match public static int lastIndexOfAny(java.lang.String str, java.lang.String[] searchStrs) Find the latest index of any of a set of potential substrings. A null String will return -1. A null search array will return -1. A null or zero length search array entry will be ignored, but a search array containing "" will return the length of str if str is not null. This method uses String.indexOf(String). StringUtils.lastIndexOfAny(null, *) = -1 StringUtils.lastIndexOfAny(*, null) = -1 StringUtils.lastIndexOfAny(*, []) = -1 StringUtils.lastIndexOfAny(*, [null]) = -1 StringUtils.lastIndexOfAny("zzabyycdxx", ["ab","cd"]) = 6 StringUtils.lastIndexOfAny("zzabyycdxx", ["cd","ab"]) = 6 StringUtils.lastIndexOfAny("zzabyycdxx", ["mn","op"]) = -1 StringUtils.lastIndexOfAny("zzabyycdxx", ["mn","op"]) = -1 StringUtils.lastIndexOfAny("zzabyycdxx", ["mn",""]) = 10 Parameters: strthe String to check, may be null searchStrsthe Strings to search for, may be null Returns: the last index of any of the Strings, -1 if no match public static java.lang.String substring(java.lang.String str, int start) Gets a substring from the specified String avoiding exceptions. A negative start position can be used to start n characters from the end of the String. A null String will return null. An empty ("") String will return "". StringUtils.substring(null, *) = null StringUtils.substring("", *) = "" StringUtils.substring("abc", 0) = "abc" StringUtils.substring("abc", 2) = "c" StringUtils.substring("abc", 4) = "" StringUtils.substring("abc", -2) = "bc" StringUtils.substring("abc", -4) = "abc" Parameters: strthe String to get the substring from, may be null startthe position to start from, negative means count back from the end of the String by this many characters Returns: substring from start position, null if null String input public static java.lang.String substring(java.lang.String str, int start, int end) Gets a substring from the specified String avoiding exceptions. A negative start position can be used to start/end n characters from the end of the String. The returned substring starts with the character in the start position and ends before the end position. All postion counting is zero-basedi.e., to start at the beginning of the string, use start = 0. Negative start and end positions can be used to specify offsets relative to the end of the String. If start is not strictly to the left of end, "" is returned. StringUtils.substring(null, *, *) = null StringUtils.substring("", * , *) = ""; StringUtils.substring("abc", 0, 2) = "ab" StringUtils.substring("abc", 2, 0) = "" StringUtils.substring("abc", 2, 4) = "c" StringUtils.substring("abc", 4, 6) = "" StringUtils.substring("abc", 2, 2) = "" StringUtils.substring("abc", -2, -1) = "b" StringUtils.substring("abc", -4, 2) = "ab" Parameters: strthe String to get the substring from, may be null startthe position to start from, negative means count back from the end of the String by this many characters endthe position to end at (exclusive), negative means count back from the end of the String by this many characters Returns: substring from start position to end positon, null if null String input public static java.lang.String left(java.lang.String str, int len) Gets the leftmost len characters of a String. If len characters are not available, or the String is null, the String will be returned without an exception. An exception is thrown if len is negative. StringUtils.left(null, *) = null StringUtils.left(*, -ve) = "" StringUtils.left("", *) = "" StringUtils.left("abc", 0) = "" StringUtils.left("abc", 2) = "ab" StringUtils.left("abc", 4) = "abc" Parameters: strthe String to get the leftmost characters from, may be null lenthe length of the required String, must be zero or positive Returns: the leftmost characters, null if null String input public static java.lang.String right(java.lang.String str, int len) Gets the rightmost len characters of a String. If len characters are not available, or the String is null, the String will be returned without an an exception. An exception is thrown if len is negative. StringUtils.right(null, *) = null StringUtils.right(*, -ve) = "" StringUtils.right("", *) = "" StringUtils.right("abc", 0) = "" StringUtils.right("abc", 2) = "bc" StringUtils.right("abc", 4) = "abc" Parameters: strthe String to get the rightmost characters from, may be null lenthe length of the required String, must be zero or positive Returns: the rightmost characters, null if null String input public static java.lang.String mid(java.lang.String str, int pos, int len) Gets len characters from the middle of a String. If len characters are not available, the remainder of the String will be returned without an exception. If the String is null, null will be returned. An exception is thrown if len is negative. StringUtils.mid(null, *, *) = null StringUtils.mid(*, *, -ve) = "" StringUtils.mid("", 0, *) = "" StringUtils.mid("abc", 0, 2) = "ab" StringUtils.mid("abc", 0, 4) = "abc" StringUtils.mid("abc", 2, 4) = "c" StringUtils.mid("abc", 4, 2) = "" StringUtils.mid("abc", -2, 2) = "ab" Parameters: strthe String to get the characters from, may be null posthe position to start from, negative treated as zero lenthe length of the required String, must be zero or positive Returns: the middle characters, null if null String input
Gets the substring before the first occurence of a separator. The separator is not returned. A null string input will return null. An empty ("") string input will return the empty string. A null separator will return the input string. StringUtils.substringBefore(null, *) = null StringUtils.substringBefore("", *) = "" StringUtils.substringBefore("abc", "a") = "" StringUtils.substringBefore("abcba", "b") = "a" StringUtils.substringBefore("abc", "c") = "ab" StringUtils.substringBefore("abc", "d") = "abc" StringUtils.substringBefore("abc", "") = "" StringUtils.substringBefore("abc", null) = "abc" Parameters: strthe String to get a substring from, may be null separatorthe String to search for, may be null Returns: the substring before the first occurence of the separator, null if null String input
Gets the substring after the first occurence of a separator. The separator is not returned. A null string input will return null. An empty ("") string input will return the empty string. A null separator will return the empty string if the input string is not null. StringUtils.substringAfter(null, *) = null StringUtils.substringAfter("", *) = "" StringUtils.substringAfter(*, null) = "" StringUtils.substringAfter("abc", "a") = "bc" StringUtils.substringAfter("abcba", "b") = "cba" StringUtils.substringAfter("abc", "c") = "" StringUtils.substringAfter("abc", "d") = "" StringUtils.substringAfter("abc", "") = "abc" Parameters: strthe String to get a substring from, may be null separatorthe String to search for, may be null Returns: the substring after the first occurence of the separator, null if null String input
Gets the substring before the last occurence of a separator. The separator is not returned. A null string input will return null. An empty ("") string input will return the empty string. An empty or null separator will return the input string. StringUtils.substringBeforeLast(null, *) = null StringUtils.substringBeforeLast("", *) = "" StringUtils.substringBeforeLast("abcba", "b") = "abc" StringUtils.substringBeforeLast("abc", "c") = "ab" StringUtils.substringBeforeLast("a", "a") = "" StringUtils.substringBeforeLast("a", "z") = "a" StringUtils.substringBeforeLast("a", null) = "a" StringUtils.substringBeforeLast("a", "") = "a" Parameters: strthe String to get a substring from, may be null separatorthe String to search for, may be null Returns: the substring before the last occurence of the separator, null if null String input
Gets the substring after the last occurence of a separator. The separator is not returned. A null string input will return null. An empty ("") string input will return the empty string. An empty or null separator will return the empty string if the input string is not null. StringUtils.substringAfterLast(null, *) = null StringUtils.substringAfterLast("", *) = "" StringUtils.substringAfterLast(*, "") = "" StringUtils.substringAfterLast(*, null) = "" StringUtils.substringAfterLast("abc", "a") = "bc" StringUtils.substringAfterLast("abcba", "b") = "a" StringUtils.substringAfterLast("abc", "c") = "" StringUtils.substringAfterLast("a", "a") = "" StringUtils.substringAfterLast("a", "z") = "" Parameters: strthe String to get a substring from, may be null separatorthe String to search for, may be null Returns: the substring after the last occurence of the separator, null if null String input public static java.lang.String substringBetween(java.lang.String str, java.lang.String tag) Gets the String that is nested in between two instances of the same String. A null input String returns null. A null tag returns null. StringUtils.substringBetween(null, *) = null StringUtils.substringBetween("", "") = "" StringUtils.substringBetween("", "tag") = null StringUtils.substringBetween("tagabctag", null) = null StringUtils.substringBetween("tagabctag", "") = "" StringUtils.substringBetween("tagabctag", "tag") = "abc" Parameters: strthe String containing the substring, may be null tagthe String before and after the substring, may be null Returns: the substring, null if no match
Gets the String that is nested in between two Strings. Only the first match is returned. A null input String returns null. A null open/close returns null (no match). An empty ("") open/close returns an empty string. StringUtils.substringBetween(null, *, *) = null StringUtils.substringBetween("", "", "") = "" StringUtils.substringBetween("", "", "tag") = null StringUtils.substringBetween("", "tag", "tag") = null StringUtils.substringBetween("yabcz", null, null) = null StringUtils.substringBetween("yabcz", "", "") = "" StringUtils.substringBetween("yabcz", "y", "z") = "abc" StringUtils.substringBetween("yabczyabcz", "y", "z") = "abc" Parameters: strthe String containing the substring, may be null openthe String before the substring, may be null closethe String after the substring, may be null Returns: the substring, null if no match public static java.lang.String[] split(java.lang.String str) Splits the provided text into an array, using whitespace as the separator. Whitespace is defined by Character.isWhitespace(char). The separator is not included in the returned String array. Adjacent separators are treated as one separator. A null input String returns null. StringUtils.split(null) = null StringUtils.split("") = [] StringUtils.split("abc def") = ["abc", "def"] StringUtils.split("abc def") = ["abc", "def"] StringUtils.split(" abc ") = ["abc"] Parameters: strthe String to parse, may be null Returns: an array of parsed Strings, null if null String input public static java.lang.String[] split(java.lang.String str, char separatorChar) Splits the provided text into an array, separator specified. This is an alternative to using StringTokenizer. The separator is not included in the returned String array. Adjacent separators are treated as one separator. A null input String returns null. StringUtils.split(null, *) = null StringUtils.split("", *) = [] StringUtils.split("a.b.c", '.') = ["a", "b", "c"] StringUtils.split("a..b.c", '.') = ["a", "b", "c"] StringUtils.split("a:b:c", '.') = ["a:b:c"] StringUtils.split("a\tb\nc", null) = ["a", "b", "c"] StringUtils.split("a b c", ' ') = ["a", "b", "c"] Parameters: strthe String to parse, may be null separatorCharthe character used as the delimiter, null splits on whitespace Returns: an array of parsed Strings, null if null String input public static java.lang.String[] split(java.lang.String str, java.lang.String separatorChars) Splits the provided text into an array, separators specified. This is an alternative to using StringTokenizer. The separator is not included in the returned String array. Adjacent separators are treated as one separator. A null input String returns null. A null separatorChars splits on whitespace. StringUtils.split(null, *) = null StringUtils.split("", *) = [] StringUtils.split("abc def", null) = ["abc", "def"] StringUtils.split("abc def", " ") = ["abc", "def"] StringUtils.split("abc def", " ") = ["abc", "def"] StringUtils.split("ab:cd:ef", ":") = ["ab", "cd", "ef"] Parameters: strthe String to parse, may be null separatorCharsthe characters used as the delimiters, null splits on whitespace Returns: an array of parsed Strings, null if null String input
Splits the provided text into an array, separators specified. This is an alternative to using StringTokenizer. The separator is not included in the returned String array. Adjacent separators are treated as one separator. A null input String returns null. A null separatorChars splits on whitespace. StringUtils.split(null, *, *) = null StringUtils.split("", *, *) = [] StringUtils.split("ab de fg", null, 0) = ["ab", "cd", "ef"] StringUtils.split("ab de fg", null, 0) = ["ab", "cd", "ef"] StringUtils.split("ab:cd:ef", ":", 0) = ["ab", "cd", "ef"] StringUtils.split("ab:cd:ef", ":", 2) = ["ab", "cdef"] Parameters: strthe String to parse, may be null separatorCharsthe characters used as the delimiters, null splits on whitespace maxthe maximum number of elements to include in the array. A zero or negative value implies no limit Returns: an array of parsed Strings, null if null String input public static java.lang.String join(java.lang.Object[] array) Joins the elements of the provided array into a single String containing the provided list of elements. No separator is added to the joined String. Null objects or empty strings within the array are represented by empty strings. StringUtils.join(null) = null StringUtils.join([]) = "" StringUtils.join([null]) = "" StringUtils.join(["a", "b", "c"]) = "abc" StringUtils.join([null, "", "a"]) = "a" Parameters: arraythe array of values to join together, may be null Returns: the joined String, null if null array input public static java.lang.String join(java.lang.Object[] array, char separator) Joins the elements of the provided array into a single String containing the provided list of elements. No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings. StringUtils.join(null, *) = null StringUtils.join([], *) = "" StringUtils.join([null], *) = "" StringUtils.join(["a", "b", "c"], ';') = "a;b;c" StringUtils.join(["a", "b", "c"], null) = "abc" StringUtils.join([null, "", "a"], ';') = ";;a" Parameters: arraythe array of values to join together, may be null separatorthe separator character to use Returns: the joined String, null if null array input public static java.lang.String join(java.lang.Object[] array, java.lang.String separator) Joins the elements of the provided array into a single String containing the provided list of elements. No delimiter is added before or after the list. A null separator is the same as an empty String (""). Null objects or empty strings within the array are represented by empty strings. StringUtils.join(null, *) = null StringUtils.join([], *) = "" StringUtils.join([null], *) = "" StringUtils.join(["a", "b", "c"], "--") = "a--b--c" StringUtils.join(["a", "b", "c"], null) = "abc" StringUtils.join(["a", "b", "c"], "") = "abc" StringUtils.join([null, "", "a"], ',') = ",,a" Parameters: arraythe array of values to join together, may be null separatorthe separator character to use, null TReated as "" Returns: the joined String, null if null array input public static java.lang.String join(java.util.Iterator iterator, char separator) Joins the elements of the provided Iterator into a single String containing the provided elements. No delimiter is added before or after the list. Null objects or empty strings within the iteration are represented by empty strings. See the examples here: join(Object[],char). Parameters: iteratorthe Iterator of values to join together, may be null separatorthe separator character to use Returns: the joined String, null if null iterator input public static java.lang.String join(java.util.Iterator iterator, java.lang.String separator) Joins the elements of the provided Iterator into a single String containing the provided elements. No delimiter is added before or after the list. A null separator is the same as an empty String (""). See the examples here: join(Object[],String). Parameters: iteratorthe Iterator of values to join together, may be null separatorthe separator character to use, null treated as "" Returns: the joined String, null if null iterator input public static java.lang.String deleteWhitespace(java.lang.String str) Deletes all whitespaces from a String as defined by Character.isWhitespace(char). StringUtils.deleteWhitespace(null) = null StringUtils.deleteWhitespace("") = "" StringUtils.deleteWhitespace("abc") = "abc" StringUtils.deleteWhitespace(" ab c ") = "abc" Parameters: strthe String to delete whitespace from, may be null Returns: the String without whitespaces, null if null String input
Replaces a String with another String inside a larger String, once. A null reference passed to this method is a no-op. StringUtils.replaceOnce(null, *, *) = null StringUtils.replaceOnce("", *, *) = "" StringUtils.replaceOnce("aba", null, null) = "aba" StringUtils.replaceOnce("aba", null, null) = "aba" StringUtils.replaceOnce("aba", "a", null) = "aba" StringUtils.replaceOnce("aba", "a", "") = "aba" StringUtils.replaceOnce("aba", "a", "z") = "zba" Parameters: texttext to search and replace in, may be null replthe String to search for, may be null withthe String to replace with, may be null Returns: the text with any replacements processed, null if null String input See Also: replace(String text, String repl, String with, int max)
Replaces all occurances of a String within another String. A null reference passed to this method is a no-op. StringUtils.replace(null, *, *) = null StringUtils.replace("", *, *) = "" StringUtils.replace("aba", null, null) = "aba" StringUtils.replace("aba", null, null) = "aba" StringUtils.replace("aba", "a", null) = "aba" StringUtils.replace("aba", "a", "") = "aba" StringUtils.replace("aba", "a", "z") = "zbz" Parameters: texttext to search and replace in, may be null replthe String to search for, may be null withthe String to replace with, may be null Returns: the text with any replacements processed, null if null String input See Also: replace(String text, String repl, String with, int max)
Replaces a String with another String inside a larger String, for the first max values of the search String. A null reference passed to this method is a no-op. StringUtils.replace(null, *, *, *) = null StringUtils.replace("", *, *, *) = "" StringUtils.replace("abaa", null, null, 1) = "abaa" StringUtils.replace("abaa", null, null, 1) = "abaa" StringUtils.replace("abaa", "a", null, 1) = "abaa" StringUtils.replace("abaa", "a", "", 1) = "abaa" StringUtils.replace("abaa", "a", "z", 0) = "abaa" StringUtils.replace("abaa", "a", "z", 1) = "zbaa" StringUtils.replace("abaa", "a", "z", 2) = "zbza" StringUtils.replace("abaa", "a", "z", -1) = "zbzz" Parameters: texttext to search and replace in, may be null replthe String to search for, may be null withthe String to replace with, may be null maxmaximum number of values to replace, or -1 if no maximum Returns: the text with any replacements processed, null if null String input
Replaces all occurrences of a character in a String with another. This is a null-safe version of String.replace(char, char). A null string input returns null. An empty ("") string input returns an empty string. StringUtils.replaceChars(null, *, *) = null StringUtils.replaceChars("", *, *) = "" StringUtils.replaceChars("abcba", 'b', 'y') = "aycya" StringUtils.replaceChars("abcba", 'z', 'y') = "abcba" Parameters: strString to replace characters in, may be null searchCharthe character to search for, may be null replaceCharthe character to replace, may be null Returns: modified String, null if null String input
Replaces multiple characters in a String in one go. This method can also be used to delete characters. For example: replaceChars("hello", "ho", "jy") = jelly. A null string input returns null. An empty ("") string input returns an empty string. A null or empty set of search characters returns the input string. The length of the search characters should normally equal the length of the replace characters. If the search characters are longer, then the extra search characters are deleted. If the search characters are shorter, then the extra replace characters are ignored. StringUtils.replaceChars(null, *, *) = null StringUtils.replaceChars("", *, *) = "" StringUtils.replaceChars("abc", null, *) = "abc" StringUtils.replaceChars("abc", "", *) = "abc" StringUtils.replaceChars("abc", "b", null) = "ac" StringUtils.replaceChars("abc", "b", "") = "ac" StringUtils.replaceChars("abcba", "bc", "yz") = "ayzya" StringUtils.replaceChars("abcba", "bc", "y") = "ayya" StringUtils.replaceChars("abcba", "bc", "yzx") = "ayzya" Parameters: strString to replace characters in, may be null searchCharsa set of characters to search for, may be null replaceCharsa set of characters to replace, may be null Returns: modified String, null if null string input
Overlays part of a String with another String. A null string input returns null. A negative index is treated as zero. An index greater than the string length is treated as the string length. The start index is always the smaller of the two indices. StringUtils.overlay(null, *, *, *) = null StringUtils.overlay("", "abc", 0, 0) = "abc" StringUtils.overlay("abcdef", null, 2, 4) = "abef" StringUtils.overlay("abcdef", "", 2, 4) = "abef" StringUtils.overlay("abcdef", "", 4, 2) = "abef" StringUtils.overlay("abcdef", "zzzz", 2, 4) = "abzzzzef" StringUtils.overlay("abcdef", "zzzz", 4, 2) = "abzzzzef" StringUtils.overlay("abcdef", "zzzz", -1, 4) = "zzzzef" StringUtils.overlay("abcdef", "zzzz", 2, 8) = "abzzzz" StringUtils.overlay("abcdef", "zzzz", -2, -3) = "zzzzabcdef" StringUtils.overlay("abcdef", "zzzz", 8, 10) = "abcdefzzzz" Parameters: strthe String to do overlaying in, may be null overlaythe String to overlay, may be null startthe position to start overlaying at endthe position to stop overlaying before Returns: overlayed String, null if null String input public static java.lang.String chomp(java.lang.String str) Removes one newline from end of a String if it's there, otherwise leave it alone. A newline is "\n", "\r", or "\r\n". NOTE: This method changed in 2.0. It now more closely matches Perl chomp. StringUtils.chomp(null) = null StringUtils.chomp("") = "" StringUtils.chomp("abc \r") = "abc " StringUtils.chomp("abc\n") = "abc" StringUtils.chomp("abc\r\n") = "abc" StringUtils.chomp("abc\r\n\r\n") = "abc\r\n" StringUtils.chomp("abc\n\r") = "abc\n" StringUtils.chomp("abc\n\rabc") = "abc\n\rabc" StringUtils.chomp("\r") = "" StringUtils.chomp("\n") = "" StringUtils.chomp("\r\n") = "" Parameters: strthe String to chomp a newline from, may be null Returns: String without newline, null if null String input public static java.lang.String chomp(java.lang.String str, java.lang.String separator) Removes separator from the end of str if it's there, otherwise leave it alone. NOTE: This method changed in version 2.0. It now more closely matches Perl chomp. For the previous behavior, use substringBeforeLast(String, String). This method uses String.endsWith(String). StringUtils.chomp(null, *) = null StringUtils.chomp("", *) = "" StringUtils.chomp("foobar", "bar") = "foo" StringUtils.chomp("foobar", "baz") = "foobar" StringUtils.chomp("foo", "foo") = "" StringUtils.chomp("foo ", "foo") = "foo" StringUtils.chomp(" foo", "foo") = " " StringUtils.chomp("foo", "foooo") = "foo" StringUtils.chomp("foo", "") = "foo" StringUtils.chomp("foo", null) = "foo" Parameters: strthe String to chomp from, may be null separatorseparator String, may be null Returns: String without trailing separator, null if null String input public static java.lang.String chop(java.lang.String str) Remove the last character from a String. If the String ends in \r\n, then remove both of them. StringUtils.chop(null) = null StringUtils.chop("") = "" StringUtils.chop("abc \r") = "abc " StringUtils.chop("abc\n") = "abc" StringUtils.chop("abc\r\n") = "abc" StringUtils.chop("abc") = "ab" StringUtils.chop("abc\nabc") = "abc\nab" StringUtils.chop("a") = "" StringUtils.chop("\r") = "" StringUtils.chop("\n") = "" StringUtils.chop("\r\n") = "" Parameters: strthe String to chop last character from, may be null Returns: String without last character, null if null String input public static java.lang.String repeat(java.lang.String str, int repeat) Repeat a String repeat times to form a new String. StringUtils.repeat(null, 2) = null StringUtils.repeat("", 0) = "" StringUtils.repeat("", 2) = "" StringUtils.repeat("a", 3) = "aaa" StringUtils.repeat("ab", 2) = "abab" StringUtils.repeat("a", -2) = "" Parameters: strthe String to repeat, may be null repeatnumber of times to repeat str, negative treated as zero Returns: a new String consisting of the original String repeated, null if null String input public static java.lang.String rightPad(java.lang.String str, int size) Right pad a String with spaces (' '). The String is padded to the size of size. StringUtils.rightPad(null, *) = null StringUtils.rightPad("", 3) = " " StringUtils.rightPad("bat", 3) = "bat" StringUtils.rightPad("bat", 5) = "bat " StringUtils.rightPad("bat", 1) = "bat" StringUtils.rightPad("bat", -1) = "bat" Parameters: strthe String to pad out, may be null sizethe size to pad to Returns: right padded String or original String if no padding is necessary, null if null String input public static java.lang.String rightPad(java.lang.String str, int size, char padChar) Right pad a String with a specified character. The String is padded to the size of size. StringUtils.rightPad(null, *, *) = null StringUtils.rightPad("", 3, 'z') = "zzz" StringUtils.rightPad("bat", 3, 'z') = "bat" StringUtils.rightPad("bat", 5, 'z') = "batzz" StringUtils.rightPad("bat", 1, 'z') = "bat" StringUtils.rightPad("bat", -1, 'z') = "bat" Parameters: strthe String to pad out, may be null sizethe size to pad to padCharthe character to pad with Returns: right padded String or original String if no padding is necessary, null if null String input
Right pad a String with a specified String. The String is padded to the size of size. StringUtils.rightPad(null, *, *) = null StringUtils.rightPad("", 3, "z") = "zzz" StringUtils.rightPad("bat", 3, "yz") = "bat" StringUtils.rightPad("bat", 5, "yz") = "batyz" StringUtils.rightPad("bat", 8, "yz") = "batyzyzy" StringUtils.rightPad("bat", 1, "yz") = "bat" StringUtils.rightPad("bat", -1, "yz") = "bat" StringUtils.rightPad("bat", 5, null) = "bat " StringUtils.rightPad("bat", 5, "") = "bat " Parameters: strthe String to pad out, may be null sizethe size to pad to padStrthe String to pad with, null or empty treated as single space Returns: right padded String or original String if no padding is necessary, null if null String input public static java.lang.String leftPad(java.lang.String str, int size) Left pad a String with spaces (' '). The String is padded to the size of size. StringUtils.leftPad(null, *) = null StringUtils.leftPad("", 3) = " " StringUtils.leftPad("bat", 3) = "bat" StringUtils.leftPad("bat", 5) = " bat" StringUtils.leftPad("bat", 1) = "bat" StringUtils.leftPad("bat", -1) = "bat" Parameters: strthe String to pad out, may be null sizethe size to pad to Returns: left padded String or original String if no padding is necessary, null if null String input public static java.lang.String leftPad(java.lang.String str, int size, char padChar) Left pad a String with a specified character. Pad to a size of size. StringUtils.leftPad(null, *, *) = null StringUtils.leftPad("", 3, 'z') = "zzz" StringUtils.leftPad("bat", 3, 'z') = "bat" StringUtils.leftPad("bat", 5, 'z') = "zzbat" StringUtils.leftPad("bat", 1, 'z') = "bat" StringUtils.leftPad("bat", -1, 'z') = "bat" Parameters: strthe String to pad out, may be null sizethe size to pad to padCharthe character to pad with Returns: left padded String or original String if no padding is necessary, null if null String input
Left pad a String with a specified String. Pad to a size of size. StringUtils.leftPad(null, *, *) = null StringUtils.leftPad("", 3, "z") = "zzz" StringUtils.leftPad("bat", 3, "yz") = "bat" StringUtils.leftPad("bat", 5, "yz") = "yzbat" StringUtils.leftPad("bat", 8, "yz") = "yzyzybat" StringUtils.leftPad("bat", 1, "yz") = "bat" StringUtils.leftPad("bat", -1, "yz") = "bat" StringUtils.leftPad("bat", 5, null) = " bat" StringUtils.leftPad("bat", 5, "") = " bat" Parameters: strthe String to pad out, may be null sizethe size to pad to padStrthe String to pad with, null or empty treated as single space Returns: left padded String or original String if no padding is necessary, null if null String input public static java.lang.String center(java.lang.String str, int size) Centers a String in a larger String of size size using the space character (' '). If the size is less than the String length, the String is returned. A null String returns null. A negative size is treated as zero. Equivalent to center(str, size, ""). StringUtils.center(null, *) = null StringUtils.center("", 4) = " " StringUtils.center("ab", -1) = "ab" StringUtils.center("ab", 4) = " ab " StringUtils.center("abcd", 2) = "abcd" StringUtils.center("a", 4) = " a " Parameters: strthe String to center, may be null sizethe int size of new String, negative treated as zero Returns: centered String, null if null String input public static java.lang.String center(java.lang.String str, int size, char padChar) Centers a String in a larger String of size size. Uses a supplied character as the value to pad the String with. If the size is less than the String length, the String is returned. A null String returns null. A negative size is treated as zero. StringUtils.center(null, *, *) = null StringUtils.center("", 4, ' ') = " " StringUtils.center("ab", -1, ' ') = "ab" StringUtils.center("ab", 4, ' ') = " ab" StringUtils.center("abcd", 2, ' ') = "abcd" StringUtils.center("a", 4, ' ') = " a " StringUtils.center("a", 4, 'y') = "yayy" Parameters: strthe String to center, may be null sizethe int size of new String, negative treated as zero padCharthe character to pad the new String with Returns: centered String, null if null String input public static java.lang.String center(java.lang.String str, int size, java.lang.String padStr) Centers a String in a larger String of size size. Uses a supplied String as the value to pad the String with. If the size is less than the String length, the String is returned. A null String returns null. A negative size is treated as zero. StringUtils.center(null, *, *) = null StringUtils.center("", 4, " ") = " " StringUtils.center("ab", -1, " ") = "ab" StringUtils.center("ab", 4, " ") = " ab" StringUtils.center("abcd", 2, " ") = "abcd" StringUtils.center("a", 4, " ") = " a " StringUtils.center("a", 4, "yz") = "yayz" StringUtils.center("abc", 7, null) = " abc " StringUtils.center("abc", 7, "") = " abc " Parameters: strthe String to center, may be null sizethe int size of new String, negative treated as zero padStrthe String to pad the new String with, must not be null or empty Returns: centered String, null if null String input Throws: java.lang.IllegalArgumentExceptionif padStr is null or empty public static java.lang.String upperCase(java.lang.String str) Converts a String to upper case as per String.toUpperCase(). A null input String returns null. StringUtils.upperCase(null) = null StringUtils.upperCase("") = "" StringUtils.upperCase("aBc") = "ABC" Parameters: strthe String to upper case, may be null Returns: the upper cased String, null if null String input public static java.lang.String lowerCase(java.lang.String str) Converts a String to lower case as per String.toLowerCase(). A null input String returns null. StringUtils.lowerCase(null) = null StringUtils.lowerCase("") = "" StringUtils.lowerCase("aBc") = "abc" Parameters: strthe String to lower case, may be null Returns: the lower cased String, null if null String input public static java.lang.String capitalize(java.lang.String str) Capitalizes a String changing the first letter to title case as per Character.toTitleCase(char). No other letters are changed. For a word based algorithm, see WordUtils.capitalize(String). A null input String returns null. StringUtils.capitalize(null) = null StringUtils.capitalize("") = "" StringUtils.capitalize("cat") = "Cat" StringUtils.capitalize("cAt") = "CAt" Parameters: strthe String to capitalize, may be null Returns: the capitalized String, null if null String input See Also: WordUtils.capitalize(String), uncapitalize(String) public static java.lang.String uncapitalize(java.lang.String str) Uncapitalizes a String changing the first letter to title case as per Character.toLowerCase(char). No other letters are changed. For a word based algorithm, see WordUtils.uncapitalize(String). A null input String returns null. StringUtils.uncapitalize(null) = null StringUtils.uncapitalize("") = "" StringUtils.uncapitalize("Cat") = "cat" StringUtils.uncapitalize("CAT") = "cAT" Parameters: strthe String to uncapitalize, may be null Returns: the uncapitalized String, null if null String input See Also: WordUtils.uncapitalize(String), capitalize(String) public static java.lang.String swapCase(java.lang.String str) Swaps the case of a String changing upper and title case to lower case, and lower case to upper case.
For a word based algorithm, see WordUtils.swapCase(String). A null input String returns null. StringUtils.swapCase(null) = null StringUtils.swapCase("") = "" StringUtils.swapCase("The dog has a BONE") = "tHE DOG HAS A bone" 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 functionality is available in WordUtils. Parameters: strthe String to swap case, may be null Returns: the changed String, null if null String input public static int countMatches(java.lang.String str, java.lang.String sub) Counts how many times the substring appears in the larger String. A null or empty ("") String input returns 0. StringUtils.countMatches(null, *) = 0 StringUtils.countMatches("", *) = 0 StringUtils.countMatches("abba", null) = 0 StringUtils.countMatches("abba", "") = 0 StringUtils.countMatches("abba", "a") = 2 StringUtils.countMatches("abba", "ab") = 1 StringUtils.countMatches("abba", "xxx") = 0 Parameters: strthe String to check, may be null subthe substring to count, may be null Returns: the number of occurences, 0 if either String is null public static boolean isAlpha(java.lang.String str) Checks if the String contains only unicode letters. null will return false. An empty String ("") will return true. StringUtils.isAlpha(null) = false StringUtils.isAlpha("") = true StringUtils.isAlpha(" ") = false StringUtils.isAlpha("abc") = true StringUtils.isAlpha("ab2c") = false StringUtils.isAlpha("ab-c") = false Parameters: strthe String to check, may be null Returns: true if only contains letters, and is non-null public static boolean isAlphaSpace(java.lang.String str) Checks if the String contains only unicode letters and space (' '). null will return false An empty String ("") will return true. StringUtils.isAlphaSpace(null) = false StringUtils.isAlphaSpace("") = true StringUtils.isAlphaSpace(" ") = true StringUtils.isAlphaSpace("abc") = true StringUtils.isAlphaSpace("ab c") = true StringUtils.isAlphaSpace("ab2c") = false StringUtils.isAlphaSpace("ab-c") = false Parameters: strthe String to check, may be null Returns: true if only contains letters and space, and is non-null public static boolean isAlphanumeric(java.lang.String str) Checks if the String contains only unicode letters or digits. null will return false. An empty String ("") will return true. StringUtils.isAlphanumeric(null) = false StringUtils.isAlphanumeric("") = true StringUtils.isAlphanumeric(" ") = false StringUtils.isAlphanumeric("abc") = true StringUtils.isAlphanumeric("ab c") = false StringUtils.isAlphanumeric("ab2c") = true StringUtils.isAlphanumeric("ab-c") = false Parameters: strthe String to check, may be null Returns: true if only contains letters or digits, and is non-null public static boolean isAlphanumericSpace(java.lang.String str) Checks if the String contains only unicode letters, digits or space (' '). null will return false. An empty String (" ") will return true. StringUtils.isAlphanumeric(null) = false StringUtils.isAlphanumeric("") = true StringUtils.isAlphanumeric(" ") = true StringUtils.isAlphanumeric("abc") = true StringUtils.isAlphanumeric("ab c") = true StringUtils.isAlphanumeric("ab2c") = true StringUtils.isAlphanumeric("ab-c") = false Parameters: strthe String to check, may be null Returns: TRue if only contains letters, digits or space, and is non-null public static boolean isNumeric(java.lang.String str) Checks if the String contains only unicode digits. A decimal point is not a unicode digit and returns false. null will return false. An empty String ("") will return true. StringUtils.isNumeric(null) = false StringUtils.isNumeric("") = true StringUtils.isNumeric(" ") = false StringUtils.isNumeric("123") = true StringUtils.isNumeric("12 3") = false StringUtils.isNumeric("ab2c") = false StringUtils.isNumeric("12-3") = false StringUtils.isNumeric("12.3") = false Parameters: strthe String to check, may be null Returns: TRue if only contains digits, and is non-null public static boolean isNumericSpace(java.lang.String str) Checks if the String contains only unicode digits or space (' '). A decimal point is not a unicode digit and returns false. null will return false. An empty String (" ") will return true. StringUtils.isNumeric(null) = false StringUtils.isNumeric("") = true StringUtils.isNumeric(" ") = true StringUtils.isNumeric("123") = true StringUtils.isNumeric("12 3") = true StringUtils.isNumeric("ab2c") = false StringUtils.isNumeric("12-3") = false StringUtils.isNumeric("12.3") = false Parameters: strthe String to check, may be null Returns: true if only contains digits or space, and is non-null public static boolean isWhitespace(java.lang.String str) Checks if the String contains only whitespace. null will return false. An empty String ("") will return true. StringUtils.isWhitespace(null) = false StringUtils.isWhitespace("") = true StringUtils.isWhitespace(" ") = true StringUtils.isWhitespace("abc") = false StringUtils.isWhitespace("ab2c") = false StringUtils.isWhitespace("ab-c") = false Parameters: strthe String to check, may be null Returns: true if only contains whitespace, and is non-null public static java.lang.String defaultString(java.lang.String str) Returns either the passed in String, or if the String is null, an empty String (""). StringUtils.defaultString(null) = "" StringUtils.defaultString("") = "" StringUtils.defaultString("bat") = "bat" Parameters: strthe String to check, may be null Returns: the passed in String, or the empty String if it was null See Also: ObjectUtils.toString(Object), String.valueOf(Object)
Returns either the passed in String, or if the String is null, an empty String (""). StringUtils.defaultString(null, "null") = "null" StringUtils.defaultString("", "null") = "" StringUtils.defaultString("bat", "null") = "bat" Parameters: strthe String to check, may be null defaultStrthe default String to return if the input is null, may be null Returns: the passed in String, or the default if it was null See Also: ObjectUtils.toString(Object,String), String.valueOf(Object) public static java.lang.String reverse(java.lang.String str) Reverses a String as per StringBuffer.reverse(). null String returns null. StringUtils.reverse(null) = null StringUtils.reverse("") = "" StringUtils.reverse("bat") = "tab" Parameters: strthe String to reverse, may be null Returns: the reversed String, null if null String input public static java.lang.String reverseDelimited(java.lang.String str, char separatorChar) Reverses a String that is delimited by a specific character. The Strings between the delimiters are not reversed. Thus java.lang.String becomes String.lang.java (if the delimiter is '.'). StringUtils.reverseDelimited(null, *) = null StringUtils.reverseDelimited("", *) = "" StringUtils.reverseDelimited("a.b.c", 'x') = "a.b.c" StringUtils.reverseDelimited("a.b.c", ".") = "c.b.a" Parameters: strthe String to reverse, may be null separatorCharthe separator character to use Returns: the reversed String, null if null String input public static java.lang.String abbreviate(java.lang.String str, int maxWidth) Abbreviates a String using ellipses. This will turn "Now is the time for all good men" into "Now is the time for. . . " Specifically:
StringUtils.abbreviate(null, *) = null StringUtils.abbreviate("", 4) = "" StringUtils.abbreviate("abcdefg", 6) = "abc..." StringUtils.abbreviate("abcdefg", 7) = "abcdefg" StringUtils.abbreviate("abcdefg", 8) = "abcdefg" StringUtils.abbreviate("abcdefg", 4) = "a..." StringUtils.abbreviate("abcdefg", 3) = IllegalArgumentException Parameters: strthe String to check, may be null maxWidthmaximum length of result String, must be at least 4 Returns: abbreviated String, null if null String input Throws: java.lang.IllegalArgumentExceptionif the width is too small public static java.lang.String abbreviate(java.lang.String str, int offset, int maxWidth) Abbreviates a String using ellipses. This will turn "Now is the time for all good men" into ". . . is the time for . . ." Works like abbreviate(String, int), but allows you to specify a "left edge" offset. Note that this left edge is not necessarily going to be the leftmost character in the result, or the first character following the ellipses, but it will appear somewhere in the result. In no case will it return a String of length greater than maxWidth. StringUtils.abbreviate(null, *, *) = null StringUtils.abbreviate("", 0, 4) = "" StringUtils.abbreviate("abcdefghijklmno", -1, 10) = "abcdefg..." StringUtils.abbreviate("abcdefghijklmno", 0, 10) = "abcdefg..." StringUtils.abbreviate("abcdefghijklmno", 1, 10) = "abcdefg..." StringUtils.abbreviate("abcdefghijklmno", 4, 10) = "abcdefg..." StringUtils.abbreviate("abcdefghijklmno", 5, 10) = "...fghi..." StringUtils.abbreviate("abcdefghijklmno", 6, 10) = "...ghij..." StringUtils.abbreviate("abcdefghijklmno", 8, 10) = "...ijklmno" StringUtils.abbreviate("abcdefghijklmno", 10, 10) = "...ijklmno" StringUtils.abbreviate("abcdefghijklmno", 12, 10) = "...ijklmno" StringUtils.abbreviate("abcdefghij", 0, 3) = IllegalArgumentException StringUtils.abbreviate("abcdefghij", 5, 6) = IllegalArgumentException Parameters: strthe String to check, may be null offsetleft edge of source String maxWidthmaximum length of result String, must be at least 4 Returns: abbreviated String, null if null String input Throws: java.lang.IllegalArgumentExceptionif the width is too small public static java.lang.String difference(java.lang.String str1, java.lang.String str2) Compares two Strings, and returns the portion where they differ. (More precisely, return the remainder of the second String, starting from where it's different from the first.) For example, difference("i am a machine", "i am a robot") -> "robot". StringUtils.difference(null, null) = null StringUtils.difference("", "") = "" StringUtils.difference("", "abc") = "abc" StringUtils.difference("abc", "") = "" StringUtils.difference("abc", "abc") = "" StringUtils.difference("ab", "abxyz") = "xyz" StringUtils.difference("abcde", "abxyz") = "xyz" StringUtils.difference("abcde", "xyz") = "xyz" Parameters: str1the first String, may be null str2the second String, may be null Returns: the portion of str2 where it differs from str1; returns the empty String if they are equal public static int indexOfDifference(java.lang.String str1, java.lang.String str2) Compares two Strings, and returns the index at which the Strings begin to differ. For example, indexOfDifference("i am a machine", "i am a robot") -> 7 StringUtils.indexOfDifference(null, null) = -1 StringUtils.indexOfDifference("", "") = -1 StringUtils.indexOfDifference("", "abc") = 0 StringUtils.indexOfDifference("abc", "") = 0 StringUtils.indexOfDifference("abc", "abc") = -1 StringUtils.indexOfDifference("ab", "abxyz") = 2 StringUtils.indexOfDifference("abcde", "abxyz") = 2 StringUtils.indexOfDifference("abcde", "xyz") = 0 Parameters: str1the first String, may be null str2the second String, may be null Returns: the index where str2 and str1 begin to differ; -1 if they are equal public static int getLevenshteinDistance(java.lang.String s, java.lang.String t) Find the Levenshtein distance between two Strings. This is the number of changes needed to change one String into another, where each change is a single character modification (deletion, insertion or substitution). This implementation of the Levenshtein distance algorithm is from http://www.merriampark.com/ld.htm StringUtils.getLevenshteinDistance(null, *) = IllegalArgumentException StringUtils.getLevenshteinDistance(*, null) = IllegalArgumentException StringUtils.getLevenshteinDistance("","") = 0 StringUtils.getLevenshteinDistance("","a") = 1 StringUtils.getLevenshteinDistance("aaapppp", "") = 7 StringUtils.getLevenshteinDistance("frog", "fog") = 1 StringUtils.getLevenshteinDistance("fly", "ant") = 3 StringUtils.getLevenshteinDistance("elephant", "hippo") = 7 StringUtils.getLevenshteinDistance("hippo", "elephant") = 7 StringUtils.getLevenshteinDistance("hippo", "zzzzzzzz") = 8 StringUtils.getLevenshteinDistance("hello", "hallo") = 1 Parameters: sthe first String, must not be null tthe second String, must not be null Returns: result distance Throws: java.lang.IllegalArgumentExceptionif either String input null |
|