com.google.common.base

Class Splitter

java.lang.Object

com.google.common.base.Splitter

@GwtCompatible(emulated=true)
public final class Splitter
extends Object

An object that divides strings (or other instances of CharSequence) into substrings, by recognizing a separator (a.k.a. "delimiter") which can be expressed as a single character, literal string, regular expression, CharMatcher, or by using a fixed substring length. This class provides the complementary functionality to Joiner.

Here is the most basic example of Splitter usage:

   Splitter.on(',').split("foo,bar")

This invocation returns an Iterable<String> containing "foo" and "bar", in that order.

By default Splitter's behavior is very simplistic:

   Splitter.on(',').split("foo,,bar, quux")

This returns an iterable containing ["foo", "", "bar", " quux"]. Notice that the splitter does not assume that you want empty strings removed, or that you wish to trim whitespace. If you want features like these, simply ask for them:

 private static final Splitter MY_SPLITTER = Splitter.on(',')
       .trimResults()
       .omitEmptyStrings();

Now MY_SPLITTER.split("foo, ,bar, quux,") returns an iterable containing just ["foo", "bar", "quux"]. Note that the order in which the configuration methods are called is never significant; for instance, trimming is always applied first before checking for an empty result, regardless of the order in which the trimResults() and omitEmptyStrings() methods were invoked.

Warning: splitter instances are always immutable; a configuration method such as omitEmptyStrings has no effect on the instance it is invoked on! You must store and use the new splitter instance returned by the method. This makes splitters thread-safe, and safe to store as static final constants (as illustrated above).

   // Bad! Do not do this!
   Splitter splitter = Splitter.on('/');
   splitter.trimResults(); // does nothing!
   return splitter.split("wrong / wrong / wrong");

The separator recognized by the splitter does not have to be a single literal character as in the examples above. See the methods on(String), on(Pattern) and on(CharMatcher) for examples of other ways to specify separators.

Note: this class does not mimic any of the quirky behaviors of similar JDK methods; for instance, it does not silently discard trailing separators, as does String.split(String), nor does it have a default behavior of using five particular whitespace characters as separators, like StringTokenizer.

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 and Description
static class	Splitter.MapSplitter An object that splits strings into maps as Splitter splits iterables and lists.

Method Summary

Methods

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

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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 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 - a CharMatcher 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,qux") returns an iterable containing ["foo", "bar", "baz,qux"].

Parameters:

separator - the literal, nonempty string to recognize as a separator

Returns:

a splitter, with default settings, that recognizes that separator

on

@GwtIncompatible(value="java.util.regex")
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 - 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 - if separatorPattern matches the empty string

onPattern

@GwtIncompatible(value="java.util.regex")
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 - 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:

PatternSyntaxException - if separatorPattern is a malformed expression

IllegalArgumentException - if separatorPattern matches the empty string

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 than length but will never be empty.

Parameters:

length - the desired length of pieces after splitting

Returns:

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

omitEmptyStrings

@CheckReturnValue
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:

a splitter with the desired configuration

limit

@CheckReturnValue
public Splitter limit(int limit)

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.

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 no 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, including the last are trimmed. Hence Splitter.on(',').limit(3).trimResults().split(" a , b , c , d ") results in @{code ["a", "b", "c , d"]}.

Parameters:

limit - the maximum number of items returns

Returns:

a splitter with the desired configuration

Since:

9.0

trimResults

@CheckReturnValue
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:

a splitter with the desired configuration

trimResults

@CheckReturnValue
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 - a CharMatcher 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)

Splits sequence into string components and makes them available through an Iterator, which may be lazily evaluated.

Parameters:

sequence - the sequence of characters to split

Returns:

an iteration over the segments split from the parameter.

withKeyValueSeparator

@CheckReturnValue
@Beta
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

@CheckReturnValue
@Beta
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.

Since:

10.0