README (1858B)
1 The datetime module implements the common international "Gregorian" chronology, 2 based on the astronomically numbered proleptic Gregorian calendar, as per ISO 3 8601, and the common 24 hour clock. It provides [[datetime]], a representation 4 of civil date/time and an extension of the [[time::chrono::moment]] type, 5 optimized for dealing with the Gregorian chronology. 6 7 The [[time::chrono]] module has many useful functions which interoperate with 8 datetimes. Any [[time::chrono]] function which accepts *moment also accepts 9 *datetime. 10 11 Datetimes are created with [[new]], [[now]], or one of the "from_" functions. 12 Alternatively, use the [[virtual]] interface to construct a datetime. 13 14 The [[virtual]] interface, coupled with the [[realize]] function, provides a way 15 to handle uncertain or invalid datetime information intermediately, transform 16 date/time values with arithmetic, [[parse]] date/time strings, and construct new 17 datetimes safely. 18 19 The "observe" functions accept a *datetime and evaluates one of its observed 20 chronological values. This includes [[year]], [[month]], [[day]], [[hour]] etc. 21 22 [[datetime]]s may be localized to different [[time::chrono::locality]]s via the 23 [[in]] function. The "observe" functions will evaluate the correct values 24 accordingly. You'll find a standard selection of world timezones in the 25 [[time::chrono]] module. 26 27 See [[parse]] and [[format]] for working with date/time strings. 28 29 Timescale-wise datetime arithmetic using the [[time::duration]] type is possible, 30 with [[add]] and [[time::chrono::diff]]. 31 32 Chronology-wise datetime arithmetic using the [[period]] type is possible, with 33 [[reckon]] and the [[calculus]] type, [[pdiff]], [[unitdiff]], and [[truncate]]. 34 Note that chronological and calendrical arithmetic is highly irregular due to 35 overflows and timezone discontinuities, so think carefully about what you want.