inc/FBaseInt8.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                FBaseInt8.h
  19  * @brief               This is the header file for the %Int8 class.
  20  *
  21  * @see                 Tizen::Base::Number
  22  *
  23  * This header file contains the declarations of the %Int8 class.
  24  */
  25 #ifndef _FBASE_INT8_H_
  26 #define _FBASE_INT8_H_
  27
  28 #include <FBaseNumber.h>
  29
  30
  31 namespace Tizen { namespace Base
  32 {
  33 /**
  34  * @class       Int8
  35  * @brief       This class is the wrapper class for the @c signed @c char built-in type.
  36  *
  37  * @since 2.0
  38  *
  39  * The %Int8 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 %Int8 (and @c char) to String, and %String to %Int8 (and @c char).
  42  *
  43  * The following example demonstrates how to use the %Int8 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 Int8 MINIMUM(123);
  56  *
  57  *              result r = E_SUCCESS;
  58  *
  59  *              char ch;
  60  *              r = Int8::Parse(string, ch);
  61  *              if (IsFailed(r))
  62  *              {
  63  *                      goto CATCH;
  64  *              }
  65  *
  66  *              out = (MINIMUM.CompareTo(ch) == 0) ? true: false;
  67  *
  68  *              return r;
  69  *      CATCH:
  70  *              return r;
  71  *      }
  72  * @endcode
  73  */
  74 class _OSP_EXPORT_ Int8
  75         : public Number
  76 {
  77 public:
  78         /**
  79          * Initializes this instance of %Int8 with the specified value.
  80          *
  81          * @since 2.0
  82          *
  83          * @param[in]   value   A @c char value
  84          */
  85         Int8(char value = 0);
  86
  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 %Int8
  94          */
  95         Int8(const Int8& value);
  96
  97         /**
  98          * This destructor overrides Tizen::Base::Object::~Object().
  99          *
 100          * @since 2.0
 101          */
 102         virtual ~Int8(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 %Int8
 110          */
 111         Int8& operator =(const Int8& rhs);
 112
 113         /**
 114          * Compares two @c char values.
 115          *
 116          * @since 2.0
 117          *
 118          * @return              A 32-bit @c signed integer value
 119          * @code
 120          * <  0  if the value of ch1 is less than the value of ch2
 121          * == 0  if the value of ch1 is equal to the value of ch2
 122          * >  0  if the value of ch1 is greater than the value of ch2
 123          * @endcode
 124          * @param[in]   ch1     The first @c char value to compare
 125          * @param[in]   ch2     The second @c char value to compare
 126          */
 127         static int Compare(char ch1, char ch2);
 128
 129         /**
 130          * Compares the value of the current instance with the value of the specified instance of the %Int8 class.
 131          *
 132          * @since 2.0
 133          *
 134          * @return              A 32-bit @c signed integer value
 135          * @code
 136          * <  0  if the value of the current instance is less than the value of the specified instance
 137          * == 0  if the value of the current instance is equal to the value of the specified instance
 138          * >  0  if the value of the current instance is greater than the value of the specified instance
 139          * @endcode
 140          * @param[in]   value   An instance of the %Int8 class to compare
 141          */
 142         int CompareTo(const Int8& value) const;
 143
 144         /**
 145          * Checks whether the value of the specified instance of %Int8 is equal to the value of the current instance.
 146          *
 147          * @since 2.0
 148          *
 149          * @return              @c true if the value of the specified instance is equal to the value of the current instance, @n
 150          *                              else @c false
 151          * @param[in]   obj An instance of Object to compare
 152          * @see                 Tizen::Base::Object::Equals()
 153          */
 154         virtual bool Equals(const Object& obj) const;
 155
 156         /**
 157          *      Gets the hash value of the current instance of %Int8.
 158          *
 159          *      @since 2.0
 160          *
 161          *      @return         An integer value indicating the hash value of the current instance of %Int8
 162          *      @remarks        Two equal instances must return the same hash value. For better performance,
 163          *                              the used hash function must generate a random distribution for all inputs. @n
 164          *                              The default implementation of this method returns the value of the current instance.
 165          */
 166         virtual int GetHashCode(void) const;
 167
 168         /**
 169         *   Gets the hash value of the specified @c char value.
 170         *
 171         *   @since 2.0
 172         *
 173         *   @return     An integer value indicating the hash value of the specified @c char value
 174         *   @param[in]   val   A @c char value to get the hash value
 175         */
 176         static int GetHashCode(char val);
 177
 178         /**
 179          * Decodes a string into a @c signed @c char.
 180          *
 181          * @since 2.0
 182          *
 183          * @return              An error code
 184          * @param[in]   s       A string representing a numeric value
 185          * @param[out]  ret     The result of the operation
 186          * @exception   E_SUCCESS        The method is successful.
 187          * @exception   E_NUM_FORMAT The specified string does not contain a number that can be parsed.
 188          * @remarks             This method accepts decimal, hexadecimal, and octal numbers given by the
 189          *                              following grammar:
 190          * @code
 191          *      - DecodableString:
 192          *              Sign[opt] DecimalNumeral
 193          *              Sign[opt] 0x HexDigits
 194          *              Sign[opt] 0X HexDigits
 195          *              Sign[opt] # HexDigits
 196          *              Sign[opt] 0 OctalDigits
 197          *      - Sign:
 198          *              '-'
 199          * @endcode
 200          * @remarks             This method has portability issue. @n
 201          *                              When the specified string is nagative number in the ARM architecture, type casting is needed like following code.
 202          * @code
 203          *      char ret;
 204          *      Int8::Decode(L"-0X20", ret);
 205          *      SomeOutputFunction(static_cast< signed char >(ret));
 206          * @endcode
 207          */
 208         static result Decode(const String& s, char& ret);
 209
 210         /**
 211          * Parses the @c signed @c char equivalent of the specified string representing a numeric value.
 212          *
 213          * @since 2.0
 214          *
 215          * @return              An error code
 216          * @param[in]   s       A string representing a numeric value
 217          * @param[out]  ret     The result of the operation
 218          * @exception   E_SUCCESS        The method is successful.
 219          * @exception   E_NUM_FORMAT The specified string does not contain a byte that can be parsed.
 220          * @remarks
 221          *                              - This method assumes that the string representing the numeric value uses a radix 10.
 222          *                              - This method guarantees that the original value of out-parameter is not changed when the method returns error.
 223          */
 224         static result Parse(const String& s, char& ret);
 225
 226         /**
 227          * Parses the specified string representing a numeric value and
 228          * returns the value as @c signed @c char (as out parameter).
 229          *
 230          * @since 2.0
 231          *
 232          * @return              The @c signed @c char equivalent of the specified string representing the numeric value using the specified index
 233          * @param[in]   s       A string representing a numeric value
 234          * @param[in]   radix   The radix of the string representing a numeric value @n
 235          *                                              It must either be 2, 8, 10, or 16.
 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.
 240          * @remarks             This method guarantees that the original value of out-parameter is not changed when the method returns error.
 241          */
 242         static result Parse(const String& s, int radix, char& ret);
 243
 244         /**
 245          * Gets the @c signed @c char equivalent of the current instance of %Int8.
 246          *
 247          * @since 2.0
 248          *
 249          * @return      The @c signed @c char equivalent of the current instance
 250          */
 251         virtual char ToChar(void) const;
 252
 253         /**
 254          * Gets the @c signed @c short equivalent of the current instance of %Int8.
 255          *
 256          * @since 2.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 %Int8.
 264          *
 265          * @since 2.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 %Int8.
 273          *
 274          * @since 2.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 %Int8.
 282         *
 283         * @since 2.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 %Int8.
 291          *
 292          * @since 2.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 %Int8.
 300          *
 301          * @since 2.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 %Int8.
 309          *
 310          * @since 2.0
 311          *
 312          * @return              A string representing the value of the current instance
 313          */
 314         virtual String ToString(void) const;
 315
 316         /**
 317          * Gets the string representing the specified @c signed @c char value using radix @c 10.
 318          *
 319          * @since 2.0
 320          *
 321          * @return              A string containing a Unicode representation of the specified @c char value using radix 10
 322          * @param[in]   value   A @c char value
 323          */
 324         static String ToString(char value);
 325
 326         /**
 327          * A constant holding the maximum value of type @c char. @n
 328          * A @c short character can hold a value of upto 2^7-1.
 329          *
 330          * @since 2.0
 331          */
 332         static const char VALUE_MAX = (signed char) 0x7F;
 333
 334         /**
 335          * A constant holding the minimum value of type @c char. @n
 336          * A @c short character can hold a value of upto -2^7.
 337          *
 338          * @since 2.0
 339          */
 340         static const char VALUE_MIN = (signed char) 0x80;
 341
 342         /**
 343          * A @c signed @c char value of this instance.
 344          *
 345          * @since 2.0
 346          */
 347         signed char value;
 348
 349
 350 private:
 351         friend class _Int8Impl;
 352         class _Int8Impl * __pInt8Impl;
 353
 354 }; // Int8
 355
 356 }} // Tizen::Base
 357
 358 #endif //_FBASE_INT8_H_