Package org.apache.shiro.lang.util

Class StringUtils

java.lang.Object

org.apache.shiro.lang.util.StringUtils

public final class StringUtils
extends Object

Simple utility class for String operations useful across the framework.

Some methods in this class were copied from the Spring Framework so we didn't have to re-invent the wheel, and in these cases, we have retained all license, copyright and author information.

Since:

0.9

Field Summary

Fields

Modifier and Type	Field	Description
static final char	DEFAULT_DELIMITER_CHAR	Constant representing the default delimiter character (comma), equal to ','
static final char	DEFAULT_QUOTE_CHAR	Constant representing the default quote character (double quote), equal to '"'
static final String	EMPTY_STRING	Constant representing the empty string, equal to ""

Method Summary

Modifier and Type	Method	Description
static String	clean(String in)	Returns a 'cleaned' representation of the specified argument.
static boolean	hasLength(String str)	Check that the given String is neither null nor of length 0.
static boolean	hasText(String str)	Check whether the given String has actual text.
static String	join(Iterator<?> iterator, String separator)	Joins the elements of the provided Iterator into a single String containing the provided elements.
static String[]	split(String line)	Splits a string using the DEFAULT_DELIMITER_CHAR (which is ',').
static String[]	split(String line, char delimiter)
static String[]	split(String line, char delimiter, char quoteChar)
static String[]	split(String line, char delimiter, char beginQuoteChar, char endQuoteChar)
static String[]	split(String aLine, char delimiter, char beginQuoteChar, char endQuoteChar, boolean retainQuotes, boolean trimTokens)	Splits the specified delimited String into tokens, supporting quoted tokens so that quoted strings themselves won't be tokenized.
static String[]	splitKeyValue(String aLine)
static Set<String>	splitToSet(String delimited, String separator)	Splits the delimited string (delimited by the specified separator character) and returns the delimited values as a Set.
static boolean	startsWithIgnoreCase(String str, String prefix)	Test if the given String starts with the specified prefix, ignoring upper/lower case.
static String	toDelimitedString(Object[] array, String delimiter)	Returns the array's contents as a string, with each element delimited by the specified delimiter argument.
static String	toDelimitedString(Collection c, String delimiter)	Returns the collection's contents as a string, with each element delimited by the specified delimiter argument.
static String[]	tokenizeToStringArray(String str, String delimiters)	Tokenize the given String into a String array via a StringTokenizer.
static String[]	tokenizeToStringArray(String str, String delimiters, boolean trimTokens, boolean ignoreEmptyTokens)	Tokenize the given String into a String array via a StringTokenizer.
static String	toString(Object[] array)	Returns the specified array as a comma-delimited (',') string.
static String[]	toStringArray(Collection collection)	Copy the given Collection into a String array.
static String	uppercaseFirstChar(String in)	Returns the input argument, but ensures the first character is capitalized (if possible).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

EMPTY_STRING

public static final String EMPTY_STRING

Constant representing the empty string, equal to ""

See Also:

• Constant Field Values

DEFAULT_DELIMITER_CHAR

public static final char DEFAULT_DELIMITER_CHAR

Constant representing the default delimiter character (comma), equal to ','

See Also:

• Constant Field Values

DEFAULT_QUOTE_CHAR

public static final char DEFAULT_QUOTE_CHAR

Constant representing the default quote character (double quote), equal to '"'

See Also:

• Constant Field Values

Method Details

hasText

public static boolean hasText(String str)

Check whether the given String has actual text. More specifically, returns true if the string not null, its length is greater than 0, and it contains at least one non-whitespace character.

StringUtils.hasText(null) == false
StringUtils.hasText("") == false
StringUtils.hasText(" ") == false
StringUtils.hasText("12345") == true
StringUtils.hasText(" 12345 ") == true

Copied from the Spring Framework while retaining all license, copyright and author information.

Parameters:

str - the String to check (may be null)

Returns:

true if the String is not null, its length is greater than 0, and it does not contain whitespace only

See Also:

• Character.isWhitespace(char)

hasLength

public static boolean hasLength(String str)

Check that the given String is neither null nor of length 0. Note: Will return true for a String that purely consists of whitespace.

StringUtils.hasLength(null) == false
StringUtils.hasLength("") == false
StringUtils.hasLength(" ") == true
StringUtils.hasLength("Hello") == true

Copied from the Spring Framework while retaining all license, copyright and author information.

Parameters:

str - the String to check (may be null)

Returns:

true if the String is not null and has length

See Also:

• hasText(String)

startsWithIgnoreCase

public static boolean startsWithIgnoreCase(String str,
 String prefix)

Test if the given String starts with the specified prefix, ignoring upper/lower case.

Copied from the Spring Framework while retaining all license, copyright and author information.

Parameters:

str - the String to check

prefix - the prefix to look for

Returns:

true starts with the specified prefix (ignoring case), false if it does not.

See Also:

• String.startsWith(java.lang.String, int)

clean

public static String clean(String in)

Returns a 'cleaned' representation of the specified argument. 'Cleaned' is defined as the following:

1. If the specified String is null, return null
2. If not null, trim() it.
3. If the trimmed string is equal to the empty String (i.e. ""), return null
4. If the trimmed string is not the empty string, return the trimmed version
.

Therefore this method always ensures that any given string has trimmed text, and if it doesn't, null is returned.

Parameters:

in - the input String to clean.

Returns:

a populated-but-trimmed String or null otherwise

toString

public static String toString(Object[] array)

Returns the specified array as a comma-delimited (',') string.

Parameters:

array - the array whose contents will be converted to a string.

