Documentation
¶
Overview ¶
Package datefmt reproduces the date/time formatting and parsing semantics of the Rust chrono crate (v0.4.44, built with default-features = false, features = ["clock"], i.e. without its locale support), for strftime-style format strings as used by chrono's DateTime::format, DateTime::parse_from_str, NaiveDateTime::parse_from_str, NaiveDate::parse_from_str, DateTime::parse_from_rfc3339 and DateTime::parse_from_rfc2822.
Every value formatted or produced by parsing is a plain time.Time representing an absolute instant; there is no notion of a "naive" (no offset) value or of a location other than UTC. Format always treats its input as a UTC instant. ParseNaiveDateTime and ParseNaiveDate interpret their input as already being in UTC (chrono's "naive" types carry no offset at all; this package represents that as UTC). ParseDateTime, ParseRFC3339 and ParseRFC2822 require an offset in the input and return the corresponding UTC instant.
Supported specifiers ¶
All specifiers documented for chrono's format::strftime module are supported: date specifiers (%Y %C %y %q %m %b %B %h %d %e %a %A %w %u %U %W %G %g %V %j %D %x %F %v), time specifiers (%H %k %I %l %P %p %M %S %f %.f %.3f %.6f %.9f %3f %6f %9f %R %T %X %r), timezone specifiers (%Z %z %:z %::z %:::z %#z, parse-only), the combined %c and %+ specifiers, %s, and the literal specifiers %t %n %%. Padding modifiers (%-?, %_?, %0?) are supported on numeric specifiers. Month, weekday and am/pm names are always the fixed English ones chrono uses without its "unstable-locales" feature.
Deviations from chrono ¶
Two deliberate deviations exist, both a consequence of Go's time.Time having no way to represent a leap second (a wall-clock time of exactly :60 whose instant is nonetheless treated by chrono as no later than :59.999999999):
- Format never observes a leap-second instant, because no time.Time value can hold one to begin with.
- Parsing a literal ":60" second is accepted (as chrono does), but the resulting instant is the following second (e.g. 12:00:60 becomes 12:01:00 plus any parsed fractional seconds), rather than chrono's cosmetic-only leap second that leaves the instant at :59. This preserves any parsed fractional-second precision and produces a valid, orderable instant; the timestamp field ("%s"), when also present, is still cross-checked against chrono's (non-rolled-over) value for consistency.
Years are supported at least in the exact range 0..9999. Chrono itself allows years from -262144 to 262143; this package additionally accepts years outside 0..9999 (down to what a Go time.Time/int can represent) without panicking, but does not guarantee exact parity with chrono for years outside chrono's own documented range or outside what time.Time can hold.
Index ¶
- func Format(t time.Time, layout string) (string, error)
- func ParseDateTime(s, layout string) (time.Time, error)
- func ParseNaiveDate(s, layout string) (time.Time, error)
- func ParseNaiveDateTime(s, layout string) (time.Time, error)
- func ParseRFC2822(s string) (time.Time, error)
- func ParseRFC3339(s string) (time.Time, error)
- type Error
- type ErrorKind
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Format ¶
Format formats t like chrono's DateTime<Utc>::format(layout). t is always treated as a UTC instant. An invalid or unsupported specifier in layout returns an *Error with kind BadFormat, mirroring chrono's fmt::Error.
func ParseDateTime ¶
ParseDateTime parses s like DateTime::<FixedOffset>::parse_from_str: an offset must be present in the input. It returns the parsed instant in UTC.
func ParseNaiveDate ¶
ParseNaiveDate parses s like NaiveDate::parse_from_str. The result is midnight UTC on the parsed date.
func ParseNaiveDateTime ¶
ParseNaiveDateTime parses s like NaiveDateTime::parse_from_str: no offset is required, and none is applied even if present in the input by way of a %z-like specifier being consumed. The result is interpreted as UTC.
func ParseRFC2822 ¶
ParseRFC2822 parses s like DateTime::parse_from_rfc2822: an RFC 2822 date-and-time string as used by HTTP and email headers, e.g. "Tue, 1 Jul 2003 10:52:37 +0200".
Types ¶
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error reports why formatting or parsing a date/time value failed. Its Error() text matches chrono's ParseError Display output for the corresponding ErrorKind.
type ErrorKind ¶
type ErrorKind int
ErrorKind categorizes why a format or parse operation failed. The set of kinds and their meaning mirrors chrono's ParseErrorKind.
const ( // OutOfRange means a field was set to a value outside its permitted // range, or a resolved date or time value has no valid representation. OutOfRange ErrorKind = iota // Impossible means there is no possible date and time value matching // the given set of fields (they are inconsistent with each other). Impossible // NotEnough means the given set of fields is not enough to resolve a // unique date and time value. NotEnough // Invalid means the input has an invalid character sequence for the // expected formatting item. Invalid // TooShort means the input ended prematurely. TooShort // TooLong means all formatting items were consumed but input remains. TooLong // BadFormat means the format string itself is invalid or contains an // unsupported specifier. BadFormat )