The Hare programming language
git clone https://git.torresjrjr.com/hare.git
Log | Files | Refs | README | LICENSE

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>

Mdatetime/README | 51+++++++++++++++++++++++++++++++++++++--------------
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)).