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