[#absl-StrSplit-011]
= xref:absl.adoc[absl]::StrSplit
:relfileprefix: ../
:mrdocs:

Splits a string into a sequence of substrings identified by `Delimiter`. The input is processed sequentially from beginning to end, and each resulting substring is filtered by an optional `Predicate` before inclusion in the result set. `StrSplit()` returns a lazy range that preserves the substrings original order and is convertible to the collection type specified by the caller.

== Synopsis

Declared in `<absl/strings/str_split.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<typename Delimiter>
/* implementation-defined */::Splitter</* implementation-defined */::type, AllowEmpty, std::string_view>
StrSplit(
    /* implementation-defined */::ConvertibleToStringView text,
    Delimiter d);
----

== Description

Optionally, you may pass a `Predicate` to `StrSplit()` indicating whether to include or exclude the resulting element within the final result set. (See the overviews for Delimiters and Predicates above.)

Example:

std::vector<std::string> v = absl::StrSplit("a,b,c,d", ','); // v[0]== "a", v[1]== "b", v[2]== "c", v[3]== "d"

You can also provide an explicit `Delimiter` object:

Example:

using absl::ByAnyChar; std::vector<std::string> v = absl::StrSplit("a,b=c", ByAnyChar(",=")); // v[0]== "a", v[1]== "b", v[2]== "c"

See above for more information on delimiters.

By default, empty strings are included in the result set. You can optionally include a third `Predicate` argument to apply a test for whether the resultant element should be included in the result set:

Example:

std::vector<std::string> v = absl::StrSplit(" a , ,,b,", ',', SkipWhitespace()); // v[0]== " a ", v[1]== "b"

See above for more information on predicates.

‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐ StrSplit() Return Types‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐

The `StrSplit()` function adapts the returned collection to the collection specified by the caller (e.g. `std::vector` above). The returned collections may contain `std::string`, `absl::string_view` (in which case the original string being split must ensure that it outlives the collection), or any object that can be explicitly created from an `absl::string_view`. This behavior works for:

1) All standard STL containers including `std::vector`, `std::list`, `std::deque`, `std::set`,`std::multiset`, 'std::map`, and `std::multimap`. 2) `std::pair` (which is not actually a container). See below. 3) `std::array`, which is a container but has different behavior due to its fixed size. See below.

Example:

// The results are returned as `absl::string_view` objects. Note that we // have to ensure that the input string outlives any results. std::vector<absl::string_view> v = absl::StrSplit("a,b,c", ',');

// Stores results in a std::set<std::string>, which also performs // de‐duplication and orders the elements in ascending order. std::set<std::string> a = absl::StrSplit("b,a,c,a,b", ','); // a[0]== "a", a[1]== "b", a[2]== "c"

// `StrSplit()` can be used within a range‐based for loop, in which case // each element will be of type `absl::string_view`. std::vector<std::string> v; for (const auto sv : absl::StrSplit("a,b,c", ',')) { if (sv != "b") v.emplace_back(sv); } // v[0]== "a", v[1]== "c"

// Stores results in a map. The map implementation assumes that the input // is provided as a series of key/value pairs. For example, the 0th element // resulting from the split will be stored as a key to the 1st element. If // an odd number of elements are resolved, the last element is paired with // a default‐constructed value (e.g., empty string). std::map<std::string, std::string> m = absl::StrSplit("a,b,c", ','); // m["a"]== "b", m["c"]== "" // last component value equals ""

Splitting to `std::pair` is an interesting case because it can hold only two elements and is not a collection type. When splitting to a `std::pair` the first two split strings become the `std::pair` `.first` and `.second` members, respectively. The remaining split substrings are discarded. If there are less than two split substrings, the empty string is used for the corresponding `std::pair` member.

Example:

// Stores first two split strings as the members in a std::pair. std::pair<std::string, std::string> p = absl::StrSplit("a,b,c", ','); // p.first == "a", p.second == "b" // "c" is omitted.

Splitting to `std::array` is similar to splitting to `std::pair`, but for N elements instead of two; missing elements are filled with the empty string and extra elements are discarded.

Examples:

// Stores first two split strings as the elements in a std::array. std::array<std::string, 2> a = absl::StrSplit("a,b,c", ','); // a[0]== "a", a[1]== "b" // "c" is omitted.

// The second element is empty. std::array<std::string, 2> a = absl::StrSplit("a,", ','); // a[0]== "a", a[1]== ""

The `StrSplit()` function can be used multiple times to perform more complicated splitting logic, such as intelligently parsing key‐value pairs.

Example:

// The input string "a=b=c,d=e,f=,g" becomes // { "a" => "b=c", "d" => "e", "f" => "", "g" => "" } std::map<std::string, std::string> m; for (absl::string_view sp : absl::StrSplit("a=b=c,d=e,f=,g", ',')) { m.insert(absl::StrSplit(sp, absl::MaxSplits('=', 1))); } EXPECT_EQ("b=c", m.find("a")‐>second); EXPECT_EQ("e", m.find("d")‐>second); EXPECT_EQ("", m.find("f")‐>second); EXPECT_EQ("", m.find("g")‐>second);

WARNING: Due to a legacy bug that is maintained for backward compatibility, splitting the following empty string_views produces different results:

absl::StrSplit(absl::string_view(""), '‐'); // {""} absl::StrSplit(absl::string_view(), '‐'); // {}, but should be {""}

Try not to depend on this distinction because the bug may one day be fixed.

== Return Value

A lazy range of substrings convertible to the caller's collection.

== Parameters

[cols="1,4"]
|===
| Name| Description
| *text*
| The string to split.
| *d*
| The delimiter identifying the split points.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#