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             This method accepts decimal, hexadecimal, and octal numbers given by the
 193          *                              following grammar:
 194          * @code
 195          *      - DecodableString:
 196          *              Sign[opt] DecimalNumeral
 197          *              Sign[opt] 0x HexDigits
 198          *              Sign[opt] 0X HexDigits
 199          *              Sign[opt] # HexDigits
 200          *              Sign[opt] 0 OctalDigits
 201          *      - Sign:
 202          *              '-'
 203          * @endcode
 204          */
 205         static result Decode(const String& s, int8_t& ret);
 206
 207         /**
 208          * Parses the specified string representing a @c signed 8-bits integral @c int8_t value and
 209          * returns the value as @c signed 8-bits integral @c int8_t (as out parameter).
 210          * @since 3.0
 211          *
 212          * @return              An error code
 213          * @param[in]   s       A string representing a numeric value
 214          * @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.
 215          * @exception   E_SUCCESS        The method is successful.
 216          * @exception   E_NUM_FORMAT The specified string does not contain a byte that can be parsed.
 217          * @exception   E_OUT_OF_RANGE  The parsed value is not between VALUE_MIN and VALUE_MAX range.
 218          * @remarks
 219          *                              - This method assumes that the string representing the @c signed 8-bits integral 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, int8_t& ret);
 223
 224         /**
 225          * Parses the specified string representing a @c signed 8-bits integral @c int8_t value and
 226          * returns the value as @c signed 8-bits integral @c int8_t (as out parameter).
 227          *
 228          * @since 3.0
 229          *
 230          * @return              An error code
 231          * @param[in]   s       A string representing a @c signed 8-bits integral value
 232          * @param[in]   radix   The radix of the string representing a numeric value. Radix value range is from 2 to 36.
 233          * @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
 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.
 238          * @remarks             This method guarantees that the original value of out-parameter is not changed when the method returns error.
 239          */
 240         static result Parse(const String& s, int radix, int8_t& ret);
 241
 242         /**
 243          * Gets the @c signed @c char equivalent of the current instance of %Integer8.
 244          *
 245          * @since 3.0
 246          *
 247          * @return      The @c signed @c char equivalent of the current instance
 248          * @remarks     This method has portability issue. Return value may not be @c signed @c char since char is treated as unsigned char in ARM architecture. @n
 249          *
 250          */
 251         virtual char ToChar(void) const;
 252
 253         /**
 254          * Gets the @c signed @c short equivalent of the current instance of %Integer8.
 255          *
 256          * @since 3.0
 257          *
 258          * @return      The @c signed @c short equivalent of the current instance
 259          */
 260         virtual short ToShort(void) const;
 261
 262         /**
 263          * Gets the @c signed @c int equivalent of the current instance of %Integer8.
 264          *
 265          * @since 3.0
 266          *
 267          * @return      The @c signed @c int equivalent of the current instance
 268          */
 269         virtual int ToInt(void) const;
 270
 271         /**
 272          * Gets the @c signed @c long equivalent of the current instance of %Integer8.
 273          *
 274          * @since 3.0
 275          *
 276          * @return      The @c signed @c long equivalent of the current instance
 277          */
 278         virtual long ToLong(void) const;
 279
 280         /**
 281         * Gets the @c signed @c long @c long equivalent of the current instance of %Integer8.
 282         *
 283         * @since 3.0
 284         *
 285         * @return       The @c signed @c long @c long equivalent of the current instance
 286         */
 287         virtual long long ToLongLong(void) const;
 288
 289         /**
 290          * Gets the @c signed @c float equivalent of the current instance of %Integer8.
 291          *
 292          * @since 3.0
 293          *
 294          * @return      The @c signed @c float equivalent of the current instance
 295          */
 296         virtual float ToFloat(void) const;
 297
 298         /**
 299          * Gets the @c signed @c double equivalent of the current instance of %Integer8.
 300          *
 301          * @since 3.0
 302          *
 303          * @return      The @c signed @c double equivalent of the current instance
 304          */
 305         virtual double ToDouble(void) const;
 306
 307         /**
 308          * Gets the string representing the value of the current instance of %Integer8 using radix @c 10.
 309          *
 310          * @since 3.0
 311          *
 312          * @return              A string representing the value of the current instance using radix 10
 313          */
 314         virtual String ToString(void) const;
 315
 316         /**
 317          * Gets the string representing the specified @c signed 8-bits integral @c int8_t value using radix @c 10.
 318          *
 319          * @since 3.0
 320          *
 321          * @return              A string containing a Unicode representation of the specified @c signed 8-bits integral @c int8_t value using radix 10
 322          * @param[in]   value   A @c signed 8-bits integral @c int8_t value
 323          */
 324         static String ToString(int8_t value);
 325
 326         /**
 327          * A constant holding the maximum value of type @c signed 8-bits integral value. @n
 328          * A @c signed 8-bits integral can hold a maximum value of upto 2^7-1.
 329          *
 330          * @since 3.0
 331          */
 332         static const int8_t VALUE_MAX = static_cast<int8_t> (0x7F);
 333
 334         /**
 335          * A constant holding the minimum value of type @c signed 8-bits integral value. @n
 336          * A @c signed 8-bits integral can hold a minimum value of upto -2^7.
 337          *
 338          * @since 3.0
 339          */
 340         static const int8_t VALUE_MIN = static_cast<int8_t> (0x80);
 341
 342         /**
 343          * A @c signed @c signed 8-bits integral value of this instance.
 344          *
 345          * @since 3.0
 346          */
 347         int8_t value;
 348
 349
 350 private:
 351         friend class _Integer8Impl;
 352         class _Integer8Impl* __pInteger8Impl;
 353
 354 }; // Integer8
 355
 356 }} // Tizen::Base
 357
 358 #endif //_FBASE_INTEGER8_H_