1 /*
2 * Copyright (C) 2009 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5 * in compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License
10 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11 * or implied. See the License for the specific language governing permissions and limitations under
12 * the License.
13 */
14
15 package com.google.common.base;
16
17 import static com.google.common.base.Preconditions.checkArgument;
18 import static com.google.common.base.Preconditions.checkNotNull;
19
20 import com.google.common.annotations.Beta;
21 import com.google.common.annotations.GwtCompatible;
22 import com.google.common.annotations.GwtIncompatible;
23 import java.util.ArrayList;
24 import java.util.Collections;
25 import java.util.Iterator;
26 import java.util.LinkedHashMap;
27 import java.util.List;
28 import java.util.Map;
29 import java.util.regex.Pattern;
30 import java.util.stream.Stream;
31 import java.util.stream.StreamSupport;
32 import javax.annotation.CheckForNull;
33
34 /**
35 * Extracts non-overlapping substrings from an input string, typically by recognizing appearances of
36 * a <i>separator</i> sequence. This separator can be specified as a single {@linkplain #on(char)
37 * character}, fixed {@linkplain #on(String) string}, {@linkplain #onPattern regular expression} or
38 * {@link #on(CharMatcher) CharMatcher} instance. Or, instead of using a separator at all, a
39 * splitter can extract adjacent substrings of a given {@linkplain #fixedLength fixed length}.
40 *
41 * <p>For example, this expression:
42 *
43 * <pre>{@code
44 * Splitter.on(',').split("foo,bar,qux")
45 * }</pre>
46 *
47 * ... produces an {@code Iterable} containing {@code "foo"}, {@code "bar"} and {@code "qux"}, in
48 * that order.
49 *
50 * <p>By default, {@code Splitter}'s behavior is simplistic and unassuming. The following
51 * expression:
52 *
53 * <pre>{@code
54 * Splitter.on(',').split(" foo,,, bar ,")
55 * }</pre>
56 *
57 * ... yields the substrings {@code [" foo", "", "", " bar ", ""]}. If this is not the desired
58 * behavior, use configuration methods to obtain a <i>new</i> splitter instance with modified
59 * behavior:
60 *
61 * <pre>{@code
62 * private static final Splitter MY_SPLITTER = Splitter.on(',')
63 * .trimResults()
64 * .omitEmptyStrings();
65 * }</pre>
66 *
67 * <p>Now {@code MY_SPLITTER.split("foo,,, bar ,")} returns just {@code ["foo", "bar"]}. Note that
68 * the order in which these configuration methods are called is never significant.
69 *
70 * <p><b>Warning:</b> Splitter instances are immutable. Invoking a configuration method has no
71 * effect on the receiving instance; you must store and use the new splitter instance it returns
72 * instead.
73 *
74 * <pre>{@code
75 * // Do NOT do this
76 * Splitter splitter = Splitter.on('/');
77 * splitter.trimResults(); // does nothing!
78 * return splitter.split("wrong / wrong / wrong");
79 * }</pre>
80 *
81 * <p>For separator-based splitters that do not use {@code omitEmptyStrings}, an input string
82 * containing {@code n} occurrences of the separator naturally yields an iterable of size {@code n +
83 * 1}. So if the separator does not occur anywhere in the input, a single substring is returned
84 * containing the entire input. Consequently, all splitters split the empty string to {@code [""]}
85 * (note: even fixed-length splitters).
86 *
87 * <p>Splitter instances are thread-safe immutable, and are therefore safe to store as {@code static
88 * final} constants.
89 *
90 * <p>The {@link Joiner} class provides the inverse operation to splitting, but note that a
91 * round-trip between the two should be assumed to be lossy.
92 *
93 * <p>See the Guava User Guide article on <a
94 * href="https://github.com/google/guava/wiki/StringsExplained#splitter">{@code Splitter}</a>.
95 *
96 * @author Julien Silland
97 * @author Jesse Wilson
98 * @author Kevin Bourrillion
99 * @author Louis Wasserman
100 * @since 1.0
101 */
102 @GwtCompatible(emulated = true)
103 @ElementTypesAreNonnullByDefault
104 public final class Splitter {
105 private final CharMatcher trimmer;
106 private final boolean omitEmptyStrings;
107 private final Strategy strategy;
108 private final int limit;
109
110 private Splitter(Strategy strategy) {
111 this(strategy, false, CharMatcher.none(), Integer.MAX_VALUE);
112 }
113
114 private Splitter(Strategy strategy, boolean omitEmptyStrings, CharMatcher trimmer, int limit) {
115 this.strategy = strategy;
116 this.omitEmptyStrings = omitEmptyStrings;
117 this.trimmer = trimmer;
118 this.limit = limit;
119 }
120
121 /**
122 * Returns a splitter that uses the given single-character separator. For example, {@code
123 * Splitter.on(',').split("foo,,bar")} returns an iterable containing {@code ["foo", "", "bar"]}.
124 *
125 * @param separator the character to recognize as a separator
126 * @return a splitter, with default settings, that recognizes that separator
127 */
128 public static Splitter on(char separator) {
129 return on(CharMatcher.is(separator));
130 }
131
132 /**
133 * Returns a splitter that considers any single character matched by the given {@code CharMatcher}
134 * to be a separator. For example, {@code
135 * Splitter.on(CharMatcher.anyOf(";,")).split("foo,;bar,quux")} returns an iterable containing
136 * {@code ["foo", "", "bar", "quux"]}.
137 *
138 * @param separatorMatcher a {@link CharMatcher} that determines whether a character is a
139 * separator
140 * @return a splitter, with default settings, that uses this matcher
141 */
142 public static Splitter on(final CharMatcher separatorMatcher) {
143 checkNotNull(separatorMatcher);
144
145 return new Splitter(
146 new Strategy() {
147 @Override
148 public SplittingIterator iterator(Splitter splitter, final CharSequence toSplit) {
149 return new SplittingIterator(splitter, toSplit) {
150 @Override
151 int separatorStart(int start) {
152 return separatorMatcher.indexIn(toSplit, start);
153 }
154
155 @Override
156 int separatorEnd(int separatorPosition) {
157 return separatorPosition + 1;
158 }
159 };
160 }
161 });
162 }
163
164 /**
165 * Returns a splitter that uses the given fixed string as a separator. For example, {@code
166 * Splitter.on(", ").split("foo, bar,baz")} returns an iterable containing {@code ["foo",
167 * "bar,baz"]}.
168 *
169 * @param separator the literal, nonempty string to recognize as a separator
170 * @return a splitter, with default settings, that recognizes that separator
171 */
172 public static Splitter on(final String separator) {
173 checkArgument(separator.length() != 0, "The separator may not be the empty string.");
174 if (separator.length() == 1) {
175 return Splitter.on(separator.charAt(0));
176 }
177 return new Splitter(
178 new Strategy() {
179 @Override
180 public SplittingIterator iterator(Splitter splitter, CharSequence toSplit) {
181 return new SplittingIterator(splitter, toSplit) {
182 @Override
183 public int separatorStart(int start) {
184 int separatorLength = separator.length();
185
186 positions:
187 for (int p = start, last = toSplit.length() - separatorLength; p <= last; p++) {
188 for (int i = 0; i < separatorLength; i++) {
189 if (toSplit.charAt(i + p) != separator.charAt(i)) {
190 continue positions;
191 }
192 }
193 return p;
194 }
195 return -1;
196 }
197
198 @Override
199 public int separatorEnd(int separatorPosition) {
200 return separatorPosition + separator.length();
201 }
202 };
203 }
204 });
205 }
206
207 /**
208 * Returns a splitter that considers any subsequence matching {@code pattern} to be a separator.
209 * For example, {@code Splitter.on(Pattern.compile("\r?\n")).split(entireFile)} splits a string
210 * into lines whether it uses DOS-style or UNIX-style line terminators.
211 *
212 * @param separatorPattern the pattern that determines whether a subsequence is a separator. This
213 * pattern may not match the empty string.
214 * @return a splitter, with default settings, that uses this pattern
215 * @throws IllegalArgumentException if {@code separatorPattern} matches the empty string
216 */
217 @GwtIncompatible // java.util.regex
218 public static Splitter on(Pattern separatorPattern) {
219 return on(new JdkPattern(separatorPattern));
220 }
221
222 private static Splitter on(final CommonPattern separatorPattern) {
223 checkArgument(
224 !separatorPattern.matcher("").matches(),
225 "The pattern may not match the empty string: %s",
226 separatorPattern);
227
228 return new Splitter(
229 new Strategy() {
230 @Override
231 public SplittingIterator iterator(final Splitter splitter, CharSequence toSplit) {
232 final CommonMatcher matcher = separatorPattern.matcher(toSplit);
233 return new SplittingIterator(splitter, toSplit) {
234 @Override
235 public int separatorStart(int start) {
236 return matcher.find(start) ? matcher.start() : -1;
237 }
238
239 @Override
240 public int separatorEnd(int separatorPosition) {
241 return matcher.end();
242 }
243 };
244 }
245 });
246 }
247
248 /**
249 * Returns a splitter that considers any subsequence matching a given pattern (regular expression)
250 * to be a separator. For example, {@code Splitter.onPattern("\r?\n").split(entireFile)} splits a
251 * string into lines whether it uses DOS-style or UNIX-style line terminators. This is equivalent
252 * to {@code Splitter.on(Pattern.compile(pattern))}.
253 *
254 * @param separatorPattern the pattern that determines whether a subsequence is a separator. This
255 * pattern may not match the empty string.
256 * @return a splitter, with default settings, that uses this pattern
257 * @throws IllegalArgumentException if {@code separatorPattern} matches the empty string or is a
258 * malformed expression
259 */
260 @GwtIncompatible // java.util.regex
261 public static Splitter onPattern(String separatorPattern) {
262 return on(Platform.compilePattern(separatorPattern));
263 }
264
265 /**
266 * Returns a splitter that divides strings into pieces of the given length. For example, {@code
267 * Splitter.fixedLength(2).split("abcde")} returns an iterable containing {@code ["ab", "cd",
268 * "e"]}. The last piece can be smaller than {@code length} but will never be empty.
269 *
270 * <p><b>Note:</b> if {@link #fixedLength} is used in conjunction with {@link #limit}, the final
271 * split piece <i>may be longer than the specified fixed length</i>. This is because the splitter
272 * will <i>stop splitting when the limit is reached</i>, and just return the final piece as-is.
273 *
274 * <p><b>Exception:</b> for consistency with separator-based splitters, {@code split("")} does not
275 * yield an empty iterable, but an iterable containing {@code ""}. This is the only case in which
276 * {@code Iterables.size(split(input))} does not equal {@code IntMath.divide(input.length(),
277 * length, CEILING)}. To avoid this behavior, use {@code omitEmptyStrings}.
278 *
279 * @param length the desired length of pieces after splitting, a positive integer
280 * @return a splitter, with default settings, that can split into fixed sized pieces
281 * @throws IllegalArgumentException if {@code length} is zero or negative
282 */
283 public static Splitter fixedLength(final int length) {
284 checkArgument(length > 0, "The length may not be less than 1");
285
286 return new Splitter(
287 new Strategy() {
288 @Override
289 public SplittingIterator iterator(final Splitter splitter, CharSequence toSplit) {
290 return new SplittingIterator(splitter, toSplit) {
291 @Override
292 public int separatorStart(int start) {
293 int nextChunkStart = start + length;
294 return (nextChunkStart < toSplit.length() ? nextChunkStart : -1);
295 }
296
297 @Override
298 public int separatorEnd(int separatorPosition) {
299 return separatorPosition;
300 }
301 };
302 }
303 });
304 }
305
306 /**
307 * Returns a splitter that behaves equivalently to {@code this} splitter, but automatically omits
308 * empty strings from the results. For example, {@code
309 * Splitter.on(',').omitEmptyStrings().split(",a,,,b,c,,")} returns an iterable containing only
310 * {@code ["a", "b", "c"]}.
311 *
312 * <p>If either {@code trimResults} option is also specified when creating a splitter, that
313 * splitter always trims results first before checking for emptiness. So, for example, {@code
314 * Splitter.on(':').omitEmptyStrings().trimResults().split(": : : ")} returns an empty iterable.
315 *
316 * <p>Note that it is ordinarily not possible for {@link #split(CharSequence)} to return an empty
317 * iterable, but when using this option, it can (if the input sequence consists of nothing but
318 * separators).
319 *
320 * @return a splitter with the desired configuration
321 */
322 public Splitter omitEmptyStrings() {
323 return new Splitter(strategy, true, trimmer, limit);
324 }
325
326 /**
327 * Returns a splitter that behaves equivalently to {@code this} splitter but stops splitting after
328 * it reaches the limit. The limit defines the maximum number of items returned by the iterator,
329 * or the maximum size of the list returned by {@link #splitToList}.
330 *
331 * <p>For example, {@code Splitter.on(',').limit(3).split("a,b,c,d")} returns an iterable
332 * containing {@code ["a", "b", "c,d"]}. When omitting empty strings, the omitted strings do not
333 * count. Hence, {@code Splitter.on(',').limit(3).omitEmptyStrings().split("a,,,b,,,c,d")} returns
334 * an iterable containing {@code ["a", "b", "c,d"}. When trim is requested, all entries are
335 * trimmed, including the last. Hence {@code Splitter.on(',').limit(3).trimResults().split(" a , b
336 * , c , d ")} results in {@code ["a", "b", "c , d"]}.
337 *
338 * @param maxItems the maximum number of items returned
339 * @return a splitter with the desired configuration
340 * @since 9.0
341 */
342 public Splitter limit(int maxItems) {
343 checkArgument(maxItems > 0, "must be greater than zero: %s", maxItems);
344 return new Splitter(strategy, omitEmptyStrings, trimmer, maxItems);
345 }
346
347 /**
348 * Returns a splitter that behaves equivalently to {@code this} splitter, but automatically
349 * removes leading and trailing {@linkplain CharMatcher#whitespace whitespace} from each returned
350 * substring; equivalent to {@code trimResults(CharMatcher.whitespace())}. For example, {@code
351 * Splitter.on(',').trimResults().split(" a, b ,c ")} returns an iterable containing {@code ["a",
352 * "b", "c"]}.
353 *
354 * @return a splitter with the desired configuration
355 */
356 public Splitter trimResults() {
357 return trimResults(CharMatcher.whitespace());
358 }
359
360 /**
361 * Returns a splitter that behaves equivalently to {@code this} splitter, but removes all leading
362 * or trailing characters matching the given {@code CharMatcher} from each returned substring. For
363 * example, {@code Splitter.on(',').trimResults(CharMatcher.is('_')).split("_a ,_b_ ,c__")}
364 * returns an iterable containing {@code ["a ", "b_ ", "c"]}.
365 *
366 * @param trimmer a {@link CharMatcher} that determines whether a character should be removed from
367 * the beginning/end of a subsequence
368 * @return a splitter with the desired configuration
369 */
370 // TODO(kevinb): throw if a trimmer was already specified!
371 public Splitter trimResults(CharMatcher trimmer) {
372 checkNotNull(trimmer);
373 return new Splitter(strategy, omitEmptyStrings, trimmer, limit);
374 }
375
376 /**
377 * Splits {@code sequence} into string components and makes them available through an {@link
378 * Iterator}, which may be lazily evaluated. If you want an eagerly computed {@link List}, use
379 * {@link #splitToList(CharSequence)}. Java 8 users may prefer {@link #splitToStream} instead.
380 *
381 * @param sequence the sequence of characters to split
382 * @return an iteration over the segments split from the parameter
383 */
384 public Iterable<String> split(final CharSequence sequence) {
385 checkNotNull(sequence);
386
387 return new Iterable<String>() {
388 @Override
389 public Iterator<String> iterator() {
390 return splittingIterator(sequence);
391 }
392
393 @Override
394 public String toString() {
395 return Joiner.on(", ")
396 .appendTo(new StringBuilder().append('['), this)
397 .append(']')
398 .toString();
399 }
400 };
401 }
402
403 private Iterator<String> splittingIterator(CharSequence sequence) {
404 return strategy.iterator(this, sequence);
405 }
406
407 /**
408 * Splits {@code sequence} into string components and returns them as an immutable list. If you
409 * want an {@link Iterable} which may be lazily evaluated, use {@link #split(CharSequence)}.
410 *
411 * @param sequence the sequence of characters to split
412 * @return an immutable list of the segments split from the parameter
413 * @since 15.0
414 */
415 public List<String> splitToList(CharSequence sequence) {
416 checkNotNull(sequence);
417
418 Iterator<String> iterator = splittingIterator(sequence);
419 List<String> result = new ArrayList<>();
420
421 while (iterator.hasNext()) {
422 result.add(iterator.next());
423 }
424
425 return Collections.unmodifiableList(result);
426 }
427
428 /**
429 * Splits {@code sequence} into string components and makes them available through an {@link
430 * Stream}, which may be lazily evaluated. If you want an eagerly computed {@link List}, use
431 * {@link #splitToList(CharSequence)}.
432 *
433 * @param sequence the sequence of characters to split
434 * @return a stream over the segments split from the parameter
435 * @since 28.2
436 */
437 @Beta
438 public Stream<String> splitToStream(CharSequence sequence) {
439 // Can't use Streams.stream() from base
440 return StreamSupport.stream(split(sequence).spliterator(), false);
441 }
442
443 /**
444 * Returns a {@code MapSplitter} which splits entries based on this splitter, and splits entries
445 * into keys and values using the specified separator.
446 *
447 * @since 10.0
448 */
449 @Beta
450 public MapSplitter withKeyValueSeparator(String separator) {
451 return withKeyValueSeparator(on(separator));
452 }
453
454 /**
455 * Returns a {@code MapSplitter} which splits entries based on this splitter, and splits entries
456 * into keys and values using the specified separator.
457 *
458 * @since 14.0
459 */
460 @Beta
461 public MapSplitter withKeyValueSeparator(char separator) {
462 return withKeyValueSeparator(on(separator));
463 }
464
465 /**
466 * Returns a {@code MapSplitter} which splits entries based on this splitter, and splits entries
467 * into keys and values using the specified key-value splitter.
468 *
469 * <p>Note: Any configuration option configured on this splitter, such as {@link #trimResults},
470 * does not change the behavior of the {@code keyValueSplitter}.
471 *
472 * <p>Example:
473 *
474 * <pre>{@code
475 * String toSplit = " x -> y, z-> a ";
476 * Splitter outerSplitter = Splitter.on(',').trimResults();
477 * MapSplitter mapSplitter = outerSplitter.withKeyValueSeparator(Splitter.on("->"));
478 * Map<String, String> result = mapSplitter.split(toSplit);
479 * assertThat(result).isEqualTo(ImmutableMap.of("x ", " y", "z", " a"));
480 * }</pre>
481 *
482 * @since 10.0
483 */
484 @Beta
485 public MapSplitter withKeyValueSeparator(Splitter keyValueSplitter) {
486 return new MapSplitter(this, keyValueSplitter);
487 }
488
489 /**
490 * An object that splits strings into maps as {@code Splitter} splits iterables and lists. Like
491 * {@code Splitter}, it is thread-safe and immutable. The common way to build instances is by
492 * providing an additional {@linkplain Splitter#withKeyValueSeparator key-value separator} to
493 * {@link Splitter}.
494 *
495 * @since 10.0
496 */
497 @Beta
498 public static final class MapSplitter {
499 private static final String INVALID_ENTRY_MESSAGE = "Chunk [%s] is not a valid entry";
500 private final Splitter outerSplitter;
501 private final Splitter entrySplitter;
502
503 private MapSplitter(Splitter outerSplitter, Splitter entrySplitter) {
504 this.outerSplitter = outerSplitter; // only "this" is passed
505 this.entrySplitter = checkNotNull(entrySplitter);
506 }
507
508 /**
509 * Splits {@code sequence} into substrings, splits each substring into an entry, and returns an
510 * unmodifiable map with each of the entries. For example, {@code
511 * Splitter.on(';').trimResults().withKeyValueSeparator("=>").split("a=>b ; c=>b")} will return
512 * a mapping from {@code "a"} to {@code "b"} and {@code "c"} to {@code "b"}.
513 *
514 * <p>The returned map preserves the order of the entries from {@code sequence}.
515 *
516 * @throws IllegalArgumentException if the specified sequence does not split into valid map
517 * entries, or if there are duplicate keys
518 */
519 public Map<String, String> split(CharSequence sequence) {
520 Map<String, String> map = new LinkedHashMap<>();
521 for (String entry : outerSplitter.split(sequence)) {
522 Iterator<String> entryFields = entrySplitter.splittingIterator(entry);
523
524 checkArgument(entryFields.hasNext(), INVALID_ENTRY_MESSAGE, entry);
525 String key = entryFields.next();
526 checkArgument(!map.containsKey(key), "Duplicate key [%s] found.", key);
527
528 checkArgument(entryFields.hasNext(), INVALID_ENTRY_MESSAGE, entry);
529 String value = entryFields.next();
530 map.put(key, value);
531
532 checkArgument(!entryFields.hasNext(), INVALID_ENTRY_MESSAGE, entry);
533 }
534 return Collections.unmodifiableMap(map);
535 }
536 }
537
538 private interface Strategy {
539 Iterator<String> iterator(Splitter splitter, CharSequence toSplit);
540 }
541
542 private abstract static class SplittingIterator extends AbstractIterator<String> {
543 final CharSequence toSplit;
544 final CharMatcher trimmer;
545 final boolean omitEmptyStrings;
546
547 /**
548 * Returns the first index in {@code toSplit} at or after {@code start} that contains the
549 * separator.
550 */
551 abstract int separatorStart(int start);
552
553 /**
554 * Returns the first index in {@code toSplit} after {@code separatorPosition} that does not
555 * contain a separator. This method is only invoked after a call to {@code separatorStart}.
556 */
557 abstract int separatorEnd(int separatorPosition);
558
559 int offset = 0;
560 int limit;
561
562 protected SplittingIterator(Splitter splitter, CharSequence toSplit) {
563 this.trimmer = splitter.trimmer;
564 this.omitEmptyStrings = splitter.omitEmptyStrings;
565 this.limit = splitter.limit;
566 this.toSplit = toSplit;
567 }
568
569 @CheckForNull
570 @Override
571 protected String computeNext() {
572 /*
573 * The returned string will be from the end of the last match to the beginning of the next
574 * one. nextStart is the start position of the returned substring, while offset is the place
575 * to start looking for a separator.
576 */
577 int nextStart = offset;
578 while (offset != -1) {
579 int start = nextStart;
580 int end;
581
582 int separatorPosition = separatorStart(offset);
583 if (separatorPosition == -1) {
584 end = toSplit.length();
585 offset = -1;
586 } else {
587 end = separatorPosition;
588 offset = separatorEnd(separatorPosition);
589 }
590 if (offset == nextStart) {
591 /*
592 * This occurs when some pattern has an empty match, even if it doesn't match the empty
593 * string -- for example, if it requires lookahead or the like. The offset must be
594 * increased to look for separators beyond this point, without changing the start position
595 * of the next returned substring -- so nextStart stays the same.
596 */
597 offset++;
598 if (offset > toSplit.length()) {
599 offset = -1;
600 }
601 continue;
602 }
603
604 while (start < end && trimmer.matches(toSplit.charAt(start))) {
605 start++;
606 }
607 while (end > start && trimmer.matches(toSplit.charAt(end - 1))) {
608 end--;
609 }
610
611 if (omitEmptyStrings && start == end) {
612 // Don't include the (unused) separator in next split string.
613 nextStart = offset;
614 continue;
615 }
616
617 if (limit == 1) {
618 // The limit has been reached, return the rest of the string as the
619 // final item. This is tested after empty string removal so that
620 // empty strings do not count towards the limit.
621 end = toSplit.length();
622 offset = -1;
623 // Since we may have changed the end, we need to trim it again.
624 while (end > start && trimmer.matches(toSplit.charAt(end - 1))) {
625 end--;
626 }
627 } else {
628 limit--;
629 }
630
631 return toSplit.subSequence(start, end).toString();
632 }
633 return endOfData();
634 }
635 }
636 }