2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
4 // Licensed under the Apache License, Version 2.0 (the License);
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
8 // http://www.apache.org/licenses/LICENSE-2.0
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
18 * @file FBaseUtilStringUtil.h
19 * @brief This is the header file for the %StringUtil class.
21 * This header file contains the declarations of the %StringUtil class.
23 #ifndef _FBASE_UTIL_STRING_UTIL_H_
24 #define _FBASE_UTIL_STRING_UTIL_H_
26 #include <FBaseString.h>
27 #include <FBaseByteBuffer.h>
28 #include <FBaseBuffer.h>
29 #include <FBaseResult.h>
32 namespace Tizen { namespace Base { namespace Utility
36 * @brief This class provides utility methods for %String operations.
40 * The %StringUtil class provides utility methods for String operations.
42 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/utility_namespace.htm">Utility</a>.
44 * The following example demonstrates how to use the %StringUtil class.
49 * using namespace Tizen::Base;
50 * using namespace Tizen::Base::Utility;
53 * MyClass::StringUtilSample(void)
55 * String str1(L"Sigma and Pi : \u03A0 and \u03A3");
58 * // String to McharBuffer
59 * McharBuffer* pMb = StringUtil::StringToMbN(str1);
61 * // Gets a length of string in McharBuffer
62 * int length = StringUtil::GetStringLengthInMb(*pMb);
64 * // McharBuffer to String
65 * StringUtil::MbToString(*pMb, str2);
67 * if (str1.Equals(str2))
76 class _OSP_EXPORT_ StringUtil
81 * Converts an McharBuffer to a null-terminated string. @n
82 * The position of the buffer is not changed.
84 * @brief <i> [Deprecated] </i>
85 * @deprecated This method is deprecated as @c mchar type is changed to @c wchar_t type.
86 * Instead of using this method, use the WcharBufferToString(const WcharBuffer& mb, String& str) method.
89 * @return An error code
90 * @param[in] mb An instance of McharBuffer
91 * @param[out] str The null-terminated string
92 * @exception E_SUCCESS The method is successful.
93 * @exception E_INVALID_ARG Either of the following conditions has occurred:
94 * - A specified input parameter is invalid.
95 * - @c null does not exist between the position and limit of buffer.
98 static result MbToString(const McharBuffer& mb, String& str);
101 * Converts an WcharBuffer to a null-terminated string. @n
102 * The position of the buffer is not changed.
106 * @return An error code
107 * @param[in] wb An instance of WcharBuffer
108 * @param[out] str The null-terminated string
109 * @exception E_SUCCESS The method is successful.
110 * @exception E_INVALID_ARG Either of the following conditions has occurred:
111 * - A specified input parameter is invalid.
112 * - @c null does not exist between the position and limit of buffer.
114 static result WcharBufferToString(const WcharBuffer& wb, String& str);
118 * Gets a new McharBuffer from the specified string. @n
119 * The buffer's limit is the length of the string plus one and the starting position is @c 0.
121 * @brief <i> [Deprecated] </i>
122 * @deprecated This method is deprecated as @c mchar type is changed to @c wchar_t type.
123 * Instead of using this method, use the StringToWcharBufferN(const String& str) method.
126 * @return A pointer to the McharBuffer instance from the specified string, @n
127 * else @c null if an exception occurs
128 * @param[in] str The string to read
129 * @exception E_SUCCESS The method is successful.
130 * @exception E_INVALID_ARG The specified @c str is an empty string.
131 * @remarks The specific error code can be accessed using the GetLastResult() method.
134 static McharBuffer* StringToMbN(const String& str);
137 * Gets a new WcharBuffer from the specified string. @n
138 * The buffer's limit is the length of the string plus one and the starting position is @c 0.
142 * @return A pointer to the WcharBuffer instance from the specified string, @n
143 * else @c null if an exception occurs
144 * @param[in] str The string to read
145 * @exception E_SUCCESS The method is successful.
146 * @exception E_INVALID_ARG The specified @c str is an empty string.
147 * @remarks The specific error code can be accessed using the GetLastResult() method.
149 static WcharBuffer* StringToWcharBufferN(const String& str);
153 * Gets a new McharBuffer from a substring of the specified string. @n
154 * The buffer's limit is the length of the string plus one and the starting position is @c 0.
156 * @brief <i> [Deprecated] </i>
157 * @deprecated This method is deprecated as @c mchar type is changed to @c wchar_t type.
158 * Instead of using this method, use the StringToWcharBufferN(const String& str, int index, int length) method.
161 * @return A pointer to the McharBuffer instance from the substring of the specified string, @n
162 * else @c null if an exception occurs
163 * @param[in] str The string to read
164 * @param[in] index The starting index for the substring in the string @n
165 * It must not be longer than the length of the string.
166 * @param[in] length The length of the substring @n
167 * It must not be longer than the length of the given string minus the specified @c index.
168 * @exception E_SUCCESS The method is successful.
169 * @exception E_INVALID_ARG The specified @c str is an empty string.
170 * @exception E_OUT_OF_RANGE The @c index and @c length are outside the bounds of the data structure.
171 * @remarks The specific error code can be accessed using the GetLastResult() method.
174 static McharBuffer* StringToMbN(const String& str, int index, int length);
177 * Gets a new WcharBuffer from a substring of the specified string. @n
178 * The buffer's limit is the length of the string plus one and the starting position is @c 0.
182 * @return A pointer to the WcharBuffer instance from the substring of the specified string, @n
183 * else @c null if an exception occurs
184 * @param[in] str The string to read
185 * @param[in] index The starting index for the substring in the string @n
186 * It must not be longer than the length of the string.
187 * @param[in] length The length of the substring @n
188 * It must not be longer than the length of the given string minus the specified @c index.
189 * @exception E_SUCCESS The method is successful.
190 * @exception E_INVALID_ARG The specified @c str is an empty string.
191 * @exception E_OUT_OF_RANGE The @c index and @c length are outside the bounds of the data structure.
192 * @remarks The specific error code can be accessed using the GetLastResult() method.
194 static WcharBuffer* StringToWcharBufferN(const String& str, int index, int length);
198 * Gets the string length in the specified McharBuffer. @n
199 * The string length is the length from the current position of the %McharBuffer to the @c null character.
200 * The position of the buffer is not changed.
202 * @brief <i> [Deprecated] </i>
203 * @deprecated This method is deprecated as @c mchar type is changed to @c wchar_t type.
204 * Instead of using this method, use the GetStringLengthInWcharBuffer(const WcharBuffer& wb) method.
208 * @return The length of the McharBuffer instance, @n
209 * else @c -1 if the %McharBuffer instance is not terminated with the @c null character
210 * @param[in] mb An instance of McharBuffer
211 * @remarks If @c null does not exist between the position and the limit of the buffer, the method returns @c -1.
214 static int GetStringLengthInMb(const McharBuffer& mb);
217 * Gets the string length in the specified WcharBuffer. @n
218 * The string length is the length from the current position of the %WcharBuffer to the @c null character.
219 * The position of the buffer is not changed.
223 * @return The length of the WcharBuffer instance, @n
224 * else @c -1 if the %WcharBuffer instance is not terminated with the @c null character
225 * @param[in] wb An instance of WcharBuffer
226 * @remarks If @c null does not exist between the position and the limit of the buffer, the method returns @c -1.
228 static int GetStringLengthInWcharBuffer(const WcharBuffer& wb);
231 * Gets a new ByteBuffer encoded from the specified string. @n
232 * The buffer's limit is the length of the string plus one and the starting position is @c 0.
236 * @return A pointer to the ByteBuffer instance encoded from the specified string, @n
237 * else @c null if an exception occurs
238 * @param[in] unicodeString The string to encode
239 * @exception E_SUCCESS The method is successful.
240 * @exception E_INVALID_ARG The specified input parameter is invalid.
241 * @remarks The specific error code can be accessed using the GetLastResult() method.
243 static ByteBuffer* StringToUtf8N(const String& unicodeString);
246 * Decodes a null-terminated UTF-8 string into a Unicode string. @n
247 * The position of the buffer is not changed.
251 * @return An error code
252 * @param[in] pUtf8String A pointer to the String instance containing UTF-8 codes
253 * @param[out] unicodeString A string containing Unicode characters
254 * @exception E_SUCCESS The method is successful.
255 * @exception E_INVALID_ARG The specified @c pUtf8String is a @c null reference.
256 * @exception E_INVALID_ENCODING_RANGE The indicated string contains UTF-8 code that is outside the bounds specified by the character encoding scheme.
258 * The following example demonstrates how to use the %Utf8ToString() method.
262 * const char* pUtf8String = "Utf8ToString";
266 * // Decodes a UTF-8 string into a Unicode string
267 * StringUtil::Utf8ToString(pUtf8String, str);
271 static result Utf8ToString(const char* pUtf8String, String& unicodeString);
274 * Decodes a string consisting of base 64 digits to a ByteBuffer. @n
275 * The ByteBuffer's limit is the length of the decoded multibyte string and the starting position is @c 0.
279 * @return A pointer to the ByteBuffer instance decoded from the specified string, @n
280 * else @c null if an exception occurs
281 * @param[in] base64String The string to decode
282 * @exception E_SUCCESS The method is successful.
283 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
284 * The specified @c base64String is not a valid Base64 string.
285 * @remarks The specific error code can be accessed using the GetLastResult() method.
287 * The following example demonstrates how to use the %DecodeBase64StringN() method.
291 * const char* pChar = "abcdefg123456";
292 * int size = strlen(pChar);
296 * buffer.Construct(size);
298 * buffer.SetArray(reinterpret_cast< const byte* >(pChar), 0, size);
301 * StringUtil::EncodeToBase64String(buffer, encodedStr);
303 * // Decodes a String consisting of base 64 digits to a ByteBuffer
304 * std::unique_ptr< ByteBuffer > pDecodedBuffer(StringUtil::DecodeBase64StringN(encodedStr));
308 static ByteBuffer* DecodeBase64StringN(const String& base64String);
311 * Encodes a ByteBuffer into a string consisting of base 64 characters. @n
312 * The position of the buffer is not changed.
316 * @return An error code
317 * @param[in] buffer An instance of ByteBuffer to encode
318 * @param[out] encodedString An instance of String consisting of base 64 characters
319 * @exception E_SUCCESS The method is successful.
320 * @exception E_INVALID_ARG Either of the following conditions has occurred:
321 * - A specified input parameter is invalid.
322 * - The @c buffer is empty.
324 * The following example demonstrates how to use the %EncodeToBase64String() method.
328 * const char* pChar = "abcdefg123456";
329 * int size = strlen(pChar);
333 * buffer.Construct(size);
335 * buffer.SetArray(reinterpret_cast< const byte* >(pChar), 0, size);
338 * // Encodes a ByteBuffer into a String consisting of base 64 characters
339 * StringUtil::EncodeToBase64String(buffer, encodedStr);
343 static result EncodeToBase64String(const ByteBuffer& buffer, String& encodedString);
347 * This default constructor is intentionally declared as private because this class cannot be constructed.
352 * This destructor is intentionally declared as private because this class cannot be constructed.
357 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
359 * @param[in] rhs The instance of the StringUtil
361 StringUtil(const StringUtil& rhs);
364 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
366 * @param[in] rhs An instance of %StringUtil
368 StringUtil& operator =(const StringUtil& rhs);
371 }}} // Tizen::Base::Utility
373 #endif // _FBASE_UTIL_STRING_UTIL_H_