inc/FTextAsciiEncoding.h

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