Add an info log in Terminate()
[platform/framework/native/appfw.git] / inc / FTextAsciiEncoding.h
1 //
2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
3 //
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
7 //
8 //     http://www.apache.org/licenses/LICENSE-2.0
9 //
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.
15 //
16
17 /**
18  * @file                FTextAsciiEncoding.h
19  * @brief               This is the header file for the %AsciiEncoding class.
20  *
21  * This header file contains the declarations of the %AsciiEncoding class. @n
22  * This class is derived from the Encoding class.
23  */
24 #ifndef _FTEXT_ASCII_ENCODING_H_
25 #define _FTEXT_ASCII_ENCODING_H_
26
27 #include <FTextEncoding.h>
28
29
30 namespace Tizen { namespace Text
31 {
32
33 /**
34  * @class       AsciiEncoding
35  * @brief       This class is an implementation of the American Standard Code for Information Interchange (ASCII) encoding.
36  *
37  * @since       2.0
38  *
39  * @final       This class is not intended for extension.
40  *
41  * The %AsciiEncoding class encodes Unicode characters as single 7-bit ASCII characters.
42  * This encoding only supports ASCII character values between U+0000 and U+007F.
43  *
44  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/text/converting_all_text_data.htm">Converting All Text Data at Once</a>.
45  *
46  * The following example demonstrates how to use the %AsciiEncoding class.
47  *
48  * @code
49  *      #include <FBase.h>
50  *      #include <FText.h>
51  *
52  *      using namespace Tizen::Base;
53  *      using namespace Tizen::Text;
54  *
55  *      void
56  *      MyClass::AsciiEncodingSample(void)
57  *      {
58  *              AsciiEncoding ascii;
59  *
60  *              String str(L"012345 ABCDE");
61  *
62  *              int byteCount;
63  *              ascii.GetByteCount(str, byteCount);
64  *
65  *              // Encodes
66  *              ByteBuffer* pBuffer = ascii.GetBytesN(str);
67  *
68  *              int charCount;
69  *              ascii.GetCharCount(*pBuffer, charCount);
70  *
71  *              // Decodes
72  *              String decodedStr;
73  *              ascii.GetString(*pBuffer, decodedStr);
74  *
75  *              if (str.Equals(decodedStr))
76  *              {
77  *                      //....
78  *              }
79  *
80  *              delete pBuffer;
81  *      }
82  * @endcode
83  */
84
85 class _OSP_EXPORT_ AsciiEncoding
86         : public Encoding
87 {
88 public:
89         /**
90          * This is the default constructor for this class.
91          *
92          * @since       2.0
93          *
94          */
95         AsciiEncoding(void);
96
97         /**
98          * This is the destructor for this class. @n
99          * This destructor overrides Tizen::Text::Encoding::~Encoding().
100          *
101          * @since       2.0
102          *
103          */
104         virtual ~AsciiEncoding(void);
105
106         /**
107          * Encodes an instance of the specified Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer.
108          *
109          * @since                       2.0
110          *
111          * @return              A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
112          *                                              else @c null if an exception occurs @n
113          *                                              The buffer limit is the position of the last encoded byte plus one and the starting position is zero.
114          * @param[in]   chars An instance of Tizen::Base::WcharBuffer to encode
115          * @exception   E_SUCCESS                The method is successful.
116          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
117          * @exception   E_INVALID_ARG            The specified @c chars is empty or invalid.
118          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
119          * @remarks             The specific error code can be accessed using the GetLastResult() method.
120          * @see                         GetCharsN()
121          * @see                         GetBytesN()
122          */
123         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::WcharBuffer& chars) const;
124
125         /**
126          * Encodes an instance of the specified Tizen::Base::String into an instance of Tizen::Base::ByteBuffer.
127          *
128          * @since                       2.0
129          *
130          * @return              A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
131          *                                              else @c null if an exception occurs @n
132          *                                              The buffer limit is the position of the last encoded byte plus one and the starting position is zero.
133          * @param[in]   str A string to encode
134          * @exception   E_SUCCESS                The method is successful.
135          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
136          * @exception   E_INVALID_ARG            The specified @c str is empty or invalid.
137          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
138          * @remarks             The specific error code can be accessed using the GetLastResult() method.
139          * @see                         GetString()
140          */
141         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::String& str) const;
142
143         /**
144          * Encodes an instance of Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer as per the specified range. @n
145          * The position and limit of the %Tizen::Base::ByteBuffer instance is not changed.
146          *
147          * @since                       2.0
148          *
149          * @return              An error code
150          * @param[in]   chars An instance of Tizen::Base::WcharBuffer to encode
151          * @param[in]   charIndex The index from where encoding begins in the Tizen::Base::WcharBuffer instance
152          * @param[in]   charCount The total number of characters to encode
153          * @param[out]  bytes The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
154          * @param[in]   byteIndex The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
155          * @exception   E_SUCCESS                The method is successful.
156          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
157          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
158          *                                         the specified @c chars or @c bytes is empty.
159          * @exception   E_OUT_OF_RANGE                   The value of an argument is outside the valid range defined by the method, or
160          *                                         the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
161          * @exception E_UNDERFLOW                    This operation has caused the memory to underflow, or
162          *                                         the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
163          * @exception   E_OVERFLOW               This operation has caused the memory to overflow, or
164          *                                         the specified @c bytes does not contain sufficient space to store the encoded characters.
165          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
166          * @see                         GetChars()
167          */
168         virtual result GetBytes(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount, Tizen::Base::ByteBuffer& bytes, int byteIndex = 0) const;
169
170         /**
171          * Encodes an instance of Tizen::Base::String into an instance of Tizen::Base::ByteBuffer as per the specified range. @n
172          * The position and limit of the %Tizen::Base::ByteBuffer instance is not changed.
173          *
174          * @since                       2.0
175          *
176          * @return              An error code
177          * @param[in]   str A string to encode
178          * @param[in]   charIndex The index from where encoding begins in the Tizen::Base::WcharBuffer instance
179          * @param[in]   charCount The total number of characters to encode
180          * @param[out]  bytes The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
181          * @param[in]   byteIndex The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
182          * @exception   E_SUCCESS                The method is successful.
183          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
184          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
185          *                                         the specified @c str or @c bytes is empty.
186          * @exception   E_OUT_OF_RANGE                   The value of an argument is outside the valid range defined by the method, or
187          *                                          the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c str.
188          * @exception   E_UNDERFLOW              This operation has caused the memory to underflow, or
189          *                                                      the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c str.
190          * @exception   E_OVERFLOW               This operation has caused the memory to overflow, or
191          *                                                                                 the specified @c bytes does not contain sufficient space to store the encoded characters.
192          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
193          * @see                         GetString()
194          */
195         virtual result GetBytes(const Tizen::Base::String& str, int charIndex, int charCount,
196                                                                                 Tizen::Base::ByteBuffer& bytes, int byteIndex = 0) const;
197
198         /**
199          * Decodes an instance of the specified Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer. @n
200          * The %GetCharsN() method does not maintain state consistency between conversions as this method is intended to
201          * convert complete blocks of bytes and characters in one operation and also to decode it in a single step.
202          *
203          * @since                       2.0
204          *
205          * @return              A pointer to the Tizen::Base::WcharBuffer instance where the resultant decoded data is stored, @n
206          *                                              else @c null if an exception occurs @n
207          *                                              The buffer limit is the position of the last decoded byte plus one and the starting position is zero.
208          * @param[in]   bytes An instance of Tizen::Base::ByteBuffer to decode
209          * @exception   E_SUCCESS                The method is successful.
210          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
211          * @exception   E_INVALID_ARG            The specified @c bytes is empty or invalid.
212          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
213          * @remarks             The specific error code can be accessed using the GetLastResult() method.
214          * @see                         GetBytesN()
215          */
216         virtual Tizen::Base::WcharBuffer* GetCharsN(const Tizen::Base::ByteBuffer& bytes) const;
217
218         /**
219          * Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer as per the specified range. @n
220          * The position and limit of the %Tizen::Base::WcharBuffer instance is not changed.
221          * The %GetChars() method does not maintain state consistency between conversions as this is intended to
222          * convert complete blocks of bytes and characters in one operation.
223          *
224          * @since                       2.0
225          *
226          * @return              An error code
227          * @param[in]   bytes An instance of Tizen::Base::ByteBuffer to decode
228          * @param[in]   byteIndex The index from where decoding begins
229          * @param[in]   byteCount The total number of bytes to decode
230          * @param[out]  chars The Tizen::Base::WcharBuffer instance where the resultant decoded string is stored
231          * @param[in]   charIndex The index from where encoding begins in the Tizen::Base::WcharBuffer instance
232          * @exception   E_SUCCESS                The method is successful.
233          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
234          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
235          *                                         the specified @c bytes or @c chars is empty.
236          * @exception   E_OUT_OF_RANGE       The value of an argument is outside the valid range defined by the method, or
237          *                                                                             the length of the specified @c byteIndex or @c byteCount is greater than the length of the specified @c bytes.
238          * @exception   E_UNDERFLOW                  This operation has caused the memory to underflow, or
239          *                                                                                 the sum of the length of the specified @c byteIndex and @c byteCount is greater than the length of the specified @c bytes.
240          * @exception E_OVERFLOW                     This operation has caused the memory to overflow, or
241          *                                                                                the specified @c chars does not contain sufficient space to store the decoded bytes.
242          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
243          * @see                         GetBytes()
244          */
245         virtual result GetChars(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount, Tizen::Base::WcharBuffer& chars, int charIndex = 0) const;
246
247         /**
248          * Gets a string containing the decoded representation of the specified Tizen::Base::ByteBuffer instance.
249          *
250          * @since                       2.0
251          *
252          * @return              An error code
253          * @param[in]   bytes An instance of Tizen::Base::ByteBuffer to decode
254          * @param[out]  str  A Tizen::Base::String instance @n
255          *                   It contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
256          * @exception   E_SUCCESS                The method is successful.
257          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
258          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
259          *                                         the specified @c bytes is empty.
260          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
261          * @remarks     This method assumes that the Tizen::Base::ByteBuffer instance contains all the bytes necessary to generate the entire string.
262          *              If the bytes are in multiple byte arrays, use the Decoder class, which maintains state consistency
263          *              between multiple calls.
264          * @see                         GetBytesN()
265          */
266         virtual result GetString(const Tizen::Base::ByteBuffer& bytes, Tizen::Base::String& str) const;
267
268         /**
269          * Gets a string containing the decoded representation of the specified Tizen::Base::ByteBuffer instance.
270          *
271          * @since                       2.0
272          *
273          * @return              An error code
274          * @param[in]   bytes An instance of Tizen::Base::ByteBuffer to decode
275          * @param[in]   index The index from where decoding begins
276          * @param[in]   count The total number of bytes to decode
277          * @param[out]  str  A Tizen::Base::String instance @n
278          *                   It contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
279          * @exception   E_SUCCESS                The method is successful.
280          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
281          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
282          *                                         the specified @c bytes is empty.
283          * @exception   E_OUT_OF_RANGE       The value of an argument is outside the valid range defined by the method, or
284          *                                                                                 the sum of the length of the specified @c index and @c count is greater than the length of the specified @c bytes.
285          * @exception E_UNDERFLOW                                This operation has caused the memory to underflow, or
286          *                                                                              the sum of the length of the specified @c index and @c count is greater than the length of the specified @c bytes.
287          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
288          * @remarks     This method assumes that the Tizen::Base::ByteBuffer instance contains all the bytes necessary to generate the entire string.
289          *              If the bytes are in multiple byte arrays, use the Decoder class, which maintains state consistency
290          *              between multiple calls.
291          * @see                         GetBytes()
292          */
293         virtual result GetString(const Tizen::Base::ByteBuffer& bytes, int index, int count, Tizen::Base::String& str) const;
294
295         /**
296         * Gets the maximum number of bytes required for encoding a given number of characters.
297         *
298         * @since                        2.0
299         *
300         * @return               The maximum number of bytes required for encoding a given number of characters
301         * @param[in]    charCount The total number of characters to encode
302         * @remarks   This method determines an appropriate buffer size for the byte arrays passed to GetBytes() for encoding.
303         * @see                          Encoding::GetByteCount()
304         * @see                          GetBytes()
305         */
306         virtual int GetMaxByteCount(int charCount) const;
307
308         /**
309          * Gets the maximum number of characters that are generated by decoding the specified number of bytes.
310          *
311          * @since                       2.0
312          *
313          * @return              The maximum number of characters that are generated by decoding the specified number of bytes
314          * @param[in]   byteCount The total number of bytes to encode
315          * @remarks   This method determines an appropriate buffer size for character arrays passed to
316          *                GetChars() or a decoder for encoding.
317          * @see                         Encoding::GetCharCount()
318          * @see                         GetChars()
319          */
320         virtual int GetMaxCharCount(int byteCount) const;
321
322
323         /**
324          * Gets the encoder for the current encoding.
325          *
326          * @since                       2.0
327          *
328          * @return              A pointer to the Encoder instance for the current encoding
329          * @remarks   Contrary to GetBytes(), an encoder can convert partial sequences of characters into
330          *            partial sequences of bytes by maintaining the appropriate state between the conversions. @n
331          *            At present, only the Utf8Encoding class supports this method. Other classes return @c null.
332          * @see                         GetBytes()
333          */
334         virtual Encoder* GetEncoderN(void) const;
335
336         /**
337          * Gets the decoder for the current encoding.
338          *
339          * @since                       2.0
340          *
341          * @return              A pointer to the Decoder instance for the current encoding
342          * @remarks   Contrary to GetChars(), a decoder can convert partial sequences of bytes
343          *            into partial sequences of characters by maintaining the appropriate state between the conversions. @n
344          *            At present, only the Utf8Encoding class supports this method. Other classes return @c null.
345          *
346          * @see                         GetChars()
347          */
348         virtual Decoder* GetDecoderN(void) const;
349
350         /**
351         * Gets the encoding type of the current instance.
352         *
353         * @since 2.0
354         *
355         * @return               An encoding type
356         */
357         virtual Tizen::Base::String GetEncodingType(void) const;
358
359 private:
360         /**
361          * The implementation of this copy constructor is intentionally blank and declared as private to
362          * prohibit copying of objects.
363          */
364         AsciiEncoding(const AsciiEncoding& asciiEncoding);
365
366         /**
367          * The implementation of this copy assignment operator is intentionally blank and declared as private
368          * to prohibit copying of objects.
369          */
370         AsciiEncoding& operator =(const AsciiEncoding& asciiEncoding);
371         
372         friend class _AsciiEncodingImpl;
373         class _AsciiEncodingImpl* __pAsciiEncodingImpl;
374 };
375
376 } } // Tizen::Text
377 #endif //_FTEXT_ASCII_ENCODING_H_