Home | History | Annotate | Download | only in strings 
      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 BASE_EXPORT std::vector<string16> SplitStringUsingSubstr(
     94     StringPiece16 input,
     95     StringPiece16 delimiter,
     96     WhitespaceHandling whitespace,
     97     SplitResult result_type);
     98 BASE_EXPORT std::vector<std::string> SplitStringUsingSubstr(
     99     StringPiece input,
    100     StringPiece delimiter,
    101     WhitespaceHandling whitespace,
    102     SplitResult result_type);
    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