Guava: Google Core Libraries for Java 33.1.0-jre · com.google.common.base.Splitter

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 or 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.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static class	Splitter.MapSplitter An object that splits strings into maps as `Splitter` splits iterables and lists.
private abstract static class	Splitter.SplittingIterator
private static interface	Splitter.Strategy

Field Summary

Modifier and Type	Field and Description
private final int	limit
private final boolean	omitEmptyStrings
private final Splitter.Strategy	strategy
private final CharMatcher	trimmer

Constructor Summary

Access	Constructor and Description
private	Splitter(Splitter.Strategy strategy)
private	Splitter(Splitter.Strategy strategy, boolean omitEmptyStrings, CharMatcher trimmer, int limit)

Method Summary

Modifier and Type	Method and Description
public static Splitter	Returns: a splitter, with default settings, that can split into fixed sized pieces fixedLength(final int the desired length of pieces after splitting, a positive integer length) Returns a splitter that divides strings into pieces of the given length.
public Splitter	Returns: a splitter with the desired configuration limit(int the maximum number of items returned maxItems) Returns a splitter that behaves equivalently to `this` splitter but stops splitting after it reaches the limit.
public Splitter	Returns: a splitter with the desired configuration omitEmptyStrings() Returns a splitter that behaves equivalently to `this` splitter, but automatically omits empty strings from the results.
public static Splitter	Returns: a splitter, with default settings, that recognizes that separator on(char the character to recognize as a separator separator) Returns a splitter that uses the given single-character separator.
public static Splitter	Returns: a splitter, with default settings, that uses this matcher on(final CharMatcher a `CharMatcher` that determines whether a character is a separator separatorMatcher) Returns a splitter that considers any single character matched by the given `CharMatcher` to be a separator.
public static Splitter	Returns: a splitter, with default settings, that recognizes that separator on(final String the literal, nonempty string to recognize as a separator separator) Returns a splitter that uses the given fixed string as a separator.
public static Splitter	Returns: a splitter, with default settings, that uses this pattern on(Pattern the pattern that determines whether a subsequence is a separator. This pattern may not match the empty string. separatorPattern) Returns a splitter that considers any subsequence matching `pattern` to be a separator.
public static Splitter	Returns: a splitter, with default settings, that uses this pattern onPattern(String the pattern that determines whether a subsequence is a separator. This pattern may not match the empty string. separatorPattern) Returns a splitter that considers any subsequence matching a given pattern (regular expression) to be a separator.
pack-priv static Splitter	onPatternInternal(final CommonPattern separatorPattern) Internal utility; see `on(Pattern)` instead.
public Iterable<String>	Returns: an iteration over the segments split from the parameter split(final CharSequence the sequence of characters to split sequence) Splits `sequence` into string components and makes them available through an `Iterator`, which may be lazily evaluated.
private Iterator<String>	splittingIterator(CharSequence sequence)
public List<String>	Returns: an immutable list of the segments split from the parameter splitToList(CharSequence the sequence of characters to split sequence) Splits `sequence` into string components and returns them as an immutable list.
public Stream<String>	Returns: a stream over the segments split from the parameter splitToStream(CharSequence the sequence of characters to split sequence) Splits `sequence` into string components and makes them available through an `Stream`, which may be lazily evaluated.
public Splitter	Returns: a splitter with the desired configuration 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())`.
public Splitter	Returns: a splitter with the desired configuration trimResults(CharMatcher a `CharMatcher` that determines whether a character should be removed from the beginning/end of a subsequence 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.
public 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 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.
public 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.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

limit	back to summary
private final int limit

omitEmptyStrings	back to summary
private final boolean omitEmptyStrings

strategy	back to summary
private final Splitter.Strategy strategy

trimmer	back to summary
private final CharMatcher trimmer

Constructor Detail

Splitter	back to summary
private Splitter(Splitter.Strategy strategy)

Splitter	back to summary
private Splitter(Splitter.Strategy strategy, boolean omitEmptyStrings, CharMatcher trimmer, int limit)

Method Detail

fixedLength back to summary

fixedLength	back to summary
public static Splitter fixedLength(final 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 than `length` but will never be empty. Note if `fixedLength` 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`. Parameters length:int the desired length of pieces after splitting, a positive integer Returns:Splitter a splitter, with default settings, that can split into fixed sized pieces Exceptions IllegalArgumentException: if `length` is zero or negative

