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

Method Summary
`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

Copyright © 2010-2012. All Rights Reserved.