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 various utility methods for %String.
40 * The %StringUtil class provides various utility methods for String.
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 current position
92 * @exception E_SUCCESS The method is successful.
93 * @exception E_INVALID_ARG A specified input parameter is invalid, or
94 * @c null does not exist between the position and limit of buffer.
97 static result MbToString(const McharBuffer& mb, String& str);
100 * Converts an WcharBuffer to a null-terminated string. @n
101 * The position of the buffer is not changed.
105 * @return An error code
106 * @param[in] wb An instance of WcharBuffer
107 * @param[out] str The current position
108 * @exception E_SUCCESS The method is successful.
109 * @exception E_INVALID_ARG A specified input parameter is invalid, or
110 * @c null does not exist between the position and limit of buffer.
112 static result WcharBufferToString(const WcharBuffer& wb, String& str);
116 * Gets a new McharBuffer from the specified string. @n
117 * The buffer's limit is the length of the string plus one and the starting position is @c 0.
119 * @brief <i> [Deprecated] </i>
120 * @deprecated This method is deprecated as @c mchar type is changed to @c wchar_t type.
121 * Instead of using this method, use the StringToWcharBufferN(const String& str) method.
124 * @return A pointer to the McharBuffer instance from the specified string, @n
125 * else @c null if an exception occurs
126 * @param[in] str The string to read
127 * @exception E_SUCCESS The method is successful.
128 * @exception E_INVALID_ARG The specified @c str is an empty string.
129 * @remarks The specific error code can be accessed using the GetLastResult() method.
132 static McharBuffer* StringToMbN(const String& str);
135 * Gets a new WcharBuffer from the specified string. @n
136 * The buffer's limit is the length of the string plus one and the starting position is @c 0.
140 * @return A pointer to the WcharBuffer instance from the specified string, @n
141 * else @c null if an exception occurs
142 * @param[in] str The string to read
143 * @exception E_SUCCESS The method is successful.
144 * @exception E_INVALID_ARG The specified @c str is an empty string.
145 * @remarks The specific error code can be accessed using the GetLastResult() method.
147 static WcharBuffer* StringToWcharBufferN(const String& str);
151 * Gets a new McharBuffer from a substring of the specified string. @n
152 * The buffer's limit is the length of the string plus one and the starting position is @c 0.
154 * @brief <i> [Deprecated] </i>
155 * @deprecated This method is deprecated as @c mchar type is changed to @c wchar_t type.
156 * Instead of using this method, use the StringToWcharBufferN(const String& str, int index, int length) method.
159 * @return A pointer to the McharBuffer instance from the substring of the specified string, @n
160 * else @c null if an exception occurs
161 * @param[in] str The string to read
162 * @param[in] index The starting index for the substring in the string @n
163 * It must not be longer than the length of the string.
164 * @param[in] length The length of the substring @n
165 * It must not be longer than the length of the given string minus the specified @c index.
166 * @exception E_SUCCESS The method is successful.
167 * @exception E_INVALID_ARG The specified @c str is an empty string.
168 * @exception E_OUT_OF_RANGE The @c index and @c length are outside the bounds of the data structure.
169 * @remarks The specific error code can be accessed using the GetLastResult() method.
172 static McharBuffer* StringToMbN(const String& str, int index, int length);
175 * Gets a new WcharBuffer from a substring of the specified string. @n
176 * The buffer's limit is the length of the string plus one and the starting position is @c 0.
180 * @return A pointer to the WcharBuffer instance from the substring of the specified string, @n
181 * else @c null if an exception occurs
182 * @param[in] str The string to read
183 * @param[in] index The starting index for the substring in the string @n
184 * It must not be longer than the length of the string.
185 * @param[in] length The length of the substring @n
186 * It must not be longer than the length of the given string minus the specified @c index.
187 * @exception E_SUCCESS The method is successful.
188 * @exception E_INVALID_ARG The specified @c str is an empty string.
189 * @exception E_OUT_OF_RANGE The @c index and @c length are outside the bounds of the data structure.
190 * @remarks The specific error code can be accessed using the GetLastResult() method.
192 static WcharBuffer* StringToWcharBufferN(const String& str, int index, int length);
196 * Gets the string length in the McharBuffer. @n
197 * The string length is the length from the current position of the %McharBuffer to the @c null character.
198 * The position of the buffer is not changed.
200 * @brief <i> [Deprecated] </i>
201 * @deprecated This method is deprecated as @c mchar type is changed to @c wchar_t type.
202 * Instead of using this method, use the GetStringLengthInWcharBuffer(const WcharBuffer& wb) method.
206 * @return The length of the McharBuffer instance, @n
207 * else @c -1 if the %McharBuffer instance is not terminated with the @c null character
208 * @param[in] mb An instance of McharBuffer
209 * @remarks If @c null does not exist between the position and the limit of the buffer, the method returns @c -1.
212 static int GetStringLengthInMb(const McharBuffer& mb);
215 * Gets the string length in the WcharBuffer. @n
216 * The string length is the length from the current position of the %WcharBuffer to the @c null character.
217 * The position of the buffer is not changed.
221 * @return The length of the WcharBuffer instance, @n
222 * else @c -1 if the %WcharBuffer instance is not terminated with the @c null character
223 * @param[in] wb An instance of WcharBuffer
224 * @remarks If @c null does not exist between the position and the limit of the buffer, the method returns @c -1.
226 static int GetStringLengthInWcharBuffer(const WcharBuffer& wb);
229 * Gets a new ByteBuffer encoded from the specified string. @n
230 * The buffer's limit is the length of the string plus one and the starting position is @c 0.
234 * @return A pointer to the ByteBuffer instance encoded from the specified string, @n
235 * else @c null if an exception occurs
236 * @param[in] unicodeString A string to encode
237 * @exception E_SUCCESS The method is successful.
238 * @exception E_INVALID_ARG The specified input parameter is invalid.
239 * @remarks The specific error code can be accessed using the GetLastResult() method.
240 * @see Tizen::Base::ByteBuffer
241 * @see Tizen::Base::String
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 a 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 A 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 A specified input parameter is invalid, or
321 * the @c buffer is empty.
323 * The following example demonstrates how to use the %EncodeToBase64String() method.
327 * const char* pChar = "abcdefg123456";
328 * int size = strlen(pChar);
332 * buffer.Construct(size);
334 * buffer.SetArray(reinterpret_cast< const byte* >(pChar), 0, size);
337 * // Encodes a ByteBuffer into a String consisting of base 64 characters
338 * StringUtil::EncodeToBase64String(buffer, encodedStr);
342 static result EncodeToBase64String(const ByteBuffer& buffer, String& encodedString);
346 * This default constructor is intentionally declared as private because this class cannot be constructed.
351 * This destructor is intentionally declared as private because this class cannot be constructed.
356 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
358 * @param[in] rhs The instance of the StringUtil
360 StringUtil(const StringUtil& rhs);
363 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
365 * @param[in] rhs An instance of %StringUtil
367 StringUtil& operator =(const StringUtil& rhs);
370 }}} // Tizen::Base::Utility
372 #endif // _FBASE_UTIL_STRING_UTIL_H_