Split a String

String.split looks simple, but its argument is a regular expression and its default drops trailing empty fields, two facts behind most splitting bugs. This page explains how split decides where to cut, shows the limit argument, metacharacters, empty parts and zero-width splits, keeps delimiters with the Java 21 splitWithDelimiters, and measures the alternatives.

Contents

How String.split decides where to cut

split takes a regular expression, finds every place it matches, and returns the text between the matches as a String[]. Three rules shape the result, and each one causes bugs when it is forgotten:

  • The delimiter is a regex, so characters such as ., | and $ have special meanings and must be escaped to be split on literally.
  • The optional limit argument controls how many times the pattern is applied. A positive limit n gives at most n parts, with the rest of the string in the last one. Zero, the default, applies it as often as possible and then removes trailing empty strings. A negative limit applies it as often as possible and keeps everything.
  • A match at the very start produces an empty first element, unless the match has zero width. That exception was added in Java 8, which is why "hello".split("") no longer starts with an empty string.

For speed, String.split has a fast path that skips the regex engine. It is used when the delimiter is one character that is not one of .$|()[{^?*+\, or two characters where the first is a backslash and the second is not a letter or digit, such as "\\.". Every other delimiter compiles a new Pattern on each call.

Ways to split text in Java
APISinceReturnsBest for
String.split(regex), split(regex, limit)Java 1.4String[]Most splitting
Pattern.splitJava 1.4String[]The same regex used on many strings
Pattern.splitAsStreamJava 8Stream<String>Processing parts lazily with streams
String.splitWithDelimitersJava 21String[] including the delimitersTokenizing expressions and keeping separators
String.lines()Java 11Stream<String>Splitting into lines on any line ending
indexOf loopJava 1.0Whatever you buildHot code paths with a one-character separator
StringTokenizer, ScannerJava 1.0, Java 5One token at a timeLegacy code; parsing typed values

Tokenizers and CSV parsing are covered on the tokenizing page. All examples ran on JDK 21. Each array element is printed in quotes so that empty strings are visible.

The limit argument and whitespace

The input is a CSV record with an empty field in the middle and two empty fields at the end, the case where the default behaviour loses data. A string with uneven spaces and a tab follows.

Java
import java.util.Arrays;
import java.util.stream.Collectors;

public class SplitBasics {

    public static void main(String[] args) {
        String csv = "ann,42,,london,,";

        show("split(\",\")", csv.split(","));            // trailing empty strings dropped
        show("split(\",\", -1)", csv.split(",", -1));     // keep them all
        show("split(\",\", 0)", csv.split(",", 0));       // same as split(",")
        show("split(\",\", 2)", csv.split(",", 2));       // at most 2 parts
        show("split(\",\", 4)", csv.split(",", 4));       // at most 4 parts

        // Uneven whitespace: \s+ treats any run as one separator
        String words = "  one two\tthree   four ";
        show("split(\" \")", words.split(" "));
        show("split(\"\\\\s+\")", words.split("\\s+"));
        show("strip().split(\"\\\\s+\")", words.strip().split("\\s+"));

        // Several delimiters at once, with optional spaces around them
        String colors = "red, green;blue ;  gold";
        show("split(\"\\\\s*[,;]\\\\s*\")", colors.split("\\s*[,;]\\s*"));
    }

    static void show(String label, String[] parts) {
        System.out.printf("%-26s %d parts %s%n", label, parts.length, quoted(parts));
    }

    // Quotes each element, so empty strings are visible
    static String quoted(String[] parts) {
        return Arrays.stream(parts).map(p -> "\"" + p + "\"")
            .collect(Collectors.joining(", ", "[", "]"));
    }
}

Output:

Output
split(",")                 4 parts ["ann", "42", "", "london"]
split(",", -1)             6 parts ["ann", "42", "", "london", "", ""]
split(",", 0)              4 parts ["ann", "42", "", "london"]
split(",", 2)              2 parts ["ann", "42,,london,,"]
split(",", 4)              4 parts ["ann", "42", "", "london,,"]
split(" ")                 7 parts ["", "", "one", "two	three", "", "", "four"]
split("\\s+")              5 parts ["", "one", "two", "three", "four"]
strip().split("\\s+")      4 parts ["one", "two", "three", "four"]
split("\\s*[,;]\\s*")      4 parts ["red", "green", "blue", "gold"]
  • split(",") returned 4 parts, not 6. The middle empty field survived, but both trailing ones were removed. split(",", 0) is the same call.
  • split(",", -1) kept all 6 fields. Use a negative limit whenever the number of fields matters, as with CSV or tab-separated data.
  • With limit 2 the pattern was applied once, so the second part is everything after the first comma, 42,,london,,. Limit 4 gave four parts with london,, at the end.
  • split(" ") on uneven spacing gives 7 parts, with empty strings for each extra space, and the tab is not a separator at all.
  • split("\\s+") treats any run of whitespace as one separator, but the leading spaces still produce an empty first element. Stripping first gives the four words.
  • \\s*[,;]\\s* accepts a comma or a semicolon with optional spaces around it, so four colors come out clean.

Regex metacharacters and zero-width splits

Version numbers, pipe-separated values and dollar amounts all use characters that a regex reads as operators. The second half of the program uses that power on purpose, splitting at positions instead of at characters.

Java
import java.util.Arrays;
import java.util.stream.Collectors;
import java.util.regex.Pattern;

public class RegexDelimiters {

    public static void main(String[] args) {
        // Metacharacters: . | $ * + ? ( ) [ { ^ \ all mean something in a regex
        String version = "21.0.4";
        show("\"21.0.4\".split(\".\")", version.split("."));
        show("split(\"\\\\.\")", version.split("\\."));
        show("split(\"[.]\")", version.split("[.]"));
        show("split(Pattern.quote(\".\"))", version.split(Pattern.quote(".")));
        show("\"a|b\".split(\"|\")", "a|b".split("|"));
        show("\"a|b\".split(\"\\\\|\")", "a|b".split("\\|"));
        show("\"a$b\".split(\"$\")", "a$b".split("$"));
        try {
            "1+2".split("+");
        } catch (java.util.regex.PatternSyntaxException e) {
            System.out.println("\"1+2\".split(\"+\")          " + e.getDescription());
        }

        // Zero-width splits with lookaround: the delimiter is a position, not a character
        show("camelCase (?=\\p{Lu})", "parseHttpResponseCode".split("(?=\\p{Lu})"));
        show("digits|letters boundary", "abc123def45".split("(?<=\\d)(?=\\D)|(?<=\\D)(?=\\d)"));
        show("\"hello\".split(\"\")", "hello".split(""));
        show("\"Hello\".split(\"(?=l)\")", "Hello".split("(?=l)"));
    }

    static void show(String label, String[] parts) {
        System.out.printf("%-28s %d parts %s%n", label, parts.length, quoted(parts));
    }

    // Quotes each element, so empty strings are visible
    static String quoted(String[] parts) {
        return Arrays.stream(parts).map(p -> "\"" + p + "\"")
            .collect(Collectors.joining(", ", "[", "]"));
    }
}

Output:

Output
"21.0.4".split(".")          0 parts []
split("\\.")                 3 parts ["21", "0", "4"]
split("[.]")                 3 parts ["21", "0", "4"]
split(Pattern.quote("."))    3 parts ["21", "0", "4"]
"a|b".split("|")             3 parts ["a", "|", "b"]
"a|b".split("\\|")           2 parts ["a", "b"]
"a$b".split("$")             1 parts ["a$b"]
"1+2".split("+")          Dangling meta character '+'
camelCase (?=\p{Lu})         4 parts ["parse", "Http", "Response", "Code"]
digits|letters boundary      4 parts ["abc", "123", "def", "45"]
"hello".split("")            5 parts ["h", "e", "l", "l", "o"]
"Hello".split("(?=l)")       3 parts ["He", "l", "lo"]
  • "21.0.4".split(".") returned 0 parts. The dot matches every character, so every part is empty, and trailing empty strings are removed until nothing is left.
  • Three equivalent fixes split it into 3 parts: an escaped dot "\\.", a character class "[.]", or Pattern.quote("."). Use Pattern.quote when the delimiter comes from configuration or user input.
  • "|" is an alternation of two empty patterns, which matches between every character, so a|b became three parts including the pipe itself. "$" matches only at the end of the input, so nothing was split.
  • "+" on its own is not a valid regex and throws PatternSyntaxException.
  • A lookahead such as (?=\p{Lu}) matches the empty position before each uppercase letter, so parseHttpResponseCode splits into its four words and no character is lost. Combining a lookbehind and a lookahead splits at every boundary between digits and non-digits.
  • "hello".split("") gives 5 one-letter parts. Before Java 8 the result started with an empty string; the zero-width rule above removed it. A split into characters is fine for ASCII but breaks emoji and other characters outside the BMP into halves; see characters and code points.

Empty input, empty fields and ArrayIndexOutOfBounds

The edge cases of split are where parsing code fails in production, usually with an ArrayIndexOutOfBoundsException on a record whose last fields are empty. The inputs are the smallest strings that show each rule.

Java
import java.util.Arrays;
import java.util.stream.Collectors;

public class EmptyParts {

    public static void main(String[] args) {
        show("\"\".split(\",\")", "".split(","));
        show("\",\".split(\",\")", ",".split(","));
        show("\",,,\".split(\",\")", ",,,".split(","));
        show("\",,,\".split(\",\", -1)", ",,,".split(",", -1));
        show("\",a\".split(\",\")", ",a".split(","));
        show("\"a,\".split(\",\")", "a,".split(","));
        show("\" a\".split(\"\\\\s\")", " a".split("\\s"));

        // A record with empty trailing fields: the field count changes
        String[] full = "id,name,email,phone".split(",");
        String[] partial = "7,Ada,,".split(",");
        System.out.println("header has " + full.length + " fields, record has " + partial.length);
        try {
            System.out.println("phone = " + partial[3]);
        } catch (ArrayIndexOutOfBoundsException e) {
            System.out.println("partial[3] -> " + e.getMessage());
        }
        String[] safe = "7,Ada,,".split(",", -1);
        System.out.println("with -1: " + safe.length + " fields, phone = [" + safe[3] + "]");
    }

    static void show(String label, String[] parts) {
        System.out.printf("%-24s %d parts %s%n", label, parts.length, quoted(parts));
    }

    // Quotes each element, so empty strings are visible
    static String quoted(String[] parts) {
        return Arrays.stream(parts).map(p -> "\"" + p + "\"")
            .collect(Collectors.joining(", ", "[", "]"));
    }
}

Output:

Output
"".split(",")            1 parts [""]
",".split(",")           0 parts []
",,,".split(",")         0 parts []
",,,".split(",", -1)     4 parts ["", "", "", ""]
",a".split(",")          2 parts ["", "a"]
"a,".split(",")          1 parts ["a"]
" a".split("\\s")        2 parts ["", "a"]
header has 4 fields, record has 2
partial[3] -> Index 3 out of bounds for length 2
with -1: 4 fields, phone = []
  • An empty string gives one element, the empty string, not zero elements. The documentation states that when the pattern does not match, the result is the input itself. Code that tests parts.length == 0 to detect empty input never sees it.
  • A string of only delimiters, "," or ",,,", gives 0 parts, because every part is a trailing empty string. With -1, ",,," gives 4 empty strings.
  • A leading delimiter always gives an empty first part, ["", "a"], while a trailing one disappears, ["a"]. The rules are not symmetric.
  • The record 7,Ada,, has 4 fields but split into 2, so reading partial[3] threw "Index 3 out of bounds for length 2". With -1 it has 4 fields and the phone is an empty string.

Keeping the delimiters: splitWithDelimiters

For an arithmetic expression the operators matter as much as the numbers, so dropping them, as split does, is not enough. Java 21 added a method that keeps them.

Java
import java.util.Arrays;

public class KeepDelimiters {

    public static void main(String[] args) {
        String expr = "12+3*4-5";

        // split drops the delimiters
        System.out.println("split:              " + Arrays.toString(expr.split("[-+*/]")));

        // Java 21: splitWithDelimiters keeps them as separate elements
        String[] tokens = expr.splitWithDelimiters("[-+*/]", 0);
        System.out.println("splitWithDelimiters: " + Arrays.toString(tokens));

        // Its limit counts the parts between delimiters, as with split
        System.out.println("limit 2:            "
            + Arrays.toString(expr.splitWithDelimiters("[-+*/]", 2)));

        // Before Java 21: lookaround splits before and after each delimiter
        String[] old = expr.split("(?<=[-+*/])|(?=[-+*/])");
        System.out.println("lookaround split:   " + Arrays.toString(old));

        // A sentence split into sentences, keeping the end punctuation with each one
        String text = "It works. Does it? Yes!";
        System.out.println("sentences:          " + Arrays.toString(text.split("(?<=[.?!])\\s+")));
    }
}

Output:

Output
split:              [12, 3, 4, 5]
splitWithDelimiters: [12, +, 3, *, 4, -, 5]
limit 2:            [12, +, 3*4-5]
lookaround split:   [12, +, 3, *, 4, -, 5]
sentences:          [It works., Does it?, Yes!]
  • split returned only the four numbers. splitWithDelimiters, added to both String and Pattern in Java 21, returned the numbers and the three operators in order, 7 elements.
  • Its limit works like split's: limit 2 gave one number, one delimiter, and the rest, 3*4-5.
  • On older versions, a regex of a lookbehind or a lookahead for the delimiter, (?<=[-+*/])|(?=[-+*/]), splits before and after each operator and gives the same 7 elements.
  • A lookbehind can also attach the delimiter to the preceding part. Splitting at whitespace that follows ., ? or ! kept each sentence with its punctuation.

Parsing records: key=value, Pattern and streams

Configuration lines are a common real use of split. The test input includes a URL whose query string contains = characters, a value with spaces around the =, a comment and an empty value.

Java
import java.util.Arrays;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import java.util.regex.Pattern;
import java.util.stream.Collectors;

public class ParseRecords {

    static final Pattern COMMA = Pattern.compile("\\s*,\\s*");

    public static void main(String[] args) {
        // Split only on the first '=': the value may contain '=' itself
        String config = """
            url=https://example.com/?a=b&c=d
            timeout = 30
            # comment
            name=
            """;
        Map<String, String> settings = new TreeMap<>();
        for (String line : config.split("\\R")) {
            if (line.isBlank() || line.startsWith("#")) {
                continue;
            }
            String[] kv = line.split("=", 2);
            settings.put(kv[0].strip(), kv.length > 1 ? kv[1].strip() : "");
        }
        System.out.println(settings);
        System.out.println("without limit: " + Arrays.toString("url=x?a=b".split("=")));
        System.out.println("\"name=\".split(\"=\", 2) has " + "name=".split("=", 2).length
            + " parts, \"name=\".split(\"=\") has " + "name=".split("=").length);

        // A compiled Pattern for many lines, and splitAsStream for lazy processing
        for (String line : List.of("a , b,c", "x,y ,  z")) {
            System.out.println(Arrays.toString(COMMA.split(line)));
        }
        List<Integer> numbers = COMMA.splitAsStream("4, 8 ,15,16 , 23,42")
            .map(Integer::valueOf)
            .filter(n -> n % 2 == 0)
            .collect(Collectors.toList());
        System.out.println("even numbers: " + numbers);

        // "a=1;b=2" into a map in one expression
        Map<String, Integer> scores = Arrays.stream("ann=3;bob=5;cy=1".split(";"))
            .map(pair -> pair.split("=", 2))
            .collect(Collectors.toMap(kv -> kv[0], kv -> Integer.parseInt(kv[1]),
                (a, b) -> b, TreeMap::new));
        System.out.println(scores);
    }
}

Output:

Output
{name=, timeout=30, url=https://example.com/?a=b&c=d}
without limit: [url, x?a, b]
"name=".split("=", 2) has 2 parts, "name=".split("=") has 1
[a, b, c]
[x, y, z]
even numbers: [4, 8, 16, 42]
{ann=3, bob=5, cy=1}
  • split("=", 2) splits on the first = only, so the URL keeps ?a=b&c=d. Without the limit, url=x?a=b broke into three parts.
  • A positive limit keeps trailing empty strings, so "name=".split("=", 2) has 2 parts and the value is an empty string. Without a limit it has 1 part. A line with no = at all also gives 1 part, which is why the code checks kv.length before reading kv[1].
  • \R matches any line ending, including \r\n, which makes it the right regex for splitting text into lines. String.lines() does the same as a stream.
  • A static final Pattern is compiled once and reused for every line. splitAsStream feeds the parts into a stream, here keeping the even numbers 4, 8, 16 and 42.
  • Splitting twice, first on ; and then on =, turns ann=3;bob=5;cy=1 into a map. See converting a list to a map for the toMap details.

How fast is each approach?

The program splits 500,000 five-field lines with each approach and reports the best of 3 runs. It also creates every part as a String, so the comparison is fair to the approaches that work token by token.

Java
import java.util.ArrayList;
import java.util.List;
import java.util.StringTokenizer;
import java.util.function.ToIntFunction;
import java.util.regex.Pattern;

public class SplitSpeed {

    static final Pattern COMMA = Pattern.compile(",");
    static final Pattern COMMA_SPACES = Pattern.compile("\\s*,\\s*");

    public static void main(String[] args) {
        String[] lines = new String[500_000];
        for (int i = 0; i < lines.length; i++) {
            lines[i] = i + ",user" + i + ",user" + i + "@example.com," + (i % 90) + ",active";
        }
        System.out.printf("%,d lines of 5 fields%n", lines.length);
        time("split(\",\") fast path", lines, s -> s.split(",").length);
        time("split(\"[,]\") regex", lines, s -> s.split("[,]").length);
        time("precompiled Pattern", lines, s -> COMMA.split(s).length);
        time("split(\"\\\\s*,\\\\s*\")", lines, s -> s.split("\\s*,\\s*").length);
        time("precompiled \\s*,\\s*", lines, s -> COMMA_SPACES.split(s).length);
        time("StringTokenizer", lines, SplitSpeed::tokenize);
        time("indexOf loop", lines, s -> indexOfSplit(s, ',').size());
    }

    static int tokenize(String s) {
        StringTokenizer st = new StringTokenizer(s, ",");
        List<String> parts = new ArrayList<>();
        while (st.hasMoreTokens()) {
            parts.add(st.nextToken());
        }
        return parts.size();
    }

    static List<String> indexOfSplit(String s, char sep) {
        List<String> parts = new ArrayList<>();
        int from = 0;
        int at;
        while ((at = s.indexOf(sep, from)) >= 0) {
            parts.add(s.substring(from, at));
            from = at + 1;
        }
        parts.add(s.substring(from));
        return parts;
    }

    // Best of 3 runs
    static void time(String name, String[] lines, ToIntFunction<String> f) {
        long best = Long.MAX_VALUE;
        long fields = 0;
        for (int run = 0; run < 3; run++) {
            fields = 0;
            long t0 = System.nanoTime();
            for (String line : lines) {
                fields += f.applyAsInt(line);
            }
            best = Math.min(best, System.nanoTime() - t0);
        }
        System.out.printf("%-24s %6.1f ms  %,d fields%n", name, best / 1e6, fields);
    }
}

Output (rough comparison on a 2-CPU Linux machine, JDK 21; the numbers varied noticeably between runs):

Output
500,000 lines of 5 fields
split(",") fast path       73.2 ms  2,500,000 fields
split("[,]") regex        132.4 ms  2,500,000 fields
precompiled Pattern       144.3 ms  2,500,000 fields
split("\\s*,\\s*")        719.8 ms  2,500,000 fields
precompiled \s*,\s*       689.9 ms  2,500,000 fields
StringTokenizer            65.0 ms  2,500,000 fields
indexOf loop               38.7 ms  2,500,000 fields
  • The one-character delimiter "," takes the fast path. "[,]" means the same thing but goes through the regex engine, and was slower in every run.
  • A delimiter that really needs a regex, \s*,\s*, was several times slower than the fast path. Precompiling it saves the compile on each call, but most of the cost is the matching.
  • StringTokenizer was in the same range as the fast path, and the hand-written indexOf loop was the fastest in every run, because it creates no array or regex objects at all.

For ordinary code, split with a simple delimiter is fast enough. In a parser that handles millions of lines, an indexOf loop is a reasonable optimization, after measuring.

Which approach to use

Choosing a way to split
SituationUse
Simple separator, empty fields do not matters.split(",")
Fixed number of fields, such as CSV columnss.split(",", -1)
Split only at the first separators.split("=", 2)
Separator is ., |, $ or another metacharacter"\\.", "[|]" or Pattern.quote(sep)
Words separated by any whitespaces.strip().split("\\s+")
Text into liness.split("\\R") or s.lines()
Keep the delimiterss.splitWithDelimiters(regex, 0) (Java 21), or a lookaround split
Same complex regex on many stringsstatic final Pattern with split or splitAsStream
Millions of lines with a one-character separatorAn indexOf loop
Quoted CSV fieldsA CSV parser; see tokenizing

To join the parts back together, see joining strings.