net.sf.mmm.util.lang.api

Interface StringUtil

All Known Implementing Classes:

StringUtilImpl

@ComponentSpecification
public interface StringUtil

This is the interface for a collection of utility functions that help with String handling and manipulation.

Since:

1.0.2

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

StringUtilImpl.getInstance(), UnicodeUtil

Field Summary

Fields

Modifier and Type	Field and Description
static char[]	EMPTY_CHAR_ARRAY An empty char array.
static String[]	EMPTY_STRING_ARRAY An empty String array.
static String	FALSE a string representing the boolean value false
static String	LINE_SEPARATOR The platform-specific line-separator string.
static String	LINE_SEPARATOR_CR The line-separator with a single carriage-return.
static String	LINE_SEPARATOR_CRLF The Windows line-separator (carriage-return line-feed).
static String	LINE_SEPARATOR_LF The Unix line-separator (line-feed).
static String	LINE_SEPARATOR_LFCR The Mac line-separator (line-feed carriage-return).
static String	NULL a string representing the undefined value null.
static String	SYSTEM_PROPERTY_LINE_SEPARATOR The system property name for LINE_SEPARATOR.
static String	TRUE a string representing the boolean value true

Method Summary

Modifier and Type	Method and Description
String	fromCamlCase(String string, char separator) This method converts the given string from caml-case syntax to lower-case using the given separator as word-boundary.
List<String>	fromSeparatedString(CharSequence separatedString, String separator, StringSyntax syntax) This method is like fromSeparatedString(CharSequence, String, StringSyntax, Collection, ValueConverter) but expects elements of the type String that do not need additional custom conversion.
<E> void	fromSeparatedString(CharSequence separatedString, String separator, StringSyntax syntax, Collection<E> collection, ValueConverter<? super String,? super E> converter, Class<E> type) This method parses the given separatedString that contains elements separated with separator and the given syntax and adds these elements to the given collection.
<E> void	fromSeparatedString(CharSequence separatedString, String separator, StringSyntax syntax, Collection<E> collection, ValueConverter<String,E> converter) This method parses the given separatedString that contains elements separated with separator and the given syntax and adds these elements to the given collection.
void	fromSeparatedString(CharSequence separatedString, String separator, StringSyntax syntax, Collection<String> collection) This method is like fromSeparatedString(CharSequence, String, StringSyntax, Collection, ValueConverter) but expects elements of the type String that do not need additional custom conversion.
String	getLineSeparator() The platform-specific line-separator string.
boolean	isAllLowerCase(String string) Determines if all characters of the given string are in lower case .
boolean	isAllUpperCase(String string) Determines if all characters of the given string are in upper case .
boolean	isEmpty(String string) This method determines if the given string contains no information.
boolean	isEmpty(String string, boolean trim) This method determines if the given string is empty.
boolean	isSubstring(char[] string, String substring, int offset) This method checks if the given string contains the given substring at the given offset.
boolean	isSubstring(String string, String substring, int offset) This method checks if the given string contains the given substring at the given offset.
String	padNumber(long number, int digits) This method formats a positive number to a string with at least the given number of digits padding it with leading zeros.
String	padNumber(long number, int digits, int radix) This method formats a positive number to a string using the given radix with at least the given number of digits padding it with leading zeros.
Boolean	parseBoolean(String booleanValue) This method parses a boolean value given as string.
void	replace(char[] string, char oldChar, char newChar) This method replaces all occurrences of oldChar in the char-array given by string with newChar.
String	replace(String string, String match, String replace) This method replaces all occurrences of the string match with the string replace in the given string.
String	replaceSuffixWithCase(String string, int suffixLength, String newSuffixLowerCase) This method delegates to replaceSuffixWithCase(String, int, String, Locale) using Locale.ENGLISH.
String	replaceSuffixWithCase(String string, int suffixLength, String newSuffixLowerCase, Locale locale) This method replaces the last suffixLength number of characters from string with the lower-case string newSuffixLowerCase with respect to the original case of the given string.
String	toCamlCase(String string) This method converts the given string to caml-case syntax using the default separators ' ', '-', '_' and '.'.
String	toCamlCase(String string, char... separators) This method converts the given string to caml-case syntax.
String	toSeparatedString(Collection<?> collection, String separator, StringSyntax syntax) This method formats the elements given by collection to a string where each value is formatted to its string representation and separated by separator.
<E> String	toSeparatedString(Collection<E> collection, String separator, StringSyntax syntax, Formatter<E> formatter) This method is like toSeparatedString(Collection, String, StringSyntax) but allows to specify an explicit Formatter to use instead of Object.toString().
<E> void	toSeparatedString(Collection<E> collection, String separator, StringSyntax syntax, Formatter<E> formatter, Appendable buffer) This method is like toSeparatedString(Collection, String, StringSyntax) but allows to specify an explicit Formatter to use instead of Object.toString().

