de.larssh.utils.text

Class Strings

java.lang.Object

de.larssh.utils.text.Strings

public final class Strings
extends Object

This class contains helper methods for String.

Field Summary

Fields

Modifier and Type	Field and Description
static Map<String,BigDecimal>	BINARY_UNITS Map of binary units to their factor K: 1024 M: 1024 * 1024 G: 1024 * 1024 * 1024 ...
static Map<String,Integer>	DECIMAL_UNITS Map of decimal units to their power of ten ...
static Charset	DEFAULT_CHARSET Constant UTF-8 for usage as default char set.
static Locale	DEFAULT_LOCALE Constant locale as default locale where no language and country is required.
static String	NEW_LINE Constant "\n" for output.

Method Summary

Modifier and Type	Method and Description
static int	compareIgnoreCaseAscii(CharSequence first, CharSequence second) Compares two strings, ignoring case differences in the ASCII range.
static boolean	containsIgnoreCase(CharSequence string, CharSequence substring) Tests if value contains substring, ignoring case considerations.
static boolean	containsIgnoreCaseAscii(CharSequence string, CharSequence substring) Tests if value contains substring, ignoring case considerations in the ACII range.
static boolean	endsWithIgnoreCase(CharSequence value, CharSequence suffix) Tests if value ends with the specified suffix, ignoring case considerations.
static boolean	endsWithIgnoreCaseAscii(CharSequence value, CharSequence suffix) Tests if value ends with the specified suffix, ignoring case considerations in the ASCII range.
static boolean	equalsIgnoreCaseAscii(CharSequence first, CharSequence second) Compares first to second, ignoring case considerations in the ASCII range.
static boolean	find(CharSequence input, Pattern pattern) Tells whether or not a subsequence input matches pattern.
static String	format(String format, Object... arguments) Returns a formatted string using the specified format string and arguments.
static int	indexOfIgnoreCase(CharSequence string, CharSequence substring) Returns the index within string of the first occurrence of substring, ignoring case considerations.
static int	indexOfIgnoreCase(CharSequence string, CharSequence substring, int fromIndex) Returns the index within string of the first occurrence of substring, ignoring case considerations, starting at the specified index.
static int	indexOfIgnoreCaseAscii(CharSequence string, CharSequence substring) Returns the index within string of the first occurrence of substring, ignoring case considerations in the ASCII range.
static int	indexOfIgnoreCaseAscii(CharSequence string, CharSequence substring, int fromIndex) Returns the index within string of the first occurrence of substring, ignoring case considerations in the ASCII range, starting at the specified index.
static boolean	isBlank(CharSequence value) Returns true if value consists of whitespace only or equals null.
static boolean	matches(CharSequence input, Pattern pattern) Tells whether or not input matches pattern.
static Comparator<String>	numericTextComparator(boolean caseInsensitive) A Comparator that orders alpha numeric strings in natural order, either case sensitive or case insensitive.
static BigInteger	parseBinaryUnit(CharSequence binaryValue) Parses binaryValue as binary value with optional sign, optional fraction and optional binary unit (case insensitive matching).
static BigDecimal	parseDecimalUnit(CharSequence decimalValue) Parses decimalValue as decimal value with optional sign, optional fraction and optional decimal unit (case insensitive matching - where possible).
static String	replaceAll(CharSequence input, Pattern pattern, String replacement) Replaces every subsequence of input that matches pattern with replacement.
static String	replaceFirst(CharSequence input, Pattern pattern, String replacement) Replaces the first subsequence of input that matches pattern with replacement.
static boolean	startsWithIgnoreCase(CharSequence value, CharSequence prefix) Tests if value starts with prefix ignoring case considerations.
static boolean	startsWithIgnoreCase(CharSequence value, CharSequence prefix, int offset) Tests if the substring of value beginning at offset starts with prefix, ignoring case considerations.
static boolean	startsWithIgnoreCaseAscii(CharSequence value, CharSequence prefix) Tests if value starts with the specified prefix, ignoring case considerations in the ASCII range.
static boolean	startsWithIgnoreCaseAscii(CharSequence value, CharSequence prefix, int offset) Tests if the substring of value beginning at the specified index starts with the specified prefix, ignoring case considerations in the ASCII range.
static String	toLowerCaseAscii(CharSequence value) Converts all of the ASCII upper case characters in value to lower case.
static String	toLowerCaseNeutral(String value) Converts all of the characters in value to lower case using DEFAULT_LOCALE.
static String	toTitleCaseNeutral(String value) Converts value to title case by converting its first character using Character.toTitleCase(char) and following to lower case using DEFAULT_LOCALE.
static String	toUpperCaseAscii(CharSequence value) Converts all of the ASCII lower case characters in value to upper case.
static String	toUpperCaseNeutral(String value) Converts all of the characters in value to upper case using DEFAULT_LOCALE.
static String	trimEnd(CharSequence value) Returns a string similar to value, but with any trailing whitespace removed.
static String	trimStart(CharSequence value) Returns a string similar to value, but with any leading whitespace removed.

