1 /*
2   ==============================================================================
3 
4    This file is part of the Water library.
5    Copyright (c) 2016 ROLI Ltd.
6    Copyright (C) 2017 Filipe Coelho <falktx@falktx.com>
7 
8    Permission is granted to use this software under the terms of the ISC license
9    http://www.isc.org/downloads/software-support-policy/isc-license/
10 
11    Permission to use, copy, modify, and/or distribute this software for any
12    purpose with or without fee is hereby granted, provided that the above
13    copyright notice and this permission notice appear in all copies.
14 
15    THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH REGARD
16    TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
17    FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT,
18    OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
19    USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
20    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
21    OF THIS SOFTWARE.
22 
23   ==============================================================================
24 */
25 
26 #ifndef WATER_TIME_H_INCLUDED
27 #define WATER_TIME_H_INCLUDED
28 
29 #include "../water.h"
30 
31 namespace water {
32 
33 //==============================================================================
34 /**
35     Holds an absolute date and time.
36 
37     Internally, the time is stored at millisecond precision.
38 
39     @see RelativeTime
40 */
41 class Time
42 {
43 public:
44     //==============================================================================
45     /** Creates a Time object.
46 
47         This default constructor creates a time of midnight Jan 1st 1970 UTC, (which is
48         represented internally as 0ms).
49 
50         To create a time object representing the current time, use getCurrentTime().
51 
52         @see getCurrentTime
53     */
54     Time() noexcept;
55 
56     /** Creates a time based on a number of milliseconds.
57 
58         To create a time object set to the current time, use getCurrentTime().
59 
60         @param millisecondsSinceEpoch   the number of milliseconds since the unix
61                                         'epoch' (midnight Jan 1st 1970 UTC).
62         @see getCurrentTime, currentTimeMillis
63     */
64     explicit Time (int64 millisecondsSinceEpoch) noexcept;
65 
66     /** Creates a copy of another Time object. */
67     Time (const Time& other) noexcept;
68 
69     /** Destructor. */
70     ~Time() noexcept;
71 
72     /** Copies this time from another one. */
73     Time& operator= (const Time& other) noexcept;
74 
75     //==============================================================================
76     /** Returns a Time object that is set to the current system time.
77 
78         This may not be monotonic, as the system time can change at any moment.
79         You should therefore not use this method for measuring time intervals.
80 
81         @see currentTimeMillis
82     */
83     static Time getCurrentTime() noexcept;
84 
85     //==============================================================================
86     // Static methods for getting system timers directly..
87 
88     /** Returns the current system time.
89 
90         Returns the number of milliseconds since midnight Jan 1st 1970 UTC.
91 
92         Should be accurate to within a few millisecs, depending on platform,
93         hardware, etc.
94     */
95     static int64 currentTimeMillis() noexcept;
96 
97     /** Returns the number of millisecs since a fixed event (usually system startup).
98 
99         This returns a monotonically increasing value which it unaffected by changes to the
100         system clock. It should be accurate to within a few millisecs, depending on platform,
101         hardware, etc.
102 
103         Being a 32-bit return value, it will of course wrap back to 0 after 2^32 seconds of
104         uptime, so be careful to take that into account. If you need a 64-bit time, you can
105         use currentTimeMillis() instead.
106     */
107     static uint32 getMillisecondCounter() noexcept;
108 
109 private:
110     //==============================================================================
111     int64 millisSinceEpoch;
112 };
113 
114 }
115 
116 #endif // WATER_TIME_H_INCLUDED
117