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