public static Splitter fixedLength(final 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 than length but will never be empty.

Note

if fixedLength 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.

Parameters

length:int: the desired length of pieces after splitting, a positive integer

Returns:Splitter

a splitter, with default settings, that can split into fixed sized pieces

Exceptions

IllegalArgumentException:: if length is zero or negative

limit back to summary

limit	back to summary
public Splitter limit(int maxItems) Returns a splitter that behaves equivalently to `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`. 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"]`. Parameters maxItems:int the maximum number of items returned Returns:Splitter a splitter with the desired configuration Since 9.0

public Splitter limit(int maxItems)

Returns a splitter that behaves equivalently to 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.

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"].

Parameters

maxItems:int: the maximum number of items returned

Returns:Splitter

a splitter with the desired configuration

Since

9.0

omitEmptyStrings back to summary

omitEmptyStrings	back to summary
public Splitter omitEmptyStrings() Returns a splitter that behaves equivalently to `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). Returns:Splitter a splitter with the desired configuration

public Splitter omitEmptyStrings()

Returns a splitter that behaves equivalently to 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).

Returns:Splitter: a splitter with the desired configuration

on back to summary

on	back to summary
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:char the character to recognize as a separator Returns:Splitter a splitter, with default settings, that recognizes that separator

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:char: the character to recognize as a separator

Returns:Splitter

a splitter, with default settings, that recognizes that separator

on back to summary

on	back to summary
public static Splitter on(final CharMatcher separatorMatcher) Returns a splitter that considers any single character matched by the given `CharMatcher` to be a separator. For example, `Splitter.on(CharMatcher.anyOf(";,")).split("foo,;bar,quux")` returns an iterable containing `["foo", "", "bar", "quux"]`. Parameters separatorMatcher:CharMatcher a `CharMatcher` that determines whether a character is a separator Returns:Splitter a splitter, with default settings, that uses this matcher

public static Splitter on(final CharMatcher separatorMatcher)

Returns a splitter that considers any single character matched by the given CharMatcher to be a separator. For example, Splitter.on(CharMatcher.anyOf(";,")).split("foo,;bar,quux") returns an iterable containing ["foo", "", "bar", "quux"].

Parameters

separatorMatcher:CharMatcher: a CharMatcher that determines whether a character is a separator

Returns:Splitter

a splitter, with default settings, that uses this matcher

on back to summary

on	back to summary
public static Splitter on(final 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:String the literal, nonempty string to recognize as a separator Returns:Splitter a splitter, with default settings, that recognizes that separator

public static Splitter on(final 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:String: the literal, nonempty string to recognize as a separator

Returns:Splitter

a splitter, with default settings, that recognizes that separator

on back to summary

on	back to summary
public static Splitter on(Pattern separatorPattern) Returns a splitter that considers any subsequence matching `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. Parameters separatorPattern:Pattern the pattern that determines whether a subsequence is a separator. This pattern may not match the empty string. Returns:Splitter a splitter, with default settings, that uses this pattern Annotations @GwtIncompatible Exceptions IllegalArgumentException: if `separatorPattern` matches the empty string

public static Splitter on(Pattern separatorPattern)

Returns a splitter that considers any subsequence matching 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.

Parameters

separatorPattern:Pattern: the pattern that determines whether a subsequence is a separator. This pattern may not match the empty string.

Returns:Splitter

a splitter, with default settings, that uses this pattern

Annotations

@GwtIncompatible

Exceptions

IllegalArgumentException:: if separatorPattern matches the empty string

onPattern back to summary

onPattern	back to summary
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 to `Splitter.on(Pattern.compile(pattern))`. Parameters separatorPattern:String the pattern that determines whether a subsequence is a separator. This pattern may not match the empty string. Returns:Splitter a splitter, with default settings, that uses this pattern Annotations @GwtIncompatible Exceptions IllegalArgumentException: if `separatorPattern` matches the empty string or is a malformed expression

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 to Splitter.on(Pattern.compile(pattern)).

Parameters

separatorPattern:String: the pattern that determines whether a subsequence is a separator. This pattern may not match the empty string.

Returns:Splitter

a splitter, with default settings, that uses this pattern

Annotations

@GwtIncompatible

Exceptions

IllegalArgumentException:: if separatorPattern matches the empty string or is a malformed expression

onPatternInternal	back to summary
pack-priv static Splitter onPatternInternal(final CommonPattern separatorPattern) Internal utility; see `on(Pattern)` instead.

split back to summary

split	back to summary
public Iterable<String> split(final CharSequence sequence) Splits `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)`. Java 8+ users may prefer `splitToStream` instead. Parameters sequence:CharSequence the sequence of characters to split Returns:Iterable<String> an iteration over the segments split from the parameter

public Iterable<String> split(final CharSequence sequence)

Splits 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). Java 8+ users may prefer splitToStream instead.

