saker.build Documentation TaskDoc JavaDoc Packages
public class StringUtils
Utility class containing functions for working with and manipulating strings and char sequences.
Methods
public static CharSequence
asCharSequence(char[] array)
Gets a CharSequence view for the argument character array.
public static CharSequence
asCharSequence(char[] array, int offset, int length)
Gets a CharSequence view for the argument character array with the given range.
public static Iterable<String>
Gets a view for the iterable that creates an iterator that converts the elements of it to Strings.
public static Iterator<String>
Gets a forwarding iterator for the argument that converts the returned elements to Strings.
public static int
Compares two string in natural order with possible null values.
public static int
Compares two string in natural order in an ignore-case manner with possible null values.
public static int
Compares two string in natural order with possible null values.
public static int
Compares two string in natural order in an ignore-case manner with possible null values.
public static int
count(CharSequence s, char c)
Counts the number of occurrences of a character in the given character sequence.
public static boolean
Checks if the given string ends with the specified prefix in a case-insensitive manner.
public static int
getLineIndex(int[] lineindices, int offset)
Searches the index of the line based on an index map and a character offset.
public static int[]
Creates an offset map for each line in the parameter string.
public static int
getLinePositionIndex(int[] lineindices, int offset)
Gets the position in the line for a given line index map and character offset.
public static int
getLinePositionIndex(int[] lineindices, int lineindex, int offset)
Gets the position in the line for a given line, index map, and offset.
public static int
Converts a hexadecimal digit to integral value.
public static int
indexOf(CharSequence cs, char c)
Gets the index of the first occurrence of the given character in the argument char sequence.
public static boolean
Checks if the argument char sequence consists of only the given character.
public static boolean
Checks if the argument string has an integral format.
public static int
Gets the index of the last occurrence of the given character in the argument char sequence.
public static int
Gets the length of the argument character sequence, returning 0 if null.
public static String
Gets a string that immediately follows the argument string given that they're ordered by natural order.
public static Comparator<String>
Gets the comparator that compares the argument strings by natural order, and orders nulls first if any.
public static Comparator<String>
Gets the comparator that compares the argument strings by natural order, and orders nulls last if any.
public static byte[]
Converts a hexadecimal character sequence back to byte array representation.
public static String
removeFromEnd(String str, int count)
Removes the specified number of characters from the end of the given string.
public static String
repeatCharacter(char c, int count)
Creates a string that has only the given character repeated in it the given number of times.
public static Iterable<extends CharSequence>
Creates an iterable that creates iterators that splits up the argument sequence by the given character.
public static Iterator<extends CharSequence>
Creates an iterator that takes the argument sequence, and splits it up based on the given character.
public static boolean
Checks if the given string starts with the specified prefix in a case-insensitive manner.
public static CharSequence
subCharSequence(CharSequence cs, int offset, int length)
Gets a sub char sequence of the argument with the given range.
public static String
toHexString(byte[] array)
Converts the contents of the argument array to hexadecimal string representation.
public static String
toHexString(byte[] array, int start, int end)
Converts the contents in the given range of the argument array to hexadecimal string representation.
public static void
toHexString(byte[] array, int start, int end, StringBuilder sb)
Converts the contents in the given range of the argument array to hexadecimal string representation and appends it to the given string builder.
public static void
toHexString(byte[] array, StringBuilder sb)
Converts the contents of the argument array to hexadecimal string representation and appends it to the given string builder.
public static String
toStringJoin(CharSequence prefix, CharSequence delimiter, Iterable<?> elements, CharSequence suffix)
Creates a string representation of the argument elements with the specified format.
public static String
toStringJoin(CharSequence prefix, CharSequence delimiter, Iterator<?> elements, CharSequence suffix)
Creates a string representation of the argument elements with the specified format.
public static String
toStringJoin(CharSequence prefix, CharSequence delimiter, Object[] elements, CharSequence suffix)
Creates a string representation of the argument elements with the specified format.
public static String
toStringJoin(CharSequence delimiter, Iterable<?> elements)
Creates a string representation of the argument elements joined with the given delimiter.
public static String
toStringJoin(CharSequence delimiter, Iterator<?> elements)
Creates a string representation of the argument elements joined with the given delimiter.
public static String
toStringJoin(CharSequence delimiter, Object[] elements)
Creates a string representation of the argument elements joined with the given delimiter.
public static String
toStringLimit(Object obj, int limit)
Converts the argument objects to string representation, but limiting its length if it is longer than the maximum limit.
public static String
toStringLimit(Object obj, int limit, String ellipsizeend)
Converts the argument objects to string representation, but limiting its length if it is longer than the maximum limit, and adding an ellipsize if limited.
public static String
Returns the argument string with quotes around it unless it is null.
public static CharSequence asCharSequence(char[] array) throws NullPointerException
Gets a CharSequence view for the argument character array.

The returned CharSequence will use the argument array for its underlying data.

Any modifications made to the array will be reflected on the returned char sequence.

The method may return a shared singleton object if the argument is empty.

arrayThe array of characters.
A character sequence that is backed by the array.
NullPointerExceptionIf the argument is null.
public static CharSequence asCharSequence(char[] array, int offset, int length) throws NullPointerException, IndexOutOfBoundsException
Gets a CharSequence view for the argument character array with the given range.

The returned CharSequence will use the argument array for its underlying data.

Any modifications made to the array in the given range will be reflected on the returned char sequence.

The method may return a shared singleton object if the specified range is empty.

arrayThe array of characters.
offsetThe offset at which the interested sequence starts.
lengthThe number of characters in the sequence.
A character sequence that is backed by the array range.
NullPointerExceptionIf the argument is null.
IndexOutOfBoundsExceptionIf the specified range is out of bounds for the array.
public static Iterable<String> asStringIterable(Iterable<?> iterable)
Gets a view for the iterable that creates an iterator that converts the elements of it to Strings.

Any modifications made to the argument will reflect on the returned iterable. The returned iterable creates iterators that support removal if and only if the argument supports removals.

iterableThe iterable.
An iterable that converts the elements to strings, or null if the argument is null.
public static Iterator<String> asStringIterator(Iterator<?> iterator)
Gets a forwarding iterator for the argument that converts the returned elements to Strings.

The returned iterator creates iterators that support removal if and only if the argument supports removals.

iteratorThe iterator.
An iterator that converts the elements to strings, or null if the argument is null.
public static int compareStringsNullFirst(String l, String r)
Compares two string in natural order with possible null values.

Any null values are ordered first.

lThe first string.
rThe second string.
The comparison result.
Compares two string in natural order in an ignore-case manner with possible null values.

Any null values are ordered first.

lThe first string.
rThe second string.
The comparison result.
public static int compareStringsNullLast(String l, String r)
Compares two string in natural order with possible null values.

Any null values are ordered last.

lThe first string.
rThe second string.
The comparison result.
Compares two string in natural order in an ignore-case manner with possible null values.

Any null values are ordered last.

lThe first string.
rThe second string.
The comparison result.
public static int count(CharSequence s, char c) throws NullPointerException
Counts the number of occurrences of a character in the given character sequence.

This method iterates over the characters of the sequence, and counts the occurrences of the specified character.

sThe character sequence.
cThe character to count.
The number of occurrences.
NullPointerExceptionIf the char sequence is null.
public static boolean endsWithIgnoreCase(String str, String ending) throws NullPointerException
Checks if the given string ends with the specified prefix in a case-insensitive manner.
strThe string to examine.
endingThe ending to check.
true if the string ends with the prefix.
NullPointerExceptionIf the ending is null.
public static int getLineIndex(int[] lineindices, int offset) throws IndexOutOfBoundsException
Searches the index of the line based on an index map and a character offset.

The method determines which is the corresponding line for the given character offset.

lineindicesThe line index map.
offsetThe character offset to search the line index of.
The found line index.
IndexOutOfBoundsExceptionIf offset is negative.
public static int[] getLineIndexMap(CharSequence data) throws NullPointerException
Creates an offset map for each line in the parameter string.

The parameter string is examined and each starting offset for each line is returned in the result array. The first element is always 0. The nth element in the array represents the offset for the nth line, and so on.

Each element in the resulting array represents the character offset in the parameter string where the given line starts.

The line ending is determined by the '\n' character.

dataThe string to create the line map for.
The line map.
NullPointerExceptionIf the argument is null.
public static int getLinePositionIndex(int[] lineindices, int offset)
Gets the position in the line for a given line index map and character offset.

This method searches the corresponding line for the offset and returns the offset in the found line.

lineindicesThe line index map.
offsetThe character offset.
The index of the character in the corresponding line.
public static int getLinePositionIndex(int[] lineindices, int lineindex, int offset) throws IndexOutOfBoundsException
Gets the position in the line for a given line, index map, and offset.

The parameter line index should be a result of getLineIndex(int[], int). It is not sanity checked if the line index is valid input, and it is the responsibility of the caller to call this method with appropriate parameters.
This method is only publicly available to avoid searching the line index multiple times if not necessary. If you don't use the line index directly, consider using getLinePositionIndex(int[], int) instead.

lineindicesThe line index map.
lineindexThe line index corresponding to the offset.
offsetThe character offset.
The index of the character in the corresponding line.
IndexOutOfBoundsExceptionIf the line index is out of bounds.
public static int hexCharToValue(char c) throws IllegalArgumentException
Converts a hexadecimal digit to integral value.

The argument must be a character in the range of '0' - '9', 'a' - 'f', 'A' - 'F' which is the range of the characters of a number in base 16.

cThe character.
The integral value of the base-16 digit.
IllegalArgumentExceptionIf the argument is out of range.
public static int indexOf(CharSequence cs, char c)
Gets the index of the first occurrence of the given character in the argument char sequence.
csThe char sequence to examine. May be null in which case the character won't be found.
cThe char to search for.
The index of the first occurrence or -1 if not found.
public static boolean isConsistsOnlyChar(CharSequence s, char c)
Checks if the argument char sequence consists of only the given character.

An empty sequence is considered to consist only of the given character.

sThe char sequence to examine.
cThe character to examine for.
true if the char sequence is non-null and contains only the given character.
public static boolean isIntegralString(String s)
Checks if the argument string has an integral format.

A string is considered to be in integral format if it only contains numeric characters in the range of '0' - '9', and may be optionally prefixed by a sign character either '-' or '+'.

A string that only contains a single sign character is not considered to be integral.

sThe string to examine.
true if the argument is non-null and has the integral format defined by the above rules.
public static int lastIndexOf(CharSequence cs, char c)
Gets the index of the last occurrence of the given character in the argument char sequence.
csThe char sequence to examine. May be null in which case the character won't be found.
cThe char to search for.
The index of the last occurrence or -1 if not found.
public static int length(CharSequence str)
Gets the length of the argument character sequence, returning 0 if null.
strThe character sequence.
The length of the argument.
Gets a string that immediately follows the argument string given that they're ordered by natural order.

For the input string S, and result R, there are no string X for which the following is true:

 S < X < R
 
The returned string R will compare to be greater than the argument.

The returned string may have characters that are not displayable, or otherwise semantically incorrect. It should not be used in any other way than comparing other strings to it.

sThe string to get the next in order for.
The string that is next in order compared to the argument.
NullPointerExceptionIf the argument is null.
Gets the comparator that compares the argument strings by natural order, and orders nulls first if any.
The comparator.
Gets the comparator that compares the argument strings by natural order, and orders nulls last if any.
The comparator.
Converts a hexadecimal character sequence back to byte array representation.

The argument sequence length must be a multiply of 2 and contain only hexadecimal characters.

sThe string to parse.
The byte data parsed from the characters.
NullPointerExceptionIf the argument is null.
IllegalArgumentExceptionIf the length is not a multiply of 2, or the string contains non-hexadecimal characters.
Removes the specified number of characters from the end of the given string.
strThe string.
countThe number of characters to remove from the end.
The string without the characters which were removed.
NullPointerExceptionIf the string is null.
IndexOutOfBoundsExceptionIf the string is shorter than the number of characters to remove.
IllegalArgumentExceptionIf the count is negative.
public static String repeatCharacter(char c, int count)
Creates a string that has only the given character repeated in it the given number of times.
cThe character to repeat.
countThe number of times to repeat the character.
The string containing the repeated character.
public static Iterable<extends CharSequence> splitCharSequenceIterable(CharSequence charsequence, char c) throws NullPointerException
Creates an iterable that creates iterators that splits up the argument sequence by the given character.

The returned iterable will create iterators that work in the same way as splitCharSequenceIterator(CharSequence, char).

charsequenceThe char sequence to split.
cThe character to split by.
An iterable that creates iterators which splits up the sequence.
NullPointerExceptionIf the argument sequence is null.
public static Iterator<extends CharSequence> splitCharSequenceIterator(CharSequence charsequence, char c) throws NullPointerException
Creates an iterator that takes the argument sequence, and splits it up based on the given character.

The returned iterator will iterate over the split parts that doesn't contain the given character.

If multiple split characters occurr after each other, the returned iterator will return empty sequences for the inner parts. If the character is at the start or end of the string, a preceeding and following empty sequence will be returned.

charsequenceThe char sequence to split.
cThe character to split by.
An iterator that splits up the sequence.
NullPointerExceptionIf the argument sequence is null.
public static boolean startsWithIgnoreCase(String str, String prefix) throws NullPointerException
Checks if the given string starts with the specified prefix in a case-insensitive manner.
strThe string to examine.
prefixThe prefix to check.
true if the string starts with the prefix.
NullPointerExceptionIf the prefix is null.
Gets a sub char sequence of the argument with the given range.

This method can be used when the caller doesn't want to use CharSequence.subSequence(int, int). This might be the case when the charsequence implementation would copy large amounts of data, create unnecessarily deep object hierarchy, or other arbitrary reasons.

This method will return a char sequence that forwards its calls to its subject. Any subsequence that is created on the result will not create long chaing of references, but will use the argument char sequence, only modifying the view range.

If the argument char sequence is already a type of the same type that this method would return, this will only call CharSequence.subSequence(int, int) on it, therefore there is no preformance penalty if this method is called with an object that was returned by this method.

Warning: This method takes an offset-length range instead of a start-end range, unlike CharSequence.subSequence(int, int).

If the created range is empty, this method may return a singleton shared object.

csThe char sequence to create a sub sequence of.
offsetThe offset at which the sequence starts. (inclusive)
lengthThe length of the sub sequence.
A subsequence that is backed by the argument contents.
NullPointerExceptionIf the argument sequence is null.
IndexOutOfBoundsExceptionIf the specified range is out of bounds.
public static String toHexString(byte[] array) throws NullPointerException
Converts the contents of the argument array to hexadecimal string representation.

Each byte will be split into two hexadecimal characters, where the 4 high order bits is the first character, and the 4 low order bits are the second.

arrayThe array of bytes.
The hexadecimal representation of the argument bytes.
NullPointerExceptionIf the argument is null.
public static String toHexString(byte[] array, int start, int end) throws NullPointerException, IndexOutOfBoundsException
Converts the contents in the given range of the argument array to hexadecimal string representation.

Each byte will be split into two hexadecimal characters, where the 4 high order bits is the first character, and the 4 low order bits are the second.

arrayThe array of bytes.
startThe starting index of the range. (inclusive)
endThe end index of the range. (exclusive)
The hexadecimal representation of the bytes in the given range.
NullPointerExceptionIf the array or string builder is null.
IndexOutOfBoundsExceptionIf the range is out of bounds for the given array.
public static void toHexString(byte[] array, int start, int end, StringBuilder sb) throws NullPointerException, IndexOutOfBoundsException
Converts the contents in the given range of the argument array to hexadecimal string representation and appends it to the given string builder.

Each byte will be split into two hexadecimal characters, where the 4 high order bits is the first character, and the 4 low order bits are the second.

arrayThe array of bytes.
startThe starting index of the range. (inclusive)
endThe end index of the range. (exclusive)
sbThe string builder to append the hexadecimal representation to.
NullPointerExceptionIf the array or string builder is null.
IndexOutOfBoundsExceptionIf the range is out of bounds for the given array.
public static void toHexString(byte[] array, StringBuilder sb) throws NullPointerException
Converts the contents of the argument array to hexadecimal string representation and appends it to the given string builder.

Each byte will be split into two hexadecimal characters, where the 4 high order bits is the first character, and the 4 low order bits are the second.

arrayThe array of bytes.
sbThe string builder to append the hexadecimal representation to.
NullPointerExceptionIf the array or string builder is null.
public static String toStringJoin(CharSequence prefix, CharSequence delimiter, Iterable<?> elements, CharSequence suffix)
Creates a string representation of the argument elements with the specified format.

The method converts the given elements into string representation and joins them into a string with the given delimiter between them. The result is then prepended with the given prefix, and appended with the given suffix.

All arguments are nullable, in which case the corresponding part will not be appended to the result. If the elements are null, the delimiters won't be printed either. If all arguments are null, an empty string is returned.

prefixThe prefix to start the result with.
delimiterThe delimiter to insert between consecutive elements.
elementsThe elements to join.
suffixThe suffix to end the result with.
The created string based on the arguments.
public static String toStringJoin(CharSequence prefix, CharSequence delimiter, Iterator<?> elements, CharSequence suffix)
Creates a string representation of the argument elements with the specified format.

The method converts the given elements into string representation and joins them into a string with the given delimiter between them. The result is then prepended with the given prefix, and appended with the given suffix.

All arguments are nullable, in which case the corresponding part will not be appended to the result. If the elements are null, the delimiters won't be printed either. If all arguments are null, an empty string is returned.

prefixThe prefix to start the result with.
delimiterThe delimiter to insert between consecutive elements.
elementsThe iterator of elements to join.
suffixThe suffix to end the result with.
The created string based on the arguments.
public static String toStringJoin(CharSequence prefix, CharSequence delimiter, Object[] elements, CharSequence suffix)
Creates a string representation of the argument elements with the specified format.

The method converts the given elements into string representation and joins them into a string with the given delimiter between them. The result is then prepended with the given prefix, and appended with the given suffix.

All arguments are nullable, in which case the corresponding part will not be appended to the result. If the elements are null, the delimiters won't be printed either. If all arguments are null, an empty string is returned.

prefixThe prefix to start the result with.
delimiterThe delimiter to insert between consecutive elements.
elementsThe array of elements to join.
suffixThe suffix to end the result with.
The created string based on the arguments.
public static String toStringJoin(CharSequence delimiter, Iterable<?> elements)
Creates a string representation of the argument elements joined with the given delimiter.

Same as:

 toStringJoin(null, delimiter, elements, null);
 
delimiterThe delimiter to insert between consecutive elements.
elementsThe elements to join.
The created string based on the arguments.
public static String toStringJoin(CharSequence delimiter, Iterator<?> elements)
Creates a string representation of the argument elements joined with the given delimiter.

Same as:

 toStringJoin(null, delimiter, elements, null);
 
delimiterThe delimiter to insert between consecutive elements.
elementsThe iterator of elements to join.
The created string based on the arguments.
public static String toStringJoin(CharSequence delimiter, Object[] elements)
Creates a string representation of the argument elements joined with the given delimiter.

Same as:

 toStringJoin(null, delimiter, elements, null);
 
delimiterThe delimiter to insert between consecutive elements.
elementsThe array of elements to join.
The created string based on the arguments.
public static String toStringLimit(Object obj, int limit)
Converts the argument objects to string representation, but limiting its length if it is longer than the maximum limit.
objThe object to convert to string.
limitThe maximum number of characters the result can contain.
The limited string representation of the object.
public static String toStringLimit(Object obj, int limit, String ellipsizeend)
Converts the argument objects to string representation, but limiting its length if it is longer than the maximum limit, and adding an ellipsize if limited.

This method works the same way as toStringLimit(Object, int, String), but if the return value is actually limited by its length, then the ellipsize argument will be appended to it to signal that it got cropped.

objThe object to convert to string.
limitThe maximum number of characters the result can contain. (Excluding the ellipsize ending.)
ellipsizeendThe ellipsize ending that should be appended if the result is cropped.
The limited string representation of the object.
public static String toStringQuoted(String str)
Returns the argument string with quotes around it unless it is null.
strThe string to quote.
"null" (without quotes in the actual result string) if the argument is null, or the given string with '\"' characters around it.