Splitter (Guava: Google Core Libraries for Java 29.0-jre API)

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

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

All Methods Static Methods Instance Methods Concrete 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 maxItems)` 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.
`Stream<String>`	`splitToStream(CharSequence sequence)` Splits `sequence` into string components and makes them available through an `Stream`, 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(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.

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") 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 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
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:
    
    IllegalArgumentException - if separatorPattern 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 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.
    
    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 - if length is zero or negative
  - omitEmptyStrings
```
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
```
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(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"].
    
    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 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
```
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. If you want an eagerly computed List, use splitToList(CharSequence). Java 8 users may prefer splitToStream(java.lang.CharSequence) instead.
    
    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)
```
    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 - the sequence of characters to split
    
    Returns:
    
    an immutable list of the segments split from the parameter
    
    Since:
    
    15.0
  - splitToStream
```
@Beta
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 - the sequence of characters to split
    
    Returns:
    
    a stream over the segments split from the parameter
    
    Since:
    
    28.2
  - withKeyValueSeparator
```
@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
```
@Beta
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
```
@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.
    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

Class Splitter

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

on

on

on

on

onPattern

fixedLength

omitEmptyStrings

limit

trimResults

trimResults

split

splitToList

splitToStream

withKeyValueSeparator

withKeyValueSeparator

withKeyValueSeparator