gul14/join_split.h

Detailed Description

Joining and splitting strings.

Functions
template<typename StringContainer = std::vector<std::string>, typename ContainerInsertFct = void (*)(StringContainer&, string_view)>
StringContainer	gul14::split (string_view text, string_view delimiter, ContainerInsertFct insert_fct=detail::emplace_back< StringContainer >)
	Separate a string at all occurrences of a delimiter, returning the strings between the delimiters in a container. More...
template<typename StringContainer = std::vector<std::string>, typename ContainerInsertFct = void (*)(StringContainer&, string_view)>
StringContainer	gul14::split (string_view text, const std::regex &delimiter, ContainerInsertFct insert_fct=detail::emplace_back< StringContainer >)
	Separate a string at all occurrences of a delimiter described by a regular expression, returning the strings between the delimiters in a container. More...
template<typename StringContainer = std::vector<string_view>, typename ContainerInsertFct = void (*)(StringContainer&, string_view)>
StringContainer	gul14::split_sv (string_view text, string_view delimiter, ContainerInsertFct insert_fct=detail::emplace_back< StringContainer >)
	Separate a string at all occurrences of a delimiter, returning the strings between the delimiters in a vector. More...
template<typename Iterator >
std::string	gul14::join (Iterator begin, Iterator end, string_view glue)
	Concatenate all strings in a range, placing a delimiter between them. More...
template<typename StringContainer >
std::string	gul14::join (const StringContainer &parts, string_view glue)
	Concatenate all strings in a range, placing a delimiter between them. More...

Function Documentation

join() [1/2]

template<typename StringContainer >

std::string gul14::join ( const StringContainer &  parts, string_view  glue  )

inline

Concatenate all strings in a range, placing a delimiter between them.

This algorithm iterates twice over the range in order to pre-allocate a string of the correct size.

This is the inverse function of split(). It is guaranteed that join(split(text, del), del) == text (unless del is a std::regex object).

Parameters

parts	A container holding strings or string views that are to be concatenated
glue	String that is put between each element of parts

Returns

all strings glued together with the delimiter glue.

Template Parameters

StringContainer

A container type that holds strings, e.g. std::vector<std::string> or std::list<gul14::string_view>. The container must provide an STL-like forward iterator interface. The string type must provide a size() member function and must support concatenation with std::string using operator+=.

See also

join(Iterator, Iterator, string_view) has a two-iterator interface, split() and associated functions can be used to split a string into a vector of substrings.

Since

GUL version 2.3, join() accepts arbitrary containers or iterators (it was limited to std::vector before).

References gul14::join().

join() [2/2]

template<typename Iterator >

std::string gul14::join ( Iterator  begin, Iterator  end, string_view  glue  )

inline

Concatenate all strings in a range, placing a delimiter between them.

This algorithm iterates twice over the range in order to pre-allocate a string of the correct size.

Parameters

begin	Iterator pointing to the first string
end	Iterator pointing past the last string
glue	String that is put between each element of parts

Returns

all strings glued together with the delimiter glue.

Template Parameters

Iterator

A forward iterator type that dereferences to a string type. The string type must provide a size() member function and must support concatenation with std::string using operator+=.

See also

join(StringContainer, string_view) is a convenience overload for joining entire containers, split() and associated functions can be used to split a string into a vector of substrings.

Since

GUL version 2.3

Referenced by gul14::join().

split() [1/2]

template<typename StringContainer = std::vector<std::string>, typename ContainerInsertFct = void (*)(StringContainer&, string_view)>

StringContainer gul14::split ( string_view  text, const std::regex &  delimiter, ContainerInsertFct  insert_fct = detail::emplace_back<StringContainer>  )

inline

Separate a string at all occurrences of a delimiter described by a regular expression, returning the strings between the delimiters in a container.

This function is a variant of split(string_view, string_view, ContainerInsertFct) that accepts a std::regex object to describe the delimiter:

// Return type is std::vector<std::string>
auto parts = split("one\ntwo\nthree"s, std::regex{"[^[:print:]]"});
assert(y.size() == 3);
assert(y[0] == "one"s);
assert(y[1] == "two"s);
assert(y[2] == "three"s);

Parameters

text	The string to be split
delimiter	A std::regex object describing the delimiters
insert_fct	Custom container inserter function

See also

