• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (c) 2021 Huawei Device Co., Ltd.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 /**
17 * @file string_ex.h
18 *
19 * @brief Provides the global string operation function implemented in c_utils.
20 */
21 
22 /**
23 * @defgroup StringOperation
24 * @{
25 * @brief Provides interfaces for operating strings.
26 *
27 * Include converting between uppercase and lowercase,
28 * string replacement, trim and split etc.
29 */
30 #ifndef STRING_EX_H
31 #define STRING_EX_H
32 
33 #include <string>
34 #include <vector>
35 
36 namespace OHOS {
37 
38 /**
39  * @ingroup StringOperation
40  * @brief Converts all letters in a string to uppercase.
41  *
42  * @param str Indicates the base string.
43  * @return Returns a new `std::string` object after conversion.
44  */
45 std::string UpperStr(const std::string& str);
46 
47 /**
48  * @ingroup StringOperation
49  * @brief Converts all letters in a string to lowercase.
50  *
51  * @param str Indicates the base string.
52  * @return Returns a new `std::string` object after conversion.
53  */
54 std::string LowerStr(const std::string& str);
55 
56 /**
57  * @ingroup StringOperation
58  * @brief Replaces a substring in the base string.
59  *
60  * @param str Indicates the substring to be replaced.
61  * @param src Indicates the base string.
62  * @param dst Indicates the expected substring for replacement.
63  * @return Returns a new `std::string` object after replacement.
64  */
65 std::string ReplaceStr(const std::string& str, const std::string& src, const std::string& dst);
66 
67 /**
68  * @ingroup StringOperation
69  * @brief Trims a string indicated by `cTrim` from both ends of the base string.
70  *
71  * @param str Indicates the base string.
72  * @param cTrim Indicates the string to trim from the base string, which is '' by default.
73  * @return Returns a new `std::string` object after trimming.
74  */
75 std::string TrimStr(const std::string& str, const char cTrim = ' ');
76 
77 /**
78  * @ingroup StringOperation
79  * @brief Converts a decimal value to a hexadecimal string.
80  *
81  * @param value Indicates the decimal value to convert.
82  * @param upper Specifies whether the output string is in uppercase.
83  * The default value is `true`.
84  * @return Returns a new `std::string` object after conversion.
85  */
86 std::string DexToHexString(int value, bool upper = true);
87 
88 /**
89  * @ingroup StringOperation
90  * @brief Splits a string by `sep`.
91  *
92  * @param str Indicates the base string.
93  * @param sep Indicates the substring to be used as the separator.
94  * @param strs Indicates the `std::vector` object to store the results.
95  * @param canEmpty Specifies whether the output string can be an empty string.
96  * The default value is `false`.
97  * @param needTrim Specifies whether to remove whitespace from the output string.
98  * The default value is `true`.
99  */
100 void SplitStr(const std::string& str, const std::string& sep, std::vector<std::string>& strs,
101               bool canEmpty = false, bool needTrim = true);
102 
103 /**
104  * @ingroup StringOperation
105  * @brief Converts a value of int, double, or any other type to a string.
106  *
107  * @tparam T Indicates the type of the input data.
108  * @param  iValue Indicates the input data.
109  * @return Returns a new `std::string` object after conversion.
110  */
111 template<class T>
ToString(T iValue)112 inline std::string ToString(T iValue)
113 {
114     return std::to_string(iValue);
115 }
116 
117 /**
118  * @ingroup StringOperation
119  * @brief Converts a string to an int value.
120  *
121  * @param str Indicates the string to be converted.
122  * @param value Indicates the `int` variable to store the result.
123  * @return Returns `true` if the operation is successful;
124  * returns `false` otherwise.
125  */
126 bool StrToInt(const std::string& str, int& value);
127 
128 /**
129  * @ingroup StringOperation
130  * @brief Checks whether all characters in a string are numeric.
131  *
132  * @param str Indicates the base string.
133  * @return Returns `true` if all characters in the string are numeric;
134  * returns `false` otherwise.
135  */
136 bool IsNumericStr(const std::string& str);
137 
138 /**
139  * @ingroup StringOperation
140  * @brief Checks whether all characters in a string are alphabetic.
141  *
142  * @param str Indicates the base string.
143  * @return Returns `true` if all characters in the string are alphabetic;
144  * returns `false` otherwise.
145  */
146 bool IsAlphaStr(const std::string& str);
147 
148 /**
149  * @ingroup StringOperation
150  * @brief Checks whether all characters in a string are in uppercase.
151  *
152  * @param str Indicates the base string.
153  * @return Returns `true` if all characters in the string are in uppercase;
154  * returns `false` otherwise.
155  */
156 bool IsUpperStr(const std::string& str);
157 
158 /**
159  * @ingroup StringOperation
160  * @brief Checks whether all characters in a string are in lowercase.
161  *
162  * @param str Indicates the base string.
163  * @return Returns `true` if all characters in the string are in lowercase;
164  * returns `false` otherwise.
165  */
166 bool IsLowerStr(const std::string& str);
167 
168 /**
169  * @ingroup StringOperation
170  * @brief Checks whether a string contains the specified substring.
171  *
172  * @param str Indicates the base string.
173  * @param sub Indicates the substring.
174  * @return Returns `true` if the string contains the specified substring;
175  * returns `false` otherwise.
176  */
177 bool IsSubStr(const std::string& str, const std::string& sub);
178 
179 /**
180  * @ingroup StringOperation
181  * @brief Obtains the first substring between the substrings specified
182  * by `left` and `right`.
183  *
184  * @param str Indicates the base string.
185  * @param left Indicates the left string.
186  * @param right Indicates the right string.
187  * @param sub Indicates the `std::string` object to store the result string.
188  * @return Returns `pos` if the operation is successful;
189  * returns `string::npos` otherwise.
190  */
191 std::string::size_type GetFirstSubStrBetween(const std::string& str, const std::string& left,
192                                              const std::string& right, std::string& sub);
193 
194 /**
195  * @ingroup StringOperation
196  * @brief Obtains all of the substrings between the substrings specified
197  * by `left` and `right`.
198  *
199  * @param str Indicates the base string.
200  * @param left Indicates the left string.
201  * @param right Indicates the right string.
202  * @param sub Indicates the `std::vector` object to store all the result strings.
203  */
204 void GetSubStrBetween(const std::string& str, const std::string& left,
205                       const std::string& right, std::vector<std::string>& sub);
206 
207 /**
208  * @ingroup StringOperation
209  * @brief Checks whether two strings are equal.
210  *
211  * @param first Indicates the first string to check.
212  * @param second Indicates the second string to check.
213  * @note The string is case-insensitive.
214  */
215 bool IsSameTextStr(const std::string& first, const std::string& second);
216 
217 /**
218  * @ingroup StringOperation
219  * @brief Checks whether all characters in a string are ASCII encoded.
220  *
221  * @param str Indicates the base string.
222  * @return Returns `true` if all characters in the string are ASCII encoded;
223  * returns `false` otherwise.
224  */
225 bool IsAsciiString(const std::string& str);
226 
227 #ifndef IOS_PLATFORM
228 /**
229  * @ingroup StringOperation
230  * @brief Converts a string from UTF-16 to UTF-8 encoded.
231  *
232  * @param str16 Indicates a `std::u16string` object.
233  * @return Returns an empty `std::string` object if the operation fails.
234  */
235 std::string Str16ToStr8(const std::u16string& str16);
236 
237 /**
238  * @ingroup StringOperation
239  * @brief Converts a string from UTF-8 to UTF-16 encoded.
240  *
241  * @param str Indicates a `std::string` object.
242  * @return Returns an empty `std::u16string` object if the operation fails.
243  */
244 std::u16string Str8ToStr16(const std::string& str);
245 #endif
246 } // namespace OHOS
247 
248 #endif // STRING_EX_H
249 
250 /**@}*/
251