1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. 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 <string> 9 #include <utility> 10 #include <vector> 11 12 #include "base/base_export.h" 13 #include "base/strings/string16.h" 14 #include "base/strings/string_piece.h" 15 16 namespace base { 17 18 enum WhitespaceHandling { 19 KEEP_WHITESPACE, 20 TRIM_WHITESPACE, 21 }; 22 23 enum SplitResult { 24 // Strictly return all results. 25 // 26 // If the input is ",," and the separator is ',' this will return a 27 // vector of three empty strings. 28 SPLIT_WANT_ALL, 29 30 // Only nonempty results will be added to the results. Multiple separators 31 // will be coalesced. Separators at the beginning and end of the input will 32 // be ignored. With TRIM_WHITESPACE, whitespace-only results will be dropped. 33 // 34 // If the input is ",," and the separator is ',', this will return an empty 35 // vector. 36 SPLIT_WANT_NONEMPTY, 37 }; 38 39 // Split the given string on ANY of the given separators, returning copies of 40 // the result. 41 // 42 // To split on either commas or semicolons, keeping all whitespace: 43 // 44 // std::vector<std::string> tokens = base::SplitString( 45 // input, ",;", base::KEEP_WHITESPACE, base::SPLIT_WANT_ALL); 46 BASE_EXPORT std::vector<std::string> SplitString( 47 StringPiece input, 48 StringPiece separators, 49 WhitespaceHandling whitespace, 50 SplitResult result_type); 51 BASE_EXPORT std::vector<string16> SplitString( 52 StringPiece16 input, 53 StringPiece16 separators, 54 WhitespaceHandling whitespace, 55 SplitResult result_type); 56 57 // Like SplitString above except it returns a vector of StringPieces which 58 // reference the original buffer without copying. Although you have to be 59 // careful to keep the original string unmodified, this provides an efficient 60 // way to iterate through tokens in a string. 61 // 62 // To iterate through all whitespace-separated tokens in an input string: 63 // 64 // for (const auto& cur : 65 // base::SplitStringPiece(input, base::kWhitespaceASCII, 66 // base::KEEP_WHITESPACE, 67 // base::SPLIT_WANT_NONEMPTY)) { 68 // ... 69 BASE_EXPORT std::vector<StringPiece> SplitStringPiece( 70 StringPiece input, 71 StringPiece separators, 72 WhitespaceHandling whitespace, 73 SplitResult result_type); 74 BASE_EXPORT std::vector<StringPiece16> SplitStringPiece( 75 StringPiece16 input, 76 StringPiece16 separators, 77 WhitespaceHandling whitespace, 78 SplitResult result_type); 79 80 using StringPairs = std::vector<std::pair<std::string, std::string>>; 81 82 // Splits |line| into key value pairs according to the given delimiters and 83 // removes whitespace leading each key and trailing each value. Returns true 84 // only if each pair has a non-empty key and value. |key_value_pairs| will 85 // include ("","") pairs for entries without |key_value_delimiter|. 86 BASE_EXPORT bool SplitStringIntoKeyValuePairs(StringPiece input, 87 char key_value_delimiter, 88 char key_value_pair_delimiter, 89 StringPairs* key_value_pairs); 90 91 // Similar to SplitString, but use a substring delimiter instead of a list of 92 // characters that are all possible delimiters. 93 // 94 // TODO(brettw) this should probably be changed and expanded to provide a 95 // mirror of the SplitString[Piece] API above, just with the different 96 // delimiter handling. 97 BASE_EXPORT void SplitStringUsingSubstr(StringPiece16 input, 98 StringPiece16 delimiter, 99 std::vector<string16>* result); 100 BASE_EXPORT void SplitStringUsingSubstr(StringPiece input, 101 StringPiece delimiter, 102 std::vector<std::string>* result); 103 104 // Like SplitStringUsingSubstr above except it returns a vector of StringPieces 105 // which reference the original buffer without copying. Although you have to be 106 // careful to keep the original string unmodified, this provides an efficient 107 // way to iterate through tokens in a string. 108 // 109 // To iterate through all newline-separated tokens in an input string: 110 // 111 // for (const auto& cur : 112 // base::SplitStringUsingSubstr(input, "\r\n", 113 // base::KEEP_WHITESPACE, 114 // base::SPLIT_WANT_NONEMPTY)) { 115 // ... 116 BASE_EXPORT std::vector<StringPiece16> SplitStringPieceUsingSubstr( 117 StringPiece16 input, 118 StringPiece16 delimiter, 119 WhitespaceHandling whitespace, 120 SplitResult result_type); 121 BASE_EXPORT std::vector<StringPiece> SplitStringPieceUsingSubstr( 122 StringPiece input, 123 StringPiece delimiter, 124 WhitespaceHandling whitespace, 125 SplitResult result_type); 126 127 } // namespace base 128 129 #endif // BASE_STRINGS_STRING_SPLIT_H_ 130