1 // Written in the D programming language
2 
3 /++
4     $(SCRIPT inhibitQuickIndex = 1;)
5 
6     Phobos provides the following functionality for time:
7 
8     $(DIVC quickindex,
9     $(BOOKTABLE ,
10     $(TR $(TH Functionality) $(TH Symbols)
11     )
12     $(TR
13         $(TD Points in Time)
14         $(TD
15             $(REF_ALTTEXT Date, Date, std, datetime, date)$(NBSP)
16             $(REF_ALTTEXT TimeOfDay, TimeOfDay, std, datetime, date)$(NBSP)
17             $(REF_ALTTEXT DateTime, DateTime, std, datetime, date)$(NBSP)
18             $(REF_ALTTEXT SysTime, SysTime, std, datetime, systime)$(NBSP)
19         )
20     )
21     $(TR
22         $(TD Timezones)
23         $(TD
24             $(REF_ALTTEXT TimeZone, TimeZone, std, datetime, timezone)$(NBSP)
25             $(REF_ALTTEXT UTC, UTC, std, datetime, timezone)$(NBSP)
26             $(REF_ALTTEXT LocalTime, LocalTime, std, datetime, timezone)$(NBSP)
27             $(REF_ALTTEXT PosixTimeZone, PosixTimeZone, std, datetime, timezone)$(NBSP)
28             $(REF_ALTTEXT WindowsTimeZone, WindowsTimeZone, std, datetime, timezone)$(NBSP)
29             $(REF_ALTTEXT SimpleTimeZone, SimpleTimeZone, std, datetime, timezone)$(NBSP)
30         )
31     )
32     $(TR
33         $(TD Intervals and Ranges of Time)
34         $(TD
35             $(REF_ALTTEXT Interval, Interval, std, datetime, interval)$(NBSP)
36             $(REF_ALTTEXT PosInfInterval, PosInfInterval, std, datetime, interval)$(NBSP)
37             $(REF_ALTTEXT NegInfInterval, NegInfInterval, std, datetime, interval)$(NBSP)
38         )
39     )
40     $(TR
41         $(TD Durations of Time)
42         $(TD
43             $(REF_ALTTEXT Duration, Duration, core, time)$(NBSP)
44             $(REF_ALTTEXT weeks, weeks, core, time)$(NBSP)
45             $(REF_ALTTEXT days, days, core, time)$(NBSP)
46             $(REF_ALTTEXT hours, hours, core, time)$(NBSP)
47             $(REF_ALTTEXT minutes, minutes, core, time)$(NBSP)
48             $(REF_ALTTEXT seconds, seconds, core, time)$(NBSP)
49             $(REF_ALTTEXT msecs, msecs, core, time)$(NBSP)
50             $(REF_ALTTEXT usecs, usecs, core, time)$(NBSP)
51             $(REF_ALTTEXT hnsecs, hnsecs, core, time)$(NBSP)
52             $(REF_ALTTEXT nsecs, nsecs, core, time)$(NBSP)
53         )
54     )
55     $(TR
56         $(TD Time Measurement and Benchmarking)
57         $(TD
58             $(REF_ALTTEXT MonoTime, MonoTime, core, time)$(NBSP)
59             $(REF_ALTTEXT StopWatch, StopWatch, std, datetime, stopwatch)$(NBSP)
60             $(REF_ALTTEXT benchmark, benchmark, std, datetime, stopwatch)$(NBSP)
61         )
62     )
63     ))
64 
65     This functionality is separated into the following modules
66 
67     $(UL
68         $(LI $(MREF std, datetime, date) for points in time without timezones.)
69         $(LI $(MREF std, datetime, timezone) for classes which represent timezones.)
70         $(LI $(MREF std, datetime, systime) for a point in time with a timezone.)
71         $(LI $(MREF std, datetime, interval) for types which represent series of points in time.)
72         $(LI $(MREF std, datetime, stopwatch) for measuring time.)
73     )
74 
75     See_Also:
76         $(DDLINK intro-to-datetime, Introduction to std.datetime,
77                  Introduction to std&#46;datetime)<br>
78         $(HTTP en.wikipedia.org/wiki/ISO_8601, ISO 8601)<br>
79         $(HTTP en.wikipedia.org/wiki/Tz_database,
80               Wikipedia entry on TZ Database)<br>
81         $(HTTP en.wikipedia.org/wiki/List_of_tz_database_time_zones,
82               List of Time Zones)<br>
83 
84     License:   $(HTTP www.boost.org/LICENSE_1_0.txt, Boost License 1.0).
85     Authors:   $(HTTP jmdavisprog.com, Jonathan M Davis) and Kato Shoichi
86     Source:    $(PHOBOSSRC std/datetime/package.d)
87 +/
88 module std.datetime;
89 
90 /// Get the current time from the system clock
91 @safe unittest
92 {
93     import std.datetime.systime : SysTime, Clock;
94 
95     SysTime currentTime = Clock.currTime();
96 }
97 
98 /**
99 Construct a specific point in time without timezone information
100 and get its ISO string.
101  */
102 @safe unittest
103 {
104     import std.datetime.date : DateTime;
105 
106     auto dt = DateTime(2018, 1, 1, 12, 30, 10);
107     assert(dt.toISOString() == "20180101T123010");
108     assert(dt.toISOExtString() == "2018-01-01T12:30:10");
109 }
110 
111 /**
112 Construct a specific point in time in the UTC timezone and
113 add two days.
114  */
115 @safe unittest
116 {
117     import std.datetime.systime : SysTime;
118     import std.datetime.timezone : UTC;
119     import core.time : days;
120 
121     auto st = SysTime(DateTime(2018, 1, 1, 12, 30, 10), UTC());
122     assert(st.toISOExtString() == "2018-01-01T12:30:10Z");
123     st += 2.days;
124     assert(st.toISOExtString() == "2018-01-03T12:30:10Z");
125 }
126 
127 public import core.time;
128 public import std.datetime.date;
129 public import std.datetime.interval;
130 public import std.datetime.systime;
131 public import std.datetime.timezone;
132 
133 import core.exception : AssertError;
134 import std.functional : unaryFun;
135 import std.traits;
136 import std.typecons : Flag, Yes, No;
137 
138 
139 // Verify module example.
140 @safe unittest
141 {
142     auto currentTime = Clock.currTime();
143     auto timeString = currentTime.toISOExtString();
144     auto restoredTime = SysTime.fromISOExtString(timeString);
145 }
146 
147 // Verify Examples for core.time.Duration which couldn't be in core.time.
148 @safe unittest
149 {
150     assert(std.datetime.Date(2010, 9, 7) + dur!"days"(5) ==
151            std.datetime.Date(2010, 9, 12));
152 
153     assert(std.datetime.Date(2010, 9, 7) - std.datetime.Date(2010, 10, 3) ==
154            dur!"days"(-26));
155 }
156 
157 @safe unittest
158 {
159     import std.traits : hasUnsharedAliasing;
160     /* https://issues.dlang.org/show_bug.cgi?id=6642 */
161     static assert(!hasUnsharedAliasing!Date);
162     static assert(!hasUnsharedAliasing!TimeOfDay);
163     static assert(!hasUnsharedAliasing!DateTime);
164     static assert(!hasUnsharedAliasing!SysTime);
165 }