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