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