Merge "Fix Exception issue on Add and remove event listener" into tizen_2.2
[platform/framework/native/appfw.git] / inc / FTextUcs2Encoding.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                FTextUcs2Encoding.h
19  * @brief               This is the header file for the %Ucs2Encoding class.
20  *
21  * This header file contains the declarations of the %Ucs2Encoding class.
22  * This class is derived from the Encoding class.
23  */
24 #ifndef _FTEXT_UCS2_ENCODING_H_
25 #define _FTEXT_UCS2_ENCODING_H_
26
27 #include <FTextEncoding.h>
28
29
30 namespace Tizen { namespace Text
31 {
32 /**
33  * @class       Ucs2Encoding
34  * @brief       This class is an implementation of the UCS-2 encoding.
35  *
36  * @since       2.0
37  *
38  * @final       This class is not intended for extension.
39  *
40  * The %Ucs2Encoding class is an implementation of the UCS-2 encoding.
41  * Universal Character Set (UCS2) is a two-octet per character encoding type with a fixed width.
42  * UCS2 prepares several characters in advance to output the needed information fast.
43  * When printing out characters, users can avail different types of character sets.
44  *
45  *  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>.
46  *
47  * The following example demonstrates how to use the %Ucs2Encoding class.
48  *
49  *  @code
50  *      #include <FBase.h>
51  *      #include <FText.h>
52  *
53  *      using namespace Tizen::Base;
54  *      using namespace Tizen::Text;
55  *
56  *      void
57  *      MyClass::Ucs2EncodingSample(void)
58  *      {
59  *              Ucs2Encoding ucs2;
60  *
61  *              String str(L"(\u03a0) and (\u03a3)"); // sigma and pi
62  *
63  *              int byteCount;
64  *              ucs2.GetByteCount(str, byteCount);
65  *
66  *              // Encodes
67  *              ByteBuffer* pBuffer = ucs2.GetBytesN(str);
68  *
69  *              int charCount;
70  *              ucs2.GetCharCount(*pBuffer, charCount);
71  *
72  *              // Decodes
73  *              String decodedStr;
74  *              ucs2.GetString(*pBuffer, decodedStr);
75  *
76  *              if (str.Equals(decodedStr))
77  *              {
78  *                      //....
79  *              }
80  *
81  *              delete pBuffer;
82  *      }
83  *
84  * @endcode
85  *
86  */
87
88 class _OSP_EXPORT_ Ucs2Encoding
89         : public Encoding
90 {
91 public:
92         /**
93          * This is the default constructor for this class.
94          *
95          * @since       2.0
96          */
97         Ucs2Encoding(void);
98
99         /**
100          * This is the destructor for this class. @n
101          * This destructor overrides Tizen::Text::Encoding::~Encoding().
102          *
103          * @since       2.0
104          */
105         virtual ~Ucs2Encoding(void);
106
107         /**
108          * Gets the total number of bytes that are generated by encoding an instance of Tizen::Base::String.
109          *
110          * @since                               2.0
111          *
112          * @return                      An error code
113          * @param[in]           str                      A string to encode
114          * @param[out]  byteCount                    The total number of bytes required to encode the string
115          * @exception           E_SUCCESS                The method is successful.
116          * @exception           E_INVALID_ARG            A specified input parameter is invalid, or
117          *                                           the specified @c str is an empty string.
118          * @exception           E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
119          * @remarks     This method determines the exact number of bytes
120          *              that are produced if the given string is encoded.
121          * @see         GetMaxByteCount()
122          */
123         virtual result GetByteCount(const Tizen::Base::String& str, int& byteCount) const;
124
125         /**
126          * Gets the total number of bytes that are generated by encoding an instance of Tizen::Base::WcharBuffer.
127          *
128          * @since                               2.0
129          *
130          * @return                      An error code
131          * @param[in]           chars                 An instance of Tizen::Base::WcharBuffer to encode
132          * @param[out]  byteCount                 The total number of bytes required to encode the specified range of characters
133          * @exception           E_SUCCESS             The method is successful.
134          * @exception           E_INVALID_ARG         A specified input parameter is invalid, or
135          *                                        the specified @c chars is empty.
136          * @exception           E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
137          * @remarks     This method determines the exact number of bytes
138          *              that are produced if the given array of characters is encoded.
139          * @see         GetMaxByteCount()
140          */
141         virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars, int& byteCount) const;
142
143         /**
144          * Gets the total number of bytes that are required to encode a range of characters in the specified Tizen::Base::WcharBuffer instance.
145          *
146          * @since                               2.0
147          *
148          * @return                      An error code
149          * @param[in]           chars                 An instance of Tizen::Base::WcharBuffer to encode
150          * @param[in]           charIndex             The index from where encoding begins in the Tizen::Base::WcharBuffer instance
151          * @param[in]   charCount                   The total number of characters to encode
152          * @param[out]  byteCount                 The total number of bytes required to encode the specified range of characters
153          * @exception           E_SUCCESS                The method is successful.
154          * @exception           E_INVALID_ARG            A specified input parameter is invalid, or
155          *                                         the specified @c chars is empty.
156          * @exception           E_OUT_OF_RANGE               The value of an argument is outside the valid range defined by the method, or
157          *                                                                                   the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
158          * @exception   E_UNDERFLOW              This operation has caused the memory to underflow, or
159          *                                                                               the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
160          * @exception           E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
161          * @remarks     This method determines the exact number of bytes
162          *              that are produced if the given array of characters is encoded.
163          * @see                 GetMaxByteCount()
164          */
165         virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount, int& byteCount) const;
166
167
168         /**
169          * Encodes an instance of Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer.
170          *
171          * @since                       2.0
172          *
173          * @return                      A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
174          *                      else @c null if an exception occurs @n
175          *                                              The buffer limit is the position of the last encoded byte plus one and the starting position is zero.
176          * @param[in]   chars                    An instance of Tizen::Base::WcharBuffer to encode
177          * @exception   E_SUCCESS                The method is successful.
178          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
179          * @exception   E_INVALID_ARG            The specified @c chars is empty or invalid.
180          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
181          * @remarks             The specific error code can be accessed using the GetLastResult() method.
182          * @see                         GetCharsN()
183          */
184         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::WcharBuffer& chars) const;
185
186         /**
187          * Encodes an instance of Tizen::Base::String into an instance of Tizen::Base::ByteBuffer.
188          *
189          * @since                       2.0
190          *
191          * @return                                      A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
192          *                                      else @c null if an exception occurs @n
193          *                                              The buffer limit is the position of the last encoded byte plus one and the starting position is zero.
194          * @param[in]   str                      A string to encode
195          * @exception       E_SUCCESS                The method is successful.
196          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
197          * @exception   E_INVALID_ARG            The specified @c str is empty or invalid.
198          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
199          * @remarks             The specific error code can be accessed using the GetLastResult() method.
200          * @see                         GetString()
201          */
202         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::String& str) const;
203
204         /**
205          * Encodes an instance of Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer as per the specified range. @n
206          * The position and limit of the pointer to the %Tizen::Base::ByteBuffer instance is not changed.
207          *
208          * @since                       2.0
209          *
210          * @return              An error code
211          * @param[in]   chars                    An instance of Tizen::Base::WcharBuffer to encode
212          * @param[in]   charIndex                The index from where encoding begins in the Tizen::Base::WcharBuffer instance
213          * @param[in]   charCount                  The total number of characters to encode
214          * @param[out]  bytes                    The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
215          * @param[in]   byteIndex                  The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
216          * @exception   E_SUCCESS                The method is successful.
217          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
218          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
219          *                                         the specified @c chars or @c bytes is empty.
220          * @exception   E_OUT_OF_RANGE          The value of an argument is outside the valid range defined by the method, or
221          *                                         the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
222          * @exception E_UNDERFLOW                    This operation has caused the memory to underflow, or
223          *                                         the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
224          * @exception   E_OVERFLOW               This operation has caused the memory to overflow, or
225          *                                         the specified @c bytes does not contain sufficient space to store the encoded characters.
226          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
227          * @remarks     This method encodes a range of characters in a Tizen::Base::WcharBuffer into a range of bytes in a Tizen::Base::ByteBuffer.
228          * @see                         GetChars()
229          */
230         virtual result GetBytes(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount,
231                 Tizen::Base::ByteBuffer& bytes, int byteIndex = 0) const;
232
233         /**
234          * Encodes an instance of Tizen::Base::String into an instance of Tizen::Base::ByteBuffer as per the specified range. @n
235          * The position and limit of the pointer to the %Tizen::Base::ByteBuffer instance is not changed.
236          *
237          * @since                       2.0
238          *
239          * @return              An error code
240          * @param[in]   str                       A string to encode
241          * @param[in]   charIndex                 The index from where encoding begins in the Tizen::Base::WcharBuffer instance
242          * @param[in]   charCount                   The total number of characters to encode
243          * @param[out]  bytes                     The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
244          * @param[in]   byteIndex                   The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
245          * @exception   E_SUCCESS                The method is successful.
246          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
247          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
248          *                                       the specified @c str or @c bytes is empty.
249          * @exception   E_OUT_OF_RANGE                   The value of an argument is outside the valid range defined by the method, or
250          *                                         the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c str.
251          * @exception   E_UNDERFLOW              This operation has caused the memory to underflow, or
252          *                                                                                 the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c str.
253          * @exception   E_OVERFLOW               This operation has caused the memory to overflow, or
254          *                                                                                 the specified @c bytes does not contain sufficient space to store the encoded characters.
255          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
256          * @see                         GetString()
257          */
258         virtual result GetBytes(const Tizen::Base::String& str, int charIndex, int charCount,
259                 Tizen::Base::ByteBuffer& bytes, int byteIndex = 0) const;
260
261         /**
262          * Gets the total number of characters that are generated by decoding an instance of Tizen::Base::ByteBuffer.
263          *
264          * @since                       2.0
265          *
266          * @return              An error code
267          * @param[in]   bytes                    An instance of Tizen::Base::ByteBuffer to decode
268          * @param[out]  charCount               The total number of characters that are generated by decoding the specified Tizen::Base::ByteBuffer instance
269          * @exception   E_SUCCESS                The method is successful.
270          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
271          *                                         the specified @c bytes is empty.
272          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
273          * @remarks     This method determines the exact number of characters
274          *              that are produced if the given range of bytes is converted.
275          * @see                         GetMaxCharCount()
276          */
277         virtual result GetCharCount(const Tizen::Base::ByteBuffer& bytes, int& charCount) const;
278
279         /**
280          * Gets the total number of characters that are generated by decoding a range of elements specified in the Tizen::Base::ByteBuffer instance.
281          *
282          * @since                       2.0
283          *
284          * @return              An error code
285          * @param[in]   bytes                    An instance of Tizen::Base::ByteBuffer to decode
286          * @param[in]   byteIndex                The index from where decoding begins
287          * @param[in]   byteCount                The total number of bytes to decode
288          * @param[out]  charCount                The total number of characters that are generated by decoding the specified Tizen::Base::ByteBuffer instance
289          * @exception   E_SUCCESS                The method is successful.
290          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
291          *                                         the specified @c bytes is empty.
292          * @exception   E_OUT_OF_RANGE          The value of an argument is outside the valid range defined by the method, or
293          *                                                                                 the length of the specified @c byteIndex or @c byteCount is greater than the length of the specified @c bytes.
294          * @exception   E_UNDERFLOW              This operation has caused the memory to underflow, or
295          *                                                                         the sum of the length of the specified @c byteIndex and @c byteCount is greater than the length of the specified @c bytes.
296          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
297          * @remarks     This method determines the exact number of characters
298          *              that are produced if the given range of bytes is converted.
299          * @see                         GetMaxCharCount()
300          */
301         virtual result GetCharCount(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount, int& charCount) const;
302
303         /**
304          *Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer.
305          *
306          * @since                       2.0
307          *
308          * @return                                   A pointer to the Tizen::Base::WcharBuffer instance where the resultant decoded data is stored, @n
309          *                                   else @c null if an exception occurs @n
310          *                                              The buffer limit is the position of the last decoded byte plus one and the starting position is zero.
311          * @param[in]   bytes                An instance of Tizen::Base::ByteBuffer to decode
312          * @exception   E_SUCCESS                The method is successful.
313          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
314          * @exception   E_INVALID_ARG            The specified @c bytes is empty or invalid.
315          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
316          * @remarks             The specific error code can be accessed using the GetLastResult() method.
317          * @see                         GetBytesN()
318          */
319         virtual Tizen::Base::WcharBuffer* GetCharsN(const Tizen::Base::ByteBuffer& bytes) const;
320
321         /**
322          * Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer as per the specified range. @n
323          * The position and limit of the pointer to the %Tizen::Base::WcharBuffer instance is not changed.
324          *
325          * @since                       2.0
326          *
327          * @return              An error code
328          * @param[in]   bytes                    An instance of Tizen::Base::ByteBuffer to decode
329          * @param[in]   byteIndex                The index from where decoding begins
330          * @param[in]   byteCount                The total number of bytes to decode
331          * @param[out]  chars                    The Tizen::Base::WcharBuffer instance where the resultant decoded data is stored
332          * @param[in]   charIndex                The index from where encoding begins in the Tizen::Base::WcharBuffer instance
333          * @exception   E_SUCCESS                The method is successful.
334          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
335          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
336          *                                        the specified @c bytes or @ chars is empty.
337          * @exception   E_OUT_OF_RANGE           The value of an argument is outside the valid range defined by the method, or
338          *                                                                             the length of the specified @c byteIndex or @c byteCount is greater than the length of the specified @c bytes.
339          * @exception   E_UNDERFLOW                  This operation has caused the memory to underflow, or
340          *                                                                                 the sum of the length of the specified @c byteIndex and @c byteCount is greater than the length of the specified @c bytes.
341          * @exception E_OVERFLOW                     This operation has caused the memory to overflow, or
342          *                                                                                the specified @c chars does not contain sufficient space to store the decoded bytes.
343          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
344          * @see                         GetBytes()
345          */
346         virtual result GetChars(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount,
347                 Tizen::Base::WcharBuffer& chars, int charIndex = 0) const;
348
349         /**
350          * Gets a string containing the decoded representation of the specified Tizen::Base::ByteBuffer instance.
351          *
352          * @since                       2.0
353          *
354          * @return              An error code
355          * @param[in]   bytes                  An instance of Tizen::Base::ByteBuffer to decode
356          * @param[out]  str                    A Tizen::Base::String instance @n
357          *                                     It contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
358          * @exception   E_SUCCESS                The method is successful.
359          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
360          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
361          *                                         the specified @c bytes is empty.
362          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
363          * @see                         GetBytesN()
364          */
365         virtual result GetString(const Tizen::Base::ByteBuffer& bytes, Tizen::Base::String& str) const;
366
367         /**
368          * Gets a string containing the decoded representation of the specified Tizen::Base::ByteBuffer instance.
369          *
370          * @since                       2.0
371          *
372          * @return              An error code
373          * @param[in]   bytes                     An instance of Tizen::Base::ByteBuffer to decode
374          * @param[in]   index                     The index from where decoding begins
375          * @param[in]   count                     The total number of bytes to decode
376          * @param[out]  str                       A Tizen::Base::String instance @n
377          *                                       It contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
378          * @exception   E_SUCCESS                The method is successful.
379          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
380          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
381          *                                         the specified @c bytes is empty.
382          * @exception   E_OUT_OF_RANGE           The value of an argument is outside the valid range defined by the method, or
383          *                                                                                 the sum of the length of the specified @c index and @c count is greater than the length of the specified @c bytes.
384          * @exception   E_UNDERFLOW                              This operation has caused the memory to underflow, or
385          *                                                                                 the sum of the length of the specified @c index and @c count is greater than the length of the specified @c bytes.
386          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
387          * @see                         GetBytesN()
388          */
389         virtual result GetString(const Tizen::Base::ByteBuffer& bytes, int index, int count, Tizen::Base::String& str) const;
390
391
392         /**
393         * Gets the maximum number of bytes required for encoding a given number of characters.
394         *
395         * @since                        2.0
396         *
397         * @return               The maximum number of bytes required for encoding the given number of characters
398         * @param[in]    charCount The total number of characters to encode
399         * @remarks   This method determines an appropriate buffer size for the byte arrays passed to GetBytes() for encoding.
400         * @see                          GetByteCount()
401         * @see                          GetBytes()
402         */
403         virtual int GetMaxByteCount(int charCount) const;
404
405
406         /**
407         * Gets the maximum number of characters that are generated by decoding the specified number of bytes.
408         *
409         * @since                                2.0
410         *
411         * @return                       The maximum number of characters generated by decoding the specified number of bytes
412         * @param[in]            byteCount The total number of bytes to encode
413         * @remarks     This method determines an appropriate buffer size for the character arrays passed to
414         *                   GetChars() or a decoder for encoding.
415         * @see                                  GetByteCount()
416         * @see                                  GetChars()
417         */
418         virtual int GetMaxCharCount(int byteCount) const;
419
420
421         /**
422          * Gets the encoder for the current encoding.
423          *
424          * @since                               2.0
425          *
426          * @return                      A pointer to the Encoder instance for the current encoding
427          * @remarks     Contrary to GetBytes(), an encoder can convert partial sequences of characters into
428          *              partial sequences of bytes by maintaining the appropriate state between the conversions.
429          *              Currently only Utf8Encoding supports this method. Other classes return @c null.
430          * @see                                 GetBytes()
431          */
432         virtual Encoder* GetEncoderN(void) const;
433
434
435         /**
436          * Gets the decoder for the current encoding.
437          *
438          * @since                               2.0
439          *
440          * @return                      A pointer to the Decoder instance for the current encoding
441          * @remarks     Contrary to GetChars(), a decoder can convert partial sequences of bytes
442          *              into partial sequences of characters by maintaining the appropriate state between the conversions.
443          *              Currently only Utf8Encoding supports this method. Other classes return @c null.
444          *
445          * @see                                 GetChars()
446          */
447         virtual Decoder* GetDecoderN(void) const;
448
449         /**
450         * Gets the encoding type of the current instance.
451         *
452         * @since                        2.0
453         *
454         * @return               An encoding type
455         */
456         virtual Tizen::Base::String GetEncodingType(void) const;
457
458 private:
459         /**
460          * The implementation of this copy constructor is intentionally blank and declared as private to
461          * prohibit copying of objects.
462          */
463         Ucs2Encoding(const Ucs2Encoding& ucs2Encoding);
464
465         /**
466          * The implementation of this copy assignment operator is intentionally blank and declared as private
467          * to prohibit copying of objects.
468          */
469         Ucs2Encoding& operator =(const Ucs2Encoding& ucs2Encoding);
470
471         friend class _Ucs2EncodingImpl;
472         class _Ucs2EncodingImpl* __pUcs2EncodingImpl;
473 };
474
475 } } // Tizen::Text
476 #endif //_FTEXT_UCS2_ENCODING_H_