Class StringsPlume
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
Deprecated.static class
Orders Objects according to theirtoString()
representation. -
Method Summary
Modifier and TypeMethodDescriptionstatic String
abbreviateNumber
(long val) Convert a number into an abbreviation such as "5.00K" for 5000 or "65.0M" for 65000000.static String
arrayToStringAndClass
(@Nullable Object a) Returns a string representation of the contents of the specified array.static String
charLiteral
(char c) Given a character, returns a Java character literal denoting the character.static String
charLiteral
(Character ch) Given a character, returns a Java character literal denoting the character.static String
conjunction
(String conjunction, List<? extends @Signed @PolyNull Object> elements) Creates a conjunction or disjunction, like "a", "a or b", and "a, b, or c".static int
Returns the number of times the character appears in the string.static int
Returns the number of times the second string appears in the first.static int
Returns the number of arguments that the given format string takes.static String
escapeJava
(char c) Deprecated.static String
escapeJava
(Character ch) Deprecated.static String
escapeJava
(String orig) Escapes a String so that it is expressible in a string literal in Java source code.static String
escapeNonASCII
(String orig) Escape unprintable characters in the target, following the usual Java backslash conventions, so that the result is sure to be printable ASCII.static @Regex String
Returns the first line separator in the given string, or "\n" if the string contains none.static String
indentLines
(@org.checkerframework.checker.index.qual.NonNegative int indent, @Nullable Object o) Returns the printed representation of a value, with each line indented byindent
spaces.static String
indentLinesExceptFirst
(@org.checkerframework.checker.index.qual.NonNegative int indent, @Nullable Object o) Returns the printed representation of a value, with each line (except the first) indented byindent
spaces.static boolean
Returns true if the string contains only white space codepoints, otherwise false.static String
join
(CharSequence delim, Iterable<? extends @Signed @PolyNull Object> v) Concatenate the string representations of the objects, placing the delimiter between them.join
(CharSequence delim, @Signed T... a) Concatenate the string representations of the array elements, placing the delimiter between them.static String
Concatenate the string representations of the objects, placing the system-specific line separator between them.joinLines
(@Signed T... a) Concatenate the string representations of the objects, placing the system-specific line separator between them.static String
listToString
(@Nullable List<? extends @Signed @PolyNull Object> lst) For use by toStringAndClass.static String
listToStringAndClass
(@Nullable List<? extends @Signed @PolyNull Object> lst) Gives a string representation of the value and its class.static String
Returns a string of the specified length, truncated if necessary (in which case the last 3 non-truncated characters are replaced by "..."), and padded with spaces to the left if necessary.static String
Returns a string of the specified length, truncated if necessary (in which case the last 3 non-truncated characters are replaced by "..."), and padded with `c` to the left if necessary.static String
lpad
(String s, @org.checkerframework.checker.index.qual.NonNegative int length, char c, boolean truncate) Returns a string of the specified length, truncated if necessary (in which case the last 3 non-truncated characters are replaced by "..."), and padded with spaces to the left if necessary.static String
mapToStringAndClass
(Map<? extends @Signed @PolyNull Object, ? extends @Signed @PolyNull Object> m) Convert a map to a string, printing the runtime class of keys and values.static String
Returns either "n noun" or "n nouns" depending on n.static String
prefixLines
(String prefix, @Nullable Object o) Returns the printed represenation of a value, with each line prefixed by another string.static String
prefixLinesExceptFirst
(String prefix, @Nullable Object o) Returns the printed represenation of a value, with each line (except the first) prefixed by another string.static String
removeWhitespaceAfter
(String arg, String delimiter) Remove all whitespace after instances of delimiter.static String
removeWhitespaceAround
(String arg, String delimiter) Remove all whitespace before or after instances of delimiter.static String
removeWhitespaceBefore
(String arg, String delimiter) Remove all whitespace before instances of delimiter.static String
replaceAll
(String s, Pattern regex, String replacement) Replaces every (non-overlapping) match for a regexp.static String
replacePrefix
(String target, String oldStr, String newStr) Returns the target with an occurrence of oldStr at the start replaced by newStr.static String
replaceSuffix
(String target, String oldStr, String newStr) Returns the target with an occurrence of oldStr at the end replaced by newStr.static String
rpad
(double num, @org.checkerframework.checker.index.qual.NonNegative int length) Converts the double to a String, then formats it usingrpad(String,int)
.static String
rpad
(int num, @org.checkerframework.checker.index.qual.NonNegative int length) Converts the int to a String, then formats it usingrpad(String,int)
.static String
Returns a string of the specified length, truncated if necessary (in which case the last 3 non-truncated characters are replaced by "..."), and padded with spaces to the right if necessary.static String
Returns a string of the specified length, truncated if necessary (in which case the last 3 non-truncated characters are replaced by "..."), and padded with the given character to the right if necessary.static String
rpad
(String s, @org.checkerframework.checker.index.qual.NonNegative int length, char c, boolean truncate) Returns a string of the specified length, truncated if necessary (in which case the last 3 non-truncated characters are replaced by "..."), and padded with the given character to the right if necessary.static String[]
splitLines
(String s) Returns an array of Strings, one for each line in the argument.splitLinesRetainSeparators
(String input) Splits a String into lines, keeping the line separator at the end of each substring.splitRetainSeparators
(String input, @Regex String regex) Splits a String according to a regex, keeping the separator at the end of each substring.splitRetainSeparators
(String input, Pattern p) Splits a String according to a pattern, keeping the separator at the end of each substring.Returns a ArrayList of the Strings returned byStringTokenizer(String)
with the given arguments.Returns a ArrayList of the Strings returned byStringTokenizer(String,String)
with the given arguments.Returns a ArrayList of the Strings returned byStringTokenizer(String,String,boolean)
with the given arguments.static String
toStringAndClass
(@Nullable Object v) Gives a string representation of the value and its class.static String
toStringAndClass
(@Nullable Object v, boolean shallow) Gives a string representation of the value and its class.static String
toStringTruncated
(Object o, int length) If the string representation of the given object is greater than the given length, truncate it to that length.static String
unescapeJava
(String orig) Convert a string from Java source code format (with escape sequences) into the string it would represent at run time.
-
Method Details
-
replacePrefix
Returns the target with an occurrence of oldStr at the start replaced by newStr. Returns the target if it does not strt with oldStr.An alternative to this is to use regular expressions:
target.replaceFirst("^" + Pattern.quote(oldStr), newStr)
- Parameters:
target
- the string to do replacement inoldStr
- the prefix to replacenewStr
- the replacement- Returns:
- the target with an occurrence of oldStr at the start replaced by newStr; returns the target if it does not start with oldStr
-
replaceSuffix
Returns the target with an occurrence of oldStr at the end replaced by newStr. Returns the target if it does not end with oldStr.An alternative to this is to use regular expressions:
target.replaceLast(Pattern.quote(oldStr) + "$", newStr)
- Parameters:
target
- the string to do replacement inoldStr
- the substring to replacenewStr
- the replacement- Returns:
- the target with an occurrence of oldStr at the start replaced by newStr; returns the target if it does not start with oldStr
-
replaceAll
Replaces every (non-overlapping) match for a regexp. LikeString.replaceAll
, but slightly more efficient because the regex has been pre-compiled.- Parameters:
s
- a string in which to replaceregex
- a regular expressionreplacement
- the replacement for each match of the regular expression- Returns:
- the string, with each match for the regex replaced
-
prefixLines
Returns the printed represenation of a value, with each line prefixed by another string.- Parameters:
prefix
- the prefix to place before each lineo
- the value to be printed- Returns:
- the printed representation of
o
, with each line prefixed by the given prefix
-
prefixLinesExceptFirst
Returns the printed represenation of a value, with each line (except the first) prefixed by another string.- Parameters:
prefix
- the prefix to place before each lineo
- the value to be printed- Returns:
- the printed representation of
o
, with each line (except the first) prefixed by the given prefix
-
indentLines
@SideEffectFree public static String indentLines(@org.checkerframework.checker.index.qual.NonNegative int indent, @Nullable Object o) Returns the printed representation of a value, with each line indented byindent
spaces.- Parameters:
indent
- the number of spaces to indento
- the value whose printed representation string to increase indentation of- Returns:
- the printed representation of
o
, with each line prefixed byindent
space characters
-
indentLinesExceptFirst
@SideEffectFree public static String indentLinesExceptFirst(@org.checkerframework.checker.index.qual.NonNegative int indent, @Nullable Object o) Returns the printed representation of a value, with each line (except the first) indented byindent
spaces.- Parameters:
indent
- the number of spaces to indento
- the value whose printed representation string to increase indentation of- Returns:
- the printed representation of
o
, with each line (except the first) prefixed byindent
space characters
-
splitLines
Returns an array of Strings, one for each line in the argument. The strings do not end with line separators. Always returns an array of length at least 1 (it might contain only the empty string). All common line separators (lf, cr, cr-lf) are supported. Note that a string that ends with a line separator will return an empty string as the last element of the array.It is probably better to use
String.lines()
rather than this method.Alternately, you could use
firstLineSeparator(java.lang.String)
and split on its return value.- Parameters:
s
- the string to split- Returns:
- an array of Strings, one for each line in the argument
-
firstLineSeparator
Returns the first line separator in the given string, or "\n" if the string contains none.- Parameters:
s
- a string- Returns:
- the first line separator in the given string
-
splitLinesRetainSeparators
Splits a String into lines, keeping the line separator at the end of each substring.- Parameters:
input
- the input String- Returns:
- the split string
-
splitRetainSeparators
Splits a String according to a regex, keeping the separator at the end of each substring.- Parameters:
input
- the input Stringregex
- the regular expression upon which to split the input- Returns:
- the split string
-
splitRetainSeparators
Splits a String according to a pattern, keeping the separator at the end of each substring.- Parameters:
input
- the input Stringp
- the pattern upon which to split the input- Returns:
- the split string
-
join
@SafeVarargs @SideEffectFree public static <T extends Object> String join(CharSequence delim, @Signed T... a) Concatenate the string representations of the array elements, placing the delimiter between them.This differs from the built-in
String.join()
method added in Java 8, in that this takes any arbitrary array but that method takes an array of CharSequences. Use the String method when the arguments are CharSequences.- Type Parameters:
T
- the type of array elements- Parameters:
a
- array of values to concatenatedelim
- delimiter to place between printed representations- Returns:
- the concatenation of the string representations of the values, with the delimiter between
-
joinLines
Concatenate the string representations of the objects, placing the system-specific line separator between them.- Type Parameters:
T
- the type of array elements- Parameters:
a
- array of values to whose string representation to concatenate- Returns:
- the concatenation of the string representations of the values, each on its own line
-
join
@SideEffectFree public static String join(CharSequence delim, Iterable<? extends @Signed @PolyNull Object> v) Concatenate the string representations of the objects, placing the delimiter between them.This differs from the
String.join()
method added in Java 8, in that this takes any Iterable but that method takes onlyIterable<? extends CharSequence>
.- Parameters:
v
- collection of values to concatenatedelim
- delimiter to place between printed representations- Returns:
- the concatenation of the string representations of the values, with the delimiter between
- See Also:
-
joinLines
Concatenate the string representations of the objects, placing the system-specific line separator between them.- Parameters:
v
- list of values to concatenate- Returns:
- the concatenation of the string representations of the values, each on its own line
- See Also:
-
escapeJava
Escapes a String so that it is expressible in a string literal in Java source code. By surrounding the return value with double quote marks, the result will be a Java string literal denoting the original string.Returns a new string only if any modifications were necessary.
Compared to the `escapeJava` method in Apache Commons Text StringEscapeUtils, this one correctly handles non-printable ASCII characters.
- Parameters:
orig
- string to quote- Returns:
- quoted version of orig
-
escapeJava
Deprecated.LikeescapeJava(String)
, but for a single character. Note that this quotes its argument for inclusion in a string literal, not in a character literal.- Parameters:
ch
- character to quote- Returns:
- quoted version of ch
-
escapeJava
Deprecated.LikeescapeJava(String)
, but for a single character. Note that this quotes its argument for inclusion in a string literal, not in a character literal.- Parameters:
c
- character to quote- Returns:
- quoted version of ch
-
charLiteral
Given a character, returns a Java character literal denoting the character.- Parameters:
ch
- character to quote- Returns:
- quoted version of ch
-
charLiteral
Given a character, returns a Java character literal denoting the character.- Parameters:
c
- character to quote- Returns:
- quoted version of ch
-
escapeNonASCII
Escape unprintable characters in the target, following the usual Java backslash conventions, so that the result is sure to be printable ASCII. Returns a new string.- Parameters:
orig
- string to quote- Returns:
- quoted version of orig
-
unescapeJava
Convert a string from Java source code format (with escape sequences) into the string it would represent at run time. This is the inverse operation ofescapeJava(java.lang.String)
, but it is not a general unescaping mechanism for Java strings.Compared to the `unescapeJava` method in Apache Commons Text StringEscapeUtils, this one correctly handles non-printable ASCII characters.
- Parameters:
orig
- string to quote- Returns:
- quoted version of orig
-
isBlank
Returns true if the string contains only white space codepoints, otherwise false.In Java 11, use
String.isBlank()
instead.- Parameters:
s
- a string- Returns:
- true if the string contains only white space codepoints, otherwise false
-
removeWhitespaceAround
Remove all whitespace before or after instances of delimiter.- Parameters:
arg
- string to remove whitespace indelimiter
- string to remove whitespace abutting- Returns:
- version of arg, with whitespace abutting delimiter removed
-
removeWhitespaceAfter
Remove all whitespace after instances of delimiter.- Parameters:
arg
- string to remove whitespace indelimiter
- a non-empty string to remove whitespace after- Returns:
- version of arg, with whitespace after delimiter removed
-
removeWhitespaceBefore
Remove all whitespace before instances of delimiter.- Parameters:
arg
- string to remove whitespace indelimiter
- a non-empty string to remove whitespace before- Returns:
- version of arg, with whitespace before delimiter removed
-
lpad
@SideEffectFree public static String lpad(String s, @org.checkerframework.checker.index.qual.NonNegative int length, char c, boolean truncate) Returns a string of the specified length, truncated if necessary (in which case the last 3 non-truncated characters are replaced by "..."), and padded with spaces to the left if necessary.- Parameters:
s
- string to truncate or padlength
- goal lengthc
- the character to use for paddingtruncate
- if false, no truncation is done, only padding- Returns:
s
truncated or padded tolength
characters
-
lpad
@SideEffectFree public static String lpad(String s, @org.checkerframework.checker.index.qual.NonNegative int length, char c) Returns a string of the specified length, truncated if necessary (in which case the last 3 non-truncated characters are replaced by "..."), and padded with `c` to the left if necessary.- Parameters:
s
- string to truncate or padlength
- goal lengthc
- character to use for padding- Returns:
s
truncated or padded tolength
characters
-
lpad
@SideEffectFree public static String lpad(String s, @org.checkerframework.checker.index.qual.NonNegative int length) Returns a string of the specified length, truncated if necessary (in which case the last 3 non-truncated characters are replaced by "..."), and padded with spaces to the left if necessary.- Parameters:
s
- string to truncate or padlength
- goal length- Returns:
s
truncated or padded tolength
characters
-
rpad
@SideEffectFree public static String rpad(String s, @org.checkerframework.checker.index.qual.NonNegative int length, char c, boolean truncate) Returns a string of the specified length, truncated if necessary (in which case the last 3 non-truncated characters are replaced by "..."), and padded with the given character to the right if necessary.- Parameters:
s
- string to truncate or padlength
- goal lengthc
- character to use for paddingtruncate
- if false, no truncation is done, only padding- Returns:
s
truncated or padded tolength
characters
-
rpad
@SideEffectFree public static String rpad(String s, @org.checkerframework.checker.index.qual.NonNegative int length, char c) Returns a string of the specified length, truncated if necessary (in which case the last 3 non-truncated characters are replaced by "..."), and padded with the given character to the right if necessary.- Parameters:
s
- string to truncate or padlength
- goal lengthc
- character to use for padding- Returns:
s
truncated or padded tolength
characters
-
rpad
@SideEffectFree public static String rpad(String s, @org.checkerframework.checker.index.qual.NonNegative int length) Returns a string of the specified length, truncated if necessary (in which case the last 3 non-truncated characters are replaced by "..."), and padded with spaces to the right if necessary.- Parameters:
s
- string to truncate or padlength
- goal length- Returns:
s
truncated or padded tolength
characters
-
rpad
@SideEffectFree public static String rpad(int num, @org.checkerframework.checker.index.qual.NonNegative int length) Converts the int to a String, then formats it usingrpad(String,int)
.- Parameters:
num
- int whose string representation to truncate or padlength
- goal length- Returns:
- a string representation of
num
padded tolength
characters
-
rpad
@SideEffectFree public static String rpad(double num, @org.checkerframework.checker.index.qual.NonNegative int length) Converts the double to a String, then formats it usingrpad(String,int)
. Does not do truncation that is after a decimal point.- Parameters:
num
- double whose string representation to truncate or padlength
- goal length- Returns:
- a string representation of
num
padded tolength
characters
-
tokens
Returns a ArrayList of the Strings returned byStringTokenizer(String,String,boolean)
with the given arguments.The static type is
ArrayList<Object>
because StringTokenizer extendsEnumeration<Object>
instead ofEnumeration<String>
as it should (probably due to backward-compatibility).- Parameters:
str
- a string to be parseddelim
- the delimitersreturnDelims
- flag indicating whether to return the delimiters as tokens- Returns:
- vector of strings resulting from tokenization
-
tokens
Returns a ArrayList of the Strings returned byStringTokenizer(String,String)
with the given arguments.- Parameters:
str
- a string to be parseddelim
- the delimiters- Returns:
- vector of strings resulting from tokenization
-
tokens
Returns a ArrayList of the Strings returned byStringTokenizer(String)
with the given arguments.- Parameters:
str
- a string to be parsed- Returns:
- vector of strings resulting from tokenization
-
toStringAndClass
Gives a string representation of the value and its class. Shows elements of collections; to omit them, pass false totoStringAndClass(Object, boolean)
.- Parameters:
v
- a value; may be null- Returns:
- the value's toString and its class
-
toStringAndClass
Gives a string representation of the value and its class. Intended for debugging.- Parameters:
v
- a value; may be nullshallow
- if true, do not show elements of arrays and lists- Returns:
- the value's toString and its class
-
listToStringAndClass
@SideEffectFree public static String listToStringAndClass(@Nullable List<? extends @Signed @PolyNull Object> lst) Gives a string representation of the value and its class. Intended for debugging.- Parameters:
lst
- a value; may be null- Returns:
- the value's toString and its class
-
listToString
@SideEffectFree public static String listToString(@Nullable List<? extends @Signed @PolyNull Object> lst) For use by toStringAndClass. Calls toStringAndClass on each element, but does not add the class of the list itself.- Parameters:
lst
- the list to print- Returns:
- a string representation of each element and its class
-
arrayToStringAndClass
Returns a string representation of the contents of the specified array. The argument must be an array or null. This just dispatches one of the 9 overloaded versions ofjava.util.Arrays.toString()
.- Parameters:
a
- an array- Returns:
- a string representation of the array
- Throws:
IllegalArgumentException
- if a is not an array
-
mapToStringAndClass
@SideEffectFree public static String mapToStringAndClass(Map<? extends @Signed @PolyNull Object, ? extends @Signed @PolyNull Object> m) Convert a map to a string, printing the runtime class of keys and values.- Parameters:
m
- a map- Returns:
- a string representation of the map
-
nplural
Returns either "n noun" or "n nouns" depending on n. Adds "es" to words ending with "ch", "s", "sh", or "x", adds "ies" to words ending with "y" when the previous letter is a consonant.- Parameters:
n
- count of nounsnoun
- word being counted; must not be the empty string- Returns:
- noun, if n==1; otherwise, pluralization of noun
- Throws:
IllegalArgumentException
- if the length of noun is 0
-
conjunction
public static String conjunction(String conjunction, List<? extends @Signed @PolyNull Object> elements) Creates a conjunction or disjunction, like "a", "a or b", and "a, b, or c". Obeys the "serial comma" or "Oxford comma" rule: when the list has size 3 or larger, puts a comma after every element but the last.- Parameters:
conjunction
- the conjunction word, like "and" or "or"elements
- the elements of the conjunction or disjunction- Returns:
- a conjunction or disjunction string
-
count
Returns the number of times the character appears in the string.- Parameters:
s
- string to search inch
- character to search for- Returns:
- number of times the character appears in the string
-
count
Returns the number of times the second string appears in the first.- Parameters:
s
- string to search insub
- non-empty string to search for- Returns:
- number of times the substring appears in the string
-
abbreviateNumber
Convert a number into an abbreviation such as "5.00K" for 5000 or "65.0M" for 65000000. K stands for 1000, not 1024; M stands for 1000000, not 1048576, etc. There are always exactly 3 decimal digits of precision in the result (counting both sides of the decimal point).- Parameters:
val
- a numeric value- Returns:
- an abbreviated string representation of the value
-
countFormatArguments
Returns the number of arguments that the given format string takes. This is the number of specifiers that take arguments (some, like%n
and%%
, do not take arguments).- Parameters:
s
- a string- Returns:
- the number of format specifiers in the string
-
toStringTruncated
If the string representation of the given object is greater than the given length, truncate it to that length.- Parameters:
o
- an objectlength
- the maximum length for the string representation; must be 6 or more- Returns:
- the string representation of the object, no more than the given length
-
Comparator.nullsFirst(Comparator.naturalOrder())