Field Detail

TRUE

static final String TRUE

a string representing the boolean value true

FALSE

static final String FALSE

a string representing the boolean value false

NULL

static final String NULL

a string representing the undefined value null.

See Also:

Constant Field Values

LINE_SEPARATOR_CR

static final String LINE_SEPARATOR_CR

The line-separator with a single carriage-return.

See Also:

Constant Field Values

LINE_SEPARATOR_LF

static final String LINE_SEPARATOR_LF

The Unix line-separator (line-feed).

See Also:

Constant Field Values

LINE_SEPARATOR_CRLF

static final String LINE_SEPARATOR_CRLF

The Windows line-separator (carriage-return line-feed).

See Also:

Constant Field Values

LINE_SEPARATOR_LFCR

static final String LINE_SEPARATOR_LFCR

The Mac line-separator (line-feed carriage-return).

See Also:

Constant Field Values

LINE_SEPARATOR

static final String LINE_SEPARATOR

The platform-specific line-separator string. Should be one of LINE_SEPARATOR_LF, LINE_SEPARATOR_CRLF, LINE_SEPARATOR_LFCR, LINE_SEPARATOR_CR.

SYSTEM_PROPERTY_LINE_SEPARATOR

static final String SYSTEM_PROPERTY_LINE_SEPARATOR

The system property name for LINE_SEPARATOR.

Since:

3.1.0

See Also:

Constant Field Values

EMPTY_STRING_ARRAY

static final String[] EMPTY_STRING_ARRAY

An empty String array.

EMPTY_CHAR_ARRAY

static final char[] EMPTY_CHAR_ARRAY

An empty char array.

Since:

2.0.0

Method Detail

getLineSeparator

String getLineSeparator()

The platform-specific line-separator string. Should be one of LINE_SEPARATOR_LF, LINE_SEPARATOR_CRLF, LINE_SEPARATOR_LFCR, LINE_SEPARATOR_CR.

Returns:

the line separator.

parseBoolean

Boolean parseBoolean(String booleanValue)

This method parses a boolean value given as string.

Parameters:

booleanValue - is the boolean value as string.

Returns:

true if the given string equals to true, false if it equals to false and null in any other case.

See Also:

Boolean.valueOf(String)

replace

void replace(char[] string,
             char oldChar,
             char newChar)

This method replaces all occurrences of oldChar in the char-array given by string with newChar.

Parameters:

string - is the char-array where the replacement should take place.

oldChar - is the character to be replaced.

newChar - is the replacement for oldChar.

See Also:

String.replace(char, char)

replace

String replace(String string,
               String match,
               String replace)

This method replaces all occurrences of the string match with the string replace in the given string.

Parameters:

string - is the string where to replace.

match - is the string that is searched and replaced.

replace - is the string match is substituted with.

Returns:

the given string with all occurrences of match replaced by replace.

replaceSuffixWithCase

String replaceSuffixWithCase(String string,
                             int suffixLength,
                             String newSuffixLowerCase)

This method delegates to replaceSuffixWithCase(String, int, String, Locale) using Locale.ENGLISH.

Parameters:

string - is the string to replace.

suffixLength - is the length of the suffix from string to replace.

