summaryrefslogtreecommitdiff
path: root/doc/api/libdate
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api/libdate')
-rw-r--r--doc/api/libdate/formatting.txt99
-rw-r--r--doc/api/libdate/index.txt95
-rw-r--r--doc/api/libdate/manipulation.txt130
-rw-r--r--doc/api/libdate/parsing.txt74
-rw-r--r--doc/api/libdate/types.txt71
5 files changed, 469 insertions, 0 deletions
diff --git a/doc/api/libdate/formatting.txt b/doc/api/libdate/formatting.txt
new file mode 100644
index 0000000..c09f2cb
--- /dev/null
+++ b/doc/api/libdate/formatting.txt
@@ -0,0 +1,99 @@
+{
+ title: Formatting
+ description: Libdate API documentation.
+}
+
+Date and Time Formatting
+---------------------
+
+Formatting in libdate is done through the standard formatting
+functionality, and there are actually no functions exposed by libdate.
+Instead, you would write something like:
+
+```{runmyr stdfmt1}
+use date
+
+const main = {
+ std.put("{}\n", date.now())
+}
+```
+
+Custom formatting is done with a format option passed to std.format that
+looks like `f=dateformat`. The format strings used resemble the strings
+provided in strptime. Any characters preceded with a '%' are format
+characters, otherwise they are copied to the output stream directly.
+
+The format strings used to control formatting are also used to control parsing.
+
+An example would look like:
+
+```{runmyr stdfmt1}
+use date
+
+const main = {
+ std.put("{f=year is %Y, the day is %d}\n", date.now())
+}
+
+
+There are a number of short format options installed, specifically, `d`,
+`D`, and `t`, which respectively map to the default date format, the
+default date and time format, and the default time only format.
+
+```{runmyr stdfmt1}
+use date
+
+const main = {
+ std.put("{d}\n", date.now())
+ std.put("{D}\n", date.now())
+ std.put("{T}\n", date.now())
+}
+```
+
+Date and Time Formatting
+---------------------
+
+Both parsing and formatting use the same format strings. The
+modifiers that are supported by libdate are listed below.
+
+When possible, the default format verbs `D`, `d`, or `t`
+should be used for formatting, and the default constants
+`Datefmt`, `Datetimefmt`, or `Timefmt` should be used for
+parsing.
+
+
+Char | Meaning
+------|----------------------------------------------
+_%a_ | Abbreviated day of week: Mon, Tues, etc
+_%A_ | Full day of week: Monday, Tuesday, Wednesday, etc
+_%b_ | Abbreviated month of year: Jan, Feb, Mar, etc.
+_%B_ | Full month of year: January, February, etc
+_%c_ | Short for %Y-%m-%d %H:%M:%S %z (ISO 8601)
+_%C_ | Century number of year, as two digit integer.
+_%d_ | Day of month as a decimal number, 00 to 31.
+_%D_ | Short for "%m/%d/%y (wtf america)"
+_%e_ | Same as d, but space padded instead of zero padded.
+_%F_ | Short for ISO 8601 date format %Y-%m-%d
+_%h_ | Same as '%b'.
+_%H_ | Hour number using the 24 hour clock, zero padded.
+_%I_ | Hour number using the 12 hour clock, zero padded.
+_%j_ | Day of year as a decimal number, 001 to 366.
+_%k_ | Hour number using the 24 hour clock, space padded.
+_%l_ | Hour number using the 12 hour clock, space padded.
+_%m_ | The month number, zero padded.
+_%M_ | The minute number, zero padded.
+_%p_ | AM or PM, according to the time provided.
+_%P_ | am or pm, according to the time provided.
+_%r_ | 12 hour time: %I:%M %p
+_%R_ | 24 hour time: %H:%M
+_%s_ | The number of seconds since the Epoch
+_%S_ | The second number, zero padded. 0 to 60.
+_%T_ | The time including seconds in 24 hour format.
+_%u_ | The day of the week in decimal, 0 to 7.
+_%x_ | The date without the time. Same as %F
+_%X_ | The date with the time. Same as %c
+_%y_ | The final two digits of year.
+_%Y_ | The full year, including century. BC dates are negative.
+_%z_ | Timezone offset.
+_%Z_ | Timezone name or abbreviation. Offset if this is not available.
+_%%_ | A literal '%'
+
diff --git a/doc/api/libdate/index.txt b/doc/api/libdate/index.txt
new file mode 100644
index 0000000..7b9cafa
--- /dev/null
+++ b/doc/api/libdate/index.txt
@@ -0,0 +1,95 @@
+{
+ title: libdate
+ description: Libdate API documentation.
+}
+
+Summary
+-------
+
+Libdate is a date API designed to cover most date related functinality in a
+sane, easy to use way. It will format, parse, and do basic manipulations on
+dates. All operations are done on the proleptic Gregorian calendar, and the
+Julian to transition is not handled.
+
+Core Concepts
+-------------
+
+### Instants
+
+An instant is a point in time. Immovable, unchanging for eternity, it is
+anchored in one spot through the microseconds of unix time in the UTC time
+zone. It is broken up into a local representation, consisting of years,
+months, days, weekdays, hours, minutes, seconds, and microseconds, with a
+timezone attached.
+
+### Durations
+
+A duration is a difference between two instants. It has a fixed magnitude, and
+is independent of timezones and the oddities of human calendars. It may be
+added or subtracted from instants of other durations. Durations have a
+resolution of microseconds. It is signed, and negative durations move instants
+backwards in time.
+
+### Periods
+
+A period is another form of differece between two instants. However, a period
+is a flighty creature, which does not anchor itself to the world of men in any
+strong way. A year may be 365 or 366 days, according to the whims and vagaries
+of the local calendar. An hour added to a time may jump ahead by two hours, if
+it so desires to follow the savings of daylight. These creatures attempt to
+mold themselves to the irrationalities of man's mind, and eschew the divine
+ordering of absolute time handed down by the prophets.
+
+### Timezones
+
+A timezone is a named zone, as decreed by the mighty IANA timezone database.
+It may take the form of a location such as "America/New_York", a well-known
+abbreviation like "EST", or a special value such as "local" or "", which mean,
+respectively, the current zone or UTC.
+
+Conventions
+-----------
+
+Timezones are pervasive, and no time is manipulated in this API without
+the awareness of the timezone. As a result, it is useful to know that dates
+are represeted using IANA zoneinfo database names. These are documented
+fully here: http://www.iana.org/time-zones
+
+There are two extensions that libdate supports: The empty string represents
+the UTC timezone, and "local" represents the time zone of the system that
+the system libdate is running on has been configured to.
+
+In the case of ambiguous timezones -- for example, parsing a date with no
+time attached, while using API call that does not specify the timezone,
+libdate will assume UTC dates.
+
+Functionality
+-------------
+
+The functionality in libdate can be grouped into three main sections: Parsing,
+Manipulation, and Formatting.
+
+### [Types](types)
+
+This covers the set of all types provided by, and used throughout, the API
+of libdate, including all public fields and types.
+
+### [Parsing](parsing)
+
+This covers parse formatted dates in a manner similar to strptime. There are
+currently plans for an flexible parse() function, but this has not yet been
+implemented.
+
+### [Creation and Manipulation](manipulation)
+
+Manipulation covers date and time creation, and transition aware APIs that
+will work for timezone crossings, daylight savings time, and so on.
+
+#### Formatting
+
+This covers date formatting, which is done through strftime-like format
+strings. There are actually no functions exposed for formatting, as this is
+done through custom formatters for libstd, however, the format strings used
+to customize the date output are described here.
+
+
diff --git a/doc/api/libdate/manipulation.txt b/doc/api/libdate/manipulation.txt
new file mode 100644
index 0000000..22f9b9e
--- /dev/null
+++ b/doc/api/libdate/manipulation.txt
@@ -0,0 +1,130 @@
+
+{
+ title: Creation and Manipulation
+ description: Libdate API documentation.
+}
+
+Creation and Manipulation
+-------------------------
+ pkg date =
+ /* useful constructors */
+ const utcnow : (-> instant)
+ const now : (tz : byte[:] -> instant)
+ const tozone : (d : instant, zone : byte[:] -> instant)
+ const mkdate : (y : int, m : int, day : int, zone : byte[:] -> instant)
+ const mkdatetime : (year : int, mon : int, day : int, \
+ h : int, m : int, s : int, zone : byte[:] -> instant)
+ const mkinstant : (tm : std.time, zone : byte[:] -> instant)
+
+ const localoff : (tm : std.time -> duration)
+ const tzoff : (tzname : byte[:], tm : std.time -> duration)
+ const tzname : (tzoff : int -> byte[:])
+ const isleap : (d : instant -> bool)
+
+ /* date differences */
+ const add : (d : instant, dt : duration -> instant)
+ const sub : (d : instant, dt : duration -> instant)
+ const addperiod : (d : instant, dt : period -> instant)
+ const subperiod : (d : instant, dt : period -> instant)
+
+ const duration : (a : instant, b : instant -> duration)
+
+ pkglocal const recalc : (inst : instant# -> std.time)
+ ;;
+
+Creation
+-----------
+
+ const utcnow : (-> instant)
+
+Creates an instant representing the current time. The timezone is UTC. As a
+general philosophical point, dates written out persisetntly should generally
+be in UTC, so this function should generally be used to get dates.
+
+Returns: An instant representing the current time in the UTC timezone.
+
+ const now : (tz : byte[:] -> instant)
+
+Creates an instant representing the current time. The timezone is the local
+time. This is useful for displaying dates and times to the user.
+
+Returns: An instant representing the current time in the local timezone.
+
+ const tozone : (d : instant, zone : byte[:] -> instant)
+
+Takes an instant and converts it to a new timezone. This takes the instants by
+value, and therefore, does not mutate any of its arguments.
+
+Returns: An instant representing provided time in the requested timezone.
+
+ const mkdate : (y : int, m : int, day : int, zone : byte[:] -> instant)
+
+Creates a date with the given year, month, and day in the given timezone. The
+time is set to 0:00:00
+
+Returns: A date representing the given ymd
+
+ const mkdatetime : (year : int, mon : int, day : int, \
+ h : int, m : int, s : int, zone : byte[:] -> instant)
+
+Creates a date and time pair with the given year, month, day, at the time
+h, m, s, in the provided timezone. The microseconds are zeroed.
+
+Returns: A date representing the given ymd:hms
+
+ const mkinstant : (tm : std.time, zone : byte[:] -> instant)
+
+Creates an instant from a time type. This time can be derived from the
+standard library, or computed from any other source. The time is in
+microseconds since the Unix epoch (Jan 1 1970, 0:00, UTC).
+
+Returns: An instant representing a std.time in the requested timezone
+
+Timezones
+---------
+
+ const localoff : (tm : std.time -> duration)
+
+Gets the local timezone offset for a time. Note that timezones can change due
+daylight savings, politics, and other similar factors, so a timezone offset
+needs to be associated with a specific instant.
+
+Returns: a duration representing the local timezone offset.
+
+ const tzoff : (tzname : byte[:], tm : std.time -> duration)
+
+Gets the timezone offset for a time and timezone pair. Note that timezones can
+change due daylight savings, politics, and other similar factors, so a
+timezone offset needs to be associated with a specific instant.
+
+Returns: a duration representing the requested timezone offset.
+
+ const isleap : (d : instant -> bool)
+
+Returns: whether a specific instant is within a leap year or not.
+
+Manipulation
+------------
+
+ const add : (d : instant, dt : duration -> instant)
+ const sub : (d : instant, dt : duration -> instant)
+
+Adds or subtracts a duration from a date. A duration is an absolute length of
+time, and is not adjusted for calendar shifts around DST and similar events.
+
+Returns: an instant representing the adjusted time.
+
+ const addperiod : (d : instant, dt : period -> instant)
+ const subperiod : (d : instant, dt : period -> instant)
+
+Adds or subtracts a period from a date. A period is a humanized length of
+time, and is adjusted for calendar shifts around DST and similar events.
+
+Returns: an instant representing the adjusted time.
+
+ const duration : (a : instant, b : instant -> duration)
+
+Returns: the duration representing the difference between the two provided
+instants.
+
+
diff --git a/doc/api/libdate/parsing.txt b/doc/api/libdate/parsing.txt
new file mode 100644
index 0000000..fc4aa4e
--- /dev/null
+++ b/doc/api/libdate/parsing.txt
@@ -0,0 +1,74 @@
+{
+ title: Date Parsing
+ description: Libdate API documentation.
+}
+
+Date and time parsing
+---------------------
+
+ type parsefail = union
+ `Doublefmt char
+ `Badsep (char, char)
+ `Badfmt char
+ `Badzone byte[:]
+ `Badname byte[:]
+ `Badchar
+ `Badampm
+ `Shortint
+ `Badint
+ ;;
+
+ const Datetimefmt
+ const Datefmt
+ const Timefmt
+
+ /* date i/o */
+ const parsefmt : (fmt : byte[:], s: byte[:] -> std.result(instant, parsefail))
+ const parsefmtl : (fmt : byte[:], s: byte[:] -> std.result(instant, parsefail))
+ const parsefmtz : (fmt : byte[:], s: byte[:], tz : byte[:] -> std.result(instant, parsefail))
+
+Descriptions
+------------
+
+ const Datetimefmt = "%Y-%m-%d %H:%M:%S %z"
+ const Datefmt = "%H:%M:%S %z"
+ const Timefmt = "%Y-%m-%d %z"
+
+These are "sane defaults" for date and time formats, and can be passed in
+where a format is required.
+
+ type parsefail
+
+Parsefail is an error type, returning descriptions of the error that the
+parsing code saw. Strings returned within the error point into the format
+string, and will be invalid when the format string is freed.
+
+ const parsefmt : (fmt : byte[:], s: byte[:] -> std.result(instant, parsefail))
+
+Parses a format string with a format. If there is a timezone specified in the
+format string, that format string will be used. If there is no format, the
+timezone will be assumed to be UTC.
+
+The format string used is similar to strptime, and is documented fully in
+the [description of formatting](/libdate/formatting)
+
+Returns: Either an instant representing the time parsed, or an error
+describing the failure.
+
+ const parsefmtl : (fmt : byte[:], s: byte[:] -> std.result(instant, parsefail))
+
+Parses a format into the local time. If a timezone is specified, the
+conversion will be done from the instant of the timezone to the local time.
+The format strings are the same as 'parsefmt'.
+
+Returns: Either an instant representing the time parsed, or an error
+describing the failure.
+
+ const parsefmtz : (fmt : byte[:], s: byte[:], tz : byte[:] -> std.result(instant, parsefail))
+
+Parses a format into the specified timezone. If a timezone is specified in the
+parsed date, the conversion will be done from the timezone to the provided
+timezone. The format strings are the same as 'parsefmt'.
+
+Returns: Either an instant representing the time parsed, or an error
+describing the failure.
diff --git a/doc/api/libdate/types.txt b/doc/api/libdate/types.txt
new file mode 100644
index 0000000..71c3ebe
--- /dev/null
+++ b/doc/api/libdate/types.txt
@@ -0,0 +1,71 @@
+{
+ title: Types
+ description: Libdate API documentation.
+}
+
+Contents
+--------
+
+ pkg date =
+ type instant = struct
+ actual : std.time /* epoch time in microseconds */
+ tzoff : duration /* timezone offset in microseconds */
+ year : int /* year, != 0 */
+ mon : int /* month, [1..12] */
+ day : int /* day, [1..31] */
+ wday : int /* weekday, [0..6] */
+ h : int /* hour: [0..23] */
+ m : int /* minute: [0..59] */
+ s : int /* second: [0..59] */
+ us : int /* microsecond: [0..999,999] */
+ tzname : byte[:] /* current time zone name */
+ ;;
+
+ type duration = std.time
+
+ type period = union
+ `Year int
+ `Month int
+ `Day int
+ `Hour int
+ `Minute int
+ `Second int
+ ;;
+ ;;
+
+Descriptions
+------------
+
+ type instant
+
+Instant represents a single instant of time, with a resolution
+of microseconds. It contains the actual instant in the member
+`actual`, which is a timestamp in microseconds since Jan 1, 1970
+at 00:00 in UTC, and breaks out the "humanized" time out into the
+various members that are exposed.
+
+The instant type always has a timezone attached, and the humanized
+time components are always in that timezone.
+
+ type duration
+
+A duration is an absolute number of microseconds that can be added
+or subtracted from an instant. This is not timezone adjusted.
+
+ type period
+
+A period is a time delta that is adjusted for crossing timezones,
+daylight savings, and other similar events. If you add a day to
+an instant, you would get the same wallclock time the next day,
+should that wallclock time exist.
+
+For example, if I were to add `\`Day 2` to the instant
+`Oct 31 2015 3:00`, then the result would be the date
+`Nov 2 2015 3:00`, regardless of the daylight savings time adjustment.
+However, adding `\`Hour 48` would not have that effect.
+
+In cases where the adjustment does not exist -- for example, leap years,
+then the time will "wrap around" to the next available day. For example,
+Feb 29th on a leap year will become Mar 1st.
+
+