split(string_view, string_view, ContainerInsertFct) splits at a fixed substring,
split_sv() does the same returning a vector of string_views, and
join() can join the vector back into a string.

split() [2/2]

template<typename StringContainer = std::vector<std::string>, typename ContainerInsertFct = void (*)(StringContainer&, string_view)>

StringContainer gul14::split ( string_view  text, string_view  delimiter, ContainerInsertFct  insert_fct = detail::emplace_back<StringContainer>  )

inline

Separate a string at all occurrences of a delimiter, returning the strings between the delimiters in a container.

The result has at least one element. If the delimiter is not present in the text, the whole text is returned. If there are consecutive delimiters, the collected string between them is the empty string. If the delimiter is directly at the end of the input, the collected string between the end of the input and the delimiter is again the empty string.

split() is the inverse function of join(). It is guaranteed that join(split(text, del), del) == text.

std::vector<std::string> parts1 = split(" hello world", " ");
assert(parts1.size() == 3);
assert(parts1[0] == ""s);
assert(parts1[1] == "hello"s);
assert(parts1[2] == "world"s);
 
std::vector<std::string> parts2 = split("<>", "<>");
assert(parts2.size() == 2);
assert(parts2[0] == ""s);
assert(parts2[1] == ""s);

This function returns a std::vector<std::string> by default, but a compatible container for string/string_view types can be specified via a template parameter:

Template Parameters

StringContainer	A container for strings or string_view-like types, e.g. std::vector<std::string> or std::list<gul14::string_view>
ContainerInsertFct	Type for the insert_fct function parameter.

Parameters

text	The string to be split
delimiter	The delimiting substring
insert_fct	By default, split() calls the emplace_back() member function on the container to insert strings. This parameter may contain a different function pointer or object with the signature void f(StringContainer&, gul14::string_view) that is called instead. This can be useful for containers that do not provide emplace_back() or for other customizations.

Returns

a container filled with the substrings that were separated by delimiter in the original string.

// Different string type
auto parts1 = split<std::vector<gul14::string_view>>("Hello world", " "); // behaves like split_sv()
assert(parts1.size() == 2);
assert(parts1[0] == "Hello"); // No lifetime problems because "Hello world" is a
assert(parts1[1] == "world"); // string literal with static storage duration
 
// Custom container type
auto parts2 = split<gul14::SmallVector<std::string, 3>>("a--b--c", "--");
assert(parts2.size() == 3);
assert(parts2[0] == "a");
assert(parts2[1] == "b");
assert(parts2[2] == "c");
 
// For a container without emplace_back(), use a custom inserter:
using WeirdContainer = std::queue<std::string>;
auto inserter = [](WeirdContainer& c, gul14::string_view sv) { c.emplace(sv); };
auto parts3 = split<WeirdContainer>("a.b", ".", inserter);
assert(parts3.size() == 2);
assert(parts3.front() == "a");
assert(parts3.back() == "b");

See also

split_sv() returns a vector of string_views,
split(const std::string&, const std::regex&) splits at a delimiter described by a regular expression, and
join() can join the vector back into a string.

Since

GUL version 2.5, the return type of split() can be specified as a template parameter and a custom inserter can be specified (it always returned std::vector<std::string> before).

split_sv()

template<typename StringContainer = std::vector<string_view>, typename ContainerInsertFct = void (*)(StringContainer&, string_view)>

StringContainer gul14::split_sv ( string_view  text, string_view  delimiter, ContainerInsertFct  insert_fct = detail::emplace_back<StringContainer>  )

inline

Separate a string at all occurrences of a delimiter, returning the strings between the delimiters in a vector.

This function is identical to split(string_view, string_view, ContainerInsertFct) except that it returns a std::vector of string_views instead of strings by default:

auto parts = split_sv("hello world", " "); // Return type is std::vector<gul14::string_view>
assert(parts.size() == 2);
assert(parts[0] == "hello"); // No problems with lifetime because "hello world"
assert(parts[1] == "world"); // is a string literal with static storage duration

See also

split(string_view, string_view, ContainerInsertFct) returns a vector of strings,
split(const std::string&, const std::regex&) splits at a delimiter described by a regular expression, and
join() can join the vector back into a string.

Since

GUL version 2.5, the return type of split_sv() can be specified as a template parameter and a custom inserter can be specified (it always returned std::vector<std::string> before).