base/strings/string_split.h

   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 }  // namespace base
 105
 106 #endif  // BASE_STRINGS_STRING_SPLIT_H_