Class Splitter
- java.lang.Object
-
- com.google.common.base.Splitter
-
@GwtCompatible(emulated=true) public final class Splitter extends Object
Extracts non-overlapping substrings from an input string, typically by recognizing appearances of a separator sequence. This separator can be specified as a single character, fixed string, regular expression orCharMatcher
instance. Or, instead of using a separator at all, a splitter can extract adjacent substrings of a given fixed length.For example, this expression:
... produces anSplitter.on(',').split("foo,bar,qux")
Iterable
containing"foo"
,"bar"
and"qux"
, in that order.By default,
Splitter
's behavior is simplistic and unassuming. The following expression:
... yields the substringsSplitter.on(',').split(" foo,,, bar ,")
[" 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 containingn
occurrences of the separator naturally yields an iterable of sizen + 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
.- Since:
- 1.0
- Author:
- Julien Silland, Jesse Wilson, Kevin Bourrillion, Louis Wasserman
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
Splitter.MapSplitter
An object that splits strings into maps asSplitter
splits iterables and lists.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static Splitter
fixedLength(int length)
Returns a splitter that divides strings into pieces of the given length.Splitter
limit(int maxItems)
Returns a splitter that behaves equivalently tothis
splitter but stops splitting after it reaches the limit.Splitter
omitEmptyStrings()
Returns a splitter that behaves equivalently tothis
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 givenCharMatcher
to be a separator.static Splitter
on(String separator)
Returns a splitter that uses the given fixed string as a separator.static Splitter
on(Pattern separatorPattern)
Returns a splitter that considers any subsequence matchingpattern
to be 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)
Splitssequence
into string components and makes them available through anIterator
, which may be lazily evaluated.List<String>
splitToList(CharSequence sequence)
Splitssequence
into string components and returns them as an immutable list.Stream<String>
splitToStream(CharSequence sequence)
Splitssequence
into string components and makes them available through anStream
, which may be lazily evaluated.Splitter
trimResults()
Returns a splitter that behaves equivalently tothis
splitter, but automatically removes leading and trailing whitespace from each returned substring; equivalent totrimResults(CharMatcher.whitespace())
.Splitter
trimResults(CharMatcher trimmer)
Returns a splitter that behaves equivalently tothis
splitter, but removes all leading or trailing characters matching the givenCharMatcher
from each returned substring.Splitter.MapSplitter
withKeyValueSeparator(char separator)
Returns aMapSplitter
which splits entries based on this splitter, and splits entries into keys and values using the specified separator.Splitter.MapSplitter
withKeyValueSeparator(Splitter keyValueSplitter)
Returns aMapSplitter
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 aMapSplitter
which splits entries based on this splitter, and splits entries into keys and values using the specified separator.
-
-
-
Method Detail
-
on
public static Splitter on(char separator)
Returns a splitter that uses the given single-character separator. For example,Splitter.on(',').split("foo,,bar")
returns an iterable containing["foo", "", "bar"]
.- Parameters:
separator
- the character to recognize as a separator- Returns:
- a splitter, with default settings, that recognizes that separator
-
on
public static Splitter on(CharMatcher separatorMatcher)
Returns a splitter that considers any single character matched by the givenCharMatcher
to be a separator. For example,Splitter.on(CharMatcher.anyOf(";,")).split("foo,;bar,quux")
returns an iterable containing["foo", "", "bar", "quux"]
.- Parameters:
separatorMatcher
- aCharMatcher
that determines whether a character is a separator- Returns:
- a splitter, with default settings, that uses this matcher
-
on
public static Splitter on(String separator)
Returns a splitter that uses the given fixed string as a separator. For example,Splitter.on(", ").split("foo, bar,baz")
returns an iterable containing["foo", "bar,baz"]
.- Parameters:
separator
- the literal, nonempty string to recognize as a separator- Returns:
- a splitter, with default settings, that recognizes that separator
-
on
@GwtIncompatible public static Splitter on(Pattern separatorPattern)
Returns a splitter that considers any subsequence matchingpattern
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.- Parameters:
separatorPattern
- the pattern that determines whether a subsequence is a separator. This pattern may not match the empty string.- Returns:
- a splitter, with default settings, that uses this pattern
- Throws:
IllegalArgumentException
- ifseparatorPattern
matches the empty string
-
onPattern
@GwtIncompatible public static Splitter onPattern(String separatorPattern)
Returns a splitter that considers any subsequence matching a given pattern (regular expression) to be a separator. For example,Splitter.onPattern("\r?\n").split(entireFile)
splits a string into lines whether it uses DOS-style or UNIX-style line terminators. This is equivalent toSplitter.on(Pattern.compile(pattern))
.- Parameters:
separatorPattern
- the pattern that determines whether a subsequence is a separator. This pattern may not match the empty string.- Returns:
- a splitter, with default settings, that uses this pattern
- Throws:
IllegalArgumentException
- ifseparatorPattern
matches the empty string or is a malformed expression
-
fixedLength
public static Splitter fixedLength(int length)
Returns a splitter that divides strings into pieces of the given length. For example,Splitter.fixedLength(2).split("abcde")
returns an iterable containing["ab", "cd", "e"]
. The last piece can be smaller thanlength
but will never be empty.Note: if
fixedLength(int)
is used in conjunction withlimit
, 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 whichIterables.size(split(input))
does not equalIntMath.divide(input.length(), length, CEILING)
. To avoid this behavior, useomitEmptyStrings
.- Parameters:
length
- the desired length of pieces after splitting, a positive integer- Returns:
- a splitter, with default settings, that can split into fixed sized pieces
- Throws:
IllegalArgumentException
- iflength
is zero or negative
-
omitEmptyStrings
public Splitter omitEmptyStrings()
Returns a splitter that behaves equivalently tothis
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).- Returns:
- a splitter with the desired configuration
-
limit
public Splitter limit(int maxItems)
Returns a splitter that behaves equivalently tothis
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 bysplitToList(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. HenceSplitter.on(',').limit(3).trimResults().split(" a , b , c , d ")
results in["a", "b", "c , d"]
.- Parameters:
maxItems
- the maximum number of items returned- Returns:
- a splitter with the desired configuration
- Since:
- 9.0
-
trimResults
public Splitter trimResults()
Returns a splitter that behaves equivalently tothis
splitter, but automatically removes leading and trailing whitespace from each returned substring; equivalent totrimResults(CharMatcher.whitespace())
. For example,Splitter.on(',').trimResults().split(" a, b ,c ")
returns an iterable containing["a", "b", "c"]
.- Returns:
- a splitter with the desired configuration
-
trimResults
public Splitter trimResults(CharMatcher trimmer)
Returns a splitter that behaves equivalently tothis
splitter, but removes all leading or trailing characters matching the givenCharMatcher
from each returned substring. For example,Splitter.on(',').trimResults(CharMatcher.is('_')).split("_a ,_b_ ,c__")
returns an iterable containing["a ", "b_ ", "c"]
.- Parameters:
trimmer
- aCharMatcher
that determines whether a character should be removed from the beginning/end of a subsequence- Returns:
- a splitter with the desired configuration
-
split
public Iterable<String> split(CharSequence sequence)
Splitssequence
into string components and makes them available through anIterator
, which may be lazily evaluated. If you want an eagerly computedList
, usesplitToList(CharSequence)
.- Parameters:
sequence
- the sequence of characters to split- Returns:
- an iteration over the segments split from the parameter
-
splitToList
public List<String> splitToList(CharSequence sequence)
Splitssequence
into string components and returns them as an immutable list. If you want anIterable
which may be lazily evaluated, usesplit(CharSequence)
.- Parameters:
sequence
- the sequence of characters to split- Returns:
- an immutable list of the segments split from the parameter
- Since:
- 15.0
-
splitToStream
public Stream<String> splitToStream(CharSequence sequence)
Splitssequence
into string components and makes them available through anStream
, which may be lazily evaluated. If you want an eagerly computedList
, usesplitToList(CharSequence)
.- Parameters:
sequence
- the sequence of characters to split- Returns:
- a stream over the segments split from the parameter
- Since:
- NEXT (but since 28.2 in the JRE flavor)
-
withKeyValueSeparator
public Splitter.MapSplitter withKeyValueSeparator(String separator)
Returns aMapSplitter
which splits entries based on this splitter, and splits entries into keys and values using the specified separator.- Since:
- 10.0
-
withKeyValueSeparator
public Splitter.MapSplitter withKeyValueSeparator(char separator)
Returns aMapSplitter
which splits entries based on this splitter, and splits entries into keys and values using the specified separator.- Since:
- 14.0
-
withKeyValueSeparator
public Splitter.MapSplitter withKeyValueSeparator(Splitter keyValueSplitter)
Returns aMapSplitter
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 thekeyValueSplitter
.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"));
- Since:
- 10.0
-
-