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