inc/FBaseFloat.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                FBaseFloat.h
  19  * @brief               This is the header file for the %Float class.
  20  *
  21  * @see                 Tizen::Base::Number
  22  *
  23  * This header file contains the declarations of the %Float class.
  24  */
  25 #ifndef _FBASE_FLOAT_H_
  26 #define _FBASE_FLOAT_H_
  27
  28 #include <FBaseNumber.h>
  29
  30
  31 namespace Tizen { namespace Base
  32 {
  33 /**
  34  *      @class  Float
  35  *      @brief  This class is the wrapper class for the @c signed @c float built-in type.
  36  *
  37  *      @since  2.0
  38  *
  39  *      The %Float class represents a single-precision 32-bit floating number. The %Float class wraps a @c float type value. This enables
  40  *      passing a @c float value to a method that only accepts an instance of Object class. This class provides methods to compare instances
  41  *      of this type, convert the value of an instance to its string representation, and convert the string representation
  42  *      of a number to an instance of this type.
  43  *
  44  * The following example demonstrates how to use the %Float 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 the string
  53  *      // representation of the pre-defined minimum float value.
  54  *      result
  55  *      MyClass::Verify(String& string, bool& out)
  56  *      {
  57  *              // Creates and initializes an instance of Double
  58  *              static const Float MINIMUM(1.23L);
  59  *
  60  *              result r = E_SUCCESS;
  61  *
  62  *              float f;
  63  *
  64  *              // Parses the string representation of the numeric value
  65  *              // Returns f (value as signed float)
  66  *              r = Float::Parse(string, f);
  67  *
  68  *              // Error Handling
  69  *              if (IsFailed(r))
  70  *              {
  71  *                      goto CATCH;
  72  *              }
  73  *
  74  *              out = (MINIMUM.CompareTo(f) == 0) ? true: false;
  75  *              return r;
  76  *      CATCH:
  77  *              return r;
  78  *      }
  79  *      @endcode
  80  */
  81 class _OSP_EXPORT_ Float
  82         : public Number
  83 {
  84 public:
  85         /**
  86          *      Initializes this instance of %Float with the specified value.
  87          *
  88          *      @since                  2.0
  89          *
  90          *      @param[in]      value   A @c float value
  91          */
  92         Float(float value = 0.0);
  93
  94
  95         /**
  96          *      Copying of objects using this copy constructor is allowed.
  97          *
  98          *      @since                  2.0
  99          *
 100          *      @param[in]      value   An instance of %Float
 101          */
 102         Float(const Float& value);
 103
 104         /**
 105          *      This destructor overrides Tizen::Base::Object::~Object().
 106          *
 107          *      @since  2.0
 108          */
 109         virtual ~Float(void);
 110
 111         /**
 112          *      Copying of objects using this copy assignment operator is allowed.
 113          *
 114          *      @since                  2.0
 115          *
 116          *      @param[in]      rhs     An instance of %Float
 117          */
 118         Float& operator =(const Float& rhs);
 119
 120         /**
 121          *      Compares two @c float values.
 122          *
 123          *      @since          2.0
 124          *
 125          *      @return         A 32-bit @c signed integer value
 126          *      @code
 127          *      <  0  if the value of @c f1 is less than the value of @c f2
 128          *      == 0  if the value of @c f1 is equal to the value of @c f2
 129          *      >  0  if the value of @c f1 is greater than the value of @c f2
 130          *      @endcode
 131          *      @param[in]      f1      The first @c float value to compare
 132          *      @param[in]      f2      The second @c float value to compare
 133          */
 134         static int Compare(float f1, float f2);
 135
 136         /**
 137          *      Compares the value of the current instance with the value of the specified instance of the %Float class.
 138          *
 139          *      @since          2.0
 140          *
 141          *      @return         A 32-bit @c signed integer value
 142          *      @code
 143          *      @li <  0    if the value of the current instance is less than the value of the specified instance
 144          *      @li == 0    if the value of the current instance is equal to the value of the specified instance
 145          *      @li >  0    if the value of the current instance is greater than the value of the specified instance
 146          *      @endcode
 147          *      @param[in]      value   An instance of the %Float class to compare
 148          */
 149         int CompareTo(const Float& value) const;
 150
 151         /**
 152          *      Checks whether the value of the specified instance of Object is equal to the value of the current instance of %Float.
 153          *
 154          *      @since          2.0
 155          *
 156          *      @return         @c true if the value of the specified instance of Object is equal to the value of the current instance of %Float, @n
 157          *                              else @c false
 158          *      @param[in]      obj             An instance of Object to compare
 159          *      @see            Tizen::Base::Object::Equals()
 160          */
 161         virtual bool Equals(const Object& obj) const;
 162
 163
 164         /**
 165          *      Gets the hash value of the current instance of %Float.
 166          *
 167          *      @since          2.0
 168          *
 169          *      @return         An integer value indicating the hash value of the current instance of %Float
 170          *      @remarks        Two equal instances must return the same hash value. For better performance,
 171          *                              the used hash function must generate a random distribution for all inputs. @n
 172          *                              The default implementation of this method returns the value of the current instance.
 173          */
 174         virtual int GetHashCode(void) const;
 175
 176         /**
 177         *        Gets the hash value of the specified @c float value.
 178         *
 179         *        @since         2.0
 180         *
 181         *        @return        An integer value indicating the hash value of the specified @c float value
 182         *        @param[in]   val   A @c float value to get the hash value
 183         */
 184         static int GetHashCode(float val);
 185
 186         /**
 187          * Parses the specified string representing a numeric value and returns the value as @c signed @c float (as out parameter).
 188          *
 189          *      @since                  2.0
 190          *
 191          *      @return                 An error code
 192          *      @param[in]      s                       A unicode string representing a @c signed @c float value
 193          *      @param[out]     ret                     The numeric representation of the string
 194          *      @exception      E_SUCCESS        The method is successful.
 195          *      @exception      E_NUM_FORMAT The specified string does not contain a number that can be parsed.
 196          *      @remarks
 197          *                              - This method guarantees that the original value of out-parameter is not changed when the method returns error.
 198          *                              - The behavior of this method is dependent on the system default locale setting.
 199          *      @see            Tizen::Base::Double::Parse()
 200          */
 201         static result Parse(const String& s, float& ret);
 202
 203         /**
 204          *      Gets the @c signed @c char equivalent of the current %Float instance.
 205          *
 206          *      @since          2.0
 207          *
 208          *      @return         A @c signed @c char equivalent of the current instance
 209          */
 210         virtual char ToChar(void) const;
 211
 212         /**
 213          *      Gets the @c signed @c short equivalent of the current %Float instance.
 214          *
 215          *      @since          2.0
 216          *
 217          *      @return         A @c signed @c short equivalent of the current instance
 218          */
 219         virtual short ToShort(void) const;
 220
 221         /**
 222          *      Gets the @c signed @c int equivalent of the current %Float instance.
 223          *
 224          *      @since          2.0
 225          *
 226          *      @return         A @c signed @c int equivalent of the current instance
 227          */
 228         virtual int ToInt(void) const;
 229
 230         /**
 231          *      Gets the @c signed @c long equivalent of the current %Float instance.
 232          *
 233          *      @since          2.0
 234          *
 235          *      @return         A @c signed @c long equivalent of the current instance
 236          */
 237         virtual long ToLong(void) const;
 238
 239         /**
 240          * Gets the @c signed @c long @c long equivalent of the current %Float instance.
 241          *
 242          * @since               2.0
 243          *
 244          * @return      A @c signed @c long @c long equivalent of the current instance
 245          */
 246         virtual long long ToLongLong(void) const;
 247
 248         /**
 249          *      Gets the @c signed @c float equivalent of the current %Float instance.
 250          *
 251          *      @since          2.0
 252          *
 253          *      @return         A @c signed @c float equivalent of the current instance
 254          */
 255         virtual float ToFloat(void) const;
 256
 257         /**
 258          *      Gets the @c signed @c double equivalent of the current %Float instance.
 259          *
 260          *      @since          2.0
 261          *
 262          *      @return         A @c signed @c double equivalent of the current instance
 263          */
 264         virtual double ToDouble(void) const;
 265
 266         /**
 267          * Gets the string representing the value of the current %Float instance.
 268          *
 269          * @since                       2.0
 270          *
 271          * @return              A string containing a Unicode representation of the value of the current instance value
 272          * @remarks
 273          *                              - If the value is Not-a-Number (NaN), the result is the string "NaN". Furthermore, infinity
 274          *                              produces the result "Infinity". @n
 275          *                              6 digits are given for the precision of this method. Use Float::ToString(int precision) to set the specific precision.
 276          *                              - The behavior of this method is dependent on the system default locale setting.
 277          */
 278         virtual String ToString(void) const;
 279
 280         /**
 281          * Gets the string representing the value of the current %Float instance.
 282          *
 283          * @since 3.0
 284          *
 285          * @param[in]   precision       Number of digits after a decimal separator
 286          * @return              A string containing a Unicode representation of the value of the current instance value
 287          * @remarks
 288          *                              - If the value of the current instance is Not-a-Number (NaN), the result is the string "NaN". Furthermore, infinity
 289          *                              produces the result "Infinity". @n
 290          *                              - The behavior of this method is dependent on the system default locale setting.
 291          *
 292          * @code
 293          *
 294          *      Float flt(3.1416);
 295          *      String str1 = flt.ToString(3);
 296          *      // str1 contains "3.142"
 297          *
 298          *      String str2 = flt.ToString(2);
 299          *      // str2 contains "3.14"
 300          *
 301          * @endcode
 302          */
 303         virtual String ToString(int precision) const;
 304
 305         /**
 306          *      Gets the string representing the specified @c float value.
 307          *
 308          *      @since          2.0
 309          *
 310          *      @return         A string containing a Unicode representation of the specified @c float value
 311          *      @param[in]      value   A @c float value to convert
 312          *  @remarks
 313          *                              - If the value is Not-a-Number (NaN), the result is the string "NaN". Furthermore, infinity
 314          *                              produces the result "Infinity". @n
 315          *                              6 digits are given for the precision of this method. Use Float::ToString(float value, int precision) to set the specific precision.
 316          *                              - The behavior of this method is dependent on the system default locale setting.
 317          */
 318         static String ToString(float value);
 319
 320         /**
 321          * Gets the string representing the specified @c float value.
 322          *
 323          * @since               3.0
 324          *
 325          * @return              A string containing a Unicode representation of the specified @c float value
 326          * @param[in]   value   A @c float value to convert
 327          * @param[in]   precision       Number of digits after a decimal separator
 328          * @remarks
 329          *                              - If the value is Not-a-Number (NaN), the result is the string "NaN". Furthermore, infinity
 330          *                              produces the result "Infinity". @n
 331          *                              - The behavior of this method is dependent on the system default locale setting.
 332          *
 333          * @code
 334          *
 335          *      String str1 = Float::ToString(3.1416f, 3);
 336          *      // str1 contains "3.142"
 337          *
 338          *      String str2 = Float::ToString(3.1416f, 2);
 339          *      // str2 contains "3.14"
 340          *
 341          * @endcode
 342          */
 343         static String ToString(float value, int precision);
 344
 345
 346         /**
 347          *      Gets the IEEE 754 floating-point "single format" bit layout representation of the specified @c float value.
 348          *
 349          *      @since          2.0
 350          *
 351          *      @return         The bits that represent the floating-point number in the IEEE 754 floating-point "single format" bit layout
 352          *      @param[in]      value   A @c float value to convert
 353          *      @see            Tizen::Base::Double::Parse()
 354          */
 355         static int ToBits(float value);
 356
 357         /**
 358          *      Gets the @c float value corresponding to the specified floating-point value in the IEEE 754 floating-point "single format" bit layout.
 359          *
 360          *      @since          2.0
 361          *
 362          *      @return         The @c float floating-point value with the same bit pattern
 363          *      @param[in]      value   A floating-point value in the IEEE 754 floating-point "single format" bit layout
 364          *      @see            Tizen::Base::Double::Parse()
 365          */
 366         static float ToFloatFromBits(int value);
 367
 368         /**
 369          *      Checks whether the current value of %Float is equal to negative or positive infinity.
 370          *
 371          *      @since          2.0
 372          *
 373          *      @return         @c true if the current value equals negative or positive infinity, @n
 374          *                              else @c false
 375          */
 376         bool IsInfinity(void) const;
 377
 378         /**
 379          *      Checks whether the specified @c float value is equal to negative or positive infinity.
 380          *
 381          *      @since          2.0
 382          *
 383          *      @return         @c true if the specified value equals negative or positive infinity, @n
 384          *                              else @c false
 385          *      @param[in]      value   A @c float value to check
 386          */
 387         static bool IsInfinity(float value);
 388
 389         /**
 390          *      Checks whether the current value is Not-a-Number.
 391          *
 392          *      @since          2.0
 393          *
 394          *      @return         @c true if the current value is Not-a-Number, @n
 395          *                              else @c false
 396          */
 397         bool IsNaN(void) const;
 398
 399         /**
 400          *      Checks whether the specified value is Not-a-Number.
 401          *
 402          *      @since          2.0
 403          *
 404          *      @return         @c true if the specified value is Not-a-Number, @n
 405          *                              else @c false
 406          *      @param[in]      value   A @c float value to check
 407          */
 408         static bool IsNaN(float value);
 409
 410         /**
 411          *      Gets a constant holding the largest positive finite value of type @c float. @n
 412          *      This is equal to the value defined in Limit.h of the C library.
 413          *
 414          *      @since          2.0
 415          *
 416          *      @return         A constant holding the largest positive finite value of type @c float
 417          */
 418         static float GetMaxValue(void);
 419
 420         /**
 421          *      Gets a constant holding the smallest positive non-zero value of type @c float. @n
 422          *      This is equal to the value defined in Limit.h of the C library.
 423          *
 424          *      @since          2.0
 425          *
 426          *      @return         A constant holding the smallest possible non-zero value of type @c float
 427          */
 428         static float GetMinValue(void);
 429
 430         /**
 431          * A @c float value of this instance.
 432          *
 433          * @since       2.0
 434          */
 435         float value;
 436
 437
 438 private:
 439         /**
 440          *      Checks if the specified @c float value is finite.
 441          *
 442          *      @since          2.0
 443          *
 444          *      @return         @c true if the specified value is finite, @n
 445          *                              else @c false
 446          *      @param[in]      value   A @c float value to check
 447          */
 448         static bool IsFinite(float value);
 449
 450         static const int __DBL_MAX_10_EXP = 308;
 451
 452         friend class _FloatImpl;
 453         class _FloatImpl* __pFloatImpl;
 454
 455 }; // Float
 456
 457 }} // Tizen::Base
 458
 459 #endif //_FBASE_FLOAT_H_