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