//

// Copyright 2017 The Abseil Authors.

//

// Licensed under the Apache License, Version 2.0 (the "License");

// you may not use this file except in compliance with the License.

// You may obtain a copy of the License at

//

//      https://www.apache.org/licenses/LICENSE-2.0

//

// Unless required by applicable law or agreed to in writing, software

// distributed under the License is distributed on an "AS IS" BASIS,

// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

// See the License for the specific language governing permissions and

// limitations under the License.

//

// -----------------------------------------------------------------------------

// File: str_split.h

// -----------------------------------------------------------------------------

//

// This file contains functions for splitting strings. It defines the main

// `StrSplit()` function, several delimiters for determining the boundaries on

// which to split the string, and predicates for filtering delimited results.

// `StrSplit()` adapts the returned collection to the type specified by the

// caller.

//

// Example:

//

//   // Splits the given string on commas. Returns the results in a

//   // vector of strings.

//   std::vector<std::string> v = absl::StrSplit("a,b,c", ',');

//   // Can also use ","

//   // v[0] == "a", v[1] == "b", v[2] == "c"

//

// See StrSplit() below for more information.

#ifndef ABSL_STRINGS_STR_SPLIT_H_

#define ABSL_STRINGS_STR_SPLIT_H_

#include <algorithm>

#include <cstddef>

#include <map>

#include <set>

#include <string>

#include <utility>

#include <vector>

#include "absl/base/internal/raw_logging.h"

#include "absl/base/macros.h"

#include "absl/strings/internal/str_split_internal.h"

#include "absl/strings/string_view.h"

#include "absl/strings/strip.h"

namespace absl {

ABSL_NAMESPACE_BEGIN

//------------------------------------------------------------------------------

// Delimiters

//------------------------------------------------------------------------------

//

// `StrSplit()` uses delimiters to define the boundaries between elements in the

// provided input. Several `Delimiter` types are defined below. If a string

// (`const char*`, `std::string`, or `absl::string_view`) is passed in place of

// an explicit `Delimiter` object, `StrSplit()` treats it the same way as if it

// were passed a `ByString` delimiter.

//

// A `Delimiter` is an object with a `Find()` function that knows how to find

// the first occurrence of itself in a given `absl::string_view`.

//

// The following `Delimiter` types are available for use within `StrSplit()`:

//

//   - `ByString` (default for string arguments)

//   - `ByChar` (default for a char argument)

//   - `ByAnyChar`

//   - `ByLength`

//   - `MaxSplits`

//

// A Delimiter's `Find()` member function will be passed an input `text` that is

// to be split and a position (`pos`) to begin searching for the next delimiter

// in `text`. The returned absl::string_view should refer to the next occurrence

// (after `pos`) of the represented delimiter; this returned absl::string_view

// represents the next location where the input `text` should be broken.

//

// The returned absl::string_view may be zero-length if the Delimiter does not

// represent a part of the string (e.g., a fixed-length delimiter). If no

// delimiter is found in the input `text`, a zero-length absl::string_view

// referring to `text.end()` should be returned (e.g.,

// `text.substr(text.size())`). It is important that the returned

// absl::string_view always be within the bounds of the input `text` given as an

// argument--it must not refer to a string that is physically located outside of

// the given string.

//

// The following example is a simple Delimiter object that is created with a

// single char and will look for that char in the text passed to the `Find()`

// function:

//

//   struct SimpleDelimiter {

//     const char c_;

//     explicit SimpleDelimiter(char c) : c_(c) {}

//     absl::string_view Find(absl::string_view text, size_t pos) {

//       auto found = text.find(c_, pos);

//       if (found == absl::string_view::npos)

//         return text.substr(text.size());

//

//       return text.substr(found, 1);

//     }

//   };

// ByString

//

// A sub-string delimiter. If `StrSplit()` is passed a string in place of a

// `Delimiter` object, the string will be implicitly converted into a

// `ByString` delimiter.

//

// Example:

//

//   // Because a string literal is converted to an `absl::ByString`,

//   // the following two splits are equivalent.

//

//   std::vector<std::string> v1 = absl::StrSplit("a, b, c", ", ");

//

//   using absl::ByString;

//   std::vector<std::string> v2 = absl::StrSplit("a, b, c",

//                                                ByString(", "));

//   // v[0] == "a", v[1] == "b", v[2] == "c"

class ByString {

 public:

  explicit ByString(absl::string_view sp);

  absl::string_view Find(absl::string_view text, size_t pos) const;

 private:

  const std::string delimiter_;

};

// ByAsciiWhitespace

//

// A sub-string delimiter that splits by ASCII whitespace

// (space, tab, vertical tab, formfeed, linefeed, or carriage return).

// Note: you probably want to use absl::SkipEmpty() as well!

//

// This class is equivalent to ByAnyChar with ASCII whitespace chars.

//

// Example:

//

//   std::vector<std::string> v = absl::StrSplit(

//       "a b\tc\n  d  \n", absl::ByAsciiWhitespace(), absl::SkipEmpty());

//   // v[0] == "a", v[1] == "b", v[2] == "c", v[3] == "d"

class ByAsciiWhitespace {

