Merge "Change error condition of ToDouble()&ToFloat()" into tizen_2.2
[platform/framework/native/appfw.git] / inc / FTextUtf8Encoder.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                FTextUtf8Encoder.h
19  * @brief               This is the header file for the %Utf8Encoder class.
20  *
21  * This header file contains the declarations of the %Utf8Encoder class.
22  *
23  */
24 #ifndef _FTEXT_UTF8_ENCODER_H_
25 #define _FTEXT_UTF8_ENCODER_H_
26
27 #include <FTextEncoder.h>
28 #include <FBaseByteBuffer.h>
29
30
31 namespace Tizen { namespace Text
32 {
33
34 /**
35  * @class       Utf8Encoder
36  * @brief       This class is an implementation of the UTF-8 encoder.
37  *
38  * @since       2.0
39  *
40  * @final       This class is not intended for extension.
41  *
42  * The %Utf8Encoder class converts the blocks of characters into encoded blocks of bytes.
43  * Universal Transformation Format-8 (UTF-8) is a translated language that is used on the internet. It converts the
44  * unicode into 8-bit bytes. @n UTF-8 encoding supports all unicode character values and surrogates.
45  * Note that %Utf8Encoder is not used in reality, because keeping the internal state of encoding from unicode
46  * to UTF-8 can be avoided if the translation unit is even.
47  * This means that the real implementation of %Utf8Encoder is the same as that of Utf8Encoding in this state.
48  *
49  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/text/converting_text_data_separate_blocks.htm">Converting Text Data in Separate Blocks</a>.
50  *
51  * The following example demonstrates how to use the %Utf8Encoder class.
52  *
53  * @code
54  *      #include <FBase.h>
55  *      #include <FText.h>
56  *
57  *      using namespace Tizen::Base;
58  *      using namespace Tizen::Text;
59  *
60  *      void
61  *      MyClass::Utf8EncoderSample(void)
62  *      {
63  *              Utf8Encoder utf8En;
64  *
65  *              // Fills a WcharBuffer with the unicode strings to encode it into UTF8 format bytes.
66  *              WcharBuffer* pMB = PrepareUtf8EncoderSample();
67  *
68  *              int charBufSize = pMB->GetCapacity();
69  *
70  *              int byteCount = 0;
71  *              utf8En.GetByteCount(*pMB, 0, charBufSize, byteCount);
72  *
73  *              ByteBuffer enBytes;
74  *              enBytes.Construct(byteCount);
75  *
76  *              int charIndex = 0;
77  *              int charCount = 100;
78  *
79  *              while (charIndex < charBufSize)
80  *              {
81  *                      ByteBuffer* pBB = null;
82  *
83  *                      if (charBufSize - charIndex < charCount)
84  *                      {
85  *                              charCount = charBufSize - charIndex;
86  *                      }
87  *
88  *                      // Converts Unicode to Utf8 using Utf8Encoder.
89  *                      pBB = utf8En.GetBytesN(*pMB, charIndex, charCount); // flush is false
90  *
91  *                      enBytes.CopyFrom(*pBB);
92  *                      charIndex += charCount;
93  *
94  *                      delete pBB;
95  *              }
96  *
97  *              enBytes.SetByte('\0');
98  *              enBytes.Rewind();
99  *
100  *              delete pMB;
101  *      }
102  * @endcode
103  */
104
105
106 class _OSP_EXPORT_ Utf8Encoder
107         : public Encoder
108 {
109 public:
110         /**
111          * This is the default constructor for this class.
112          *
113          * @since       2.0
114          *
115          */
116         Utf8Encoder(void);
117
118         /**
119          * This is the destructor for this class. @n
120          * This destructor overrides Tizen::Text::Encoder::~Encoder().
121          *
122          * @since       2.0
123          */
124         virtual ~Utf8Encoder(void);
125
126         /**
127          * Gets the total number of bytes that are required to encode a range of characters in the specified Tizen::Base::WcharBuffer instance.
128          *
129          * @since                       2.0
130          *
131          * @return              An error code
132          * @param[in]   chars                  An instance of Tizen::Base::WcharBuffer to encode
133          * @param[in]   charIndex              The index from where encoding begins in the Tizen::Base::WcharBuffer instance
134          * @param[in]   charCount                 The total number of characters to encode
135          * @param[in]   flush                     Set to @c true to allow this instance to flush its state at the end of the conversion, @n
136          *                                                              else @c false
137          * @param[out]  byteCount               The total number of bytes required to encode the specified range of characters
138          * @exception   E_SUCCESS                The method is successful.
139          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
140          *                                        the specified @c chars is empty.
141          * @exception   E_OUT_OF_RANGE                   The value of an argument is outside the valid range defined by the method, or
142          *                                                                               the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
143          * @exception   E_UNDERFLOW              This operation has caused the memory to underflow, or
144          *                                                                               the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
145          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
146          * @see                 Utf8Decoder::GetCharCount()
147          */
148         virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars,
149                 int charIndex, int charCount, int& byteCount, bool flush = false) const;
150
151         /**
152          * Encodes an instance of Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer.
153          *
154          * @since                       2.0
155          *
156          * @return                                 A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
157          *                                 else @c null if an exception occurs @n
158          *                                                         The buffer limit is the position of the last encoded byte plus one and the starting position is zero.
159          * @param[in]   chars              An instance of Tizen::Base::WcharBuffer to encode
160          * @param[in]   flush              Set to @c true to allow this instance to flush its state at the end of the conversion, @n
161          *                                                 else @c false
162          * @exception   E_SUCCESS                The method is successful.
163          * @exception   E_OUT_OF_MEMORY      The memory is insufficient.
164          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
165          *                                       the specified @c chars is empty.
166          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
167          * @remarks             The specific error code can be accessed using the GetLastResult() method.
168          * @see         Utf8Decoder::GetCharsN()
169          */
170         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::WcharBuffer& chars, bool flush = false) const;
171
172         /**
173          * Encodes an instance of Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer as per the specified range.
174          *
175          * @since                       2.0
176          *
177          * @return                                 A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
178          *                                 else @c null if an exception occurs @n
179          *                                                          The buffer limit is the position of the last encoded byte and the starting position is zero.
180          * @param[in]   chars               An instance of Tizen::Base::WcharBuffer to encode
181          * @param[in]   charIndex               The index from where encoding begins in the Tizen::Base::WcharBuffer instance
182          * @param[in]   charCount The total number of characters to encode
183          * @param[in]   flush                    Set to @c true to allow this instance to flush its state at the end of the conversion, @n
184          *                                                       else @c false
185          * @exception   E_SUCCESS                The method is successful.
186          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
187          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
188          *                                       the specified @c chars is empty.
189          * @exception   E_OUT_OF_RANGE          The value of an argument is outside the valid range defined by the method, or
190          *                                       the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
191          * @exception   E_UNDERFLOW                  This operation has caused the memory to underflow, or
192          *                                        the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
193          * @exception   E_INVALID_ENCODING_RANGE  The specified string contains code points that are outside the bounds of the character encoding scheme.
194          * @remarks             The specific error code can be accessed using the GetLastResult() method.
195          * @remarks             The pointer to the Tizen::Base::ByteBuffer instance is not terminated by a @c null character.
196          * @see         Utf8Decoder::GetCharsN()
197          */
198         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount,
199                 bool flush = false) const;
200
201 private:
202         /**
203          * The implementation of this copy constructor is intentionally blank and declared as private to
204          * prohibit copying of objects.
205          */
206         Utf8Encoder(const Utf8Encoder& utf8Encoder);
207
208         /**
209          * The implementation of this copy assignment operator is intentionally blank and declared as private
210          * to prohibit copying of objects.
211          */
212         Utf8Encoder& operator =(const Utf8Encoder& utf8Encoder);
213
214         friend class _Utf8EncoderImpl;
215         class _Utf8EncoderImpl* __pUtf8EncoderImpl;
216 };
217
218 } } // Tizen::Text
219 #endif //_FTEXT_UTF8_ENCODER_H_