newSuffixLowerCase - is the new suffix for the given string in lower-case .

Returns:

the given string with the last suffixLength characters cut off and replaced by newSuffixLowerCase with respect to the original case of string.

See Also:

replaceSuffixWithCase(String, int, String, Locale)

replaceSuffixWithCase

String replaceSuffixWithCase(String string,
                             int suffixLength,
                             String newSuffixLowerCase,
                             Locale locale)

This method replaces the last suffixLength number of characters from string with the lower-case string newSuffixLowerCase with respect to the original case of the given string.
Here are some examples for Locale.ENGLISH:

string	suffixLength	newSuffixLowerCase	replaceSuffixWithCase(String, int, String)
foobar	3	foo	foofoo
FOOBAR	3	foo	FOOFOO
FooBar	3	foo	FooFoo
FooBar	2	foo	FooBfoo

Parameters:

string - is the string to replace.

suffixLength - is the length of the suffix from string to replace.

newSuffixLowerCase - is the new suffix for the given string in lower-case .

locale - is the locale used for case transformation.

Returns:

the given string with the last suffixLength characters cut off and replaced by newSuffixLowerCase with respect to the original case of string.

isEmpty

boolean isEmpty(String string)

This method determines if the given string contains no information.

Parameters:

string - is the string to check.

Returns:

true if the given string is null or has a trimmed length of zero, false otherwise.

See Also:

isEmpty(String, boolean)

isEmpty

boolean isEmpty(String string,
                boolean trim)

This method determines if the given string is empty.

Parameters:

string - is the string to check.

trim - if whitespaces should be ignored and a string with a trimmed length of zero is considered as empty.

Returns:

true if the given string is null or has a (trimmed) length of zero, false otherwise.

isAllUpperCase

boolean isAllUpperCase(String string)

Determines if all characters of the given string are in upper case .

string	isAllUpperCase(string)
UPPER_CASE	true
lower_case	false
CamlCase	false

Parameters:

string - the String to check.

Returns:

true if all characters are in upper case, false otherwise.

Since:

6.0.0

isAllLowerCase

boolean isAllLowerCase(String string)

Determines if all characters of the given string are in lower case .

string	isAllLowerCase(string)
UPPER_CASE	false
lower_case	true
CamlCase	false

Parameters:

string - the String to check.

Returns:

true if all characters are in lower case, false otherwise.

Since:

6.0.0

padNumber

String padNumber(long number,
                 int digits)

This method formats a positive number to a string with at least the given number of digits padding it with leading zeros.
Examples:

• padNumber(5, 3) will return "005"
• padNumber(25, 3) will return "025"
• padNumber(100, 3) will return "100"
• padNumber(1234, 3) will return "1234"

Parameters:

number - is the positive number to format.

digits - is the (minimum) number of digits required.

Returns:

the number as string with the length of (at least) digits. If the number is less, leading zeros are appended.

padNumber

String padNumber(long number,
                 int digits,
                 int radix)

This method formats a positive number to a string using the given radix with at least the given number of digits padding it with leading zeros.
Examples:

• padNumber(31, 3, 16) will return "01f"
• padNumber(5, 6, 2) will return "000101"

To pad a number to a constant length you can use the following value for digits:

Radix	byte	short	int	long
2	8	16	32	64
8	3	6	9	12
10	3	5	9	19
16	2	4	8	16

Parameters:

number - is the positive number to format.

digits - is the (minimum) number of digits required.

radix - is the radix to use.

Returns:

the number as string with the length of (at least) digits. If the number is less, leading zeros are appended.

toCamlCase

String toCamlCase(String string)

This method converts the given string to caml-case syntax using the default separators ' ', '-', '_' and '.'.

Parameters:

string - is the string to convert.

Returns:

the given string in caml-case syntax.

See Also:

toCamlCase(String, char[])

toCamlCase

String toCamlCase(String string,
                  char... separators)

This method converts the given string to caml-case syntax.
In caml-case syntax words are written without a separator but each new word starts with a capitalized letter. This method removes all characters from the given string that are in the list given by separators and capitalizes the first character of the following word.
Examples for separators ' ', '-', '_', '.':

