Skip to content

Commit 0d45880

Browse files
dlang-botdlang-bot
authored
Merge pull request #6356 from JackStouffer/datetime-docs
Simplified std.datetime.package overview merged-on-behalf-of: Jack Stouffer <jack@jackstouffer.com>
2 parents c1fcea4 + a737f62 commit 0d45880

File tree

1 file changed

+107
-92
lines changed

1 file changed

+107
-92
lines changed

‎std/datetime/package.d‎

Lines changed: 107 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,102 +1,80 @@
11
// Written in the D programming language
22

33
/++
4-
Module containing Date/Time functionality.
4+
$(SCRIPT inhibitQuickIndex = 1;)
55
6-
This module provides:
7-
$(UL
8-
$(LI Types to represent points in time:
9-
$(REF SysTime,std,_datetime,systime),
10-
$(REF Date,std,_datetime,date),
11-
$(REF TimeOfDay,std,_datetime,date),
12-
$(REF DateTime,std,_datetime,date).)
13-
$(LI Types to represent intervals of time.)
14-
$(LI Types to represent ranges over intervals of time.)
15-
$(LI Types to represent time zones (used by
16-
$(REF SysTime,std,_datetime,systime)).)
17-
$(LI A platform-independent, high precision stopwatch type:
18-
$(LREF StopWatch))
19-
$(LI Benchmarking functions.)
20-
$(LI Various helper functions.)
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+
)
2154
)
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
2266
23-
Closely related to std.datetime is <a href="core_time.html">`core.time`</a>,
24-
and some of the time types used in std.datetime come from there - such as
25-
$(REF Duration, core,time), $(REF TickDuration, core,time), and
26-
$(REF FracSec, core,time).
27-
core.time is publically imported into std.datetime, it isn't necessary
28-
to import it separately.
29-
30-
Three of the main concepts used in this module are time points, time
31-
durations, and time intervals.
32-
33-
A time point is a specific point in time. e.g. January 5th, 2010
34-
or 5:00.
35-
36-
A time duration is a length of time with units. e.g. 5 days or 231 seconds.
37-
38-
A time interval indicates a period of time associated with a fixed point in
39-
time. It is either two time points associated with each other,
40-
indicating the time starting at the first point up to, but not including,
41-
the second point - e.g. [January 5th, 2010 - March 10th, 2010$(RPAREN) - or
42-
it is a time point and a time duration associated with one another. e.g.
43-
January 5th, 2010 and 5 days, indicating [January 5th, 2010 -
44-
January 10th, 2010$(RPAREN).
45-
46-
Various arithmetic operations are supported between time points and
47-
durations (e.g. the difference between two time points is a time duration),
48-
and ranges can be gotten from time intervals, so range-based operations may
49-
be done on a series of time points.
50-
51-
The types that the typical user is most likely to be interested in are
52-
$(REF Date,std,_datetime,date) (if they want dates but don't care about
53-
time), $(REF DateTime,std,_datetime,date) (if they want dates and times
54-
but don't care about time zones), $(REF SysTime,std,_datetime,systime) (if
55-
they want the date and time from the OS and/or do care about time zones),
56-
and StopWatch (a platform-independent, high precision stop watch).
57-
$(REF Date,std,_datetime,date) and $(REF DateTime,std,_datetime,date) are
58-
optimized for calendar-based operations, while
59-
$(REF SysTime,std,_datetime,systime) is designed for dealing with time from
60-
the OS. Check out their specific documentation for more details.
61-
62-
To get the current time, use $(REF Clock.currTime,std,_datetime,systime).
63-
It will return the current time as a $(REF SysTime,std,_datetime,systime). To
64-
print it, `toString` is sufficient, but if using `toISOString`,
65-
`toISOExtString`, or `toSimpleString`, use the corresponding
66-
`fromISOString`, `fromISOExtString`, or `fromSimpleString` to
67-
create a $(REF SysTime,std,_datetime,systime) from the string.
68-
69-
--------------------
70-
auto currentTime = Clock.currTime();
71-
auto timeString = currentTime.toISOExtString();
72-
auto restoredTime = SysTime.fromISOExtString(timeString);
73-
--------------------
74-
75-
Various functions take a string (or strings) to represent a unit of time
76-
(e.g. $(D convert!("days", "hours")(numDays))). The valid strings to use
77-
with such functions are `"years"`, `"months"`, `"weeks"`,
78-
`"days"`, `"hours"`, `"minutes"`, `"seconds"`,
79-
`"msecs"` (milliseconds), `"usecs"` (microseconds),
80-
`"hnsecs"` (hecto-nanoseconds - i.e. 100 ns), or some subset thereof.
81-
There are a few functions in core.time which take `"nsecs"`, but because
82-
nothing in std.datetime has precision greater than hnsecs, and very little
83-
in core.time does, no functions in std.datetime accept `"nsecs"`.
84-
To remember which units are abbreviated and which aren't,
85-
all units seconds and greater use their full names, and all
86-
sub-second units are abbreviated (since they'd be rather long if they
87-
weren't).
88-
89-
Note:
90-
$(REF DateTimeException,std,_datetime,date) is an alias for
91-
$(REF TimeException, core,time), so you don't need to worry about
92-
core.time functions and std.datetime functions throwing different
93-
exception types (except in the rare case that they throw something other
94-
than $(REF TimeException, core,time) or
95-
$(REF DateTimeException,std,_datetime,date)).
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+
)
9674
9775
See_Also:
98-
$(DDLINK intro-to-_datetime, Introduction to std.datetime,
99-
Introduction to std&#46;_datetime)<br>
76+
$(DDLINK intro-to-datetime, Introduction to std.datetime,
77+
Introduction to std&#46;datetime)<br>
10078
$(HTTP en.wikipedia.org/wiki/ISO_8601, ISO 8601)<br>
10179
$(HTTP en.wikipedia.org/wiki/Tz_database,
10280
Wikipedia entry on TZ Database)<br>
@@ -105,10 +83,47 @@ auto restoredTime = SysTime.fromISOExtString(timeString);
10583
10684
License: $(HTTP www.boost.org/LICENSE_1_0.txt, Boost License 1.0).
10785
Authors: $(HTTP jmdavisprog.com, Jonathan M Davis) and Kato Shoichi
108-
Source: $(PHOBOSSRC std/_datetime/package.d)
86+
Source: $(PHOBOSSRC std/datetime/package.d)
10987
+/
11088
module std.datetime;
11189

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+
112127
public import core.time;
113128
public import std.datetime.date;
114129
public import std.datetime.interval;

0 commit comments

Comments
 (0)