 public:

  absl::string_view Find(absl::string_view text, size_t pos) const;

};

// ByChar

//

// A single character delimiter. `ByChar` is functionally equivalent to a

// 1-char string within a `ByString` delimiter, but slightly more efficient.

//

// Example:

//

//   // Because a char literal is converted to a absl::ByChar,

//   // the following two splits are equivalent.

//   std::vector<std::string> v1 = absl::StrSplit("a,b,c", ',');

//   using absl::ByChar;

//   std::vector<std::string> v2 = absl::StrSplit("a,b,c", ByChar(','));

//   // v[0] == "a", v[1] == "b", v[2] == "c"

//

// `ByChar` is also the default delimiter if a single character is given

// as the delimiter to `StrSplit()`. For example, the following calls are

// equivalent:

//

//   std::vector<std::string> v = absl::StrSplit("a-b", '-');

//

//   using absl::ByChar;

//   std::vector<std::string> v = absl::StrSplit("a-b", ByChar('-'));

//

class ByChar {

 public:

  explicit ByChar(char c) : c_(c) {}

  absl::string_view Find(absl::string_view text, size_t pos) const;

 private:

  char c_;

};

// ByAnyChar

//

// A delimiter that will match any of the given byte-sized characters within

// its provided string.

//

// Note: this delimiter works with single-byte string data, but does not work

// with variable-width encodings, such as UTF-8.

//

// Example:

//

//   using absl::ByAnyChar;

//   std::vector<std::string> v = absl::StrSplit("a,b=c", ByAnyChar(",="));

//   // v[0] == "a", v[1] == "b", v[2] == "c"

//

// If `ByAnyChar` is given the empty string, it behaves exactly like

// `ByString` and matches each individual character in the input string.

//

class ByAnyChar {

 public:

  explicit ByAnyChar(absl::string_view sp);

  absl::string_view Find(absl::string_view text, size_t pos) const;

 private:

  const std::string delimiters_;

};

// ByLength

//

// 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 absl::ByLength;

//   std::vector<std::string> v = absl::StrSplit("123456789", ByLength(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 absl::ByLength;

//   std::vector<std::string> v = absl::StrSplit("12345", ByLength(2));

//

//   // v[0] == "12", v[1] == "34", v[2] == "5"

class ByLength {

 public:

  explicit ByLength(ptrdiff_t length);

  absl::string_view Find(absl::string_view text, size_t pos) const;

 private:

  const ptrdiff_t length_;

};

namespace strings_internal {

// A traits-like metafunction for selecting the default Delimiter object type

// for a particular Delimiter type. The base case simply exposes type Delimiter

// itself as the delimiter's Type. However, there are specializations for

// string-like objects that map them to the ByString delimiter object.

// This allows functions like absl::StrSplit() and absl::MaxSplits() to accept

// string-like objects (e.g., ',') as delimiter arguments but they will be

// treated as if a ByString delimiter was given.

template <typename Delimiter>

struct SelectDelimiter {

  using type = Delimiter;

};

template <>

struct SelectDelimiter<char> {

  using type = ByChar;

};

template <>

struct SelectDelimiter<char*> {

  using type = ByString;

};

template <>

struct SelectDelimiter<const char*> {

  using type = ByString;

};

template <>

struct SelectDelimiter<absl::string_view> {

  using type = ByString;

};

template <>

struct SelectDelimiter<std::string> {

  using type = ByString;

};

// Wraps another delimiter and sets a max number of matches for that delimiter.

template <typename Delimiter>

class MaxSplitsImpl {

 public:

  MaxSplitsImpl(Delimiter delimiter, int limit)

      : delimiter_(delimiter), limit_(limit), count_(0) {}

  absl::string_view Find(absl::string_view text, size_t pos) {

    if (count_++ == limit_) {

      return absl::string_view(text.data() + text.size(),

                               0);  // No more matches.

    }

    return delimiter_.Find(text, pos);

  }

 private:

  Delimiter delimiter_;

  const int limit_;

  int count_;

};

}  // namespace strings_internal

// MaxSplits()

//

// 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 absl::MaxSplits;

//   std::vector<std::string> v = absl::StrSplit("a,b,c", MaxSplits(',', 1));

//

//   // v[0] == "a", v[1] == "b,c"

template <typename Delimiter>

inline strings_internal::MaxSplitsImpl<