Methods inherited from class java.lang.Object

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

Field Detail

BINARY_UNITS

public static final Map<String,BigDecimal> BINARY_UNITS

Map of binary units to their factor

• K: 1024
• M: 1024 * 1024
• G: 1024 * 1024 * 1024
• ...

DECIMAL_UNITS

public static final Map<String,Integer> DECIMAL_UNITS

Map of decimal units to their power of ten

• ...
• m: -3
• k: 3
• M: 6
• ...

DEFAULT_CHARSET

public static final Charset DEFAULT_CHARSET

Constant UTF-8 for usage as default char set.

Using Charset.defaultCharset() leads to unexpected compatibility problems. While the new Files API has been changed to use UTF-8 by default, old and third-party implementations still depend on the default char set or require a custom char set.

Why shouldn't I use StandardCharsets.UTF_8 directly?
Using StandardCharsets.UTF_8 is bad practice, as it holds implementation specific information.

DEFAULT_LOCALE

public static final Locale DEFAULT_LOCALE

Constant locale as default locale where no language and country is required.

Using Locale.getDefault() leads to unexpected behavior for technical formatting operations. Therefore this locale specifies a default value.

The returned value is Locale.ROOT.

NEW_LINE

public static final String NEW_LINE

Constant "\n" for output. Remember to accept "\r\n" and "\r" on the input side, too!

Using System.lineSeparator() leads to files, which cannot (should not) be transferred between UNIX and Microsoft Windows systems. To avoid problems, some developers decided to depend on the UNIX line separator only.

Why shouldn't I use "\n" directly?
Using "\n" is bad practice, as it holds implementation specific information.

Method Detail

compareIgnoreCaseAscii

public static int compareIgnoreCaseAscii(CharSequence first,
                                         CharSequence second)

Compares two strings, ignoring case differences in the ASCII range.

Parameters:

first - the first string to compare

second - the second string to compare

Returns:

a positive integer, zero, or a negative integer as first is greater than, equal to, or less than second, ignoring case considerations in the ASCII range.

containsIgnoreCase

public static boolean containsIgnoreCase(CharSequence string,
                                         CharSequence substring)

Tests if value contains substring, ignoring case considerations.

Parameters:

string - the string to search in

substring - the sequence to search for

Returns:

true if value contains substring, ignoring case considerations, else false

containsIgnoreCaseAscii

public static boolean containsIgnoreCaseAscii(CharSequence string,
                                              CharSequence substring)

Tests if value contains substring, ignoring case considerations in the ACII range.

Parameters:

string - the string to search in

substring - the sequence to search for

Returns:

true if value contains substring, ignoring case considerations in the ACII range, else false

equalsIgnoreCaseAscii

public static boolean equalsIgnoreCaseAscii(@Nullable
                                            CharSequence first,
                                            @Nullable
                                            CharSequence second)

Compares first to second, ignoring case considerations in the ASCII range. Two strings are considered equal ignoring case if they are of the same length and corresponding characters in the two strings are equal ignoring case in the ASCII range.

Parameters:

first - the first of both strings to compare

second - the second of both strings to compare

Returns:

true if first and second are considered equal, ignoring case in the ACII range, else false

endsWithIgnoreCase

public static boolean endsWithIgnoreCase(CharSequence value,
                                         CharSequence suffix)

Tests if value ends with the specified suffix, ignoring case considerations.

Parameters:

value - string to compare against

suffix - the suffix

Returns:

true if prefix is a suffix of the character sequence represented by value, ignoring case considerations, else false

endsWithIgnoreCaseAscii

public static boolean endsWithIgnoreCaseAscii(CharSequence value,
                                              CharSequence suffix)

Tests if value ends with the specified suffix, ignoring case considerations in the ASCII range.

Parameters:

value - string to compare against

suffix - the suffix

Returns:

true if prefix is a suffix of the character sequence represented by value, ignoring case considerations in the ASCII range, else false

find

public static boolean find(CharSequence input,
                           Pattern pattern)

Tells whether or not a subsequence input matches pattern.

Use Patterns.find(Pattern, CharSequence) if you need a matcher.

Parameters:

input - the input sequence to find the pattern in

pattern - the matching pattern

Returns:

true if, and only if, input matches pattern

format

public static String format(String format,
                            Object... arguments)

Returns a formatted string using the specified format string and arguments. In that way this method works similar to String.format(String, Object...).

Here are the differences:

• In case arguments is empty, no checks and formatting is performed. format is returned immediately and without modification.
• DEFAULT_LOCALE is used instead of the systems default Locale.
• On formatting failure no exception is thrown. When used for error messages this often hides the original error message. Instead a failure message is returned, containing format.

Parameters:

format - format string

arguments - arguments referenced by format specifiers in format

Returns:

formatted string

indexOfIgnoreCase

public static int indexOfIgnoreCase(CharSequence string,
                                    CharSequence substring)

Returns the index within string of the first occurrence of substring, ignoring case considerations.

Parameters:

string - the string to search in

substring - the substring to search for

Returns:

the index of the first occurrence of substring, ignoring case considerations, or -1 if there is no such occurrence

indexOfIgnoreCase

public static int indexOfIgnoreCase(CharSequence string,
                                    CharSequence substring,
                                    int fromIndex)

Returns the index within string of the first occurrence of substring, ignoring case considerations, starting at the specified index.

Parameters:

string - the string to search in

substring - the substring to search for

fromIndex - the index from which to start the search

Returns:

the index of the first occurrence of substring, ignoring case considerations, starting at the specified index, or -1 if there is no such occurrence

indexOfIgnoreCaseAscii

public static int indexOfIgnoreCaseAscii(CharSequence string,
                                         CharSequence substring)

Returns the index within string of the first occurrence of substring, ignoring case considerations in the ASCII range.

Parameters:

string - the string to search in

substring - the substring to search for

Returns:

the index of the first occurrence of substring, ignoring case considerations in the ASCII range, or -1 if there is no such occurrence

indexOfIgnoreCaseAscii

public static int indexOfIgnoreCaseAscii(CharSequence string,
                                         CharSequence substring,
                                         int fromIndex)

Returns the index within string of the first occurrence of substring, ignoring case considerations in the ASCII range, starting at the specified index.

Parameters:

string - the string to search in

substring - the substring to search for

fromIndex - the index from which to start the search

Returns:

the index of the first occurrence of substring, ignoring case considerations in the ASCII range, starting at the specified index, or -1 if there is no such occurrence

isBlank

public static boolean isBlank(@Nullable
                              CharSequence value)

Returns true if value consists of whitespace only or equals null.

This is an optimized way of value.trim().isEmpty().

Parameters:

value - string

Returns:

true if value consists of whitespace only or equals null

matches

public static boolean matches(CharSequence input,
                              Pattern pattern)

Tells whether or not input matches pattern.

Use Patterns.matches(Pattern, CharSequence) if you need a matcher.

Parameters:

input - the value to match

pattern - the matching pattern

Returns:

true if, and only if, input matches pattern

numericTextComparator

public static Comparator<String> numericTextComparator(boolean caseInsensitive)

A Comparator that orders alpha numeric strings in natural order, either case sensitive or case insensitive. It is appreciated to use this kind of ordering for user output.

Because numeric values are not deserialized into numeric data types, their length is not limited. Fractions are not supported and will be handled as two separate numeric values.

Numeric values can have a leading plus or minus sign when following a whitespace character or at a strings start.

The following lists some example values to demonstrate the ordering.

• Banana -12 Circus
• Banana -5 Circus
• Banana +5 Circus
• Banana 5 Circus
• Banana +5 Dolphin
• Banana 8 Circus
• Banana 12 Circus
• Banana-5 Circus
• Banana-12 Circus
• Banana--5 Circus
• Elephant 5 Circus

This comparator permits null values.

Note that this Comparator does not take locale into account, and will result in an unsatisfactory ordering for certain locales.

Parameters:

caseInsensitive - true if comparison should take place case insensitive

Returns:

a Comparator that orders alpha numeric strings in natural order, either case sensitive or case insensitive. It is appreciated to use this kind of ordering for user output.

parseBinaryUnit

public static BigInteger parseBinaryUnit(CharSequence binaryValue)
                                  throws StringParseException

Parses binaryValue as binary value with

• optional sign,
• optional fraction
• and optional binary unit (case insensitive matching).

Binary units multiply by 1024. Though strings with fractions can be parsed, the resulting value must not contain a fraction part. Numeric values can be formatted using underscore, just as numeric Java literals can be formatted.

Examples:

Examples

Parameter	Calculation	Return Value
-2m	-2 * 1024 * 1024	-2 097 152
0		0
5.4k	5.4 * 1024	5529.6 -> ArithmeticException
+5_432		5 432

Parameters:

binaryValue - binary string

Returns:

binary value

Throws:

StringParseException - on parse failure

parseDecimalUnit

public static BigDecimal parseDecimalUnit(CharSequence decimalValue)
                                   throws StringParseException

Parses decimalValue as decimal value with

• optional sign,
• optional fraction
• and optional decimal unit (case insensitive matching - where possible).

Numeric values can be formatted using underscore, just as numeric Java literals can be formatted.

Examples:

Examples

Parameter	Return Value
-2m	-0.002
0	0
5.4k	5 400
+5_432	5 432

Parameters:

decimalValue - decimal string

Returns:

decimal value

Throws:

StringParseException - on parse failure

replaceFirst

public static String replaceFirst(CharSequence input,
                                  Pattern pattern,
                                  String replacement)

Replaces the first subsequence of input that matches pattern with replacement.

Note that replacement is not a literal replacement string. Backslashes (\) and dollar signs ($) may be treated differently. Quote unknown literal replacement strings using Matcher.quoteReplacement(String).

Parameters:

input - the value to match

pattern - the matching pattern

replacement - the replacement string

Returns:

the string constructed by replacing each matching subsequence by the replacement string, substituting captured subsequences as needed

replaceAll

public static String replaceAll(CharSequence input,
                                Pattern pattern,
                                String replacement)

Replaces every subsequence of input that matches pattern with replacement.

Note that replacement is not a literal replacement string. Backslashes (\) and dollar signs ($) may be treated differently. Quote unknown literal replacement strings using Matcher.quoteReplacement(String).

Parameters:

input - the value to match

pattern - the matching pattern

replacement - the replacement string

Returns:

the string constructed by replacing each matching subsequence by the replacement string, substituting captured subsequences as needed

startsWithIgnoreCase

public static boolean startsWithIgnoreCase(CharSequence value,
                                           CharSequence prefix)

Tests if value starts with prefix ignoring case considerations.

Parameters:

value - string to compare against

prefix - the prefix

Returns:

true if prefix is a prefix of value, ignoring case considerations, else false

startsWithIgnoreCase

public static boolean startsWithIgnoreCase(CharSequence value,
                                           CharSequence prefix,
                                           int offset)

Tests if the substring of value beginning at offset starts with prefix, ignoring case considerations.

Parameters:

value - string to compare against

prefix - the prefix

offset - where to begin looking in value

Returns:

true if prefix is a prefix of the substring of value starting at offset, ignoring case considerations, else false. The result is false if offset is negative or greater than the length of value.

startsWithIgnoreCaseAscii

public static boolean startsWithIgnoreCaseAscii(CharSequence value,
                                                CharSequence prefix)

Tests if value starts with the specified prefix, ignoring case considerations in the ASCII range.

Parameters:

value - string to compare against

prefix - the prefix

Returns:

true if prefix is a prefix of the character sequence represented by value, ignoring case considerations in the ASCII range, else false

startsWithIgnoreCaseAscii

public static boolean startsWithIgnoreCaseAscii(CharSequence value,
                                                CharSequence prefix,
                                                int offset)

Tests if the substring of value beginning at the specified index starts with the specified prefix, ignoring case considerations in the ASCII range.

Parameters:

value - string to compare against

prefix - the prefix

offset - where to begin looking in value.

Returns:

true if prefix is a prefix of the substring of value starting at index offset, ignoring case considerations in the ASCII range, else false. The result is false if offset is negative or greater than the length of this String object.

toLowerCaseAscii

public static String toLowerCaseAscii(CharSequence value)

Converts all of the ASCII upper case characters in value to lower case.

Parameters:

value - string to convert

Returns:

converted string

toLowerCaseNeutral

public static String toLowerCaseNeutral(String value)

Converts all of the characters in value to lower case using DEFAULT_LOCALE. This method is equivalent to toLowerCase(Locale.ROOT).

Parameters:

value - string to convert

Returns:

converted string

toTitleCaseNeutral

public static String toTitleCaseNeutral(String value)

Converts value to title case by converting its first character using Character.toTitleCase(char) and following to lower case using DEFAULT_LOCALE.

Parameters:

value - string to convert

Returns:

converted string

toUpperCaseAscii

public static String toUpperCaseAscii(CharSequence value)

Converts all of the ASCII lower case characters in value to upper case.

Parameters:

value - string to convert

Returns:

converted string

toUpperCaseNeutral

public static String toUpperCaseNeutral(String value)

Converts all of the characters in value to upper case using DEFAULT_LOCALE. This method is equivalent to toUpperCase(Locale.ROOT).

Parameters:

value - string to convert

Returns:

converted string

trimStart

public static String trimStart(CharSequence value)

Returns a string similar to value, but with any leading whitespace removed.

This method works similar to String.trim(), though it handles only the strings start.

Whitespace characters are recognized using Characters.isAsciiWhitespace(char).

Parameters:

value - value

Returns:

left trimmed value

trimEnd

public static String trimEnd(CharSequence value)

Returns a string similar to value, but with any trailing whitespace removed.

This method works similar to String.trim(), though it handles only the strings end.

Whitespace characters are recognized using Characters.isAsciiWhitespace(char).

Parameters:

value - value

Returns:

left trimmed value