Returns:

the array's contents as a comma-delimited (',') string.

Since:

1.0

toDelimitedString

public static String toDelimitedString(Object[] array,
 String delimiter)

Returns the array's contents as a string, with each element delimited by the specified delimiter argument. Useful for toString() implementations and log messages.

Parameters:

array - the array whose contents will be converted to a string

delimiter - the delimiter to use between each element

Returns:

a single string, delimited by the specified delimiter.

Since:

1.0

toDelimitedString

public static String toDelimitedString(Collection c,
 String delimiter)

Returns the collection's contents as a string, with each element delimited by the specified delimiter argument. Useful for toString() implementations and log messages.

Parameters:

c - the collection whose contents will be converted to a string

delimiter - the delimiter to use between each element

Returns:

a single string, delimited by the specified delimiter.

Since:

1.2

tokenizeToStringArray

public static String[] tokenizeToStringArray(String str,
 String delimiters)

Tokenize the given String into a String array via a StringTokenizer. Trims tokens and omits empty tokens.

The given delimiters string is supposed to consist of any number of delimiter characters. Each of those characters can be used to separate tokens. A delimiter is always a single character; for multi-character delimiters, consider using delimitedListToStringArray

Copied from the Spring Framework while retaining all license, copyright and author information.

Parameters:

str - the String to tokenize

delimiters - the delimiter characters, assembled as String (each of those characters is individually considered as delimiter).

Returns:

an array of the tokens

See Also:

• StringTokenizer
• String.trim()

tokenizeToStringArray

public static String[] tokenizeToStringArray(String str,
 String delimiters,
 boolean trimTokens,
 boolean ignoreEmptyTokens)

Tokenize the given String into a String array via a StringTokenizer.

The given delimiters string is supposed to consist of any number of delimiter characters. Each of those characters can be used to separate tokens. A delimiter is always a single character; for multi-character delimiters, consider using delimitedListToStringArray

Copied from the Spring Framework while retaining all license, copyright and author information.

Parameters:

str - the String to tokenize

delimiters - the delimiter characters, assembled as String (each of those characters is individually considered as delimiter)

trimTokens - trim the tokens via String's trim

ignoreEmptyTokens - omit empty tokens from the result array (only applies to tokens that are empty after trimming; StringTokenizer will not consider subsequent delimiters as token in the first place).

Returns:

an array of the tokens (null if the input String was null)

See Also:

• StringTokenizer
• String.trim()

toStringArray

public static String[] toStringArray(Collection collection)

Copy the given Collection into a String array. The Collection must contain String elements only.

Copied from the Spring Framework while retaining all license, copyright and author information.

Parameters:

collection - the Collection to copy

Returns:

the String array (null if the passed-in Collection was null)

splitKeyValue

public static String[] splitKeyValue(String aLine)
                              throws ParseException

Throws:

ParseException

split

public static String[] split(String line)

Splits a string using the DEFAULT_DELIMITER_CHAR (which is ','). This method also recognizes quoting using the DEFAULT_QUOTE_CHAR (which is '\"'), but does not retain them.

This is equivalent of calling split(String, char, char, char, boolean, boolean) with line, DEFAULT_DELIMITER_CHAR, DEFAULT_QUOTE_CHAR, DEFAULT_QUOTE_CHAR, false, true.

Parameters:

line - the line to split using the DEFAULT_DELIMITER_CHAR.

Returns:

the split line, split tokens do not contain quotes and are trimmed.

See Also:

• split(String, char, char, char, boolean, boolean)

split

public static String[] split(String line,
 char delimiter)

split

public static String[] split(String line,
 char delimiter,
 char quoteChar)

split

public static String[] split(String line,
 char delimiter,
 char beginQuoteChar,
 char endQuoteChar)

split

public static String[] split(String aLine,
 char delimiter,
 char beginQuoteChar,
 char endQuoteChar,
 boolean retainQuotes,
 boolean trimTokens)

Splits the specified delimited String into tokens, supporting quoted tokens so that quoted strings themselves won't be tokenized.

This method's implementation is very loosely based (with significant modifications) on Glen Smith's open-source CSVReader.java file.

That file is Apache 2.0 licensed as well, making Glen's code a great starting point for us to modify to our needs.

Parameters:

aLine - the String to parse

delimiter - the delimiter by which the line argument is to be split

beginQuoteChar - the character signifying the start of quoted text (so the quoted text will not be split)

endQuoteChar - the character signifying the end of quoted text

retainQuotes - if the quotes themselves should be retained when constructing the corresponding token

trimTokens - if leading and trailing whitespace should be trimmed from discovered tokens.

Returns:

the tokens discovered from parsing the given delimited line.

join

public static String join(Iterator<?> iterator,
 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 ("").

Copied from Commons Lang, version 3 (r1138702).

Parameters:

iterator - the Iterator of values to join together, may be null

separator - the separator character to use, null treated as ""

Returns:

the joined String, null if null iterator input

Since:

1.2

splitToSet

public static Set<String> splitToSet(String delimited,
 String separator)

Splits the delimited string (delimited by the specified separator character) and returns the delimited values as a Set.

If either argument is null, this method returns null.

Parameters:

delimited - the string to split

separator - the character that delineates individual tokens to split

Returns:

the delimited values as a Set.

Since:

1.2

uppercaseFirstChar

public static String uppercaseFirstChar(String in)

Returns the input argument, but ensures the first character is capitalized (if possible).

Parameters:

in - the string to uppercase the first character.

Returns:

the input argument, but with the first character capitalized (if possible).

Since:

1.2