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