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