juce/source/src/core/juce_RelativeTime.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_RELATIVETIME_JUCEHEADER__
  27 #define __JUCE_RELATIVETIME_JUCEHEADER__
  28
  29 #include "../text/juce_String.h"
  30
  31
  32 //==============================================================================
  33 /** A relative measure of time.
  34
  35     The time is stored as a number of seconds, at double-precision floating
  36     point accuracy, and may be positive or negative.
  37
  38     If you need an absolute time, (i.e. a date + time), see the Time class.
  39 */
  40 class JUCE_API  RelativeTime
  41 {
  42 public:
  43     //==============================================================================
  44     /** Creates a RelativeTime.
  45
  46         @param seconds  the number of seconds, which may be +ve or -ve.
  47         @see milliseconds, minutes, hours, days, weeks
  48     */
  49     explicit RelativeTime (double seconds = 0.0) noexcept;
  50
  51     /** Copies another relative time. */
  52     RelativeTime (const RelativeTime& other) noexcept;
  53
  54     /** Copies another relative time. */
  55     RelativeTime& operator= (const RelativeTime& other) noexcept;
  56
  57     /** Destructor. */
  58     ~RelativeTime() noexcept;
  59
  60     //==============================================================================
  61     /** Creates a new RelativeTime object representing a number of milliseconds.
  62         @see minutes, hours, days, weeks
  63     */
  64     static const RelativeTime milliseconds (int milliseconds) noexcept;
  65
  66     /** Creates a new RelativeTime object representing a number of milliseconds.
  67         @see minutes, hours, days, weeks
  68     */
  69     static const RelativeTime milliseconds (int64 milliseconds) noexcept;
  70
  71     /** Creates a new RelativeTime object representing a number of minutes.
  72         @see milliseconds, hours, days, weeks
  73     */
  74     static const RelativeTime minutes (double numberOfMinutes) noexcept;
  75
  76     /** Creates a new RelativeTime object representing a number of hours.
  77         @see milliseconds, minutes, days, weeks
  78     */
  79     static const RelativeTime hours (double numberOfHours) noexcept;
  80
  81     /** Creates a new RelativeTime object representing a number of days.
  82         @see milliseconds, minutes, hours, weeks
  83     */
  84     static const RelativeTime days (double numberOfDays) noexcept;
  85
  86     /** Creates a new RelativeTime object representing a number of weeks.
  87         @see milliseconds, minutes, hours, days
  88     */
  89     static const RelativeTime weeks (double numberOfWeeks) noexcept;
  90
  91     //==============================================================================
  92     /** Returns the number of milliseconds this time represents.
  93         @see milliseconds, inSeconds, inMinutes, inHours, inDays, inWeeks
  94     */
  95     int64 inMilliseconds() const noexcept;
  96
  97     /** Returns the number of seconds this time represents.
  98         @see inMilliseconds, inMinutes, inHours, inDays, inWeeks
  99     */
 100     double inSeconds() const noexcept       { return seconds; }
 101
 102     /** Returns the number of minutes this time represents.
 103         @see inMilliseconds, inSeconds, inHours, inDays, inWeeks
 104     */
 105     double inMinutes() const noexcept;
 106
 107     /** Returns the number of hours this time represents.
 108         @see inMilliseconds, inSeconds, inMinutes, inDays, inWeeks
 109     */
 110     double inHours() const noexcept;
 111
 112     /** Returns the number of days this time represents.
 113         @see inMilliseconds, inSeconds, inMinutes, inHours, inWeeks
 114     */
 115     double inDays() const noexcept;
 116
 117     /** Returns the number of weeks this time represents.
 118         @see inMilliseconds, inSeconds, inMinutes, inHours, inDays
 119     */
 120     double inWeeks() const noexcept;
 121
 122     /** Returns a readable textual description of the time.
 123
 124         The exact format of the string returned will depend on
 125         the magnitude of the time - e.g.
 126
 127         "1 min 4 secs", "1 hr 45 mins", "2 weeks 5 days", "140 ms"
 128
 129         so that only the two most significant units are printed.
 130
 131         The returnValueForZeroTime value is the result that is returned if the
 132         length is zero. Depending on your application you might want to use this
 133         to return something more relevant like "empty" or "0 secs", etc.
 134
 135         @see inMilliseconds, inSeconds, inMinutes, inHours, inDays, inWeeks
 136     */
 137     String getDescription (const String& returnValueForZeroTime = "0") const;
 138
 139
 140     //==============================================================================
 141     /** Adds another RelativeTime to this one. */
 142     const RelativeTime& operator+= (const RelativeTime& timeToAdd) noexcept;
 143     /** Subtracts another RelativeTime from this one. */
 144     const RelativeTime& operator-= (const RelativeTime& timeToSubtract) noexcept;
 145
 146     /** Adds a number of seconds to this time. */
 147     const RelativeTime& operator+= (double secondsToAdd) noexcept;
 148     /** Subtracts a number of seconds from this time. */
 149     const RelativeTime& operator-= (double secondsToSubtract) noexcept;
 150
 151 private:
 152     //==============================================================================
 153     double seconds;
 154 };
 155
 156 //==============================================================================
 157 /** Compares two RelativeTimes. */
 158 bool operator== (const RelativeTime& t1, const RelativeTime& t2) noexcept;
 159 /** Compares two RelativeTimes. */
 160 bool operator!= (const RelativeTime& t1, const RelativeTime& t2) noexcept;
 161 /** Compares two RelativeTimes. */
 162 bool operator>  (const RelativeTime& t1, const RelativeTime& t2) noexcept;
 163 /** Compares two RelativeTimes. */
 164 bool operator<  (const RelativeTime& t1, const RelativeTime& t2) noexcept;
 165 /** Compares two RelativeTimes. */
 166 bool operator>= (const RelativeTime& t1, const RelativeTime& t2) noexcept;
 167 /** Compares two RelativeTimes. */
 168 bool operator<= (const RelativeTime& t1, const RelativeTime& t2) noexcept;
 169
 170 //==============================================================================
 171 /** Adds two RelativeTimes together. */
 172 RelativeTime  operator+  (const RelativeTime&  t1, const RelativeTime& t2) noexcept;
 173 /** Subtracts two RelativeTimes. */
 174 RelativeTime  operator-  (const RelativeTime&  t1, const RelativeTime& t2) noexcept;
 175
 176
 177
 178 #endif   // __JUCE_RELATIVETIME_JUCEHEADER__