1 // Copyright 2012 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef BASE_STRINGS_STRING_SPLIT_H_ 6 #define BASE_STRINGS_STRING_SPLIT_H_ 7 8 #include <optional> 9 #include <string> 10 #include <string_view> 11 #include <utility> 12 #include <vector> 13 14 #include "base/base_export.h" 15 #include "build/build_config.h" 16 17 namespace base { 18 19 // Splits a string at the first instance of `separator`, returning a pair of 20 // `std::string_view`: `first` is the (potentially empty) part that comes before 21 // the separator, and `second` is the (potentially empty) part that comes after. 22 // If `separator` is not in `input`, returns `std::nullopt`. 23 BASE_EXPORT std::optional<std::pair<std::string_view, std::string_view>> 24 SplitStringOnce(std::string_view input, char separator); 25 26 // Similar to the above, but splits the string at the first instance of any 27 // separator in `separators`. 28 BASE_EXPORT std::optional<std::pair<std::string_view, std::string_view>> 29 SplitStringOnce(std::string_view input, std::string_view separators); 30 31 // Splits a string at the last instance of `separator`, returning a pair of 32 // `std::string_view`: `first` is the (potentially empty) part that comes before 33 // the separator, and `second` is the (potentially empty) part that comes after. 34 // If `separator` is not in `input`, returns `std::nullopt`. 35 BASE_EXPORT std::optional<std::pair<std::string_view, std::string_view>> 36 RSplitStringOnce(std::string_view input, char separator); 37 38 // Similar to the above, but splits the string at the last instance of any 39 // separator in `separators`. 40 BASE_EXPORT std::optional<std::pair<std::string_view, std::string_view>> 41 RSplitStringOnce(std::string_view input, std::string_view separators); 42 43 enum WhitespaceHandling { 44 KEEP_WHITESPACE, 45 TRIM_WHITESPACE, 46 }; 47 48 enum SplitResult { 49 // Strictly return all results. 50 // 51 // If the input is ",," and the separator is ',' this will return a 52 // vector of three empty strings. 53 SPLIT_WANT_ALL, 54 55 // Only nonempty results will be added to the results. Multiple separators 56 // will be coalesced. Separators at the beginning and end of the input will 57 // be ignored. With TRIM_WHITESPACE, whitespace-only results will be dropped. 58 // 59 // If the input is ",," and the separator is ',', this will return an empty 60 // vector. 61 SPLIT_WANT_NONEMPTY, 62 }; 63 64 // Split the given string on ANY of the given separators, returning copies of 65 // the result. 66 // 67 // Note this is inverse of JoinString() defined in string_util.h. 68 // 69 // To split on either commas or semicolons, keeping all whitespace: 70 // 71 // std::vector<std::string> tokens = base::SplitString( 72 // input, ",;", base::KEEP_WHITESPACE, base::SPLIT_WANT_ALL); 73 [[nodiscard]] BASE_EXPORT std::vector<std::string> SplitString( 74 std::string_view input, 75 std::string_view separators, 76 WhitespaceHandling whitespace, 77 SplitResult result_type); 78 [[nodiscard]] BASE_EXPORT std::vector<std::u16string> SplitString( 79 std::u16string_view input, 80 std::u16string_view separators, 81 WhitespaceHandling whitespace, 82 SplitResult result_type); 83 84 // Like SplitString above except it returns a vector of StringPieces which 85 // reference the original buffer without copying. Although you have to be 86 // careful to keep the original string unmodified, this provides an efficient 87 // way to iterate through tokens in a string. 88 // 89 // Note this is inverse of JoinString() defined in string_util.h. 90 // 91 // To iterate through all whitespace-separated tokens in an input string: 92 // 93 // for (const auto& cur : 94 // base::SplitStringPiece(input, base::kWhitespaceASCII, 95 // base::KEEP_WHITESPACE, 96 // base::SPLIT_WANT_NONEMPTY)) { 97 // ... 98 [[nodiscard]] BASE_EXPORT std::vector<std::string_view> SplitStringPiece( 99 std::string_view input, 100 std::string_view separators, 101 WhitespaceHandling whitespace, 102 SplitResult result_type); 103 [[nodiscard]] BASE_EXPORT std::vector<std::u16string_view> SplitStringPiece( 104 std::u16string_view input, 105 std::u16string_view separators, 106 WhitespaceHandling whitespace, 107 SplitResult result_type); 108 109 using StringPairs = std::vector<std::pair<std::string, std::string>>; 110 111 // Splits |line| into key value pairs according to the given delimiters and 112 // removes whitespace leading each key and trailing each value. Returns true 113 // only if each pair has a non-empty key and value. |key_value_pairs| will 114 // include ("","") pairs for entries without |key_value_delimiter|. 115 BASE_EXPORT bool SplitStringIntoKeyValuePairs(std::string_view input, 116 char key_value_delimiter, 117 char key_value_pair_delimiter, 118 StringPairs* key_value_pairs); 119 120 // Similar to SplitStringIntoKeyValuePairs, but use a substring 121 // |key_value_pair_delimiter| instead of a single char. 122 BASE_EXPORT bool SplitStringIntoKeyValuePairsUsingSubstr( 123 std::string_view input, 124 char key_value_delimiter, 125 std::string_view key_value_pair_delimiter, 126 StringPairs* key_value_pairs); 127 128 // Similar to SplitString, but use a substring delimiter instead of a list of 129 // characters that are all possible delimiters. 130 [[nodiscard]] BASE_EXPORT std::vector<std::u16string> SplitStringUsingSubstr( 131 std::u16string_view input, 132 std::u16string_view delimiter, 133 WhitespaceHandling whitespace, 134 SplitResult result_type); 135 [[nodiscard]] BASE_EXPORT std::vector<std::string> SplitStringUsingSubstr( 136 std::string_view input, 137 std::string_view delimiter, 138 WhitespaceHandling whitespace, 139 SplitResult result_type); 140 141 // Like SplitStringUsingSubstr above except it returns a vector of StringPieces 142 // which reference the original buffer without copying. Although you have to be 143 // careful to keep the original string unmodified, this provides an efficient 144 // way to iterate through tokens in a string. 145 // 146 // To iterate through all newline-separated tokens in an input string: 147 // 148 // for (const auto& cur : 149 // base::SplitStringUsingSubstr(input, "\r\n", 150 // base::KEEP_WHITESPACE, 151 // base::SPLIT_WANT_NONEMPTY)) { 152 // ... 153 [[nodiscard]] BASE_EXPORT std::vector<std::u16string_view> 154 SplitStringPieceUsingSubstr(std::u16string_view input, 155 std::u16string_view delimiter, 156 WhitespaceHandling whitespace, 157 SplitResult result_type); 158 [[nodiscard]] BASE_EXPORT std::vector<std::string_view> 159 SplitStringPieceUsingSubstr(std::string_view input, 160 std::string_view delimiter, 161 WhitespaceHandling whitespace, 162 SplitResult result_type); 163 164 } // namespace base 165 166 #if BUILDFLAG(IS_WIN) 167 #include "base/strings/string_split_win.h" 168 #endif 169 170 #endif // BASE_STRINGS_STRING_SPLIT_H_ 171