inc/FBaseTimeSpan.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                FBaseTimeSpan.h
  20  * @brief               This is the header file for the %TimeSpan class.
  21  *
  22  * This header file contains the declarations of the %TimeSpan class.
  23  */
  24 #ifndef _FBASE_TIME_SPAN_H_
  25 #define _FBASE_TIME_SPAN_H_
  26
  27 #include <FBaseTypes.h>
  28 #include <FBaseObject.h>
  29
  30
  31 namespace Tizen { namespace Base
  32 {
  33 /**
  34  *      @class  TimeSpan
  35  *      @brief  This class represents a time interval.
  36  *
  37  *      @since 2.0
  38  *
  39  *      The %TimeSpan class represents a time interval. An instance of %TimeSpan represents a period of time measured in ticks. A tick is the smallest
  40  *      unit of time used by the platform or system. In %Tizen, it is a millisecond.
  41  *
  42  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/datetime_timespan.htm">DateTime and TimeSpan</a>.
  43  *
  44  *      The following example demonstrates how to use the %TimeSpan class.
  45  *      @code
  46  *
  47  *      #include <FBase.h>
  48  *
  49  *      using namespace Tizen::Base;
  50  *
  51  *      void
  52  *      MyClass::TimeSpanSample(void)
  53  *      {
  54  *              TimeSpan span1(1, 1, 1);        // one hour + one minute + one second
  55  *              TimeSpan span2(1, 23, 70, 100); // 1 days + 23 hours + 70 minutes + 100 seconds
  56  *
  57  *              if (span2 > span1)
  58  *              {
  59  *                      TimeSpan span3 = (span2 - span1);
  60  *                      if (TimeSpan::Compare(span1, span3) == 0)
  61  *                      {
  62  *                              // ...
  63  *                      }
  64  *              }
  65  *
  66  *
  67  *              long long days, hours, minutes, seconds;
  68  *
  69  *              days = span2.GetDays();                         // 2 days
  70  *              hours = span2.GetHours();                       // 0 hours
  71  *              minutes = span2.GetMinutes();           // 11 minutes
  72  *              seconds = span2.GetSeconds();           // 40 seconds
  73  *
  74  *      }
  75  *      @endcode
  76  */
  77 class _OSP_EXPORT_ TimeSpan
  78         : public Object
  79 {
  80 public:
  81         /**
  82          * Copying of objects using this copy constructor is allowed.
  83          *
  84          * @since 2.0
  85          *
  86          * @param[in] value             An instance of %TimeSpan to copy
  87          */
  88         TimeSpan(const TimeSpan& value);
  89
  90
  91         /**
  92          * Initializes an instance of %TimeSpan with the specified parameters.
  93          *
  94          * @since 2.0
  95          *
  96          * @param[in]   hours   The number of hours
  97          * @param[in]   minutes The number of minutes
  98          * @param[in]   seconds The number of seconds
  99          */
 100         TimeSpan(int hours, int minutes, int seconds);
 101
 102
 103         /**
 104          * Initializes an instance of %TimeSpan with the specified parameters.
 105          *
 106          * @since 2.0
 107          *
 108          * @param[in]   days    The number of days
 109          * @param[in]   hours   The number of hours
 110          * @param[in]   minutes The number of minutes
 111          * @param[in]   seconds The number of seconds
 112          */
 113         TimeSpan(int days, int hours, int minutes, int seconds);
 114
 115
 116         /**
 117          * Initializes an instance of %TimeSpan with the specified parameters.
 118          *
 119          * @since 2.0
 120          *
 121          * @param[in]   days                    The number of days
 122          * @param[in]   hours                   The number of hours
 123          * @param[in]   minutes                 The number of minutes
 124          * @param[in]   seconds                 The number of seconds
 125          * @param[in]   milliseconds    The number of milliseconds
 126          */
 127         TimeSpan(int days, int hours, int minutes, int seconds, int milliseconds);
 128
 129
 130         /**
 131          * Initializes an instance of %TimeSpan with the specified number of ticks.
 132          *
 133          * @since 2.0
 134          *
 135          * @param[in]   ticks   The number of ticks (in milliseconds)
 136          */
 137         TimeSpan(long long ticks);
 138
 139         /**
 140          * This destructor overrides Tizen::Base::Object::~Object().
 141          *
 142          * @since 2.0
 143          */
 144         virtual ~TimeSpan(void);
 145
 146         /**
 147          * Adds the values of the two instances of %TimeSpan.
 148          *
 149          * @since 2.0
 150          *
 151          * @return              An instance of %TimeSpan
 152          * @param[in]   rhs     An instance of %TimeSpan to add
 153          */
 154         TimeSpan operator +(const TimeSpan& rhs) const;
 155
 156         /**
 157          * Subtracts the values of the two instances of %TimeSpan.
 158          *
 159          * @since 2.0
 160          *
 161          * @return              An instance of %TimeSpan
 162          * @param[in]   rhs     An instance of %TimeSpan to subtract
 163          */
 164         TimeSpan operator -(const TimeSpan& rhs) const;
 165
 166         /**
 167          * Copying of objects using this copy assignment operator is allowed.
 168          *
 169          * @since 2.0
 170          *
 171          * @return              A reference to the current instance of %TimeSpan
 172          * @param[in]   rhs     An instance of %TimeSpan
 173          */
 174         TimeSpan& operator =(const TimeSpan& rhs);
 175
 176         /**
 177          * Checks whether the value of this instance is equal to the value of the
 178          * specified instance of %TimeSpan.
 179          *
 180          * @since 2.0
 181          *
 182          * @return              @c true if the two values are equal, @n
 183          *                              else @c false
 184          * @param[in]   rhs     An instance of %TimeSpan to compare
 185          */
 186         bool operator ==(const TimeSpan& rhs) const;
 187
 188         /**
 189          * Checks whether the value of this instance is not equal to
 190          * the value of the specified instance of %TimeSpan.
 191          *
 192          * @since 2.0
 193          *
 194          * @return              @c true if the two values are not equal, @n
 195          *                              else @c false
 196          * @param[in]   rhs     An instance of %TimeSpan to compare
 197          */
 198         bool operator !=(const TimeSpan& rhs) const;
 199
 200         /**
 201          * Checks whether the value of the calling instance is less than that of
 202          * the specified instance of %TimeSpan.
 203          *
 204          * @since 2.0
 205          *
 206          * @return              @c true if the value of the calling instance is less than that of the specified instance of %TimeSpan, @n
 207          *                              else @c false
 208          * @param[in]   rhs     An instance of %TimeSpan to compare
 209          */
 210         bool operator <(const TimeSpan& rhs) const;
 211
 212         /**
 213          * Checks whether the value of the calling instance is greater than that of
 214          * the specified instance of %TimeSpan.
 215          *
 216          * @since 2.0
 217          *
 218          * @return              @c true if the value of the calling instance is greater than that of the specified instance of %TimeSpan, @n
 219          *                              else @c false
 220          * @param[in]   rhs     An instance of %TimeSpan to compare
 221          */
 222         bool operator >(const TimeSpan& rhs) const;
 223
 224         /**
 225          * Checks whether the value of the calling instance is less than or equal to
 226          * the value of the specified instance of %TimeSpan.
 227          *
 228          * @since 2.0
 229          *
 230          * @return              @c true if the value of the calling instance is less than or equal to the value of the specified instance of %TimeSpan, @n
 231          *                              else @c false
 232          * @param[in]   rhs     An instance of %TimeSpan to compare
 233          */
 234         bool operator <=(const TimeSpan& rhs) const;
 235
 236         /**
 237          * Checks whether the value of the calling instance is greater than or equal to
 238          * the value of the specified instance of %TimeSpan.
 239          *
 240          * @since 2.0
 241          *
 242          * @return              @c true if the value of the calling instance is greater than or equal to the value of the specified instance of %TimeSpan, @n
 243          *                              else @c false
 244          * @param[in]   rhs     An instance of %TimeSpan to compare
 245          */
 246         bool operator >=(const TimeSpan& rhs) const;
 247
 248         /**
 249          * Compares the two specified instances of %TimeSpan.
 250          *
 251          * @since 2.0
 252          *
 253          * @return              A 32-bit @c signed integer value
 254          * @param[in]   t1      An instance of %TimeSpan to compare
 255          * @param[in]   t2      An instance of %TimeSpan to compare
 256          *
 257          * @code
 258          * <  0  if the value of @c t1 is less than the value of @c t2
 259          * == 0  if the value of @c t1 is equal to the value of @c t2
 260          * >  0  if the value of @c t1 is greater than the value of @c t2
 261          * @endcode
 262          */
 263         static int Compare(const TimeSpan& t1, const TimeSpan& t2);
 264
 265         /**
 266          * Compares the value of the calling instance to the value of the specified instance.
 267          *
 268          * @since 2.0
 269          *
 270          * @return              A 32-bit @c signed integer value
 271          * @param[in]   value   An instance of %TimeSpan to compare
 272          *
 273          * @code
 274          * <  0  if the value of the current instance is less than the value of @c obj
 275          * == 0  if the value of the current instance is equal to the value of @c obj
 276          * >  0  if the value of the current instance is greater than the value of @c obj
 277          * @endcode
 278          */
 279         int CompareTo(const TimeSpan& value) const;
 280
 281         /**
 282          * Checks whether the specified instance of Object is equal to the current instance of %TimeSpan.
 283          *
 284          * @since 2.0
 285          *
 286          * @return              @c true if the specified instance of Object is equal to the current instance of %TimeSpan, @n
 287          *                              else @c false
 288          * @param[in]   obj An instance of Object to compare
 289          * @see                 Tizen::Base::Object::GetHashCode()
 290          */
 291         virtual bool Equals(const Object& obj) const;
 292
 293         /**
 294          * Gets the absolute value of the calling instance.
 295          *
 296          *  @since 2.0
 297          *
 298          *      @return                 An instance of %TimeSpan containing the absolute value
 299          *      @remarks                This method is used to get absolute difference between two %TimeSpan instances.
 300          *
 301          *      @code
 302          *      TimeSpan t1(1000); // 1000 milliseconds
 303          *      TimeSpan t2(2000); // 2000 milliseconds
 304          *      TimeSpan t3 = t1 - t2; // t3 == -1000
 305          *      TimeSpan t4 = t3.Duration(); // t4 == 1000
 306          *      @endcode
 307          */
 308         TimeSpan Duration(void) const;
 309
 310         /**
 311          * Gets the hash value of the current instance.
 312          *
 313          * @since 2.0
 314          *
 315          * @return      The hash value of the current instance
 316          * @see                 Tizen::Base::Object::Equals()
 317          */
 318         virtual int GetHashCode(void) const;
 319
 320         /**
 321          * Gets the negative value of the calling instance.
 322          *
 323          * @since 2.0
 324          *
 325          * @return              An instance of %Timespan containing the negative value of the calling instance
 326          */
 327         TimeSpan Negate(void) const;
 328
 329         /**
 330          * Gets the number of whole days represented by the calling instance.
 331          *
 332          * @since 2.0
 333          *
 334          * @return              The number of whole days represented by the calling instance
 335          */
 336         long long GetDays(void) const;
 337
 338         /**
 339          * Gets the number of hours represented by the calling instance.
 340          *
 341          * @since 2.0
 342          *
 343          * @return              The number of hours represented by the calling instance
 344          */
 345         long long GetHours(void) const;
 346
 347         /**
 348          * Gets the number of minutes represented by the calling instance.
 349          *
 350          * @since 2.0
 351          *
 352          * @return              The number of minutes represented by the calling instance
 353          */
 354         long long GetMinutes(void) const;
 355
 356         /**
 357          * Gets the number of seconds represented by the calling instance.
 358          *
 359          * @since 2.0
 360          *
 361          * @return              The number of seconds represented by the calling instance
 362          */
 363         long long GetSeconds(void) const;
 364
 365         /**
 366          * Gets the number of milliseconds represented by the calling instance.
 367          *
 368          * @since 2.0
 369          *
 370          * @return              The number of milliseconds represented by the calling instance
 371          */
 372         long long GetMilliseconds(void) const;
 373
 374         /**
 375          * Gets the number of ticks represented by the calling instance.
 376          *
 377          * @since 2.0
 378          *
 379          * @return              The number of ticks represented by the calling instance
 380          */
 381         long long GetTicks(void) const;
 382
 383         /**
 384          * A constant holding the number of ticks in a day.
 385          *
 386          * @since 2.0
 387          */
 388         static const long long NUM_OF_TICKS_IN_DAY = 86400000LL;
 389
 390         /**
 391          * A constant holding the number of ticks in an hour.
 392          *
 393          * @since 2.0
 394          */
 395         static const long long NUM_OF_TICKS_IN_HOUR = 3600000LL;
 396
 397         /**
 398          * A constant holding the number of ticks in a minute.
 399          *
 400          * @since 2.0
 401          */
 402         static const long long NUM_OF_TICKS_IN_MINUTE = 60000LL;
 403
 404         /**
 405          * A constant holding the number of ticks in a second.
 406          *
 407          * @since 2.0
 408          */
 409         static const long long NUM_OF_TICKS_IN_SECOND = 1000LL;
 410
 411 private:
 412         //
 413         // Gets the numbers of ticks.
 414         // @return              The numbers of ticks
 415         // @param[in]   days                    The number of whole days
 416         // @param[in]   hours                   The number of hours
 417         // @param[in]   minutes                 The number of minutes
 418         // @param[in]   seconds                 The number of seconds
 419         // @param[in]   milliseconds    The number of milliseconds
 420         //
 421         static long long CalcTicks(int days, int hours, int minutes, int seconds, int milliseconds);
 422
 423         long long __ticks;
 424
 425         friend class _TimeSpanImpl;
 426         class _TimeSpanImpl * __pTimeSpanImpl;
 427
 428 }; // TimeSpan
 429
 430 }} // Tizen::Base
 431
 432 #endif //_FBASE_TIME_SPAN_H_