2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
19 * @file FBaseUtilStringUtil.h
20 * @brief This is the header file for the %StringUtil class.
22 * This header file contains the declarations of the %StringUtil class.
24 #ifndef _FBASE_UTIL_STRING_UTIL_H_
25 #define _FBASE_UTIL_STRING_UTIL_H_
27 #include <FBaseString.h>
28 #include <FBaseByteBuffer.h>
29 #include <FBaseBuffer.h>
30 #include <FBaseResult.h>
33 namespace Tizen { namespace Base { namespace Utility
37 * @brief This class provides various utility methods for String.
41 * The %StringUtil class provides various utility methods for String.
43 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/utility_namespace.htm">Utility</a>.
45 * The following example demonstrates how to use the %StringUtil class.
50 * using namespace Tizen::Base;
51 * using namespace Tizen::Base::Utility;
54 * MyClass::StringUtilSample(void)
56 * String str1(L"Sigma and Pi : \u03A0 and \u03A3");
59 * // String to McharBuffer
60 * McharBuffer* pMb = StringUtil::StringToMbN(str1);
62 * // Gets a length of string in McharBuffer
63 * int length = StringUtil::GetStringLengthInMb(*pMb);
65 * // McharBuffer to String
66 * StringUtil::MbToString(*pMb, str2);
68 * if (str1.Equals(str2))
77 class _OSP_EXPORT_ StringUtil
82 * Converts an McharBuffer to a null-terminated string. @n
83 * The position of the buffer is not changed.
85 * @brief <i> [Deprecated] </i>
86 * @deprecated This method is deprecated as @c mchar type is changed to @c wchar_t type.
87 * Instead of using this method, use the WcharBufferToString(const WcharBuffer& mb, String& str) method.
90 * @return An error code
91 * @param[in] mb An instance of McharBuffer
92 * @param[out] str The current position
93 * @exception E_SUCCESS The method is successful.
94 * @exception E_INVALID_ARG A specified input parameter is invalid, or
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 current position
109 * @exception E_SUCCESS The method is successful.
110 * @exception E_INVALID_ARG A specified input parameter is invalid, or
111 * @c null does not exist between the position and limit of buffer.
113 static result WcharBufferToString(const WcharBuffer& wb, String& str);
117 * Gets a new McharBuffer from the specified string. @n
118 * The buffer's limit is the length of the string plus one and the starting position is @c 0.
120 * @brief <i> [Deprecated] </i>
121 * @deprecated This method is deprecated as @c mchar type is changed to @c wchar_t type.
122 * Instead of using this method, use the StringToWcharBufferN(const String& str) method.
125 * @return A pointer to the McharBuffer instance from the specified string, @n
126 * else @c null if an exception occurs
127 * @param[in] str The string to read
128 * @exception E_SUCCESS The method is successful.
129 * @exception E_INVALID_ARG The specified @c str is an empty string.
130 * @remarks The specific error code can be accessed using the GetLastResult() method.
133 static McharBuffer* StringToMbN(const String& str);
136 * Gets a new WcharBuffer from the specified string. @n
137 * The buffer's limit is the length of the string plus one and the starting position is @c 0.
141 * @return A pointer to the WcharBuffer instance from the specified string, @n
142 * else @c null if an exception occurs
143 * @param[in] str The string to read
144 * @exception E_SUCCESS The method is successful.
145 * @exception E_INVALID_ARG The specified @c str is an empty string.
146 * @remarks The specific error code can be accessed using the GetLastResult() method.
148 static WcharBuffer* StringToWcharBufferN(const String& str);
152 * Gets a new McharBuffer from a substring of the specified string. @n
153 * The buffer's limit is the length of the string plus one and the starting position is @c 0.
155 * @brief <i> [Deprecated] </i>
156 * @deprecated This method is deprecated as @c mchar type is changed to @c wchar_t type.
157 * Instead of using this method, use the StringToWcharBufferN(const String& str, int index, int length) method.
160 * @return A pointer to the McharBuffer instance from the substring of the specified string, @n
161 * else @c null if an exception occurs
162 * @param[in] str The string to read
163 * @param[in] index The starting index for the substring in the string @n
164 * It must not be longer than the length of the string.
165 * @param[in] length The length of the substring @n
166 * It must not be longer than the length of the given string minus the specified @c index.
167 * @exception E_SUCCESS The method is successful.
168 * @exception E_INVALID_ARG The specified @c str is an empty string.
169 * @exception E_OUT_OF_RANGE The @c index and @c length are outside the bounds of the data structure.
170 * @remarks The specific error code can be accessed using the GetLastResult() method.
173 static McharBuffer* StringToMbN(const String& str, int index, int length);
176 * Gets a new WcharBuffer from a substring of the specified string. @n
177 * The buffer's limit is the length of the string plus one and the starting position is @c 0.
181 * @return A pointer to the WcharBuffer instance from the substring of the specified string, @n
182 * else @c null if an exception occurs
183 * @param[in] str The string to read
184 * @param[in] index The starting index for the substring in the string @n
185 * It must not be longer than the length of the string.
186 * @param[in] length The length of the substring @n
187 * It must not be longer than the length of the given string minus the specified @c index.
188 * @exception E_SUCCESS The method is successful.
189 * @exception E_INVALID_ARG The specified @c str is an empty string.
190 * @exception E_OUT_OF_RANGE The @c index and @c length are outside the bounds of the data structure.
191 * @remarks The specific error code can be accessed using the GetLastResult() method.
193 static WcharBuffer* StringToWcharBufferN(const String& str, int index, int length);
197 * Gets the string length in the McharBuffer. @n
198 * The string length is the length from the current position of the %McharBuffer to the @c null character.
199 * The position of the buffer is not changed.
201 * @brief <i> [Deprecated] </i>
202 * @deprecated This method is deprecated as @c mchar type is changed to @c wchar_t type.
203 * Instead of using this method, use the GetStringLengthInWcharBuffer(const WcharBuffer& wb) method.
207 * @return The length of the McharBuffer instance, @n
208 * else @c -1 if the %McharBuffer instance is not terminated with the @c null character
209 * @param[in] mb An instance of McharBuffer
210 * @remarks If @c null does not exist between the position and the limit of the buffer, the method returns @c -1.
213 static int GetStringLengthInMb(const McharBuffer& mb);
216 * Gets the string length in the WcharBuffer. @n
217 * The string length is the length from the current position of the %WcharBuffer to the @c null character.
218 * The position of the buffer is not changed.
222 * @return The length of the WcharBuffer instance, @n
223 * else @c -1 if the %WcharBuffer instance is not terminated with the @c null character
224 * @param[in] wb An instance of WcharBuffer
225 * @remarks If @c null does not exist between the position and the limit of the buffer, the method returns @c -1.
227 static int GetStringLengthInWcharBuffer(const WcharBuffer& wb);
230 * Gets a new ByteBuffer encoded from the specified string. @n
231 * The buffer's limit is the length of the string plus one and the starting position is @c 0.
235 * @return A pointer to the ByteBuffer instance encoded from the specified string, @n
236 * else @c null if an exception occurs
237 * @param[in] unicodeString A string to encode
238 * @exception E_SUCCESS The method is successful.
239 * @exception E_INVALID_ARG The specified input parameter is invalid.
240 * @remarks The specific error code can be accessed using the GetLastResult() method.
241 * @see Tizen::Base::ByteBuffer
242 * @see Tizen::Base::String
244 static ByteBuffer* StringToUtf8N(const String& unicodeString);
247 * Decodes a null-terminated UTF-8 string into a Unicode string. @n
248 * The position of the buffer is not changed.
252 * @return An error code
253 * @param[in] pUtf8String A pointer to a String instance containing UTF-8 codes
254 * @param[out] unicodeString A string containing Unicode characters
255 * @exception E_SUCCESS The method is successful.
256 * @exception E_INVALID_ARG The specified @c pUtf8String is a @c null reference.
257 * @exception E_INVALID_ENCODING_RANGE The indicated string contains UTF-8 code that is outside the bounds specified by the character encoding scheme.
259 * The following example demonstrates how to use the %Utf8ToString() method.
263 * const char* pUtf8String = "Utf8ToString";
267 * // Decodes a UTF-8 string into a Unicode string
268 * StringUtil::Utf8ToString(pUtf8String, str);
272 static result Utf8ToString(const char* pUtf8String, String& unicodeString);
275 * Decodes a string consisting of base 64 digits to a ByteBuffer. @n
276 * The buffer's limit is the length of the string plus one and the starting position is @c 0.
280 * @return A pointer to the ByteBuffer instance decoded from the specified string, @n
281 * else @c null if an exception occurs
282 * @param[in] base64String A string to decode
283 * @exception E_SUCCESS The method is successful.
284 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
285 * The specified @c base64String is not a valid Base64 string.
286 * @remarks The specific error code can be accessed using the GetLastResult() method.
288 * The following example demonstrates how to use the %DecodeBase64StringN() method.
292 * const char* pChar = "abcdefg123456";
293 * int size = strlen(pChar);
297 * buffer.Construct(size + 1);
299 * buffer.SetArray((byte*)pChar, 0, size);
300 * buffer.SetByte('\0');
303 * StringUtil::EncodeToBase64String(buffer, encodedStr);
305 * // Decodes a String consisting of base 64 digits to a ByteBuffer
306 * ByteBuffer* pDecodedBuffer = StringUtil::DecodeBase64StringN(encodedStr);
310 static ByteBuffer* DecodeBase64StringN(const String& base64String);
313 * Encodes a ByteBuffer into a string consisting of base 64 characters. @n
314 * The position of the buffer is not changed.
318 * @return An error code
319 * @param[in] buffer An instance of ByteBuffer to encode
320 * @param[out] encodedString An instance of String consisting of base 64 characters
321 * @exception E_SUCCESS The method is successful.
322 * @exception E_INVALID_ARG A specified input parameter is invalid, or
323 * the @c buffer is empty.
325 * The following example demonstrates how to use the %EncodeToBase64String() method.
329 * const char* pChar = "abcdefg123456";
330 * int size = strlen(pChar);
334 * buffer.Construct(size + 1);
336 * buffer.SetArray((byte*)pChar, 0, size);
337 * buffer.SetByte('\0');
340 * // Encodes a ByteBuffer into a String consisting of base 64 characters
341 * StringUtil::EncodeToBase64String(buffer, encodedStr);
345 static result EncodeToBase64String(const ByteBuffer& buffer, String& encodedString);
349 * This default constructor is intentionally declared as private because this class cannot be constructed.
354 * This destructor is intentionally declared as private because this class cannot be constructed.
359 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
361 * @param[in] rhs The instance of the StringUtil
363 StringUtil(const StringUtil& rhs);
366 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
368 * @param[in] rhs An instance of %StringUtil
370 StringUtil& operator =(const StringUtil& rhs);
373 }}} // Tizen::Base::Utility
375 #endif // _FBASE_UTIL_STRING_UTIL_H_