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