@GwtCompatible(emulated=true) public final class Splitter extends Object
CharMatcher
instance. Or, instead of using a separator at all, a
splitter can extract adjacent substrings of a given fixed length.
For example, this expression:
Splitter.on(',').split("foo,bar,qux")
... produces an Iterable
containing "foo"
, "bar"
and "qux"
, in
that order.
By default, Splitter
's behavior is simplistic and unassuming. The following
expression:
Splitter.on(',').split(" foo,,, bar ,")
... yields the substrings [" foo", "", "", " bar ", ""]
. If this is not the desired
behavior, use configuration methods to obtain a new splitter instance with modified
behavior:
private static final Splitter MY_SPLITTER = Splitter.on(',')
.trimResults()
.omitEmptyStrings();
Now MY_SPLITTER.split("foo,,, bar ,")
returns just ["foo", "bar"]
. Note that
the order in which these configuration methods are called is never significant.
Warning: Splitter instances are immutable. Invoking a configuration method has no effect on the receiving instance; you must store and use the new splitter instance it returns instead.
// Do NOT do this
Splitter splitter = Splitter.on('/');
splitter.trimResults(); // does nothing!
return splitter.split("wrong / wrong / wrong");
For separator-based splitters that do not use omitEmptyStrings
, an input string
containing n
occurrences of the separator naturally yields an iterable of size n +
1
. So if the separator does not occur anywhere in the input, a single substring is returned
containing the entire input. Consequently, all splitters split the empty string to [""]
(note: even fixed-length splitters).
Splitter instances are thread-safe immutable, and are therefore safe to store as static
final
constants.
The Joiner
class provides the inverse operation to splitting, but note that a
round-trip between the two should be assumed to be lossy.
See the Guava User Guide article on Splitter
.
Modifier and Type | Class and Description |
---|---|
static class |
Splitter.MapSplitter
An object that splits strings into maps as
Splitter splits iterables and lists. |
Modifier and Type | Method and Description |
---|---|
static Splitter |
fixedLength(int length)
Returns a splitter that divides strings into pieces of the given length.
|
Splitter |
limit(int limit)
Returns a splitter that behaves equivalently to
this splitter but stops splitting after
it reaches the limit. |
Splitter |
omitEmptyStrings()
Returns a splitter that behaves equivalently to
this splitter, but automatically omits
empty strings from the results. |
static Splitter |
on(char separator)
Returns a splitter that uses the given single-character separator.
|
static Splitter |
on(CharMatcher separatorMatcher)
Returns a splitter that considers any single character matched by the given
CharMatcher
to be a separator. |
static Splitter |
on(Pattern separatorPattern)
Returns a splitter that considers any subsequence matching
pattern to be a separator. |
static Splitter |
on(String separator)
Returns a splitter that uses the given fixed string as a separator.
|
static Splitter |
onPattern(String separatorPattern)
Returns a splitter that considers any subsequence matching a given pattern (regular expression)
to be a separator.
|
Iterable<String> |
split(CharSequence sequence)
Splits
sequence into string components and makes them available through an Iterator , which may be lazily evaluated. |
List<String> |
splitToList(CharSequence sequence)
Splits
sequence into string components and returns them as an immutable list. |
Splitter |
trimResults()
Returns a splitter that behaves equivalently to
this splitter, but automatically
removes leading and trailing whitespace from each returned
substring; equivalent to trimResults(CharMatcher.whitespace()) . |
Splitter |
trimResults(CharMatcher trimmer)
Returns a splitter that behaves equivalently to
this splitter, but removes all leading
or trailing characters matching the given CharMatcher from each returned substring. |
Splitter.MapSplitter |
withKeyValueSeparator(char separator)
Returns a
MapSplitter which splits entries based on this splitter, and splits entries
into keys and values using the specified separator. |
Splitter.MapSplitter |
withKeyValueSeparator(Splitter keyValueSplitter)
Returns a
MapSplitter which splits entries based on this splitter, and splits entries
into keys and values using the specified key-value splitter. |
Splitter.MapSplitter |
withKeyValueSeparator(String separator)
Returns a
MapSplitter which splits entries based on this splitter, and splits entries
into keys and values using the specified separator. |
public static Splitter on(char separator)
Splitter.on(',').split("foo,,bar")
returns an iterable containing ["foo", "", "bar"]
.separator
- the character to recognize as a separatorpublic static Splitter on(CharMatcher separatorMatcher)
CharMatcher
to be a separator. For example, Splitter.on(CharMatcher.anyOf(";,")).split("foo,;bar,quux")
returns an iterable containing
["foo", "", "bar", "quux"]
.separatorMatcher
- a CharMatcher
that determines whether a character is a
separatorpublic static Splitter on(String separator)
Splitter.on(", ").split("foo, bar,baz")
returns an iterable containing ["foo",
"bar,baz"]
.separator
- the literal, nonempty string to recognize as a separator@GwtIncompatible public static Splitter on(Pattern separatorPattern)
pattern
to be a separator.
For example, Splitter.on(Pattern.compile("\r?\n")).split(entireFile)
splits a string
into lines whether it uses DOS-style or UNIX-style line terminators.separatorPattern
- the pattern that determines whether a subsequence is a separator. This
pattern may not match the empty string.IllegalArgumentException
- if separatorPattern
matches the empty string@GwtIncompatible public static Splitter onPattern(String separatorPattern)
Splitter.onPattern("\r?\n").split(entireFile)
splits a
string into lines whether it uses DOS-style or UNIX-style line terminators. This is equivalent
to Splitter.on(Pattern.compile(pattern))
.separatorPattern
- the pattern that determines whether a subsequence is a separator. This
pattern may not match the empty string.IllegalArgumentException
- if separatorPattern
matches the empty string or is a
malformed expressionpublic static Splitter fixedLength(int length)
Splitter.fixedLength(2).split("abcde")
returns an iterable containing ["ab", "cd",
"e"]
. The last piece can be smaller than length
but will never be empty.
Note: if fixedLength(int)
is used in conjunction with limit
, the final
split piece may be longer than the specified fixed length. This is because the splitter
will stop splitting when the limit is reached, and just return the final piece as-is.
Exception: for consistency with separator-based splitters, split("")
does not
yield an empty iterable, but an iterable containing ""
. This is the only case in which
Iterables.size(split(input))
does not equal IntMath.divide(input.length(),
length, CEILING)
. To avoid this behavior, use omitEmptyStrings
.
length
- the desired length of pieces after splitting, a positive integerIllegalArgumentException
- if length
is zero or negativepublic Splitter omitEmptyStrings()
this
splitter, but automatically omits
empty strings from the results. For example, Splitter.on(',').omitEmptyStrings().split(",a,,,b,c,,")
returns an iterable containing only
["a", "b", "c"]
.
If either trimResults
option is also specified when creating a splitter, that
splitter always trims results first before checking for emptiness. So, for example, Splitter.on(':').omitEmptyStrings().trimResults().split(": : : ")
returns an empty iterable.
Note that it is ordinarily not possible for split(CharSequence)
to return an empty
iterable, but when using this option, it can (if the input sequence consists of nothing but
separators).
public Splitter limit(int limit)
this
splitter but stops splitting after
it reaches the limit. The limit defines the maximum number of items returned by the iterator,
or the maximum size of the list returned by splitToList(java.lang.CharSequence)
.
For example, Splitter.on(',').limit(3).split("a,b,c,d")
returns an iterable
containing ["a", "b", "c,d"]
. When omitting empty strings, the omitted strings do not
count. Hence, Splitter.on(',').limit(3).omitEmptyStrings().split("a,,,b,,,c,d")
returns
an iterable containing ["a", "b", "c,d"
. When trim is requested, all entries are
trimmed, including the last. Hence Splitter.on(',').limit(3).trimResults().split(" a , b
, c , d ")
results in ["a", "b", "c , d"]
.
limit
- the maximum number of items returnedpublic Splitter trimResults()
this
splitter, but automatically
removes leading and trailing whitespace from each returned
substring; equivalent to trimResults(CharMatcher.whitespace())
. For example, Splitter.on(',').trimResults().split(" a, b ,c ")
returns an iterable containing ["a",
"b", "c"]
.public Splitter trimResults(CharMatcher trimmer)
this
splitter, but removes all leading
or trailing characters matching the given CharMatcher
from each returned substring. For
example, Splitter.on(',').trimResults(CharMatcher.is('_')).split("_a ,_b_ ,c__")
returns an iterable containing ["a ", "b_ ", "c"]
.trimmer
- a CharMatcher
that determines whether a character should be removed from
the beginning/end of a subsequencepublic Iterable<String> split(CharSequence sequence)
sequence
into string components and makes them available through an Iterator
, which may be lazily evaluated. If you want an eagerly computed List
, use
splitToList(CharSequence)
.sequence
- the sequence of characters to splitpublic List<String> splitToList(CharSequence sequence)
sequence
into string components and returns them as an immutable list. If you
want an Iterable
which may be lazily evaluated, use split(CharSequence)
.sequence
- the sequence of characters to split@Beta public Splitter.MapSplitter withKeyValueSeparator(String separator)
MapSplitter
which splits entries based on this splitter, and splits entries
into keys and values using the specified separator.@Beta public Splitter.MapSplitter withKeyValueSeparator(char separator)
MapSplitter
which splits entries based on this splitter, and splits entries
into keys and values using the specified separator.@Beta public Splitter.MapSplitter withKeyValueSeparator(Splitter keyValueSplitter)
MapSplitter
which splits entries based on this splitter, and splits entries
into keys and values using the specified key-value splitter.
Note: Any configuration option configured on this splitter, such as trimResults()
,
does not change the behavior of the keyValueSplitter
.
Example:
String toSplit = " x -> y, z-> a ";
Splitter outerSplitter = Splitter.on(',').trimResults();
MapSplitter mapSplitter = outerSplitter.withKeyValueSeparator(Splitter.on("->"));
Map<String, String> result = mapSplitter.split(toSplit);
assertThat(result).isEqualTo(ImmutableMap.of("x ", " y", "z", " a"));
Copyright © 2010–2019. All rights reserved.