string	toCamlCase(string)
foo bar	fooBar
aAa-bBB-CcC	aAaBBBCcC
X--m_._l..	XML

Parameters:

string - is the string to convert.

separators - is the list of characters that are treated as word-separators.

Returns:

the given string in caml-case syntax.

fromCamlCase

String fromCamlCase(String string,
                    char separator)

This method converts the given string from caml-case syntax to lower-case using the given separator as word-boundary.
Example:

string	separator	fromCamlCase(string, separator)
FooBar	-	foo-bar
someWordMix	.	some.word.mix
AbbreviationsLikeXMLshouldNotBeCapitalized	_	abbreviations_like_xmlshould_not_be_capitalized
FOO_BAR	*	foo_bar

Parameters:

string - is the string to convert.

separator - is the character to insert at word-boundaries indicated by a switch from lower- to upper-case.

Returns:

the given string in lower-case with the given separator inserted at word-boundaries.

See Also:

toCamlCase(String, char...)

isSubstring

boolean isSubstring(String string,
                    String substring,
                    int offset)

This method checks if the given string contains the given substring at the given offset.
This is an efficient implementation of

 string.indexOf(substring, offset) == offset
 

or

 string.substring(offset).beginsWith(substring)
 

Parameters:

string - is the string potentially containing substring.

substring - is the substring that should be contained in string at the given offset.

offset - is the offset in string where to check for substring.

Returns:

true if the given string contains the given substring at the given offset and false otherwise.

isSubstring

boolean isSubstring(char[] string,
                    String substring,
                    int offset)

This method checks if the given string contains the given substring at the given offset.
This is an efficient implementation of

 string.indexOf(substring, offset) == offset
 

or

 string.substring(offset).beginsWith(substring)
 

Parameters:

string - is the char[] representing the string potentially containing substring.

substring - is the substring that should be contained in string at the given offset.

offset - is the offset in string where to check for substring.

Returns:

true if the given string contains the given substring at the given offset and false otherwise.

toSeparatedString

String toSeparatedString(Collection<?> collection,
                         String separator,
                         StringSyntax syntax)

This method formats the elements given by collection to a string where each value is formatted to its string representation and separated by separator.
Examples:

collection	separator	syntax.escape	syntax.quoteStart	syntax.quoteEnd	toSeparatedString(Collection, String, StringSyntax)
{"abc;", "a,b,c", Integer.valueOf(123), Character.valueOf('\'')}	","	'\\'	'\0'	'\0'	"abc;,a\\,b\\,c,123,'"
{"abc;", "a,b,c", Integer.valueOf(123), Character.valueOf('\'')}	","	'\\'	'\''	'\''	"'abc;','a,b,c','123','\\''"
{"abc;", "a,b,c", Integer.valueOf(123), Character.valueOf('\'')}	"; "	'\\'	'['	']'	"[abc;]; [a,b,c]; [123]; [']"

Please note that Collections with heterogeneous elements can NOT be converted back from String.

Parameters:

collection - is the Collection with the elements to format as separated string. May be empty.

separator - is the String used to separate elements. It is appended after each but the last element. Typically this should be a specific character that may be followed by a whitespace. Common separators are comma (,) or semicolon (;) often also followed by a whitespace (", ").

syntax - is the StringSyntax defining escape as well as start and end of elements.

Returns:

the formatted string.

Since:

3.0.0

toSeparatedString

<E> String toSeparatedString(Collection<E> collection,
                             String separator,
                             StringSyntax syntax,
                             Formatter<E> formatter)

This method is like toSeparatedString(Collection, String, StringSyntax) but allows to specify an explicit Formatter to use instead of Object.toString().

Type Parameters:

E - is the generic type of the elements in the collection.

Parameters:

collection - is the Collection with the elements to format as separated string. May be empty.

separator - is the String used to separate elements. It is appended after each but the last element. Typically this should be a specific character that may be followed by a whitespace. Common separators are comma (,) or semicolon (;) often also followed by a whitespace (", ").

