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
15namespace base {
16
17// Splits |str| into a vector of strings delimited by |c|, placing the results
18// in |r|. If several instances of |c| are contiguous, or if |str| begins with
19// or ends with |c|, then an empty string is inserted.
20//
21// Every substring is trimmed of any leading or trailing white space.
22// NOTE: |c| must be in BMP (Basic Multilingual Plane)
23BASE_EXPORT void SplitString(const string16& str,
24                             char16 c,
25                             std::vector<string16>* r);
26
27// |str| should not be in a multi-byte encoding like Shift-JIS or GBK in which
28// the trailing byte of a multi-byte character can be in the ASCII range.
29// UTF-8, and other single/multi-byte ASCII-compatible encodings are OK.
30// Note: |c| must be in the ASCII range.
31BASE_EXPORT void SplitString(const std::string& str,
32                             char c,
33                             std::vector<std::string>* r);
34
35typedef std::vector<std::pair<std::string, std::string> > StringPairs;
36
37// Splits |line| into key value pairs according to the given delimiters and
38// removes whitespace leading each key and trailing each value. Returns true
39// only if each pair has a non-empty key and value. |key_value_pairs| will
40// include ("","") pairs for entries without |key_value_delimiter|.
41BASE_EXPORT bool SplitStringIntoKeyValuePairs(const std::string& line,
42                                              char key_value_delimiter,
43                                              char key_value_pair_delimiter,
44                                              StringPairs* key_value_pairs);
45
46// The same as SplitString, but use a substring delimiter instead of a char.
47BASE_EXPORT void SplitStringUsingSubstr(const string16& str,
48                                        const string16& s,
49                                        std::vector<string16>* r);
50BASE_EXPORT void SplitStringUsingSubstr(const std::string& str,
51                                        const std::string& s,
52                                        std::vector<std::string>* r);
53
54// The same as SplitString, but don't trim white space.
55// NOTE: |c| must be in BMP (Basic Multilingual Plane)
56BASE_EXPORT void SplitStringDontTrim(const string16& str,
57                                     char16 c,
58                                     std::vector<string16>* r);
59// |str| should not be in a multi-byte encoding like Shift-JIS or GBK in which
60// the trailing byte of a multi-byte character can be in the ASCII range.
61// UTF-8, and other single/multi-byte ASCII-compatible encodings are OK.
62// Note: |c| must be in the ASCII range.
63BASE_EXPORT void SplitStringDontTrim(const std::string& str,
64                                     char c,
65                                     std::vector<std::string>* r);
66
67// WARNING: this uses whitespace as defined by the HTML5 spec. If you need
68// a function similar to this but want to trim all types of whitespace, then
69// factor this out into a function that takes a string containing the characters
70// that are treated as whitespace.
71//
72// Splits the string along whitespace (where whitespace is the five space
73// characters defined by HTML 5). Each contiguous block of non-whitespace
74// characters is added to result.
75BASE_EXPORT void SplitStringAlongWhitespace(const string16& str,
76                                            std::vector<string16>* result);
77BASE_EXPORT void SplitStringAlongWhitespace(const std::string& str,
78                                            std::vector<std::string>* result);
79
80}  // namespace base
81
82#endif  // BASE_STRINGS_STRING_SPLIT_H_
83