inc/FTextAsciiEncoding.h

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