1// Copyright (c) 2011 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_STRING_SPLIT_H_
6#define BASE_STRING_SPLIT_H_
7#pragma once
8
9#include <string>
10#include <utility>
11#include <vector>
12
13#include "base/base_api.h"
14#include "base/string16.h"
15
16namespace base {
17
18// Splits |str| into a vector of strings delimited by |s|. Append the results
19// into |r| as they appear. If several instances of |s| are contiguous, or if
20// |str| begins with or ends with |s|, then an empty string is inserted.
21//
22// Every substring is trimmed of any leading or trailing white space.
23// Where wchar_t is char16 (i.e. Windows), |c| must be in BMP
24// (Basic Multilingual Plane). Elsewhere (Linux/Mac), wchar_t
25// should be a valid Unicode code point (32-bit).
26BASE_API void SplitString(const std::wstring& str,
27                          wchar_t c,
28                          std::vector<std::wstring>* r);
29// NOTE: |c| must be in BMP (Basic Multilingual Plane)
30BASE_API void SplitString(const string16& str,
31                          char16 c,
32                          std::vector<string16>* r);
33// |str| should not be in a multi-byte encoding like Shift-JIS or GBK in which
34// the trailing byte of a multi-byte character can be in the ASCII range.
35// UTF-8, and other single/multi-byte ASCII-compatible encodings are OK.
36// Note: |c| must be in the ASCII range.
37BASE_API void SplitString(const std::string& str,
38                          char c,
39                          std::vector<std::string>* r);
40
41BASE_API bool SplitStringIntoKeyValues(
42    const std::string& line,
43    char key_value_delimiter,
44    std::string* key, std::vector<std::string>* values);
45
46BASE_API bool SplitStringIntoKeyValuePairs(
47    const std::string& line,
48    char key_value_delimiter,
49    char key_value_pair_delimiter,
50    std::vector<std::pair<std::string, std::string> >* kv_pairs);
51
52// The same as SplitString, but use a substring delimiter instead of a char.
53BASE_API void SplitStringUsingSubstr(const string16& str,
54                                     const string16& s,
55                                     std::vector<string16>* r);
56BASE_API void SplitStringUsingSubstr(const std::string& str,
57                                     const std::string& s,
58                                     std::vector<std::string>* r);
59
60// The same as SplitString, but don't trim white space.
61// NOTE: |c| must be in BMP (Basic Multilingual Plane)
62BASE_API void SplitStringDontTrim(const string16& str,
63                                  char16 c,
64                                  std::vector<string16>* r);
65// |str| should not be in a multi-byte encoding like Shift-JIS or GBK in which
66// the trailing byte of a multi-byte character can be in the ASCII range.
67// UTF-8, and other single/multi-byte ASCII-compatible encodings are OK.
68// Note: |c| must be in the ASCII range.
69BASE_API void SplitStringDontTrim(const std::string& str,
70                                  char c,
71                                  std::vector<std::string>* r);
72
73// WARNING: this uses whitespace as defined by the HTML5 spec. If you need
74// a function similar to this but want to trim all types of whitespace, then
75// factor this out into a function that takes a string containing the characters
76// that are treated as whitespace.
77//
78// Splits the string along whitespace (where whitespace is the five space
79// characters defined by HTML 5). Each contiguous block of non-whitespace
80// characters is added to result.
81BASE_API void SplitStringAlongWhitespace(const std::wstring& str,
82                                         std::vector<std::wstring>* result);
83BASE_API void SplitStringAlongWhitespace(const string16& str,
84                                         std::vector<string16>* result);
85BASE_API void SplitStringAlongWhitespace(const std::string& str,
86                                         std::vector<std::string>* result);
87
88}  // namespace base
89
90#endif  // BASE_STRING_SPLIT_H
91