source/modules/juce_core/time/juce_RelativeTime.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library.
   5    Copyright (c) 2022 - Raw Material Software Limited
   6
   7    JUCE is an open source library subject to commercial or open-source
   8    licensing.
   9
  10    The code included in this file is provided under the terms of the ISC license
  11    http://www.isc.org/downloads/software-support-policy/isc-license. Permission
  12    To use, copy, modify, and/or distribute this software for any purpose with or
  13    without fee is hereby granted provided that the above copyright notice and
  14    this permission notice appear in all copies.
  15
  16    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  17    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  18    DISCLAIMED.
  19
  20   ==============================================================================
  21 */
  22
  23 namespace juce
  24 {
  25
  26 //==============================================================================
  27 /** A relative measure of time.
  28
  29     The time is stored as a number of seconds, at double-precision floating
  30     point accuracy, and may be positive or negative.
  31
  32     If you need an absolute time, (i.e. a date + time), see the Time class.
  33
  34     @tags{Core}
  35 */
  36 class JUCE_API  RelativeTime
  37 {
  38 public:
  39     //==============================================================================
  40     /** Creates a RelativeTime.
  41
  42         @param seconds  the number of seconds, which may be +ve or -ve.
  43         @see milliseconds, minutes, hours, days, weeks
  44     */
  45     explicit RelativeTime (double seconds = 0.0) noexcept;
  46
  47     /** Copies another relative time. */
  48     RelativeTime (const RelativeTime& other) noexcept;
  49
  50     /** Copies another relative time. */
  51     RelativeTime& operator= (const RelativeTime& other) noexcept;
  52
  53     /** Destructor. */
  54     ~RelativeTime() noexcept;
  55
  56     //==============================================================================
  57     /** Creates a new RelativeTime object representing a number of milliseconds.
  58         @see seconds, minutes, hours, days, weeks
  59     */
  60     static RelativeTime milliseconds (int milliseconds) noexcept;
  61
  62     /** Creates a new RelativeTime object representing a number of milliseconds.
  63         @see seconds, minutes, hours, days, weeks
  64     */
  65     static RelativeTime milliseconds (int64 milliseconds) noexcept;
  66
  67     /** Creates a new RelativeTime object representing a number of seconds.
  68         @see milliseconds, minutes, hours, days, weeks
  69     */
  70     static RelativeTime seconds (double seconds) noexcept;
  71
  72     /** Creates a new RelativeTime object representing a number of minutes.
  73         @see milliseconds, hours, days, weeks
  74     */
  75     static RelativeTime minutes (double numberOfMinutes) noexcept;
  76
  77     /** Creates a new RelativeTime object representing a number of hours.
  78         @see milliseconds, minutes, days, weeks
  79     */
  80     static RelativeTime hours (double numberOfHours) noexcept;
  81
  82     /** Creates a new RelativeTime object representing a number of days.
  83         @see milliseconds, minutes, hours, weeks
  84     */
  85     static RelativeTime days (double numberOfDays) noexcept;
  86
  87     /** Creates a new RelativeTime object representing a number of weeks.
  88         @see milliseconds, minutes, hours, days
  89     */
  90     static RelativeTime weeks (double numberOfWeeks) noexcept;
  91
  92     //==============================================================================
  93     /** Returns the number of milliseconds this time represents.
  94         @see milliseconds, inSeconds, inMinutes, inHours, inDays, inWeeks
  95     */
  96     int64 inMilliseconds() const noexcept;
  97
  98     /** Returns the number of seconds this time represents.
  99         @see inMilliseconds, inMinutes, inHours, inDays, inWeeks
 100     */
 101     double inSeconds() const noexcept       { return numSeconds; }
 102
 103     /** Returns the number of minutes this time represents.
 104         @see inMilliseconds, inSeconds, inHours, inDays, inWeeks
 105     */
 106     double inMinutes() const noexcept;
 107
 108     /** Returns the number of hours this time represents.
 109         @see inMilliseconds, inSeconds, inMinutes, inDays, inWeeks
 110     */
 111     double inHours() const noexcept;
 112
 113     /** Returns the number of days this time represents.
 114         @see inMilliseconds, inSeconds, inMinutes, inHours, inWeeks
 115     */
 116     double inDays() const noexcept;
 117
 118     /** Returns the number of weeks this time represents.
 119         @see inMilliseconds, inSeconds, inMinutes, inHours, inDays
 120     */
 121     double inWeeks() const noexcept;
 122
 123     /** Returns a readable textual description of the time.
 124
 125         The exact format of the string returned will depend on
 126         the magnitude of the time - e.g.
 127
 128         "1 min 4 secs", "1 hr 45 mins", "2 weeks 5 days", "140 ms"
 129
 130         so that only the two most significant units are printed.
 131
 132         The returnValueForZeroTime value is the result that is returned if the
 133         length is zero. Depending on your application you might want to use this
 134         to return something more relevant like "empty" or "0 secs", etc.
 135
 136         @see inMilliseconds, inSeconds, inMinutes, inHours, inDays, inWeeks
 137     */
 138     String getDescription (const String& returnValueForZeroTime = "0") const;
 139
 140     //==============================================================================
 141     /** This returns a string that roughly describes how long ago this time was, which
 142         can be handy for showing ages of files, etc.
 143         This will only attempt to be accurate to within the nearest order of magnitude
 144         so returns strings such as "5 years", "2 weeks", "< 1 minute", "< 1 sec" etc.
 145     */
 146     String getApproximateDescription() const;
 147
 148     //==============================================================================
 149     /** Adds another RelativeTime to this one. */
 150     RelativeTime operator+= (RelativeTime timeToAdd) noexcept;
 151     /** Subtracts another RelativeTime from this one. */
 152     RelativeTime operator-= (RelativeTime timeToSubtract) noexcept;
 153
 154     /** Adds a number of seconds to this time. */
 155     RelativeTime operator+= (double secondsToAdd) noexcept;
 156     /** Subtracts a number of seconds from this time. */
 157     RelativeTime operator-= (double secondsToSubtract) noexcept;
 158
 159 private:
 160     //==============================================================================
 161     double numSeconds;
 162 };
 163
 164 //==============================================================================
 165 /** Compares two RelativeTimes. */
 166 JUCE_API bool JUCE_CALLTYPE operator== (RelativeTime t1, RelativeTime t2) noexcept;
 167 /** Compares two RelativeTimes. */
 168 JUCE_API bool JUCE_CALLTYPE operator!= (RelativeTime t1, RelativeTime t2) noexcept;
 169 /** Compares two RelativeTimes. */
 170 JUCE_API bool JUCE_CALLTYPE operator>  (RelativeTime t1, RelativeTime t2) noexcept;
 171 /** Compares two RelativeTimes. */
 172 JUCE_API bool JUCE_CALLTYPE operator<  (RelativeTime t1, RelativeTime t2) noexcept;
 173 /** Compares two RelativeTimes. */
 174 JUCE_API bool JUCE_CALLTYPE operator>= (RelativeTime t1, RelativeTime t2) noexcept;
 175 /** Compares two RelativeTimes. */
 176 JUCE_API bool JUCE_CALLTYPE operator<= (RelativeTime t1, RelativeTime t2) noexcept;
 177
 178 //==============================================================================
 179 /** Adds two RelativeTimes together. */
 180 JUCE_API RelativeTime  JUCE_CALLTYPE operator+  (RelativeTime t1, RelativeTime t2) noexcept;
 181 /** Subtracts two RelativeTimes. */
 182 JUCE_API RelativeTime  JUCE_CALLTYPE operator-  (RelativeTime t1, RelativeTime t2) noexcept;
 183
 184 } // namespace juce