inc/FBaseInteger8.h

   1 //
   2 // Copyright (c) 2013 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                FBaseInteger8.h
  19  * @brief               This is the header file for the %Integer8 class.
  20  *
  21  * @see                 Tizen::Base::Number
  22  *
  23  * This header file contains the declarations of the %Integer8 class.
  24  */
  25 #ifndef _FBASE_INTEGER8_H_
  26 #define _FBASE_INTEGER8_H_
  27
  28 #include <stdint.h>
  29 #include <FBaseNumber.h>
  30
  31 namespace Tizen { namespace Base
  32 {
  33 /**
  34  * @class       Integer8
  35  * @brief       This class is the wrapper class for the  @c 8-bits integral built-in type @c int8_t.
  36  *
  37  * @since 3.0
  38  *
  39  * The %Integer8 class represents an integer value ranging from -128 to 127. The class is useful when passing an 8-bit
  40  * signed integral value to a method that accepts only an instance of Object. Furthermore, this class provides
  41  * methods for converting %Integer8 (and @c char) to String, and %String to %Integer8 (and @c char).
  42  *
  43  * The following example demonstrates how to use the %Integer8 class.
  44  * @code
  45  *
  46  *      #include <FBase.h>
  47  *
  48  *      using namespace Tizen::Base;
  49  *
  50  *      // This method checks whether the given string object contains a string
  51  *      // representation of the pre-defined minimum 8-bit integral value.
  52  *      result
  53  *      MyClass::Verify(String& string, bool& out)
  54  *      {
  55  *              static const Integer8 i1(123);
  56  *
  57  *              int8_t int8Val;
  58  *              result r = Integer8::Parse(string, int8Val);
  59  *              static const Integer8 i2(int8Val);
  60  *              if (!IsFailed(r))
  61  *              {
  62  *                      out = (i1.CompareTo(i2) == 0) ? true: false;
  63  *              }
  64  *
  65  *              return r;
  66  *      }
  67  * @endcode
  68  */
  69 class _OSP_EXPORT_ Integer8
  70         : public Number
  71 {
  72 public:
  73         /**
  74          * This is the default constructor for this class. Initializes the value to 0.
  75          *
  76          * @since 3.0
  77          *
  78          */
  79         Integer8();
  80
  81         /**
  82          * Initializes this instance of %Integer8 with the specified value.
  83          *
  84          * @since 3.0
  85          *
  86          * @param[in]   value   A @c signed 8-bits integral @c int8_t value
  87          */
  88         explicit Integer8(int8_t value);
  89
  90
  91         /**
  92          * Copying of objects using this copy constructor is allowed.
  93          *
  94          * @since 3.0
  95          *
  96          * @param[in]   value   An instance of %Integer8
  97          */
  98         Integer8(const Integer8& value);
  99
 100         /**
 101          * This destructor overrides Tizen::Base::Object::~Object().
 102          *
 103          * @since 3.0
 104          */
 105         virtual ~Integer8(void);
 106
 107         /**
 108          * Copying of objects using this copy assignment operator is allowed.
 109          *
 110          * @since 3.0
 111          *
 112          * @param[in]   rhs     An instance of %Integer8
 113          */
 114         Integer8& operator =(const Integer8& rhs);
 115
 116         /**
 117          * Compares two @c signed 8-bits integral @c int8_t values.
 118          *
 119          * @since 3.0
 120          *
 121          * @return              A 32-bit @c signed integr value
 122          * @code
 123          * <  0  if the value of i81 is less than the value of i82
 124          * == 0  if the value of i81 is equal to the value of i82
 125          * >  0  if the value of i81 is greater than the value of i82
 126          * @endcode
 127          * @param[in]   i81     The first @c signed 8-bits integral @c int8_t value to compare
 128          * @param[in]   i82     The second @c signed 8-bits integral @c int8_t value to compare
 129          */
 130         static int Compare(int8_t i81, int8_t i82);
 131
 132         /**
 133          * Compares the value of the current instance with the value of the specified instance of the %Integer8 class.
 134          *
 135          * @since 3.0
 136          *
 137          * @return              A 32-bit @c signed integer value
 138          * @code
 139          * <  0  if the value of the current instance is less than the value of the specified instance
 140          * == 0  if the value of the current instance is equal to the value of the specified instance
 141          * >  0  if the value of the current instance is greater than the value of the specified instance
 142          * @endcode
 143          * @param[in]   value   An instance of the %Integer8 class to compare
 144          */
 145         int CompareTo(const Integer8& value) const;
 146
 147         /**
 148          * Checks whether the value of the specified instance of %Integer8 is equal to the value of the current instance.
 149          *
 150          * @since 3.0
 151          *
 152          * @return              @c true if the value of the specified instance is equal to the value of the current instance, @n
 153          *                              else @c false
 154          * @param[in]   obj An instance of Object to compare
 155          * @see                 Tizen::Base::Object::Equals()
 156          */
 157         virtual bool Equals(const Object& obj) const;
 158
 159         /**
 160          *      Gets the hash value of the current instance of %Integer8.
 161          *
 162          *      @since 3.0
 163          *
 164          *      @return         An integer value indicating the hash value of the current instance of %Integer8
 165          *      @remarks        Two equal instances must return the same hash value. For better performance,
 166          *                              the used hash function must generate a random distribution for all inputs. @n
 167          *                              The default implementation of this method returns the value of the current instance.
 168          */
 169         virtual int GetHashCode(void) const;
 170
 171         /**
 172         *   Gets the hash value of the specified @c signed 8-bits integral @c int8_t value.
 173         *
 174         *   @since 3.0
 175         *
 176         *   @return     An integer value indicating the hash value of the specified @c signed 8-bits integral @c int8_t value
 177         *   @param[in]   val   A @c signed 8-bits integral @c int8_t value to get the hash value
 178         */
 179         static int GetHashCode(int8_t val);
 180
 181         /**
 182          * Decodes a string into a @c signed 8-bits integral @c int8_t value.
 183          *
 184          * @since 3.0
 185          *
 186          * @return              An error code
 187          * @param[in]   s       A string representing a numeric value
 188          * @param[out]  ret     The result of the operation
 189          * @exception   E_SUCCESS       The method is successful.
 190          * @exception   E_NUM_FORMAT    The specified string does not contain a number that can be parsed.
 191          * @exception   E_OUT_OF_RANGE  The decoded value is not between VALUE_MIN and VALUE_MAX range.
 192          * @remarks
 193          *              - This method guarantees that the original value of out-parameter is not changed when the method returns error.
 194          *              - This method accepts decimal, hexadecimal, and octal numbers given by the
 195          *                              following grammar:
 196          * @code
 197          *      - DecodableString:
 198          *              Sign[opt] DecimalNumeral
 199          *              Sign[opt] 0x HexDigits
 200          *              Sign[opt] 0X HexDigits
 201          *              Sign[opt] # HexDigits
 202          *              Sign[opt] 0 OctalDigits
 203          *      - Sign:
 204          *              '-'
 205          * @endcode
 206          */
 207         static result Decode(const String& s, int8_t& ret);
 208
 209         /**
 210          * Parses the specified string representing a @c signed 8-bits integral @c int8_t value and
 211          * returns the value as @c signed 8-bits integral @c int8_t (as out parameter).
 212          * @since 3.0
 213          *
 214          * @return              An error code
 215          * @param[in]   s       A string representing a numeric value
 216          * @param[out]  ret     The @c signed 8-bits integral @c int8_t equivalent of the specified string representing the numeric value using the decimal radix.
 217          * @exception   E_SUCCESS        The method is successful.
 218          * @exception   E_NUM_FORMAT The specified string does not contain a byte that can be parsed.
 219          * @exception   E_OUT_OF_RANGE  The parsed value is not between VALUE_MIN and VALUE_MAX range.
 220          * @remarks
 221          *                              - This method assumes that the string representing the @c signed 8-bits integral value uses a radix 10.
 222          *                              - This method guarantees that the original value of out-parameter is not changed when the method returns error.
 223          */
 224         static result Parse(const String& s, int8_t& ret);
 225
 226         /**
 227          * Parses the specified string representing a @c signed 8-bits integral @c int8_t value and
 228          * returns the value as @c signed 8-bits integral @c int8_t (as out parameter).
 229          *
 230          * @since 3.0
 231          *
 232          * @return              An error code
 233          * @param[in]   s       A string representing a @c signed 8-bits integral value
 234          * @param[in]   radix   The radix of the string representing a numeric value. Radix value range is from 2 to 36.
 235          * @param[out]  ret     The @c signed 8-bits integral @c int8_t equivalent of the specified string representing the numeric value using the specified radix
 236          * @exception   E_SUCCESS        The method is successful.
 237          * @exception   E_NUM_FORMAT    The specified string does not contain a number that can be parsed.
 238          * @exception   E_OUT_OF_RANGE  The specified @c radix is invalid, or
 239          *                              The parsed value is not between VALUE_MIN and VALUE_MAX range.
 240          * @remarks             This method guarantees that the original value of out-parameter is not changed when the method returns error.
 241          */
 242         static result Parse(const String& s, int radix, int8_t& ret);
 243
 244         /**
 245          * Gets the @c char equivalent of the current instance of %Integer8.
 246          *
 247          * @since 3.0
 248          * @brief       <i> [Deprecated] </i>
 249          *
 250          * @deprecated  This method has portability issue.
 251          *              Return value may not be @c signed @c char since char is treated as unsigned char in ARM architecture. @n
 252          *              Use ToInt8() method to get @c int8_t
 253          *
 254          * @return      The @c char equivalent of the current instance
 255          *
 256          */
 257         virtual char ToChar(void) const;
 258
 259         /**
 260          * Gets the @c int8_t equivalent of the current instance of %Integer8.
 261          *
 262          * @since 3.0
 263          *
 264          * @return      The @c int8_t equivalent of the current instance
 265          *
 266          */
 267         virtual int8_t ToInt8(void) const;
 268
 269         /**
 270          * Gets the @c signed @c short equivalent of the current instance of %Integer8.
 271          *
 272          * @since 3.0
 273          *
 274          * @return      The @c signed @c short equivalent of the current instance
 275          */
 276         virtual short ToShort(void) const;
 277
 278         /**
 279          * Gets the @c signed @c int equivalent of the current instance of %Integer8.
 280          *
 281          * @since 3.0
 282          *
 283          * @return      The @c signed @c int equivalent of the current instance
 284          */
 285         virtual int ToInt(void) const;
 286
 287         /**
 288          * Gets the @c signed @c long equivalent of the current instance of %Integer8.
 289          *
 290          * @since 3.0
 291          *
 292          * @return      The @c signed @c long equivalent of the current instance
 293          */
 294         virtual long ToLong(void) const;
 295
 296         /**
 297         * Gets the @c signed @c long @c long equivalent of the current instance of %Integer8.
 298         *
 299         * @since 3.0
 300         *
 301         * @return       The @c signed @c long @c long equivalent of the current instance
 302         */
 303         virtual long long ToLongLong(void) const;
 304
 305         /**
 306          * Gets the @c signed @c float equivalent of the current instance of %Integer8.
 307          *
 308          * @since 3.0
 309          *
 310          * @return      The @c signed @c float equivalent of the current instance
 311          */
 312         virtual float ToFloat(void) const;
 313
 314         /**
 315          * Gets the @c signed @c double equivalent of the current instance of %Integer8.
 316          *
 317          * @since 3.0
 318          *
 319          * @return      The @c signed @c double equivalent of the current instance
 320          */
 321         virtual double ToDouble(void) const;
 322
 323         /**
 324          * Gets the string representing the value of the current instance of %Integer8 using radix @c 10.
 325          *
 326          * @since 3.0
 327          *
 328          * @return              A string representing the value of the current instance using radix 10
 329          */
 330         virtual String ToString(void) const;
 331
 332         /**
 333          * Gets the string representing the specified @c signed 8-bits integral @c int8_t value using radix @c 10.
 334          *
 335          * @since 3.0
 336          *
 337          * @return              A string containing a Unicode representation of the specified @c signed 8-bits integral @c int8_t value using radix 10
 338          * @param[in]   value   A @c signed 8-bits integral @c int8_t value
 339          */
 340         static String ToString(int8_t value);
 341
 342         /**
 343          * A constant holding the maximum value of type @c signed 8-bits integral value. @n
 344          * A @c signed 8-bits integral can hold a maximum value of upto 2^7-1.
 345          *
 346          * @since 3.0
 347          */
 348         static const int8_t VALUE_MAX = static_cast<int8_t> (0x7F);
 349
 350         /**
 351          * A constant holding the minimum value of type @c signed 8-bits integral value. @n
 352          * A @c signed 8-bits integral can hold a minimum value of upto -2^7.
 353          *
 354          * @since 3.0
 355          */
 356         static const int8_t VALUE_MIN = static_cast<int8_t> (0x80);
 357
 358         /**
 359          * A @c signed @c signed 8-bits integral value of this instance.
 360          *
 361          * @since 3.0
 362          */
 363         int8_t value;
 364
 365
 366 private:
 367         friend class _Integer8Impl;
 368         class _Integer8Impl* __pInteger8Impl;
 369
 370 }; // Integer8
 371
 372 }} // Tizen::Base
 373
 374 #endif //_FBASE_INTEGER8_H_