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  * The %AsciiEncoding 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 maintains no state consistency between conversions. The method is intended for
 202          * conversions of complete blocks of bytes and characters in one operation.
 203          * This method decodes in a single step.
 204          *
 205          * @since                       2.0
 206          *
 207          * @return              A pointer to the Tizen::Base::WcharBuffer instance where the resultant decoded data is stored, @n
 208          *                                              else @c null if an exception occurs @n
 209          *                                              The buffer limit is the position of the last decoded byte plus one and the starting position is zero.
 210          * @param[in]   bytes An instance of Tizen::Base::ByteBuffer to decode
 211          * @exception   E_SUCCESS                The method is successful.
 212          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 213          * @exception   E_INVALID_ARG            The specified @c bytes is empty or invalid.
 214          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 215          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 216          * @see                         GetBytesN()
 217          */
 218         virtual Tizen::Base::WcharBuffer* GetCharsN(const Tizen::Base::ByteBuffer& bytes) const;
 219
 220         /**
 221          * Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer as per the specified range. @n
 222          * The position and limit of the %Tizen::Base::WcharBuffer instance is not changed.
 223          * The GetChars() method maintains no state consistency between conversions. The method is intended for
 224          * conversions of complete blocks of bytes and characters in one operation.
 225          *
 226          * @since                       2.0
 227          *
 228          * @return              An error code
 229          * @param[in]   bytes An instance of Tizen::Base::ByteBuffer to decode
 230          * @param[in]   byteIndex The index from where decoding begins
 231          * @param[in]   byteCount The total number of bytes to decode
 232          * @param[out]  chars The Tizen::Base::WcharBuffer instance where the resultant decoded string is stored
 233          * @param[in]   charIndex The index from where encoding begins in the Tizen::Base::WcharBuffer instance
 234          * @exception   E_SUCCESS                The method is successful.
 235          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 236          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
 237          *                                         the specified @c bytes or @c chars is empty.
 238          * @exception   E_OUT_OF_RANGE       The value of an argument is outside the valid range defined by the method, or
 239          *                                                                             the length of the specified @c byteIndex or @c byteCount is greater than the length of the specified @c bytes.
 240          * @exception   E_UNDERFLOW                  This operation has caused the memory to underflow, or
 241          *                                                                                 the sum of the length of the specified @c byteIndex and @c byteCount is greater than the length of the specified @c bytes.
 242          * @exception E_OVERFLOW                     This operation has caused the memory to overflow, or
 243          *                                                                                the specified @c chars does not contain sufficient space to store the decoded bytes.
 244          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 245          * @see                         GetBytes()
 246          */
 247         virtual result GetChars(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount, Tizen::Base::WcharBuffer& chars, int charIndex = 0) const;
 248
 249         /**
 250          * Gets a string containing the decoded representation of the specified Tizen::Base::ByteBuffer instance.
 251          *
 252          * @since                       2.0
 253          *
 254          * @return              An error code
 255          * @param[in]   bytes An instance of Tizen::Base::ByteBuffer to decode
 256          * @param[out]  str  A Tizen::Base::String instance @n
 257          *                   It contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
 258          * @exception   E_SUCCESS                The method is successful.
 259          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 260          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
 261          *                                         the specified @c bytes is empty.
 262          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 263          * @remarks     GetString() assumes that the Tizen::Base::ByteBuffer instance contains all the bytes necessary to generate the entire string.
 264          *              If the bytes are in multiple byte arrays, use the Decoder class, which maintains state consistency
 265          *              between multiple calls.
 266          * @see                         GetBytesN()
 267          */
 268         virtual result GetString(const Tizen::Base::ByteBuffer& bytes, Tizen::Base::String& str) const;
 269
 270         /**
 271          * Gets a string containing the decoded representation of the specified Tizen::Base::ByteBuffer instance.
 272          *
 273          * @since                       2.0
 274          *
 275          * @return              An error code
 276          * @param[in]   bytes An instance of Tizen::Base::ByteBuffer to decode
 277          * @param[in]   index The index from where decoding begins
 278          * @param[in]   count The total number of bytes to decode
 279          * @param[out]  str  A Tizen::Base::String instance @n
 280          *                   It contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
 281          * @exception   E_SUCCESS                The method is successful.
 282          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 283          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
 284          *                                         the specified @c bytes is empty.
 285          * @exception   E_OUT_OF_RANGE       The value of an argument is outside the valid range defined by the method, or
 286          *                                                                                 the sum of the length of the specified @c index and @c count is greater than the length of the specified @c bytes.
 287          * @exception E_UNDERFLOW                                This operation has caused the memory to underflow, or
 288          *                                                                              the sum of the length of the specified @c index and @c count is greater than the length of the specified @c bytes.
 289          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 290          * @remarks     GetString() assumes that the Tizen::Base::ByteBuffer instance contains all the bytes necessary to generate the entire string.
 291          *              If the bytes are in multiple byte arrays, use the Decoder class, which maintains state consistency
 292          *              between multiple calls.
 293          * @see                         GetBytes()
 294          */
 295         virtual result GetString(const Tizen::Base::ByteBuffer& bytes, int index, int count, Tizen::Base::String& str) const;
 296
 297         /**
 298         * Gets the maximum number of bytes required for encoding a given number of characters.
 299         *
 300         * @since                        2.0
 301         *
 302         * @return               The maximum number of bytes required for encoding a given number of characters
 303         * @param[in]    charCount The total number of characters to encode
 304         * @remarks   GetMaxByteCount() determines an appropriate buffer size for the byte arrays passed to GetBytes() for encoding.
 305         * @see                          Encoding::GetByteCount()
 306         * @see                          GetBytes()
 307         */
 308         virtual int GetMaxByteCount(int charCount) const;
 309
 310         /**
 311          * Gets the maximum number of characters that are generated by decoding the specified number of bytes.
 312          *
 313          * @since                       2.0
 314          *
 315          * @return              The maximum number of characters that are generated by decoding the specified number of bytes
 316          * @param[in]   byteCount The total number of bytes to encode
 317          * @remarks   GetMaxCharCount() determines an appropriate buffer size for character arrays passed to
 318          *                GetChars() or a decoder for encoding.
 319          * @see                         Encoding::GetCharCount()
 320          * @see                         GetChars()
 321          */
 322         virtual int GetMaxCharCount(int byteCount) const;
 323
 324
 325         /**
 326          * Gets the encoder for the current encoding.
 327          *
 328          * @since                       2.0
 329          *
 330          * @return              A pointer to the Encoder instance for the current encoding
 331          * @remarks   Contrary to GetBytes(), an encoder can convert partial sequences of characters into
 332          *            partial sequences of bytes by maintaining the appropriate state between the conversions. @n
 333          *            At present, only the Utf8Encoding class supports this method. Other classes return @c null.
 334          * @see                         GetBytes()
 335          */
 336         virtual Encoder* GetEncoderN(void) const;
 337
 338         /**
 339          * Gets the decoder for the current encoding.
 340          *
 341          * @since                       2.0
 342          *
 343          * @return              A pointer to the Decoder instance for the current encoding
 344          * @remarks   Contrary to GetChars(), a decoder can convert partial sequences of bytes
 345          *            into partial sequences of characters by maintaining the appropriate state between the conversions. @n
 346          *            At present, only the Utf8Encoding class supports this method. Other classes return @c null.
 347          *
 348          * @see                         GetChars()
 349          */
 350         virtual Decoder* GetDecoderN(void) const;
 351
 352         /**
 353         * Gets the encoding type of the current instance.
 354         *
 355         * @since 2.0
 356         *
 357         * @return               An encoding type
 358         */
 359         virtual Tizen::Base::String GetEncodingType(void) const;
 360
 361 private:
 362         /**
 363          * The implementation of this copy constructor is intentionally blank and declared as private to
 364          * prohibit copying of objects.
 365          */
 366         AsciiEncoding(const AsciiEncoding& asciiEncoding);
 367
 368         /**
 369          * The implementation of this copy assignment operator is intentionally blank and declared as private
 370          * to prohibit copying of objects.
 371          */
 372         AsciiEncoding& operator =(const AsciiEncoding& asciiEncoding);
 373
 374         friend class _AsciiEncodingImpl;
 375         class _AsciiEncodingImpl* __pAsciiEncodingImpl;
 376 };
 377
 378 } } // Tizen::Text
 379 #endif //_FTEXT_ASCII_ENCODING_H_