summaryrefslogtreecommitdiff
path: root/doc/api/libdate/parsing.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api/libdate/parsing.txt')
-rw-r--r--doc/api/libdate/parsing.txt74
1 files changed, 74 insertions, 0 deletions
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.