    typename strings_internal::SelectDelimiter<Delimiter>::type>

MaxSplits(Delimiter delimiter, int limit) {

  typedef

      typename strings_internal::SelectDelimiter<Delimiter>::type DelimiterType;

  return strings_internal::MaxSplitsImpl<DelimiterType>(

      DelimiterType(delimiter), limit);

}

//------------------------------------------------------------------------------

// Predicates

//------------------------------------------------------------------------------

//

// Predicates filter the results of a `StrSplit()` by determining whether or not

// a resultant element is included in the result set. A predicate may be passed

// as an optional third argument to the `StrSplit()` function.

//

// Predicates are unary functions (or functors) that take a single

// `absl::string_view` argument and return a bool indicating whether the

// argument should be included (`true`) or excluded (`false`).

//

// Predicates are useful when filtering out empty substrings. By default, empty

// substrings may be returned by `StrSplit()`, which is similar to the way split

// functions work in other programming languages.

// AllowEmpty()

//

// 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 `StrSplit()`;

// however, it might be useful at some call sites to make the intent explicit.

//

// Example:

//

//  std::vector<std::string> v = absl::StrSplit(" a , ,,b,", ',', AllowEmpty());

//

//  // v[0] == " a ", v[1] == " ", v[2] == "", v[3] = "b", v[4] == ""

struct AllowEmpty {

  bool operator()(absl::string_view) const { return true; }

};

// SkipEmpty()

//

// Returns `false` if the given `absl::string_view` is empty, indicating that

// `StrSplit()` should omit the empty string.

//

// Example:

//

//   std::vector<std::string> v = absl::StrSplit(",a,,b,", ',', SkipEmpty());

//

//   // v[0] == "a", v[1] == "b"

//

// Note: `SkipEmpty()` does not consider a string containing only whitespace

// to be empty. To skip such whitespace as well, use the `SkipWhitespace()`

// predicate.

struct SkipEmpty {

  bool operator()(absl::string_view sp) const { return !sp.empty(); }

};

// SkipWhitespace()

//

// Returns `false` if the given `absl::string_view` is empty *or* contains only

// whitespace, indicating that `StrSplit()` should omit the string.

//

// Example:

//

//   std::vector<std::string> v = absl::StrSplit(" a , ,,b,",

//                                               ',', SkipWhitespace());

//   // v[0] == " a ", v[1] == "b"

//

//   // SkipEmpty() would return whitespace elements

//   std::vector<std::string> v = absl::StrSplit(" a , ,,b,", ',', SkipEmpty());

//   // v[0] == " a ", v[1] == " ", v[2] == "b"

struct SkipWhitespace {

  bool operator()(absl::string_view sp) const {

    sp = absl::StripAsciiWhitespace(sp);

    return !sp.empty();

  }

};

template <typename T>

using EnableSplitIfString =

    typename std::enable_if<std::is_same<T, std::string>::value ||

                            std::is_same<T, const std::string>::value,

                            int>::type;

//------------------------------------------------------------------------------

//                                  StrSplit()

//------------------------------------------------------------------------------

// StrSplit()

//

// Splits 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 `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.

//

// 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.

//

// 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.

template <typename Delimiter>

strings_internal::Splitter<

    typename strings_internal::SelectDelimiter<Delimiter>::type, AllowEmpty,

    absl::string_view>

StrSplit(strings_internal::ConvertibleToStringView text, Delimiter d) {

  using DelimiterType =

      typename strings_internal::SelectDelimiter<Delimiter>::type;

  return strings_internal::Splitter<DelimiterType, AllowEmpty,

                                    absl::string_view>(

      text.value(), DelimiterType(d), AllowEmpty());

}

template <typename Delimiter, typename StringType,

          EnableSplitIfString<StringType> = 0>

strings_internal::Splitter<

    typename strings_internal::SelectDelimiter<Delimiter>::type, AllowEmpty,

    std::string>

StrSplit(StringType&& text, Delimiter d) {

  using DelimiterType =

      typename strings_internal::SelectDelimiter<Delimiter>::type;

  return strings_internal::Splitter<DelimiterType, AllowEmpty, std::string>(

      std::move(text), DelimiterType(d), AllowEmpty());

}

template <typename Delimiter, typename Predicate>

strings_internal::Splitter<

    typename strings_internal::SelectDelimiter<Delimiter>::type, Predicate,

    absl::string_view>

StrSplit(strings_internal::ConvertibleToStringView text, Delimiter d,

         Predicate p) {

  using DelimiterType =

      typename strings_internal::SelectDelimiter<Delimiter>::type;

  return strings_internal::Splitter<DelimiterType, Predicate,

                                    absl::string_view>(

      text.value(), DelimiterType(std::move(d)), std::move(p));

}

template <typename Delimiter, typename Predicate, typename StringType,

          EnableSplitIfString<StringType> = 0>

strings_internal::Splitter<

    typename strings_internal::SelectDelimiter<Delimiter>::type, Predicate,

    std::string>

StrSplit(StringType&& text, Delimiter d, Predicate p) {

  using DelimiterType =

      typename strings_internal::SelectDelimiter<Delimiter>::type;

  return strings_internal::Splitter<DelimiterType, Predicate, std::string>(

      std::move(text), DelimiterType(d), std::move(p));

}

ABSL_NAMESPACE_END

}  // namespace absl

#endif  // ABSL_STRINGS_STR_SPLIT_H_