Parameters

sequence:CharSequence: the sequence of characters to split

Returns:Iterable<String>

an iteration over the segments split from the parameter

splittingIterator	back to summary
private Iterator<String> splittingIterator(CharSequence sequence)

splitToList back to summary

splitToList	back to summary
public List<String> splitToList(CharSequence sequence) Splits `sequence` into string components and returns them as an immutable list. If you want an `Iterable` which may be lazily evaluated, use `split(CharSequence)`. Parameters sequence:CharSequence the sequence of characters to split Returns:List<String> an immutable list of the segments split from the parameter Since 15.0

public List<String> splitToList(CharSequence sequence)

Splits sequence into string components and returns them as an immutable list. If you want an Iterable which may be lazily evaluated, use split(CharSequence).

Parameters

sequence:CharSequence: the sequence of characters to split

Returns:List<String>

an immutable list of the segments split from the parameter

Since

15.0

splitToStream back to summary

splitToStream	back to summary
public Stream<String> splitToStream(CharSequence sequence) Splits `sequence` into string components and makes them available through an `Stream`, which may be lazily evaluated. If you want an eagerly computed `List`, use `splitToList(CharSequence)`. Parameters sequence:CharSequence the sequence of characters to split Returns:Stream<String> a stream over the segments split from the parameter Since 28.2

public Stream<String> splitToStream(CharSequence sequence)

Splits sequence into string components and makes them available through an Stream, which may be lazily evaluated. If you want an eagerly computed List, use splitToList(CharSequence).

Parameters

sequence:CharSequence: the sequence of characters to split

Returns:Stream<String>

a stream over the segments split from the parameter

Since

28.2

trimResults back to summary

trimResults	back to summary
public 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())`. For example, `Splitter.on(',').trimResults().split(" a, b ,c ")` returns an iterable containing `["a", "b", "c"]`. Returns:Splitter a splitter with the desired configuration

public 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()). For example, Splitter.on(',').trimResults().split(" a, b ,c ") returns an iterable containing ["a", "b", "c"].

Returns:Splitter: a splitter with the desired configuration

trimResults back to summary

trimResults	back to summary
public 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. For example, `Splitter.on(',').trimResults(CharMatcher.is('_')).split("_a ,_b_ ,c__")` returns an iterable containing `["a ", "b_ ", "c"]`. Parameters trimmer:CharMatcher a `CharMatcher` that determines whether a character should be removed from the beginning/end of a subsequence Returns:Splitter a splitter with the desired configuration

public 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. For example, Splitter.on(',').trimResults(CharMatcher.is('_')).split("_a ,_b_ ,c__") returns an iterable containing ["a ", "b_ ", "c"].

Parameters

trimmer:CharMatcher: a CharMatcher that determines whether a character should be removed from the beginning/end of a subsequence

Returns:Splitter

a splitter with the desired configuration

withKeyValueSeparator back to summary

withKeyValueSeparator	back to summary
public 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. Since 10.0

public 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.

Since: 10.0

withKeyValueSeparator back to summary

withKeyValueSeparator	back to summary
public 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. Since 14.0

public 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.

Since: 14.0

withKeyValueSeparator back to summary

withKeyValueSeparator	back to summary
public 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. 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"));` Since 10.0

public 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.

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"));

Since: 10.0

Modifier and Type	Method and Description
protected String	computeNext() Implements abstract com.google.common.base.AbstractIterator.computeNext.
pack-priv abstract int	separatorEnd(int separatorPosition) Returns the first index in `toSplit` after `separatorPosition` that does not contain a separator.
pack-priv abstract int	separatorStart(int start) Returns the first index in `toSplit` at or after `start` that contains the separator.

public final Class Splitter

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public final Class Splitter.MapSplitter

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private abstract Class Splitter.SplittingIterator

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Interface Splitter.Strategy

Method Summary

Method Detail

Modifier and Type	Field and Description
private final Splitter	entrySplitter
private static final String	INVALID_ENTRY_MESSAGE
private final Splitter	outerSplitter

Modifier and Type	Field and Description
pack-priv int	limit
pack-priv int	offset
pack-priv final boolean	omitEmptyStrings
pack-priv final CharSequence	toSplit
pack-priv final CharMatcher	trimmer