datefmt

package
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 28, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func Format

func Format(t time.Time, layout string) (string, error)

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

func ParseDateTime(s, layout string) (time.Time, error)

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

func ParseNaiveDate(s, layout string) (time.Time, error)

ParseNaiveDate parses s like NaiveDate::parse_from_str. The result is midnight UTC on the parsed date.

func ParseNaiveDateTime

func ParseNaiveDateTime(s, layout string) (time.Time, error)

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

func ParseRFC2822(s string) (time.Time, error)

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

func ParseRFC3339

func ParseRFC3339(s string) (time.Time, error)

ParseRFC3339 parses s like DateTime::parse_from_rfc3339: a strict RFC 3339 date-and-time string, e.g. "1996-12-19T16:39:57-08:00".

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.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Kind

func (e *Error) Kind() ErrorKind

Kind returns the category of this error.

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
)

func (ErrorKind) String

func (k ErrorKind) String() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL