Package com.globalmentor.java
Class CharSequences
java.lang.Object
com.globalmentor.java.CharSequences
Various text manipulating functions. These methods work on objects that implement the
CharSequence
interface. To avoid creation of new strings, some
of these methods should be avoided in favor of their corresponding StringBuilders
methods, which operate on StringBuilder
objects.- Author:
- Garret Wilson
- See Also:
-
Field Summary
Modifier and TypeFieldDescriptionstatic final ToIntBiFunction<CharSequence,
CharSequence> Strategy for constraining that truncates at the end of a character sequence.static final ToIntBiFunction<CharSequence,
CharSequence> Strategy for constraining that truncates in the middle of a character sequence.static final ToIntBiFunction<CharSequence,
CharSequence> Strategy for constraining that truncates at the start of a character sequence. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic int
charIndexOf
(CharSequence charSequence, Characters characters) Deprecated.static int
charIndexOf
(CharSequence charSequence, Characters characters, int index) Deprecated.to be removed in favor ofindexOf(CharSequence, Characters, int)
.static int
charLastIndexOf
(CharSequence charSequence, Characters characters) Deprecated.to be removed in favor oflastIndexNotOf(CharSequence, Characters)
.static int
charLastIndexOf
(CharSequence charSequence, Characters characters, int index) Deprecated.to be removed in favor oflastIndexOf(CharSequence, Characters, int)
.static CharSequence
checkBounds
(CharSequence charSequence, int start, int end) Checks the given bounds of a character sequence.static <T extends CharSequence>
TcheckMinLength
(T charSequence, int minLength) Ensures that the given character sequence has a minimum the specified number of characters.static CharSequence
constrain
(CharSequence charSequence, int maxLength, ToIntBiFunction<CharSequence, CharSequence> truncateIndexStrategy, CharSequence omissionSequence) Ensures a sequence of characters is not longer than the given maximum, by truncating if necessary and replacing with an omission sequence.static boolean
contains
(CharSequence charSequence, char character) Determines if a character sequence contains the given character.static boolean
contains
(CharSequence charSequence, Characters characters) Determines if a character sequence contains any of the given characters.static boolean
containsLetter
(CharSequence charSequence) Determines if the following character sequence contains a letter.static boolean
containsLetterOrDigit
(CharSequence charSequence) Determines if the following character sequence contains a letter or a digit.static boolean
containsNonTrim
(CharSequence charSequence) Determines if a character sequence contains characters that are not characters that can be trimmed.static boolean
containsNonWhitespace
(CharSequence charSequence) Determines if a character sequence contains characters that are not Unicode whitespace (marked by "WS" in Unicode data).static boolean
containsOnly
(CharSequence charSequence, Characters characters) Determines if a character sequence contains only the given characters.static boolean
containsToken
(CharSequence charSequence, Characters delimiters, CharSequence... tokens) Searches the given character sequence for one of the given tokens, separated by the given delimiters.static boolean
containsTrim
(CharSequence charSequence) Determines if a character sequence contains characters that can be trimmed.static boolean
containsWhitespace
(CharSequence charSequence) Determines if a character sequence contains Unicode whitespace.static int
count
(CharSequence charSequence, char character) Counts the number of occurrences of a particular character in a character sequence.static int
count
(CharSequence charSequence, char character, int index) Counts the number of occurrences of a particular character in a character sequence, starting at a specified index and searching forward.static CharSequence
denull
(CharSequence charSequence) Turns a null character sequence into an empty character sequence.static boolean
endsWith
(CharSequence charSequence, char character) Determines if the character sequence ends with the given character.static boolean
endsWith
(CharSequence charSequence, Characters characters) Determines if the character sequence ends with one of the given characters.static boolean
endsWith
(CharSequence charSequence, String string) Determines if the character sequence ends with the given string.static boolean
endsWithIgnoreCase
(CharSequence charSequence, String string) Determines if the character sequence ends with the given string without case sensitivity.static boolean
equals
(CharSequence charSequence, char character) Determines if the given character sequence is composed of the single given character.static boolean
equals
(CharSequence charSequence1, int start1, int end1, CharSequence charSequence2, int start2, int end2) Compares characters in one character sequence with characters in another character sequence.static boolean
equals
(CharSequence charSequence1, CharSequence charSequence2) Compares the characters in one character sequence with characters in another character sequence.static boolean
equals
(CharSequence charSequence1, CharSequence charSequence2, int start) Compares the characters in one character sequence with characters in another character sequence, starting at the given location to the end of the second character sequence.static boolean
equals
(CharSequence charSequence1, CharSequence charSequence2, int start, int end) Compares the characters in one character sequence with characters in another character sequence.static String
escape
(CharSequence charSequence, Characters restricted, char escape) Escapes a given string by inserting an escape character before every restricted character, including any occurrence of the given escape character.static String
escapeHex
(CharSequence charSequence, Characters validCharacters, Characters invalidCharacters, int maxCharacter, char escapeChar, int escapeLength) Escapes the indicated characters in the character sequence using the supplied escape character.static String
escapeHex
(CharSequence charSequence, Characters validCharacters, Characters invalidCharacters, int maxCharacter, char escapeChar, int escapeLength, Case hexCase) Escapes the indicated characters in the character sequence using the supplied escape character.static <S extends CharSequence>
SgetStartsWith
(CharSequence charSequence, int index, Collection<S> strings) Determines which if any of the given strings the character sequence starts with, starting at the given index.static <S extends CharSequence>
SgetStartsWith
(CharSequence charSequence, Collection<S> strings) Determines which if any of the given strings the character sequence starts with.static CharSequence
getToken
(CharSequence charSequence, Characters delimiters, CharSequence... tokens) Searches the given character sequence for one of the given tokens, separated by the given delimiters.static int
indexNotOf
(CharSequence charSequence, char character) Determines the first index not of the given character.static int
indexNotOf
(CharSequence charSequence, char character, int index) Determines the first index not of the given character.static int
indexNotOf
(CharSequence charSequence, Characters characters) Searches a character sequence and returns the first index of any character not of the given characters, starting at the beginning.static int
indexNotOf
(CharSequence charSequence, Characters characters, int index) Searches a character sequence and returns the first index of any character not of the given characters, starting at the given index.static int
indexNotOfLength
(CharSequence charSequence, char character) Determines the first index not of the given character.static int
indexNotOfLength
(CharSequence charSequence, char character, int index) Determines the first index not of the given character.static int
indexNotOfLength
(CharSequence charSequence, Characters characters) Searches a character sequence and returns the first index of any character not of the given characters, starting at the beginning.static int
indexNotOfLength
(CharSequence charSequence, Characters characters, int index) Searches a character sequence and returns the first index of any character not of the given characters, starting at the given index.static int
indexOf
(CharSequence charSequence, char character) Determines the first index of the given character.static int
indexOf
(CharSequence charSequence, char character, int index) Determines the first index of the given character.static int
indexOf
(CharSequence charSequence, Characters characters) Searches a character sequence and returns the first index of any character of the given characters, starting at the beginning.static int
indexOf
(CharSequence charSequence, Characters characters, int index) Searches a character sequence and returns the first index of any character of the given characters, starting at the given index.static int
indexOfLength
(CharSequence charSequence, char character) Determines the first index of the given character.static int
indexOfLength
(CharSequence charSequence, char character, int index) Determines the first index of the given character.static int
indexOfLength
(CharSequence charSequence, Characters characters) Searches a character sequence and returns the first index of any character of the given characters, starting at the beginning.static int
indexOfLength
(CharSequence charSequence, Characters characters, int index) Searches a character sequence and returns the first index of any character of the given characters, starting at the given index.static final boolean
isAll
(CharSequence charSequence, char c) Determines if the character sequence consists of nothing but the following character.static final boolean
isAllChars
(CharSequence charSequence, Characters characters) Determines if the character sequence consists of nothing but the given characters.static final boolean
isCapitalized
(CharSequence charSequence) Determines whether a character sequence is capitalized.static final boolean
isDigits
(CharSequence charSequence) Determines whether a character sequence contains only Unicode digits.static final boolean
isLatinDigits
(CharSequence charSequence) Deprecated.Create separateisCharacters()
method and useASCII.DIGIT_CHARACTERS
.static final boolean
isLetters
(CharSequence charSequence) Determines whether a character sequence contains only Unicode letters.static final boolean
isLettersDigits
(CharSequence charSequence) Determines whether a character sequence contains only Unicode letters and digits.static final boolean
isLettersDigitsCharacters
(CharSequence charSequence, String characters) Determines whether a character sequence contains only Unicode letters, digits, and the supplied extra characters.static final boolean
isNumber
(CharSequence charSequence) Determines whether a character sequence contains only numbers and decimals or commas.static final boolean
isRomanNumerals
(CharSequence charSequence) Determines whether a character sequence contains only Roman numerals.static final boolean
isUpperCase
(CharSequence charSequence) Determines whether all the letters in a character sequence are capital letters.static CharSequence
join
(char delimiter, CharSequence... charSequences) Concatenates the given character sequences, separated by the given delimiter.static CharSequence
join
(CharSequence... charSequences) Concatenates the given character sequences with no delimiter between them.static int
lastIndexNotOf
(CharSequence charSequence, char character) Determines the last index not of the given character.static int
lastIndexNotOf
(CharSequence charSequence, char character, int index) Determines the last index not of the given character.static int
lastIndexNotOf
(CharSequence charSequence, Characters characters) Searches a character sequence and returns the last index of any character not of the given characters.static int
lastIndexNotOf
(CharSequence charSequence, Characters characters, int index) Searches a character sequence and returns the last index of any character not of the given characters, starting at the given index.static int
lastIndexOf
(CharSequence charSequence, char character) Determines the last index of the given character.static int
lastIndexOf
(CharSequence charSequence, char character, int index) Determines the last index of the given character.static int
lastIndexOf
(CharSequence charSequence, Characters characters) Searches a character sequence and returns the last index of any character of the given characters.static int
lastIndexOf
(CharSequence charSequence, Characters characters, int index) Searches a character sequence and returns the last index of any character of the given characters, starting at the given index.longestCommonSegmentSuffix
(List<? extends CharSequence> charSequences, char delimiter) Determines the longest common suffix of segments from a list of character sequences.static String
normalizeForSearch
(CharSequence charSequence) Normalizes a string so that it can be used as a liberally matching lookup without regard to diacritics or case.static String
normalizeForSearch
(CharSequence charSequence, Locale locale) Normalizes a string so that it can be used as a liberally matching lookup without regard to diacritics or case.static int
notCharIndexOf
(CharSequence charSequence, Characters notCharacters) Deprecated.to be removed in favor ofindexNotOf(CharSequence, Characters)
.static int
notCharIndexOf
(CharSequence charSequence, Characters notCharacters, int index) Deprecated.to be removed in favor ofindexNotOf(CharSequence, Characters, int)
.static int
notCharLastIndexOf
(CharSequence charSequence, Characters notCharacters) Deprecated.to be removed in favor oflastIndexNotOf(CharSequence, Characters)
.static int
notCharLastIndexOf
(CharSequence charSequence, Characters notCharacters, int index) Deprecated.to be removed in favor oflastIndexNotOf(CharSequence, Characters, int)
.static boolean
notContains
(CharSequence charSequence, char character) Determines if a character sequence does not contain the given character.static boolean
notContains
(CharSequence charSequence, Characters characters) Determines if a character sequence does not contain any of the given characters.static boolean
notContainsOnly
(CharSequence charSequence, Characters characters) Determines if a character sequence does not contain only the given characters.static <CS extends CharSequence>
CSnullify
(CS charSequence) Turns an empty character sequence intonull
.static String
removeMarks
(CharSequence charSequence) Removes all normalized Unicode marks such as accents from a string.static CharSequence[]
split
(CharSequence charSequence, char delimiter) Deprecated.static boolean
startsWith
(CharSequence charSequence, char character) Determines if the character sequence starts with the given character.static boolean
startsWith
(CharSequence charSequence, int index, CharSequence string) Determines if the character sequence starts with the given string, starting at the given index.static boolean
startsWith
(CharSequence charSequence, Characters characters) Determines if the character sequence starts with one of the given characters.static boolean
startsWith
(CharSequence charSequence, CharSequence string) Determines if the character sequence starts with the given string.static boolean
startsWithChar
(CharSequence charSequence, Characters characters) Determines if the character sequence starts with one of the given characters.static char[]
toCharArray
(CharSequence charSequence) Returns a character array containing the characters from the given character sequence.static CharSequence
truncateAtFirst
(CharSequence charSequence, char truncateChar) Truncates the end of the string beginning at the first occurrence of the given character.static CharSequence
truncateAtLast
(CharSequence charSequence, char truncateChar) Truncates the end of the string beginning at the last occurrence of the given character.static CharSequence
unescapeHex
(CharSequence charSequence, char escapeChar, int escapeLength) Decodes the escaped characters in the character sequence by converting the hex value after each occurrence of the escape character to the corresponding Unicode character using UTF-8.
-
Field Details
-
CONSTRAIN_TRUNCATE_START
Strategy for constraining that truncates at the start of a character sequence. -
CONSTRAIN_TRUNCATE_MIDDLE
Strategy for constraining that truncates in the middle of a character sequence. -
CONSTRAIN_TRUNCATE_END
Strategy for constraining that truncates at the end of a character sequence.
-
-
Constructor Details
-
CharSequences
public CharSequences()
-
-
Method Details
-
checkBounds
Checks the given bounds of a character sequence.- Parameters:
charSequence
- The character sequence against which the bounds should be checked.start
- The start to check, inclusive.end
- The end to check, exclusive.- Returns:
- The given character sequence.
- Throws:
StringIndexOutOfBoundsException
- ifstart
orend
is negative or greater thanlength()
, orstart
is greater thanend
.
-
charIndexOf
Deprecated.to be removed in favor ofindexOf(CharSequence, Characters)
.Searches a character sequence and returns the first index of any specified characters, starting at the beginning.- Parameters:
charSequence
- The character sequence to be searched.characters
- The string of characters to check.- Returns:
- The index of the first occurrence of one of the supplied characters, or -1 if none were found.
-
charIndexOf
@Deprecated public static int charIndexOf(CharSequence charSequence, Characters characters, int index) Deprecated.to be removed in favor ofindexOf(CharSequence, Characters, int)
.Searches a character sequence and returns the first index of any specified characters, starting at the given index.- Parameters:
charSequence
- The character sequence to be searched.characters
- The string of characters to check.index
- The index to search from.- Returns:
- The index of the first occurrence of one of the supplied characters, or -1 if none were found.
-
charLastIndexOf
Deprecated.to be removed in favor oflastIndexNotOf(CharSequence, Characters)
.Searches a character sequence in reverse and returns the last index of any specified characters.- Parameters:
charSequence
- The character sequence to be searched.characters
- The string of characters to check.- Returns:
- The index of the last occurrence of one of the supplied characters, or -1 if none were found.
-
charLastIndexOf
@Deprecated public static int charLastIndexOf(CharSequence charSequence, Characters characters, int index) Deprecated.to be removed in favor oflastIndexOf(CharSequence, Characters, int)
.Searches a character sequence in reverse and returns the last index of any specified characters, starting from the given index.- Parameters:
charSequence
- The character sequence to be searched.characters
- The string of characters to check.index
- The index to search from.- Returns:
- The index of the last occurrence of one of the supplied characters, or -1 if none were found.
-
checkMinLength
Ensures that the given character sequence has a minimum the specified number of characters.- Type Parameters:
T
- The type of character sequence being used.- Parameters:
charSequence
- The character sequence to check.minLength
- The minimum length required.- Returns:
- The given character sequence.
- Throws:
NullPointerException
- if the given character sequence isnull
.IllegalArgumentException
- if the length of the given character sequence is less than the indicated minimum length.
-
constrain
public static CharSequence constrain(@Nonnull CharSequence charSequence, @Nonnegative int maxLength, @Nonnull ToIntBiFunction<CharSequence, CharSequence> truncateIndexStrategy, @Nonnull CharSequence omissionSequence) Ensures a sequence of characters is not longer than the given maximum, by truncating if necessary and replacing with an omission sequence.- API Note:
- Normally one of the existing truncate index strategies should be used.
- Implementation Note:
- The returned character sequence is meant to be used and discarded; it may be mutable and may retain references to larger buffers. If the
character sequence is to be referenced for a longer time, it should be converted to a string using
CharSequence.toString()
. - Parameters:
charSequence
- The character sequence to constrain.maxLength
- The maximum length to constrain; must not be negative.truncateIndexStrategy
- The strategy for determining the initial index to truncate, given a non-empty character sequence and a non-null
omission sequence which may be empty. The omission sequence is guaranteed to be less than the maximum length. The strategy may provide any valid index within the original character sequence; this method will make the any further adjustments as necessary to constrain the string.omissionSequence
- The sequence (e.g. an ellipsis or three dots), which may be empty, to be inserted in place of any truncated characters. If the omission sequence is longer than the maximum length, the omission sequence itself will be truncated arbitrarily.- Returns:
- The label constrained to a certain length.
- Throws:
IllegalArgumentException
- if the maximum length is negative.IndexOutOfBoundsException
- if the truncate index strategy returns an index not within the range of the original character sequence (end exclusive).- See Also:
-
contains
Determines if a character sequence contains the given character.- Parameters:
charSequence
- The character sequence to be searched.character
- The character to check.- Returns:
true
if the given character sequence contains the given character.
-
notContains
Determines if a character sequence does not contain the given character.- Parameters:
charSequence
- The character sequence to be searched.character
- The character to check.- Returns:
true
if the given character sequence does not contain the given character.
-
contains
Determines if a character sequence contains any of the given characters.- Parameters:
charSequence
- The character sequence to be searched.characters
- The characters to check.- Returns:
true
if the given character sequence contains one of the given characters.
-
notContains
Determines if a character sequence does not contain any of the given characters.- Parameters:
charSequence
- The character sequence to be searched.characters
- The characters to check.- Returns:
true
if the given character sequence does not contain one of the given characters.
-
containsOnly
Determines if a character sequence contains only the given characters.- Parameters:
charSequence
- The character sequence to be searched.characters
- The characters to check.- Returns:
true
if the given character sequence contains only the given characters.
-
notContainsOnly
Determines if a character sequence does not contain only the given characters.- Parameters:
charSequence
- The character sequence to be searched.characters
- The characters to check.- Returns:
true
if the given character sequence does not contain only the given characters.
-
containsLetter
Determines if the following character sequence contains a letter.- Parameters:
charSequence
- The character sequence to search.- Returns:
true
if the sequence has at least one letter.
-
containsLetterOrDigit
Determines if the following character sequence contains a letter or a digit.- Parameters:
charSequence
- The character sequence to search.- Returns:
true
if the sequence has at least one letter or digit.- See Also:
-
containsWhitespace
Determines if a character sequence contains Unicode whitespace. Whitespace is denoted by the "WS" bidi class inUnicodeData.txt
. This method does not handle Unicode supplementary characters.- Parameters:
charSequence
- The character sequence to be searched.- Returns:
true
if the given character sequence contains whitespace.- See Also:
-
containsNonWhitespace
Determines if a character sequence contains characters that are not Unicode whitespace (marked by "WS" in Unicode data). Whitespace is denoted by the "WS" bidi class inUnicodeData.txt
. This method does not handle Unicode supplementary characters.- Parameters:
charSequence
- The character sequence to be searched.- Returns:
true
if the given character sequence contains non-whitespace.- See Also:
-
containsToken
public static boolean containsToken(CharSequence charSequence, Characters delimiters, CharSequence... tokens) Searches the given character sequence for one of the given tokens, separated by the given delimiters.- Parameters:
charSequence
- The character sequence to search.delimiters
- The delimiters to skip.tokens
- The tokens for which to check.- Returns:
- The
true
if one of the given tokens was found. - Throws:
NullPointerException
- if the given character sequence, delimiters, and/or tokens isnull
.
-
getToken
public static CharSequence getToken(CharSequence charSequence, Characters delimiters, CharSequence... tokens) Searches the given character sequence for one of the given tokens, separated by the given delimiters.- Parameters:
charSequence
- The character sequence to search.delimiters
- The delimiters to skip.tokens
- The tokens for which to check.- Returns:
- The token that was found, or
null
if no token was found. - Throws:
NullPointerException
- if the given character sequence, delimiters, and/or tokens isnull
.
-
containsTrim
Determines if a character sequence contains characters that can be trimmed. Trimmed characters are denoted by the "WS" (whitespace) bidi class, the "Cc" (control) category, or the "Cf" (format) category inUnicodeData.txt
. This method does not handle Unicode supplementary characters.- Parameters:
charSequence
- The character sequence to be searched.- Returns:
true
if the given character sequence contains trim characters.- See Also:
-
containsNonTrim
Determines if a character sequence contains characters that are not characters that can be trimmed. This is useful for determining if a characer sequence actually contains useful data. Trimmed characters are denoted by the "WS" (whitespace) bidi class, the "Cc" (control) category, or the "Cf" (format) category inUnicodeData.txt
. This method does not handle Unicode supplementary characters.- Parameters:
charSequence
- The character sequence to be searched.- Returns:
true
if the given character sequence contains non-trim characters.- See Also:
-
count
Counts the number of occurrences of a particular character in a character sequence.- Parameters:
charSequence
- The character sequence to examine.character
- The character to count.- Returns:
- The number of occurrences of the character in the character sequence.
-
count
Counts the number of occurrences of a particular character in a character sequence, starting at a specified index and searching forward.- Parameters:
charSequence
- The character sequence to examine.character
- The character to count.index
- The index to start counting at.- Returns:
- The number of occurrences of the character in the character sequence.
-
endsWith
Determines if the character sequence ends with the given character.- Parameters:
charSequence
- The character sequence to examine.character
- The character to compare.- Returns:
true
if the last character of the character sequence matches the given character.
-
endsWith
Determines if the character sequence ends with one of the given characters.- Parameters:
charSequence
- The character sequence to examine.characters
- The characters to compare.- Returns:
true
if the last character of the character sequence matches one of the given characters.- See Also:
-
endsWith
Determines if the character sequence ends with the given string.- Parameters:
charSequence
- The character sequence to examine.string
- The string to compare.- Returns:
true
if the last characters of the character sequence match those of the given string.
-
endsWithIgnoreCase
Determines if the character sequence ends with the given string without case sensitivity.- Parameters:
charSequence
- The character sequence to examine.string
- The string to compare.- Returns:
true
if the last characters of the character sequence match those of the given string, case insensitively.
-
escape
Escapes a given string by inserting an escape character before every restricted character, including any occurrence of the given escape character.- Implementation Specification:
- This implementation delegates to
StringBuilders.escape(StringBuilder, Characters, char)
. - Parameters:
charSequence
- The data to escape.restricted
- The characters to be escaped; should not include the escape character.escape
- The character used to escape the restricted characters.- Returns:
- A string containing the escaped data.
- Throws:
NullPointerException
- if the given character sequence isnull
.
-
escapeHex
public static String escapeHex(CharSequence charSequence, Characters validCharacters, Characters invalidCharacters, int maxCharacter, char escapeChar, int escapeLength) Escapes the indicated characters in the character sequence using the supplied escape character. All characters are first encoded using UTF-8. Every invalid character is converted to its Unicode hex equivalent and prefixed with the given escape character. This method uses lowercase hexadecimal escape codes. Characters are assumed to be valid unless specified otherwise. The escape character, if encountered, is not escaped unless it specifically meets one of the specified criteria; this allows re-escaping strings that may contain escape characters produced under less-strict rules (e.g. a URI containing escaped restricted characters, but still containing non-ASCII characters).- Parameters:
charSequence
- The data to escape.validCharacters
- The characters that should not be escaped and all others should be escaped, ornull
if characters should not be matched against valid characters.invalidCharacters
- The characters that, if they appear, should be escaped, ornull
if characters should not be matched against invalid characters.maxCharacter
- The character value that represents the highest non-escaped value.escapeChar
- The character to prefix the hex representation.escapeLength
- The number of characters to use for the hex representation.- Returns:
- A string containing the escaped data.
- Throws:
IllegalArgumentException
- if neither valid nor invalid characters are given.
-
escapeHex
public static String escapeHex(CharSequence charSequence, Characters validCharacters, Characters invalidCharacters, int maxCharacter, char escapeChar, int escapeLength, Case hexCase) Escapes the indicated characters in the character sequence using the supplied escape character. All characters are first encoded using UTF-8. Every invalid character is converted to its Unicode hex equivalent and prefixed with the given escape character. Characters are assumed to be valid unless specified otherwise. The escape character, if encountered, is not escaped unless it specifically meets one of the specified criteria; this allows re-escaping strings that may contain escape characters produced under less-strict rules (e.g. a URI containing escaped restricted characters, but still containing non-ASCII characters).- Parameters:
charSequence
- The data to escape.validCharacters
- The characters that should not be escaped and all others should be escaped, ornull
if characters should not be matched against valid characters.invalidCharacters
- The characters that, if they appear, should be escaped, ornull
if characters should not be matched against invalid characters.maxCharacter
- The character value that represents the highest non-escaped value.escapeChar
- The character to prefix the hex representation.escapeLength
- The number of characters to use for the hex representation.hexCase
- Whether the hex characters should be lowercase or uppercase.- Returns:
- A string containing the escaped data.
- Throws:
IllegalArgumentException
- if neither valid nor invalid characters are given.
-
unescapeHex
public static CharSequence unescapeHex(CharSequence charSequence, char escapeChar, int escapeLength) Decodes the escaped characters in the character sequence by converting the hex value after each occurrence of the escape character to the corresponding Unicode character using UTF-8.- Parameters:
charSequence
- The data to unescape.escapeChar
- The character that prefixes the hex representation.escapeLength
- The number of characters used for the hex representation.- Returns:
- A character sequence containing the unescaped data.
- Throws:
IllegalArgumentException
- if a given escape character is not followed by an escape sequence.IllegalArgumentException
- if an encountered escape sequence is not valid UTF-8.
-
indexOf
Determines the first index of the given character.- Parameters:
charSequence
- The character sequence to check.character
- The character to search for.- Returns:
- The index of the first occurrence of the given character, or -1 if the character was not found.
-
indexOfLength
Determines the first index of the given character.- Parameters:
charSequence
- The character sequence to check.character
- The character to search for.- Returns:
- The index of the first occurrence of the given character, or the length of the character sequence if the character was not found.
-
indexOf
Determines the first index of the given character.- Implementation Specification:
- If the character sequence is a
String
, this method delegates toString.indexOf(int, int)
. - Parameters:
charSequence
- The character sequence to check.character
- The character to search for.index
- The first index to examine.- Returns:
- The index of the first occurrence of the given character, or -1 if the character was not found.
-
indexOfLength
Determines the first index of the given character.- Implementation Specification:
- If the character sequence is a
String
, this method delegates toString.indexOf(int, int)
. - Parameters:
charSequence
- The character sequence to check.character
- The character to search for.index
- The first index to examine.- Returns:
- The index of the first occurrence of the given character, or the length of the character sequence if the character was not found.
-
indexOf
Searches a character sequence and returns the first index of any character of the given characters, starting at the beginning.- Parameters:
charSequence
- The character sequence to be searched.characters
- The characters to check.- Returns:
- The index of the first occurrence of one of the supplied characters, or -1 if none were found.
-
indexOfLength
Searches a character sequence and returns the first index of any character of the given characters, starting at the beginning.- Parameters:
charSequence
- The character sequence to be searched.characters
- The characters to check.- Returns:
- The index of the first occurrence of one of the supplied characters, or the length of the character sequence if none were found.
-
indexOf
Searches a character sequence and returns the first index of any character of the given characters, starting at the given index.- Parameters:
charSequence
- The character sequence to be searched.characters
- The characters to check.index
- The index to search from.- Returns:
- The index of the first occurrence of one of the supplied characters, or -1 if none were found.
-
indexOfLength
Searches a character sequence and returns the first index of any character of the given characters, starting at the given index.- Parameters:
charSequence
- The character sequence to be searched.characters
- The characters to check.index
- The index to search from.- Returns:
- The index of the first occurrence of one of the supplied characters, or the length of the character sequence if none were found.
-
lastIndexOf
Determines the last index of the given character.- Parameters:
charSequence
- The character sequence to check.character
- The character to search for.- Returns:
- The index of the last occurrence of the given character, or -1 if the character was not found.
- See Also:
-
lastIndexOf
Determines the last index of the given character.- Implementation Specification:
- If the character sequence is a
String
, this method delegates toString.lastIndexOf(int, int)
. - Parameters:
charSequence
- The character sequence to check.character
- The character to search for.index
- The last index to examine; if greater than or equal to the length of this character sequence, it has the same effect as if it were equal to one less than the length of this character sequence, and the entire character sequence may be searched; if negative, it has the same effect as if it were -1, and -1 is returned.- Returns:
- The index of the last occurrence of the given character, or -1 if the character was not found.
- See Also:
-
lastIndexOf
Searches a character sequence and returns the last index of any character of the given characters.- Parameters:
charSequence
- The character sequence to be searched.characters
- The characters to check.- Returns:
- The index of the last occurrence of one of the supplied characters, or -1 if none were found.
- See Also:
-
lastIndexOf
Searches a character sequence and returns the last index of any character of the given characters, starting at the given index.- Parameters:
charSequence
- The character sequence to be searched.characters
- The characters to check.index
- The last index to examine; if greater than or equal to the length of this character sequence, it has the same effect as if it were equal to one less than the length of this character sequence, and the entire character sequence may be searched; if negative, it has the same effect as if it were -1, and -1 is returned.- Returns:
- The index of the last occurrence of one of the supplied characters, or -1 if none were found.
- See Also:
-
indexNotOf
Determines the first index not of the given character.- Parameters:
charSequence
- The character sequence to check.character
- The character to search for.- Returns:
- The index of the first occurrence not of the given character, or -1 if only the character was not found.
-
indexNotOfLength
Determines the first index not of the given character.- Parameters:
charSequence
- The character sequence to check.character
- The character to search for.- Returns:
- The index of the first occurrence not of the given character, or the length of the character sequence if only the character was not found.
-
indexNotOf
Determines the first index not of the given character.- Parameters:
charSequence
- The character sequence to check.character
- The character to search for.index
- The first index to examine.- Returns:
- The index of the first occurrence not of the given character, or -1 if only the character was not found.
-
indexNotOfLength
Determines the first index not of the given character.- Parameters:
charSequence
- The character sequence to check.character
- The character to search for.index
- The first index to examine.- Returns:
- The index of the first occurrence not of the given character, or the length of the character sequence if only the character was not found.
-
indexNotOf
Searches a character sequence and returns the first index of any character not of the given characters, starting at the beginning.- Parameters:
charSequence
- The character sequence to be searched.characters
- The characters to check.- Returns:
- The index of the first occurrence not of one of the supplied characters, or -1 if only the characters were found.
-
indexNotOfLength
Searches a character sequence and returns the first index of any character not of the given characters, starting at the beginning.- Parameters:
charSequence
- The character sequence to be searched.characters
- The characters to check.- Returns:
- The index of the first occurrence not of one of the supplied characters, or the length of the character sequence if only the characters were found.
-
indexNotOf
Searches a character sequence and returns the first index of any character not of the given characters, starting at the given index.- Parameters:
charSequence
- The character sequence to be searched.characters
- The characters to check.index
- The index to search from.- Returns:
- The index of the first occurrence not of one of the supplied characters, or -1 if only the characters were found.
-
indexNotOfLength
Searches a character sequence and returns the first index of any character not of the given characters, starting at the given index.- Parameters:
charSequence
- The character sequence to be searched.characters
- The characters to check.index
- The index to search from.- Returns:
- The index of the first occurrence not of one of the supplied characters, or the length of the character sequence if only the characters were found.
-
lastIndexNotOf
Determines the last index not of the given character.- Parameters:
charSequence
- The character sequence to check.character
- The character to search for.- Returns:
- The index of the last occurrence not of the given character, or -1 if only the character was not found.
- See Also:
-
lastIndexNotOf
Determines the last index not of the given character.- Parameters:
charSequence
- The character sequence to check.character
- The character to search for.index
- The last index to examine; if greater than or equal to the length of this character sequence, it has the same effect as if it were equal to one less than the length of this character sequence, and the entire character sequence may be searched; if negative, it has the same effect as if it were -1, and -1 is returned.- Returns:
- The index of the last occurrence not of the given character, or -1 if only the character was not found.
- See Also:
-
lastIndexNotOf
Searches a character sequence and returns the last index of any character not of the given characters.- Parameters:
charSequence
- The character sequence to be searched.characters
- The characters to check.- Returns:
- The index of the last occurrence not of one of the supplied characters, or -1 if only the characters were found.
- See Also:
-
lastIndexNotOf
Searches a character sequence and returns the last index of any character not of the given characters, starting at the given index.- Parameters:
charSequence
- The character sequence to be searched.characters
- The characters to check.index
- The last index to examine; if greater than or equal to the length of this character sequence, it has the same effect as if it were equal to one less than the length of this character sequence, and the entire character sequence may be searched; if negative, it has the same effect as if it were -1, and -1 is returned.- Returns:
- The index of the last occurrence not of one of the supplied characters, or -1 if only the characters were found.
- See Also:
-
longestCommonSegmentSuffix
public static Optional<String> longestCommonSegmentSuffix(@Nonnull List<? extends CharSequence> charSequences, char delimiter) Determines the longest common suffix of segments from a list of character sequences. For example if any combination of the strings"www.example.com"
,"test.example.com"
, and"example.com"
are passed using the delimiter'.'
, the common segment suffix"example.com"
is returned.- API Note:
- This method does not make any checks to determine whether a segment is empty, e.g.
"foo..bar"
. - Implementation Note:
- The current implementation does not distinguish between sequences beginning and/or ending with the delimiter. That is
foo.bar
andfoo.bar.
are considered to have the same common segment suffixfoo.bar
, for example. - Parameters:
charSequences
- The list of character sequences to check.delimiter
- The delimiter to use in determining the segments.- Returns:
- A string representing the longest common suffix of segments, which may not be present if there is no longest common segment suffix.
- Throws:
NullPointerException
- if the list isnull
or contains anull
value.
-
notCharIndexOf
Deprecated.to be removed in favor ofindexNotOf(CharSequence, Characters)
.Searches a character sequence and returns the first index of any character not in the specified characters, starting from the beginning.- Parameters:
charSequence
- The character sequence to be searched.notCharacters
- The characters to check.- Returns:
- The index of the first occurrence of one of the supplied characters, or -1 if none were found.
-
notCharIndexOf
@Deprecated public static int notCharIndexOf(CharSequence charSequence, Characters notCharacters, int index) Deprecated.to be removed in favor ofindexNotOf(CharSequence, Characters, int)
.Searches a character sequence and returns the first index of any character not in the specified characters, starting at the given index.- Parameters:
charSequence
- The character sequence to be searched.notCharacters
- The characters to check.index
- The index to search from.- Returns:
- The index of the first occurrence of one of the supplied characters, or -1 if none were found.
-
notCharLastIndexOf
@Deprecated public static int notCharLastIndexOf(CharSequence charSequence, Characters notCharacters) Deprecated.to be removed in favor oflastIndexNotOf(CharSequence, Characters)
.Searches a character sequence and returns the last index of any character not in the specified characters, starting at the last index.- Parameters:
charSequence
- The character sequence to be searched.notCharacters
- The characters to check.- Returns:
- The index of the last occurrence of one of the supplied characters, or -1 if none were found.
-
notCharLastIndexOf
@Deprecated public static int notCharLastIndexOf(CharSequence charSequence, Characters notCharacters, int index) Deprecated.to be removed in favor oflastIndexNotOf(CharSequence, Characters, int)
.Searches a character sequence and returns the last index of any character not in the specified characters, starting at the given index.- Parameters:
charSequence
- The character sequence to be searched.notCharacters
- The characters to check.index
- The last index to examine; if greater than or equal to the length of this character sequence, it has the same effect as if it were equal to one less than the length of this character sequence, and the entire character sequence may be searched; if negative, it has the same effect as if it were -1, and -1 is returned.- Returns:
- The index of the last occurrence of one of the supplied characters, or -1 if none were found.
-
isAll
Determines if the character sequence consists of nothing but the following character.- Parameters:
charSequence
- The character sequence to examine.c
- The character that could make up the entire sequence.- Returns:
true
if there are no other characters but the specified character,false
if there are other characters or if the string is the empty string.
-
isAllChars
Determines if the character sequence consists of nothing but the given characters.- Parameters:
charSequence
- The character sequence to examine.characters
- The characters that could make up the entire string, in any order.- Returns:
true
if there are no other characters but the specified characters,false
if there are other characters or if the character sequence is empty.
-
isCapitalized
Determines whether a character sequence is capitalized. A character sequence is capitalized if it contains any characters and the first character is uppercase.- Parameters:
charSequence
- The character sequence to examine.- Returns:
true
if the character sequence is capitalized.
-
isDigits
Determines whether a character sequence contains only Unicode digits.- Parameters:
charSequence
- The character sequence to examine.- Returns:
true
if all the characters in the sequence are digits.
-
isLatinDigits
Deprecated.Create separateisCharacters()
method and useASCII.DIGIT_CHARACTERS
.Determines whether a character sequence contains only the digits '0'-'9'.- Parameters:
charSequence
- The character sequence to examine.- Returns:
true
if all the characters in the sequence are ISO_LATIN_1 digits.
-
isLetters
Determines whether a character sequence contains only Unicode letters.- Parameters:
charSequence
- The character sequence to examine.- Returns:
true
if all the characters in the sequence are letters.
-
isLettersDigits
Determines whether a character sequence contains only Unicode letters and digits.- Parameters:
charSequence
- The character sequence to examine.- Returns:
true
if all the characters in the sequence are letters and digits.
-
isLettersDigitsCharacters
Determines whether a character sequence contains only Unicode letters, digits, and the supplied extra characters.- Parameters:
charSequence
- The character sequence to examine.characters
- Extra characters to allow.- Returns:
true
if all the characters in the sequence are letters, digits, and/or allowed characters.
-
isNumber
Determines whether a character sequence contains only numbers and decimals or commas.- Parameters:
charSequence
- The character sequence to examine.- Returns:
true
if all the characters represent a number.
-
isRomanNumerals
Determines whether a character sequence contains only Roman numerals.- Parameters:
charSequence
- The character sequence to examine.- Returns:
true
if all the characters in the sequence are roman numerals.
-
isUpperCase
Determines whether all the letters in a character sequence are capital letters.- Parameters:
charSequence
- The character sequence to examine.- Returns:
true
if all the letters in the sequence are capitalized.
-
join
Concatenates the given character sequences with no delimiter between them.- Parameters:
charSequences
- The character sequences to be concatenated.- Returns:
- The string containing the concatenated character sequences.
- Throws:
NullPointerException
- if the given character sequences isnull
.
-
join
Concatenates the given character sequences, separated by the given delimiter.- Parameters:
delimiter
- The delimiter to be placed between each character sequence, orCharacters.UNDEFINED_CHAR
if no delimiter should be placed between the character sequences.charSequences
- The character sequences to be concatenated.- Returns:
- The string containing the concatenated character sequences.
- Throws:
NullPointerException
- if the given character sequences isnull
.
-
split
Deprecated.Splits a characters sequence into subsequences based upon the given delimiter. Subsequences will be returned between delimiters even if they are empty, and a subsequence will be returned after the last delimiter, even if there are no remaining characters. In other words, the number of character subsequences returned is delimiterCount+1.- Parameters:
charSequence
- The character sequence to split.delimiter
- The delimiter to use for splitting.- Returns:
- An array of character subsequences between the delimiters.
-
removeMarks
Removes all normalized Unicode marks such as accents from a string. For example:- 'é' will be converted to 'e' (Unicode non-spacing marks)
- vowel signs in Hindi will be removed (Unicode spacing combining marks)
- circles around characters will be removed (Unicode enclosing marks)
- Parameters:
charSequence
- The character sequence from which to remove marks.- Returns:
- The normalized string with marks removed.
- See Also:
-
normalizeForSearch
Normalizes a string so that it can be used as a liberally matching lookup without regard to diacritics or case.- Decomposes characters such as fi to fi.
- Removes all normalized Unicode marks such as accents.
- Converts the string to lowercase.
This method converts to lowercase using
Locale.ROOT
. If you wish you supply a specific locale, usenormalizeForSearch(CharSequence, Locale)
.- Parameters:
charSequence
- The character sequence from which to remove marks.- Returns:
- The normalized string with marks removed.
- See Also:
-
normalizeForSearch
Normalizes a string so that it can be used as a liberally matching lookup without regard to diacritics or case.- Decomposes characters such as fi to fi.
- Removes all normalized Unicode marks such as accents.
- Converts the string to lowercase.
- Parameters:
charSequence
- The character sequence from which to remove marks.locale
- The locale to use for normalization; specifically for converting to lowercase.- Returns:
- The normalized string with marks removed.
- See Also:
-
startsWith
Determines if the character sequence starts with the given character.- Parameters:
charSequence
- The character sequence to examine.character
- The character to compare.- Returns:
true
if the first character of the character sequence matches the given character.
-
startsWith
Determines if the character sequence starts with one of the given characters.- Parameters:
charSequence
- The character sequence to examine.characters
- The characters to compare.- Returns:
true
if the first character of the character sequence matches one of the given characters.- See Also:
-
startsWith
Determines if the character sequence starts with the given string.- Parameters:
charSequence
- The character sequence to examine.string
- The string to compare.- Returns:
true
if the first characters of the character sequence match those of the given string.- Throws:
NullPointerException
- if the given string isnull
.
-
startsWith
Determines if the character sequence starts with the given string, starting at the given index.- Parameters:
charSequence
- The character sequence to examine.index
- The index at which to search.string
- The string to compare.- Returns:
true
if the first characters of the character sequence match those of the given string.- Throws:
NullPointerException
- if the given string isnull
.
-
getStartsWith
public static <S extends CharSequence> S getStartsWith(CharSequence charSequence, Collection<S> strings) Determines which if any of the given strings the character sequence starts with.- Type Parameters:
S
- The type of the charSequence.- Parameters:
charSequence
- The character sequence to examine.strings
- The string to compare.- Returns:
- The string beginning the character sequence, or
null
if none of the strings start the character sequence. - Throws:
NullPointerException
- if the collection of strings of any of the strings isnull
.
-
getStartsWith
public static <S extends CharSequence> S getStartsWith(CharSequence charSequence, int index, Collection<S> strings) Determines which if any of the given strings the character sequence starts with, starting at the given index.- Type Parameters:
S
- The type of the charSequence.- Parameters:
charSequence
- The character sequence to examine.index
- The index at which to search.strings
- The string to compare.- Returns:
- The string beginning the character sequence, or
null
if none of the strings start the character sequence. - Throws:
NullPointerException
- if the collection of strings of any of the strings isnull
.
-
startsWithChar
Determines if the character sequence starts with one of the given characters.- Parameters:
charSequence
- The character sequence to examine.characters
- The characters to compare.- Returns:
true
if the first character of the character sequence matches one of those in the given string.
-
toCharArray
Returns a character array containing the characters from the given character sequence.- Parameters:
charSequence
- The character sequence from which to retrieve characters.- Returns:
- A character array containing the characters from the given character sequence.
- Throws:
NullPointerException
- if the given character sequence isnull
.
-
truncateAtFirst
Truncates the end of the string beginning at the first occurrence of the given character. If the character sequence does not contain the truncate character, no action takes place.- Parameters:
charSequence
- The character sequence to check.truncateChar
- The character indicating the part of the sequence to trim.- Returns:
- A new character sequence with the specified character and following characters removed.
-
truncateAtLast
Truncates the end of the string beginning at the last occurrence of the given character. If the character sequence does not contain the truncate character, no action takes place.- Parameters:
charSequence
- The character sequence to check.truncateChar
- The character indicating the part of the sequence to trim.- Returns:
- A new character sequence with the last of the specified character and following characters removed.
-
equals
Determines if the given character sequence is composed of the single given character. This method allows comparison of a character string with a character without creating a string for the character, for example.- Parameters:
charSequence
- The character sequence to compare.character
- The character to compare with the character sequence.- Returns:
true
if the character sequence is composed of one character and that character matches the given character.
-
equals
Compares the characters in one character sequence with characters in another character sequence.- Parameters:
charSequence1
- The character sequence to compare.charSequence2
- The character sequence to compare with.- Returns:
true
if the characters in the first character sequence equal the characters in the second character sequence.
-
equals
Compares the characters in one character sequence with characters in another character sequence, starting at the given location to the end of the second character sequence.- Parameters:
charSequence1
- The character sequence to compare.charSequence2
- The character sequence to compare with.start
- The starting location in the second character sequence, inclusive.- Returns:
true
if the characters in the first character sequence equal the indicated characters in the second character sequence.- Throws:
StringIndexOutOfBoundsException
- ifstart
is negative or greater than the length of the second character sequence.
-
equals
public static boolean equals(CharSequence charSequence1, CharSequence charSequence2, int start, int end) Compares the characters in one character sequence with characters in another character sequence. If the given end of the second character sequence (the character sequence to which the first is being compared) is past the end, it is adjusted to be equal to the end of the second character sequence.- Parameters:
charSequence1
- The character sequence to compare.charSequence2
- The character sequence to compare with.start
- The starting location in the second character sequence, inclusive.end
- The ending location in the second character sequence, exclusive.- Returns:
true
if the characters in the first character sequence equal the indicated characters in the second character sequence.- Throws:
StringIndexOutOfBoundsException
- ifstart
orend
is negative or greater thanlength()
, orstart
is greater thanend
, with the exception that ifend
is greater than the length of the second character sequence it will be adjusted to equal the end.
-
equals
public static boolean equals(CharSequence charSequence1, int start1, int end1, CharSequence charSequence2, int start2, int end2) Compares characters in one character sequence with characters in another character sequence. If the given end of the second character sequence (the character sequence to which the first is being compared) is past the end, it is adjusted to be equal to the end of the second character sequence.- Parameters:
charSequence1
- The character sequence to compare.start1
- The starting location in the first character sequence, inclusive.end1
- The ending location in the first character sequence, exclusive.charSequence2
- The character sequence to compare with.start2
- The starting location in the second character sequence, inclusive.end2
- The ending location in the second character sequence, exclusive.- Returns:
true
if the indicated characters in the first character sequence equal the indicated characters in the second character sequence.- Throws:
StringIndexOutOfBoundsException
- ifstart
orend
is negative or greater thanlength()
, orstart
is greater thanend
, with the exception that ifend2
is greater than the length of the second character sequence it will be adjusted to equal the end.
-
denull
Turns a null character sequence into an empty character sequence.- Parameters:
charSequence
- The character sequence to examine, ornull
.- Returns:
- The given character sequence, or an empty character sequence if the given character sequence is
null
;. - See Also:
-
nullify
Turns an empty character sequence intonull
.- Type Parameters:
CS
- The type of the charSequence.- Parameters:
charSequence
- The character sequence to examine, ornull
.- Returns:
- The given character sequence, or
null
if the given character sequence has no characters or no character sequence was given. - See Also:
-
indexOf(CharSequence, Characters)
.