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+/
88module 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/**
99Construct a specific point in time without timezone information
100and 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/**
112Construct a specific point in time in the UTC timezone and
113add 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
127public import core.time;
128public import std.datetime.date;
129public import std.datetime.interval;
130public import std.datetime.systime;
131public import std.datetime.timezone;
132
133import core.exception : AssertError;
134import std.functional : unaryFun;
135import std.traits;
136import 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}
166