1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2 <!--NewPage--> 3 <HTML> 4 <HEAD> 5 <!-- Generated by javadoc (build 1.6.0-google-internal) on Mon Jan 04 20:47:57 PST 2010 --> 6 <TITLE> 7 Splitter (Guava Libraries 2010.01.04) 8 </TITLE> 9 10 <META NAME="date" CONTENT="2010-01-04"> 11 12 <LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../stylesheet.css" TITLE="Style"> 13 14 <SCRIPT type="text/javascript"> 15 function windowTitle() 16 { 17 if (location.href.indexOf('is-external=true') == -1) { 18 parent.document.title="Splitter (Guava Libraries 2010.01.04)"; 19 } 20 } 21 </SCRIPT> 22 <NOSCRIPT> 23 </NOSCRIPT> 24 25 </HEAD> 26 27 <BODY BGCOLOR="white" onload="windowTitle();"> 28 <HR> 29 30 31 <!-- ========= START OF TOP NAVBAR ======= --> 32 <A NAME="navbar_top"><!-- --></A> 33 <A HREF="#skip-navbar_top" title="Skip navigation links"></A> 34 <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> 35 <TR> 36 <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> 37 <A NAME="navbar_top_firstrow"><!-- --></A> 38 <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> 39 <TR ALIGN="center" VALIGN="top"> 40 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> 41 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD> 42 <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD> 43 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/Splitter.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD> 44 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> 45 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> 46 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> 47 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> 48 </TR> 49 </TABLE> 50 </TD> 51 <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> 52 </EM> 53 </TD> 54 </TR> 55 56 <TR> 57 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 58 <A HREF="../../../../com/google/common/base/Service.State.html" title="enum in com.google.common.base"><B>PREV CLASS</B></A> 59 <A HREF="../../../../com/google/common/base/Supplier.html" title="interface in com.google.common.base"><B>NEXT CLASS</B></A></FONT></TD> 60 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 61 <A HREF="../../../../index.html?com/google/common/base/Splitter.html" target="_top"><B>FRAMES</B></A> 62 <A HREF="Splitter.html" target="_top"><B>NO FRAMES</B></A> 63 <SCRIPT type="text/javascript"> 64 <!-- 65 if(window==top) { 66 document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>'); 67 } 68 //--> 69 </SCRIPT> 70 <NOSCRIPT> 71 <A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A> 72 </NOSCRIPT> 73 74 75 </FONT></TD> 76 </TR> 77 <TR> 78 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 79 SUMMARY: NESTED | FIELD | CONSTR | <A HREF="#method_summary">METHOD</A></FONT></TD> 80 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 81 DETAIL: FIELD | CONSTR | <A HREF="#method_detail">METHOD</A></FONT></TD> 82 </TR> 83 </TABLE> 84 <A NAME="skip-navbar_top"></A> 85 <!-- ========= END OF TOP NAVBAR ========= --> 86 87 <HR> 88 <!-- ======== START OF CLASS DATA ======== --> 89 <H2> 90 <FONT SIZE="-1"> 91 com.google.common.base</FONT> 92 <BR> 93 Class Splitter</H2> 94 <PRE> 95 <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true" title="class or interface in java.lang">java.lang.Object</A> 96 <IMG SRC="../../../../resources/inherit.gif" ALT="extended by "><B>com.google.common.base.Splitter</B> 97 </PRE> 98 <HR> 99 <DL> 100 <DT><PRE>public final class <B>Splitter</B><DT>extends <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true" title="class or interface in java.lang">Object</A></DL> 101 </PRE> 102 103 <P> 104 An object that divides strings (or other instances of <code>CharSequence</code>) 105 into substrings, by recognizing a <i>separator</i> (a.k.a. "delimiter") 106 which can be expressed as a single character, literal string, regular 107 expression, <code>CharMatcher</code>, or by using a fixed substring length. This 108 class provides the complementary functionality to <A HREF="../../../../com/google/common/base/Joiner.html" title="class in com.google.common.base"><CODE>Joiner</CODE></A>. 109 110 <p>Here is the most basic example of <code>Splitter</code> usage: <pre> <code>Splitter.on(',').split("foo,bar")</code></pre> 111 112 This invocation returns an <code>Iterable<String></code> containing <code>"foo"</code> 113 and <code>"bar"</code>, in that order. 114 115 <p>By default <code>Splitter</code>'s behavior is very simplistic: <pre> <code>Splitter.on(',').split("foo,,bar, quux")</code></pre> 116 117 This returns an iterable containing <code>["foo", "", "bar", " quux"]</code>. 118 Notice that the splitter does not assume that you want empty strings removed, 119 or that you wish to trim whitespace. If you want features like these, simply 120 ask for them: <pre> <code>private static final Splitter MY_SPLITTER = Splitter.on(',') 121 .trimResults() 122 .omitEmptyStrings();</code></pre> 123 124 Now <code>MY_SPLITTER.split("foo, ,bar, quux,")</code> returns an iterable 125 containing just <code>["foo", "bar", "quux"]</code>. Note that the order in which 126 the configuration methods are called is never significant; for instance, 127 trimming is always applied first before checking for an empty result, 128 regardless of the order in which the <A HREF="../../../../com/google/common/base/Splitter.html#trimResults()"><CODE>trimResults()</CODE></A> and 129 <A HREF="../../../../com/google/common/base/Splitter.html#omitEmptyStrings()"><CODE>omitEmptyStrings()</CODE></A> methods were invoked. 130 131 <p><b>Warning: splitter instances are always immutable</b>; a configuration 132 method such as <code>omitEmptyStrings</code> has no effect on the instance it 133 is invoked on! You must store and use the new splitter instance returned by 134 the method. This makes splitters thread-safe, and safe to store as <code>static final</code> constants (as illustrated above). <pre> <code>// Bad! Do not do this! 135 Splitter splitter = Splitter.on('/'); 136 splitter.trimResults(); // does nothing! 137 return splitter.split("wrong / wrong / wrong");</code></pre> 138 139 The separator recognized by the splitter does not have to be a single 140 literal character as in the examples above. See the methods <A HREF="../../../../com/google/common/base/Splitter.html#on(java.lang.String)"><CODE>on(String)</CODE></A>, <A HREF="../../../../com/google/common/base/Splitter.html#on(java.util.regex.Pattern)"><CODE>on(Pattern)</CODE></A> and <A HREF="../../../../com/google/common/base/Splitter.html#on(com.google.common.base.CharMatcher)"><CODE>on(CharMatcher)</CODE></A> for examples 141 of other ways to specify separators. 142 143 <p><b>Note:</b> this class does not mimic any of the quirky behaviors of 144 similar JDK methods; for instance, it does not silently discard trailing 145 separators, as does <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/String.html?is-external=true#split(java.lang.String)" title="class or interface in java.lang"><CODE>String.split(String)</CODE></A>, nor does it have a default 146 behavior of using five particular whitespace characters as separators, like 147 <A HREF="http://java.sun.com/javase/6/docs/api/java/util/StringTokenizer.html?is-external=true" title="class or interface in java.util"><CODE>StringTokenizer</CODE></A>. 148 <P> 149 150 <P> 151 <DL> 152 <DT><B>Since:</B></DT> 153 <DD>2009.09.15 <b>tentative</b></DD> 154 <DT><B>Author:</B></DT> 155 <DD>Julien Silland, Jesse Wilson, Kevin Bourrillion</DD> 156 </DL> 157 <HR> 158 159 <P> 160 161 <!-- ========== METHOD SUMMARY =========== --> 162 163 <A NAME="method_summary"><!-- --></A> 164 <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> 165 <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> 166 <TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2"> 167 <B>Method Summary</B></FONT></TH> 168 </TR> 169 <TR BGCOLOR="white" CLASS="TableRowColor"> 170 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> 171 <CODE>static <A HREF="../../../../com/google/common/base/Splitter.html" title="class in com.google.common.base">Splitter</A></CODE></FONT></TD> 172 <TD><CODE><B><A HREF="../../../../com/google/common/base/Splitter.html#fixedLength(int)">fixedLength</A></B>(int length)</CODE> 173 174 <BR> 175 Returns a splitter that divides strings into pieces of the given length.</TD> 176 </TR> 177 <TR BGCOLOR="white" CLASS="TableRowColor"> 178 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> 179 <CODE> <A HREF="../../../../com/google/common/base/Splitter.html" title="class in com.google.common.base">Splitter</A></CODE></FONT></TD> 180 <TD><CODE><B><A HREF="../../../../com/google/common/base/Splitter.html#omitEmptyStrings()">omitEmptyStrings</A></B>()</CODE> 181 182 <BR> 183 Returns a splitter that behaves equivalently to <code>this</code> splitter, but 184 automatically omits empty strings from the results.</TD> 185 </TR> 186 <TR BGCOLOR="white" CLASS="TableRowColor"> 187 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> 188 <CODE>static <A HREF="../../../../com/google/common/base/Splitter.html" title="class in com.google.common.base">Splitter</A></CODE></FONT></TD> 189 <TD><CODE><B><A HREF="../../../../com/google/common/base/Splitter.html#on(char)">on</A></B>(char separator)</CODE> 190 191 <BR> 192 Returns a splitter that uses the given single-character separator.</TD> 193 </TR> 194 <TR BGCOLOR="white" CLASS="TableRowColor"> 195 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> 196 <CODE>static <A HREF="../../../../com/google/common/base/Splitter.html" title="class in com.google.common.base">Splitter</A></CODE></FONT></TD> 197 <TD><CODE><B><A HREF="../../../../com/google/common/base/Splitter.html#on(com.google.common.base.CharMatcher)">on</A></B>(<A HREF="../../../../com/google/common/base/CharMatcher.html" title="class in com.google.common.base">CharMatcher</A> separatorMatcher)</CODE> 198 199 <BR> 200 Returns a splitter that considers any single character matched by the 201 given <code>CharMatcher</code> to be a separator.</TD> 202 </TR> 203 <TR BGCOLOR="white" CLASS="TableRowColor"> 204 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> 205 <CODE>static <A HREF="../../../../com/google/common/base/Splitter.html" title="class in com.google.common.base">Splitter</A></CODE></FONT></TD> 206 <TD><CODE><B><A HREF="../../../../com/google/common/base/Splitter.html#on(java.util.regex.Pattern)">on</A></B>(<A HREF="http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html?is-external=true" title="class or interface in java.util.regex">Pattern</A> separatorPattern)</CODE> 207 208 <BR> 209 Returns a splitter that considers any subsequence matching <code>pattern</code> to be a separator.</TD> 210 </TR> 211 <TR BGCOLOR="white" CLASS="TableRowColor"> 212 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> 213 <CODE>static <A HREF="../../../../com/google/common/base/Splitter.html" title="class in com.google.common.base">Splitter</A></CODE></FONT></TD> 214 <TD><CODE><B><A HREF="../../../../com/google/common/base/Splitter.html#on(java.lang.String)">on</A></B>(<A HREF="http://java.sun.com/javase/6/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</A> separator)</CODE> 215 216 <BR> 217 Returns a splitter that uses the given fixed string as a separator.</TD> 218 </TR> 219 <TR BGCOLOR="white" CLASS="TableRowColor"> 220 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> 221 <CODE>static <A HREF="../../../../com/google/common/base/Splitter.html" title="class in com.google.common.base">Splitter</A></CODE></FONT></TD> 222 <TD><CODE><B><A HREF="../../../../com/google/common/base/Splitter.html#onPattern(java.lang.String)">onPattern</A></B>(<A HREF="http://java.sun.com/javase/6/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</A> separatorPattern)</CODE> 223 224 <BR> 225 Returns a splitter that considers any subsequence matching a given 226 pattern (regular expression) to be a separator.</TD> 227 </TR> 228 <TR BGCOLOR="white" CLASS="TableRowColor"> 229 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> 230 <CODE> <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Iterable.html?is-external=true" title="class or interface in java.lang">Iterable</A><<A HREF="http://java.sun.com/javase/6/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</A>></CODE></FONT></TD> 231 <TD><CODE><B><A HREF="../../../../com/google/common/base/Splitter.html#split(java.lang.CharSequence)">split</A></B>(<A HREF="http://java.sun.com/javase/6/docs/api/java/lang/CharSequence.html?is-external=true" title="class or interface in java.lang">CharSequence</A> sequence)</CODE> 232 233 <BR> 234 Splits the <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/CharSequence.html?is-external=true" title="class or interface in java.lang"><CODE>CharSequence</CODE></A> passed in parameter.</TD> 235 </TR> 236 <TR BGCOLOR="white" CLASS="TableRowColor"> 237 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> 238 <CODE> <A HREF="../../../../com/google/common/base/Splitter.html" title="class in com.google.common.base">Splitter</A></CODE></FONT></TD> 239 <TD><CODE><B><A HREF="../../../../com/google/common/base/Splitter.html#trimResults()">trimResults</A></B>()</CODE> 240 241 <BR> 242 Returns a splitter that behaves equivalently to <code>this</code> splitter, but 243 automatically removes leading and trailing <A HREF="../../../../com/google/common/base/CharMatcher.html#WHITESPACE">whitespace</A> from each returned substring; equivalent 244 to <code>trimResults(CharMatcher.WHITESPACE)</code>.</TD> 245 </TR> 246 <TR BGCOLOR="white" CLASS="TableRowColor"> 247 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> 248 <CODE> <A HREF="../../../../com/google/common/base/Splitter.html" title="class in com.google.common.base">Splitter</A></CODE></FONT></TD> 249 <TD><CODE><B><A HREF="../../../../com/google/common/base/Splitter.html#trimResults(com.google.common.base.CharMatcher)">trimResults</A></B>(<A HREF="../../../../com/google/common/base/CharMatcher.html" title="class in com.google.common.base">CharMatcher</A> trimmer)</CODE> 250 251 <BR> 252 Returns a splitter that behaves equivalently to <code>this</code> splitter, but 253 removes all leading or trailing characters matching the given <code>CharMatcher</code> from each returned substring.</TD> 254 </TR> 255 </TABLE> 256 <A NAME="methods_inherited_from_class_java.lang.Object"><!-- --></A> 257 <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> 258 <TR BGCOLOR="#EEEEFF" CLASS="TableSubHeadingColor"> 259 <TH ALIGN="left"><B>Methods inherited from class java.lang.<A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true" title="class or interface in java.lang">Object</A></B></TH> 260 </TR> 261 <TR BGCOLOR="white" CLASS="TableRowColor"> 262 <TD><CODE><A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#clone()" title="class or interface in java.lang">clone</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#equals(java.lang.Object)" title="class or interface in java.lang">equals</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#finalize()" title="class or interface in java.lang">finalize</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#getClass()" title="class or interface in java.lang">getClass</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#hashCode()" title="class or interface in java.lang">hashCode</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#notify()" title="class or interface in java.lang">notify</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#notifyAll()" title="class or interface in java.lang">notifyAll</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#toString()" title="class or interface in java.lang">toString</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#wait()" title="class or interface in java.lang">wait</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#wait(long)" title="class or interface in java.lang">wait</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#wait(long, int)" title="class or interface in java.lang">wait</A></CODE></TD> 263 </TR> 264 </TABLE> 265 266 <P> 267 268 <!-- ============ METHOD DETAIL ========== --> 269 270 <A NAME="method_detail"><!-- --></A> 271 <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> 272 <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> 273 <TH ALIGN="left" COLSPAN="1"><FONT SIZE="+2"> 274 <B>Method Detail</B></FONT></TH> 275 </TR> 276 </TABLE> 277 278 <A NAME="on(char)"><!-- --></A><H3> 279 on</H3> 280 <PRE> 281 public static <A HREF="../../../../com/google/common/base/Splitter.html" title="class in com.google.common.base">Splitter</A> <B>on</B>(char separator)</PRE> 282 <DL> 283 <DD>Returns a splitter that uses the given single-character separator. For 284 example, <code>Splitter.on(',').split("foo,,bar")</code> returns an iterable 285 containing <code>["foo", "", "bar"]</code>. 286 <P> 287 <DD><DL> 288 <DT><B>Parameters:</B><DD><CODE>separator</CODE> - the character to recognize as a separator 289 <DT><B>Returns:</B><DD>a splitter, with default settings, that recognizes that separator</DL> 290 </DD> 291 </DL> 292 <HR> 293 294 <A NAME="on(com.google.common.base.CharMatcher)"><!-- --></A><H3> 295 on</H3> 296 <PRE> 297 public static <A HREF="../../../../com/google/common/base/Splitter.html" title="class in com.google.common.base">Splitter</A> <B>on</B>(<A HREF="../../../../com/google/common/base/CharMatcher.html" title="class in com.google.common.base">CharMatcher</A> separatorMatcher)</PRE> 298 <DL> 299 <DD>Returns a splitter that considers any single character matched by the 300 given <code>CharMatcher</code> to be a separator. For example, <code>Splitter.on(CharMatcher.anyOf(";,")).split("foo,;bar,quux")</code> returns an 301 iterable containing <code>["foo", "", "bar", "quux"]</code>. 302 <P> 303 <DD><DL> 304 <DT><B>Parameters:</B><DD><CODE>separatorMatcher</CODE> - a <A HREF="../../../../com/google/common/base/CharMatcher.html" title="class in com.google.common.base"><CODE>CharMatcher</CODE></A> that determines whether a 305 character is a separator 306 <DT><B>Returns:</B><DD>a splitter, with default settings, that uses this matcher</DL> 307 </DD> 308 </DL> 309 <HR> 310 311 <A NAME="on(java.lang.String)"><!-- --></A><H3> 312 on</H3> 313 <PRE> 314 public static <A HREF="../../../../com/google/common/base/Splitter.html" title="class in com.google.common.base">Splitter</A> <B>on</B>(<A HREF="http://java.sun.com/javase/6/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</A> separator)</PRE> 315 <DL> 316 <DD>Returns a splitter that uses the given fixed string as a separator. For 317 example, <code>Splitter.on(", ").split("foo, bar, baz,qux")</code> returns an 318 iterable containing <code>["foo", "bar", "baz,qux"]</code>. 319 <P> 320 <DD><DL> 321 <DT><B>Parameters:</B><DD><CODE>separator</CODE> - the literal, nonempty string to recognize as a separator 322 <DT><B>Returns:</B><DD>a splitter, with default settings, that recognizes that separator</DL> 323 </DD> 324 </DL> 325 <HR> 326 327 <A NAME="on(java.util.regex.Pattern)"><!-- --></A><H3> 328 on</H3> 329 <PRE> 330 public static <A HREF="../../../../com/google/common/base/Splitter.html" title="class in com.google.common.base">Splitter</A> <B>on</B>(<A HREF="http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html?is-external=true" title="class or interface in java.util.regex">Pattern</A> separatorPattern)</PRE> 331 <DL> 332 <DD>Returns a splitter that considers any subsequence matching <code>pattern</code> to be a separator. For example, <code>Splitter.on(Pattern.compile("\r?\n")).split(entireFile)</code> splits a string 333 into lines whether it uses DOS-style or UNIX-style line terminators. 334 <P> 335 <DD><DL> 336 <DT><B>Parameters:</B><DD><CODE>separatorPattern</CODE> - the pattern that determines whether a subsequence 337 is a separator. This pattern may not match the empty string. 338 <DT><B>Returns:</B><DD>a splitter, with default settings, that uses this pattern 339 <DT><B>Throws:</B> 340 <DD><CODE><A HREF="http://java.sun.com/javase/6/docs/api/java/lang/IllegalArgumentException.html?is-external=true" title="class or interface in java.lang">IllegalArgumentException</A></CODE> - if <code>separatorPattern</code> matches the 341 empty string</DL> 342 </DD> 343 </DL> 344 <HR> 345 346 <A NAME="onPattern(java.lang.String)"><!-- --></A><H3> 347 onPattern</H3> 348 <PRE> 349 public static <A HREF="../../../../com/google/common/base/Splitter.html" title="class in com.google.common.base">Splitter</A> <B>onPattern</B>(<A HREF="http://java.sun.com/javase/6/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</A> separatorPattern)</PRE> 350 <DL> 351 <DD>Returns a splitter that considers any subsequence matching a given 352 pattern (regular expression) to be a separator. For example, <code>Splitter.onPattern("\r?\n").split(entireFile)</code> splits a string into lines 353 whether it uses DOS-style or UNIX-style line terminators. This is 354 equivalent to <code>Splitter.on(Pattern.compile(pattern))</code>. 355 <P> 356 <DD><DL> 357 <DT><B>Parameters:</B><DD><CODE>separatorPattern</CODE> - the pattern that determines whether a subsequence 358 is a separator. This pattern may not match the empty string. 359 <DT><B>Returns:</B><DD>a splitter, with default settings, that uses this pattern 360 <DT><B>Throws:</B> 361 <DD><CODE><A HREF="http://java.sun.com/javase/6/docs/api/java/util/regex/PatternSyntaxException.html?is-external=true" title="class or interface in java.util.regex">PatternSyntaxException</A></CODE> - if <code>separatorPattern</code> is a malformed 362 expression 363 <DD><CODE><A HREF="http://java.sun.com/javase/6/docs/api/java/lang/IllegalArgumentException.html?is-external=true" title="class or interface in java.lang">IllegalArgumentException</A></CODE> - if <code>separatorPattern</code> matches the 364 empty string</DL> 365 </DD> 366 </DL> 367 <HR> 368 369 <A NAME="fixedLength(int)"><!-- --></A><H3> 370 fixedLength</H3> 371 <PRE> 372 public static <A HREF="../../../../com/google/common/base/Splitter.html" title="class in com.google.common.base">Splitter</A> <B>fixedLength</B>(int length)</PRE> 373 <DL> 374 <DD>Returns a splitter that divides strings into pieces of the given length. 375 For example, <code>Splitter.atEach(2).split("abcde")</code> returns an 376 iterable containing <code>["ab", "cd", "e"]</code>. The last piece can be 377 smaller than <code>length</code> but will never be empty. 378 <P> 379 <DD><DL> 380 <DT><B>Parameters:</B><DD><CODE>length</CODE> - the desired length of pieces after splitting 381 <DT><B>Returns:</B><DD>a splitter, with default settings, that can split into fixed sized 382 pieces</DL> 383 </DD> 384 </DL> 385 <HR> 386 387 <A NAME="omitEmptyStrings()"><!-- --></A><H3> 388 omitEmptyStrings</H3> 389 <PRE> 390 public <A HREF="../../../../com/google/common/base/Splitter.html" title="class in com.google.common.base">Splitter</A> <B>omitEmptyStrings</B>()</PRE> 391 <DL> 392 <DD>Returns a splitter that behaves equivalently to <code>this</code> splitter, but 393 automatically omits empty strings from the results. For example, <code>Splitter.on(',').omitEmptyStrings().split(",a,,,b,c,,")</code> returns an 394 iterable containing only <code>["a", "b", "c"]</code>. 395 396 <p>If either <code>trimResults</code> option is also specified when creating a 397 splitter, that splitter always trims results first before checking for 398 emptiness. So, for example, <code>Splitter.on(':').omitEmptyStrings().trimResults().split(": : : ")</code> returns 399 an empty iterable. 400 401 <p>Note that it is ordinarily not possible for <A HREF="../../../../com/google/common/base/Splitter.html#split(java.lang.CharSequence)"><CODE>split(CharSequence)</CODE></A> 402 to return an empty iterable, but when using this option, it can (if the 403 input sequence consists of nothing but separators). 404 <P> 405 <DD><DL> 406 407 <DT><B>Returns:</B><DD>a splitter with the desired configuration</DL> 408 </DD> 409 </DL> 410 <HR> 411 412 <A NAME="trimResults()"><!-- --></A><H3> 413 trimResults</H3> 414 <PRE> 415 public <A HREF="../../../../com/google/common/base/Splitter.html" title="class in com.google.common.base">Splitter</A> <B>trimResults</B>()</PRE> 416 <DL> 417 <DD>Returns a splitter that behaves equivalently to <code>this</code> splitter, but 418 automatically removes leading and trailing <A HREF="../../../../com/google/common/base/CharMatcher.html#WHITESPACE">whitespace</A> from each returned substring; equivalent 419 to <code>trimResults(CharMatcher.WHITESPACE)</code>. For example, <code>Splitter.on(',').trimResults().split(" a, b ,c ")</code> returns an iterable 420 containing <code>["a", "b", "c"]</code>. 421 <P> 422 <DD><DL> 423 424 <DT><B>Returns:</B><DD>a splitter with the desired configuration</DL> 425 </DD> 426 </DL> 427 <HR> 428 429 <A NAME="trimResults(com.google.common.base.CharMatcher)"><!-- --></A><H3> 430 trimResults</H3> 431 <PRE> 432 public <A HREF="../../../../com/google/common/base/Splitter.html" title="class in com.google.common.base">Splitter</A> <B>trimResults</B>(<A HREF="../../../../com/google/common/base/CharMatcher.html" title="class in com.google.common.base">CharMatcher</A> trimmer)</PRE> 433 <DL> 434 <DD>Returns a splitter that behaves equivalently to <code>this</code> splitter, but 435 removes all leading or trailing characters matching the given <code>CharMatcher</code> from each returned substring. For example, <code>Splitter.on(',').trimResults(CharMatcher.is('_')).split("_a ,_b_ ,c__")</code> 436 returns an iterable containing <code>["a ", "b_ ", "c"]</code>. 437 <P> 438 <DD><DL> 439 <DT><B>Parameters:</B><DD><CODE>trimmer</CODE> - a <A HREF="../../../../com/google/common/base/CharMatcher.html" title="class in com.google.common.base"><CODE>CharMatcher</CODE></A> that determines whether a character 440 should be removed from the beginning/end of a subsequence 441 <DT><B>Returns:</B><DD>a splitter with the desired configuration</DL> 442 </DD> 443 </DL> 444 <HR> 445 446 <A NAME="split(java.lang.CharSequence)"><!-- --></A><H3> 447 split</H3> 448 <PRE> 449 public <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Iterable.html?is-external=true" title="class or interface in java.lang">Iterable</A><<A HREF="http://java.sun.com/javase/6/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</A>> <B>split</B>(<A HREF="http://java.sun.com/javase/6/docs/api/java/lang/CharSequence.html?is-external=true" title="class or interface in java.lang">CharSequence</A> sequence)</PRE> 450 <DL> 451 <DD>Splits the <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/CharSequence.html?is-external=true" title="class or interface in java.lang"><CODE>CharSequence</CODE></A> passed in parameter. 452 <P> 453 <DD><DL> 454 <DT><B>Parameters:</B><DD><CODE>sequence</CODE> - the sequence of characters to split 455 <DT><B>Returns:</B><DD>an iteration over the segments split from the parameter.</DL> 456 </DD> 457 </DL> 458 <!-- ========= END OF CLASS DATA ========= --> 459 <HR> 460 461 462 <!-- ======= START OF BOTTOM NAVBAR ====== --> 463 <A NAME="navbar_bottom"><!-- --></A> 464 <A HREF="#skip-navbar_bottom" title="Skip navigation links"></A> 465 <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> 466 <TR> 467 <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> 468 <A NAME="navbar_bottom_firstrow"><!-- --></A> 469 <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> 470 <TR ALIGN="center" VALIGN="top"> 471 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> 472 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD> 473 <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD> 474 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/Splitter.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD> 475 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> 476 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> 477 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> 478 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> 479 </TR> 480 </TABLE> 481 </TD> 482 <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> 483 </EM> 484 </TD> 485 </TR> 486 487 <TR> 488 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 489 <A HREF="../../../../com/google/common/base/Service.State.html" title="enum in com.google.common.base"><B>PREV CLASS</B></A> 490 <A HREF="../../../../com/google/common/base/Supplier.html" title="interface in com.google.common.base"><B>NEXT CLASS</B></A></FONT></TD> 491 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 492 <A HREF="../../../../index.html?com/google/common/base/Splitter.html" target="_top"><B>FRAMES</B></A> 493 <A HREF="Splitter.html" target="_top"><B>NO FRAMES</B></A> 494 <SCRIPT type="text/javascript"> 495 <!-- 496 if(window==top) { 497 document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>'); 498 } 499 //--> 500 </SCRIPT> 501 <NOSCRIPT> 502 <A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A> 503 </NOSCRIPT> 504 505 506 </FONT></TD> 507 </TR> 508 <TR> 509 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 510 SUMMARY: NESTED | FIELD | CONSTR | <A HREF="#method_summary">METHOD</A></FONT></TD> 511 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 512 DETAIL: FIELD | CONSTR | <A HREF="#method_detail">METHOD</A></FONT></TD> 513 </TR> 514 </TABLE> 515 <A NAME="skip-navbar_bottom"></A> 516 <!-- ======== END OF BOTTOM NAVBAR ======= --> 517 518 <HR> 519 520 </BODY> 521 </HTML> 522