syntax - is the StringSyntax defining escape as well as start and end of elements.

formatter - is the Formatter to use.

Returns:

the formatted string.

Since:

3.0.0

toSeparatedString

<E> void toSeparatedString(Collection<E> collection,
                           String separator,
                           StringSyntax syntax,
                           Formatter<E> formatter,
                           Appendable buffer)

This method is like toSeparatedString(Collection, String, StringSyntax) but allows to specify an explicit Formatter to use instead of Object.toString().

Type Parameters:

E - is the generic type of the elements in the collection.

Parameters:

collection - is the Collection with the elements to format as separated string. May be empty.

separator - is the String used to separate elements. It is appended after each but the last element. Typically this should be a specific character that may be followed by a whitespace. Common separators are comma (,) or semicolon (;) often also followed by a whitespace (", ").

syntax - is the StringSyntax defining escape as well as start and end of elements.

formatter - is the Formatter to use.

buffer - is where the separated string is appended to.

Since:

3.0.0

fromSeparatedString

List<String> fromSeparatedString(CharSequence separatedString,
                                 String separator,
                                 StringSyntax syntax)

This method is like fromSeparatedString(CharSequence, String, StringSyntax, Collection, ValueConverter) but expects elements of the type String that do not need additional custom conversion.

Parameters:

separatedString - is the separated String of elements to add to the collection.

separator - is the String used to separate the individual elements in separatedString. There should be no separator after the last element in separatedString.

syntax - is the StringSyntax defining escape as well as start and end of elements.

Returns:

the List of elements from separatedString.

Since:

3.0.0

fromSeparatedString

void fromSeparatedString(CharSequence separatedString,
                         String separator,
                         StringSyntax syntax,
                         Collection<String> collection)

This method is like fromSeparatedString(CharSequence, String, StringSyntax, Collection, ValueConverter) but expects elements of the type String that do not need additional custom conversion.

Parameters:

separatedString - is the separated String of elements to add to the collection.

separator - is the String used to separate the individual elements in separatedString. There should be no separator after the last element in separatedString.

syntax - is the StringSyntax defining escape as well as start and end of elements.

collection - is where to add the elements to. This should be initially empty.

Since:

3.0.0

fromSeparatedString

<E> void fromSeparatedString(CharSequence separatedString,
                             String separator,
                             StringSyntax syntax,
                             Collection<E> collection,
                             ValueConverter<String,E> converter)

This method parses the given separatedString that contains elements separated with separator and the given syntax and adds these elements to the given collection.
This is the inverse operation of toSeparatedString(Collection, String, StringSyntax, Formatter).

Type Parameters:

E - is the generic type of the elements in the collection.

Parameters:

separatedString - is the separated String of elements to add to the collection.

separator - is the String used to separate the individual elements in separatedString. There should be no separator after the last element in separatedString.

syntax - is the StringSyntax defining escape as well as start and end of elements.

collection - is where to add the elements to. This should be initially empty.

converter - is used to parse the given elements from String to their actual type ( <E>).

Since:

3.0.0

fromSeparatedString

<E> void fromSeparatedString(CharSequence separatedString,
                             String separator,
                             StringSyntax syntax,
                             Collection<E> collection,
                             ValueConverter<? super String,? super E> converter,
                             Class<E> type)

This method parses the given separatedString that contains elements separated with separator and the given syntax and adds these elements to the given collection.
This is the inverse operation of toSeparatedString(Collection, String, StringSyntax, Formatter).

Type Parameters:

E - is the generic type of the elements in the collection.

Parameters:

separatedString - is the separated String of elements to add to the collection.

separator - is the String used to separate the individual elements in separatedString. There should be no separator after the last element in separatedString.

syntax - is the StringSyntax defining escape as well as start and end of elements.

collection - is where to add the elements to. This should be initially empty.

converter - is used to parse the given elements from String to their actual type ( <E>). May be the GenericValueConverter.

type - is the Class reflecting the elements to add to collection.

Since:

3.0.0