commit 73781e8f52bd8a62f9153f6c0157101592c2c11d
parent 25281e18bfb499b821f97a8e92572639273c33db
Author: Byron Torres <b@torresjrjr.com>
Date: Wed, 26 Jan 2022 22:36:07 +0000
datetime/README: update
Signed-off-by: Byron Torres <b@torresjrjr.com>
Diffstat:
1 file changed, 37 insertions(+), 14 deletions(-)
diff --git a/datetime/README b/datetime/README
@@ -1,19 +1,42 @@
-The datetime module implements the international de facto "Gregorian"
-chronology, based on the astronomically numbered, proleptic Gregorian
-calendar, as per ISO 8601. It provides [[datetime]], a representation of
-civil date/time and an extension of the [[chrono::moment]] type,
-optimized for dealing with the Gregorian chronology.
+The datetime module implements the common international "Gregorian"
+chronology, based on the astronomically numbered proleptic Gregorian
+calendar, as per ISO 8601, and the common 24 hour clock. It provides
+[[datetime]], a representation of civil date/time and an extension of
+the [[chrono::moment]] type, optimized for dealing with the Gregorian
+chronology.
-Datetimes are created with [[new]] or [[now]], or be constructed piece
-by piece via a [[builder]].
+Datetimes are created with [[new]], [[now]], or with one of the various
+"from_" functions. Alternatively, use a [[builder]] to construct a
+datetime piece-by-piece, by field assignements or by parsing strings
+with [[parse]].
+
+[[datetime]] instances are designed to be always valid and internally
+consistent. They should be treated as immutable, and their fields as
+private. All functions herein return valid datetimes (or appropriate
+errors), and never modify a datetime's value, even if passed as a
+pointer, which is used only for internal caching.
+
+[[datetime]] fields are accessed, evaluated, and cached via the various
+"field" functions ([[year]], [[month]], [[day]], etc). Accessing or
+modifying a [[datetime]]'s fields directly is highly discouraged. See
+[[builder]] for "modifiable datetimes".
+
+[[datetime]]s may be localized to different [[chrono::timezone]]s via
+the [[in]] function. The "field" functions will evaluate the correct
+values accordingly. You'll find a standard selection of world timezones
+in the [[time::olson]] module.
+
+TODO: Settle on consistent naming and language for localisation.
+"timezone" or "locality"?
+
+TODO: Rename [[localize]] to something less confusing and more dangerous
+sounding? Perhaps not export it? It's use is special case and often not
+what users want.
+
+Both formatting and parsing use a sensible subset of the POSIX
+format specifiers (see strptime(3)), and it is trivial to contruct your
+own textual representations with the functions herein.
For arithmetics, use [[diff]], [[add]] and [[hop]]. Note that
calendrical arithmetic is highly irregular with many edge cases, so
think carefully about what you want.
-
-[[datetime]] instances are designed to always be valid and internally
-consistent. The one exception is during timezone transitions.
-Non-existant datetimes should be tested for by attempting to converting
-them to their "normal" timezone (usually UTC0).
-
-Both formatting and parsing use POSIX specifiers (see strptime(3)).
