split¶

group turbo_strings_split

Functions

template<typename Delimiter> inline strings_internal::MaxSplitsImpl<typename strings_internal::SelectDelimiter<Delimiter>::type> max_splits(Delimiter delimiter, int limit)¶

A delimiter that limits the number of matches which can occur to the passed limit.

The last element in the returned collection will contain all remaining unsplit pieces, which may contain instances of the delimiter. The collection will contain at most limit + 1 elements. Example:

using turbo::max_splits;
std::vector<std::string> v = turbo::str_split("a,b,c", max_splits(',', 1));
// v[0] == "a", v[1] == "b,c"

Parameters:

delimiter – The delimiter.
limit – The maximum number of splits.

template<typename Delimiter> strings_internal::Splitter<typename strings_internal::SelectDelimiter<Delimiter>::type, allow_empty, std::string_view> str_split(strings_internal::ConvertibleToStringView text, Delimiter d)¶

Splits the given string on the given delimiter.

Split a given string based on the provided Delimiter object, returning the elements within the type specified by the caller. Optionally, you may pass a Predicate to str_split() indicating whether to include or exclude the resulting element within the final result set. Example:

std::vector<std::string> v = turbo::str_split("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 turbo::by_any_char;
std::vector<std::string> v = turbo::str_split("a,b=c", by_any_char(",="));
// 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 = turbo::str_split(" a , ,,b,", ',', skip_whitespace());
// v[0] == " a ", v[1] == "b"

See above for more information on predicates. str_split() Return Types The str_split() function adapts the returned collection to the collection specified by the caller (e.g. std::vector above). The returned collections may contain std::string, std::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 std::string_view. This behavior works for: 1) All standard STL containers including std::vector, std::list, std::deque, std::set,std::multiset, ‘std::map<tt>, andstd::multimap<tt> 2)std::pair` (which is not actually a container). See below. Example:

// The results are returned as `std::string_view` objects. Note that we
// have to ensure that the input string outlives any results.
std::vector<std::string_view> v = turbo::str_split("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 = turbo::str_split("b,a,c,a,b", ',');
// v[0] == "a", v[1] == "b", v[2] = "c"
// `str_split()` can be used within a range-based for loop, in which case
// each element will be of type `std::string_view`.
std::vector<std::string> v;
for (const auto sv : turbo::str_split("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 = turbo::str_split("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 = turbo::str_split("a,b,c", ',');
// p.first == "a", p.second == "b"       // "c" is omitted.

The str_split() 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 (std::string_view sp : turbo::str_split("a=b=c,d=e,f=,g", ',')) {
    m.insert(turbo::str_split(sp, turbo::max_splits('=', 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:

turbo::str_split(std::string_view(""), '-');  // {""}
turbo::str_split(std::string_view(), '-');    // {}, but should be {""}

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

Parameters:

text – [input] The string to split.
d – [input] The delimiter.
p – [input] The predicate.

Returns:

The split string.

class by_string¶

#include <str_split.h>

A sub-string delimiter.

If str_split() is passed a string in place of a Delimiter object, the string will be implicitly converted into a by_string delimiter. Example:

// Because a string literal is converted to an `turbo::by_string`,
// the following two splits are equivalent.
std::vector<std::string> v1 = turbo::str_split("a, b, c", ", ");
using turbo::by_string;
std::vector<std::string> v2 = turbo::str_split("a, b, c", by_string(", "));
// v[0] == "a", v[1] == "b", v[2] == "c"

See also

by_char

See also

by_any_char

See also

by_length

See also

max_splits

Param sp:: The delimiter string.

class by_char¶

#include <str_split.h>

A single character delimiter.

by_char is functionally equivalent to a 1-char string within a by_string delimiter, but slightly more efficient. Example:

// Because a char literal is converted to a turbo::by_char,
// the following two splits are equivalent.
std::vector<std::string> v1 = turbo::str_split("a,b,c", ',');
using turbo::by_char;
std::vector<std::string> v2 = turbo::str_split("a,b,c", by_char(','));
// v[0] == "a", v[1] == "b", v[2] == "c"

by_char is also the default delimiter if a single character is given as the delimiter to str_split(). For example, the following calls are equivalent:

std::vector<std::string> v = turbo::str_split("a-b", '-');
using turbo::by_char;
std::vector<std::string> v = turbo::str_split("a-b", by_char('-'));

Param c:: The delimiter character.

class by_any_char¶

#include <str_split.h>

A delimiter that will match any of the given byte-sized characters within its provided string.

Example:

using turbo::by_any_char;
std::vector<std::string> v = turbo::str_split("a,b=c", by_any_char(",="));
// v[0] == "a", v[1] == "b", v[2] == "c"

If by_any_char is given the empty string, it behaves exactly like by_string and matches each individual character in the input string.

See also

by_string

Note

This delimiter works with single-byte string data, but does not work with variable-width encodings, such as UTF-8. if by_any_char is given the empty string, it behaves exactly like by_string and matches each individual character in the input string.

Param sp:: The delimiter string.

class by_length¶

#include <str_split.h>

A delimiter for splitting into equal-length strings.

The length argument to the constructor must be greater than 0. Note: this delimiter works with single-byte string data, but does not work with variable-width encodings, such as UTF-8. Example:

using turbo::by_length;
std::vector<std::string> v = turbo::str_split("123456789", by_length(3));
// v[0] == "123", v[1] == "456", v[2] == "789"

Note that the string does not have to be a multiple of the fixed split length. In such a case, the last substring will be shorter.

using turbo::by_length;
std::vector<std::string> v = turbo::str_split("12345", by_length(2));
// v[0] == "12", v[1] == "34", v[2] == "5"

Param length:: The length of the delimiter.

struct allow_empty¶

#include <str_split.h>

A predicate that always returns true, indicating that all strings— including empty strings—should be included in the split output.

This predicate is not strictly needed because this is the default behavior of str_split(); however, it might be useful at some call sites to make the intent explicit. Example:

std::vector<std::string> v = turbo::str_split(" a , ,,b,", ',', allow_empty());
// v[0] == " a ", v[1] == " ", v[2] == "", v[3] = "b", v[4] == ""

struct skip_empty¶

#include <str_split.h>

A predicate that returns false if the given std::string_view is empty, indicating that str_split() should omit the empty string.

Example:

std::vector<std::string> v = turbo::str_split(",a,,b,", ',', skip_empty());
// v[0] == "a", v[1] == "b"

Note

skip_empty() does not consider a string containing only whitespace to be empty. To skip such whitespace as well, use the skip_whitespace() predicate.

struct skip_whitespace¶

#include <str_split.h>

A predicate that returns false if the given std::string_view is empty or contains only whitespace, indicating that str_split() should omit the string.

Example:

std::vector<std::string> v = turbo::str_split(" a , ,,b,", ',', skip_whitespace());
// v[0] == " a ", v[1] == "b"

skip_empty() would return whitespace elements.

Note

skip_whitespace() does not consider a string containing only whitespace to be empty. To skip such whitespace as well, use the skip_whitespace() predicate.