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