shithub: mc

ref: d0ffb958c7247028223c7e53253249d52a47a324
dir: /doc/api/libdate/parsing.txt/

{
	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.