javadoc.com.google.common.base.Splitter.html Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of guava-osgi

Repackaging of Google Guava libraries as OSGi bundle

There is a newer version: 8.0.0








Splitter (Guava: Google Core Libraries for Java 11.0.1 API)























  
      Overview 
      Package 
    Class 
      Use 
      Tree 
      Deprecated 
      Index 
      Help 
  









 PREV CLASS 
 NEXT CLASS

  FRAMES   
 NO FRAMES   
 







  SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD









com.google.common.base


Class Splitter
java.lang.Object
  com.google.common.base.Splitter



@GwtCompatible(emulated=true)
public final class Splitterextends 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.




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















  
      Overview 
      Package 
    Class 
      Use 
      Tree 
      Deprecated 
      Index 
      Help 
  









 PREV CLASS 
 NEXT CLASS

  FRAMES   
 NO FRAMES   
 







  SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD






Copyright © 2010-2012. All Rights Reserved.

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.

javadoc.com.google.common.base.Splitter.html Maven / Gradle / Ivy

com.google.common.base Class Splitter

on

on

on

on

onPattern

fixedLength

omitEmptyStrings

limit

trimResults

trimResults

split

withKeyValueSeparator

withKeyValueSeparator

com.google.common.base
Class Splitter