datetimeformat

package
v0.2.8 Latest Latest
Warning

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

 Go to latest Published: Jun 19, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package datetimeformat implements the ECMA-402 Intl.DateTimeFormat constructor. 

locales, _ := locale.ParseList("en-US")
format, _ := datetimeformat.New(locales, datetimeformat.Options{})
out := format.Format(time.Now())
_ = out

See README.md for usage examples and SPECS/30-datetimeformat.md for the contract.

Example

Example demonstrates Intl.DateTimeFormat.prototype.format from ECMA-402. 

package main

import (
	"fmt"
	"time"

	"github.com/agentable/go-intl/datetimeformat"
	"github.com/agentable/go-intl/locale"
)

func main() {
	format, err := datetimeformat.New(mustLocaleList("en-US"), datetimeformat.Options{
		TimeZone: "UTC",
	})
	if err != nil {
		panic(err)
	}

	t := time.Date(2020, time.May, 14, 15, 4, 0, 0, time.UTC)
	fmt.Println(format.Format(t))

}

func mustLocaleList(tags ...string) locale.List {
	locales, err := locale.ParseList(tags...)
	if err != nil {
		panic(err)
	}
	return locales
}

Output:
5/14/2020
Example (Options)

Example_options demonstrates Intl.DateTimeFormat constructor options from ECMA-402. 

package main

import (
	"fmt"
	"time"

	"github.com/agentable/go-intl/datetimeformat"
	"github.com/agentable/go-intl/locale"
)

func main() {
	format, err := datetimeformat.New(mustLocaleList("en-US"), datetimeformat.Options{
		DateStyle: datetimeformat.LongDateTimeStyle,
		TimeZone:  "UTC",
	})
	if err != nil {
		panic(err)
	}

	t := time.Date(2020, time.May, 14, 15, 4, 0, 0, time.UTC)
	fmt.Println(format.Format(t))

}

func mustLocaleList(tags ...string) locale.List {
	locales, err := locale.ParseList(tags...)
	if err != nil {
		panic(err)
	}
	return locales
}

Output:
May 14, 2020

Index

Examples

Constants

View Source 
const (
	LookupLocaleMatcher  LocaleMatcher = "lookup"
	BestFitLocaleMatcher LocaleMatcher = "best fit"

	BasicFormatMatcher   FormatMatcher = "basic"
	BestFitFormatMatcher FormatMatcher = "best fit"

	H11HourCycle HourCycle = "h11"
	H12HourCycle HourCycle = "h12"
	H23HourCycle HourCycle = "h23"
	H24HourCycle HourCycle = "h24"

	NarrowFieldStyle FieldStyle = "narrow"
	ShortFieldStyle  FieldStyle = "short"
	LongFieldStyle   FieldStyle = "long"

	NumericFieldStyle  NumericStyle = "numeric"
	TwoDigitFieldStyle NumericStyle = "2-digit"

	NumericMonthStyle  MonthStyle = "numeric"
	TwoDigitMonthStyle MonthStyle = "2-digit"
	NarrowMonthStyle   MonthStyle = "narrow"
	ShortMonthStyle    MonthStyle = "short"
	LongMonthStyle     MonthStyle = "long"

	ShortTimeZoneName        TimeZoneName = "short"
	LongTimeZoneName         TimeZoneName = "long"
	ShortOffsetTimeZoneName  TimeZoneName = "shortOffset"
	LongOffsetTimeZoneName   TimeZoneName = "longOffset"
	ShortGenericTimeZoneName TimeZoneName = "shortGeneric"
	LongGenericTimeZoneName  TimeZoneName = "longGeneric"

	FullDateTimeStyle   Style = "full"
	LongDateTimeStyle   Style = "long"
	MediumDateTimeStyle Style = "medium"
	ShortDateTimeStyle  Style = "short"
)

Variables

This section is empty.

Functions

func SupportedLocalesOf 

func SupportedLocalesOf(locales locale.List, opts Options) (locale.List, error)

Types

type DateTimeFormat 

type DateTimeFormat struct {
	// contains filtered or unexported fields
}

func New 

func New(locales locale.List, opts Options) (*DateTimeFormat, error)

func (*DateTimeFormat) Format 

func (f *DateTimeFormat) Format(t time.Time) string
Example 
format, err := New(mustLocaleList("en-US"), Options{Year: NumericFieldStyle, Month: ShortMonthStyle, Day: NumericFieldStyle})
if err != nil {
	panic(err)
}

fmt.Println(format.Format(time.Date(2026, time.May, 8, 0, 0, 0, 0, time.UTC)))

Output:
May 8, 2026
Example (Timezone) 
format, err := New(mustLocaleList("en-US"), Options{TimeZone: "America/New_York", Hour: NumericFieldStyle, TimeZoneName: LongGenericTimeZoneName})
if err != nil {
	panic(err)
}

fmt.Println(format.Format(time.Date(2026, time.January, 8, 12, 0, 0, 0, time.UTC)))

Output:
7 AM Eastern Time

func (*DateTimeFormat) FormatRange 

func (f *DateTimeFormat) FormatRange(start, end time.Time) string

func (*DateTimeFormat) FormatRangeToParts 

func (f *DateTimeFormat) FormatRangeToParts(start, end time.Time) []RangePart

func (*DateTimeFormat) FormatToParts 

func (f *DateTimeFormat) FormatToParts(t time.Time) []Part
Example

ExampleDateTimeFormat_FormatToParts demonstrates Intl.DateTimeFormat.prototype.formatToParts from ECMA-402. 

package main

import (
	"fmt"
	"time"

	"github.com/agentable/go-intl/datetimeformat"
	"github.com/agentable/go-intl/locale"
)

func main() {
	format, err := datetimeformat.New(mustLocaleList("en-US"), datetimeformat.Options{
		Year:     datetimeformat.NumericFieldStyle,
		Month:    datetimeformat.ShortMonthStyle,
		Day:      datetimeformat.NumericFieldStyle,
		TimeZone: "UTC",
	})
	if err != nil {
		panic(err)
	}

	t := time.Date(2020, time.May, 14, 15, 4, 0, 0, time.UTC)
	for _, part := range format.FormatToParts(t) {
		fmt.Printf("%s=%q\n", part.Type, part.Value)
	}

}

func mustLocaleList(tags ...string) locale.List {
	locales, err := locale.ParseList(tags...)
	if err != nil {
		panic(err)
	}
	return locales
}

Output:
month="May"
literal=" "
day="14"
literal=", "
year="2020"
Example 
format, err := New(mustLocaleList("en-US"), Options{Weekday: LongFieldStyle, Month: LongMonthStyle, Day: NumericFieldStyle, Year: NumericFieldStyle})
if err != nil {
	panic(err)
}

for _, part := range format.FormatToParts(time.Date(2026, time.May, 8, 0, 0, 0, 0, time.UTC)) {
	fmt.Printf("%s=%q\n", part.Type, part.Value)
}

Output:
weekday="Friday"
literal=", "
month="May"
literal=" "
day="8"
literal=", "
year="2026"

func (*DateTimeFormat) ResolvedOptions 

func (f *DateTimeFormat) ResolvedOptions() ResolvedOptions

type FieldStyle 

type FieldStyle string

FieldStyle selects textual field width. Mirrors Intl.DateTimeFormat options "weekday", "era", and "dayPeriod".

type FormatMatcher 

type FormatMatcher string

FormatMatcher selects date-time component matching. Mirrors Intl.DateTimeFormat option "formatMatcher".

type HourCycle 

type HourCycle string

HourCycle selects the resolved hour cycle. Mirrors Intl.DateTimeFormat option "hourCycle".

type LocaleMatcher 

type LocaleMatcher string

LocaleMatcher selects locale negotiation behavior. Mirrors Intl.DateTimeFormat option "localeMatcher".

type MonthStyle 

type MonthStyle string

MonthStyle selects month field width. Mirrors Intl.DateTimeFormat option "month".

type NumericStyle 

type NumericStyle string

NumericStyle selects numeric or two-digit field width. Mirrors Intl.DateTimeFormat numeric field options.

type Options 

type Options struct {
	Calendar               string
	NumberingSystem        string
	LocaleMatcher          LocaleMatcher
	FormatMatcher          FormatMatcher
	TimeZone               string
	TimeZoneName           TimeZoneName
	Weekday                FieldStyle
	Era                    FieldStyle
	Year                   NumericStyle
	Month                  MonthStyle
	Day                    NumericStyle
	DayPeriod              FieldStyle
	Hour                   NumericStyle
	Minute                 NumericStyle
	Second                 NumericStyle
	HourCycle              HourCycle
	Hour12                 *bool
	DateStyle              Style
	TimeStyle              Style
	FractionalSecondDigits *int
}

type Part 

type Part struct {
	Type  PartType `json:"type"`
	Value string   `json:"value"`
}

type PartType 

type PartType string

PartType identifies a format part record. Mirrors Intl.DateTimeFormat part field "type". 

const (
	// ECMA-402 §15.5.1 Table 9 (Type Field of FormatDateTimePattern part records).
	PartYear                   PartType = "year"
	PartMonth                  PartType = "month"
	PartDay                    PartType = "day"
	PartHour                   PartType = "hour"
	PartMinute                 PartType = "minute"
	PartSecond                 PartType = "second"
	PartWeekday                PartType = "weekday"
	PartEra                    PartType = "era"
	PartDayPeriod              PartType = "dayPeriod"
	PartTimeZoneName           PartType = "timeZoneName"
	PartLiteral                PartType = "literal"
	PartFractionalSecondDigits PartType = "fractionalSecondDigits"
	// PartRelatedYear and PartYearName appear when the resolved calendar is a
	// non-Gregorian cyclic calendar (e.g. Chinese, Dangi); the active Gregorian
	// path never emits them, but the constants must exist so consumer switches
	// remain exhaustive when calendar support widens.
	PartRelatedYear PartType = "relatedYear"
	PartYearName    PartType = "yearName"
	// PartUnknown is ECMA-402's explicit fallback for an unrecognized format
	// pattern element.
	PartUnknown PartType = "unknown"
)

type RangePart 

type RangePart struct {
	Type   PartType    `json:"type"`
	Value  string      `json:"value"`
	Source RangeSource `json:"source"`
}

type RangeSource 

type RangeSource string

RangeSource identifies a range part source. Mirrors Intl.DateTimeFormat range part field "source". 

const (
	SourceStartRange RangeSource = "startRange"
	SourceShared     RangeSource = "shared"
	SourceEndRange   RangeSource = "endRange"
)

type ResolvedOptions 

type ResolvedOptions struct {
	// Locale is the resolved locale. Mirrors Intl.DateTimeFormat resolved option "locale".
	Locale locale.Locale `json:"locale"`
	// Calendar is the resolved calendar. Mirrors Intl.DateTimeFormat resolved option "calendar".
	Calendar string `json:"calendar"`
	// NumberingSystem is the resolved numbering system. Mirrors Intl.DateTimeFormat resolved option "numberingSystem".
	NumberingSystem string `json:"numberingSystem"`
	// TimeZone is the resolved time zone. Mirrors Intl.DateTimeFormat resolved option "timeZone".
	TimeZone string `json:"timeZone"`
	// HourCycle is the resolved hour cycle. Mirrors Intl.DateTimeFormat resolved option "hourCycle".
	// Empty when ECMA-402 omits hour-cycle properties because no hour field is present.
	HourCycle HourCycle `json:"hourCycle,omitempty"`
	// Hour12 is the resolved 12-hour preference. Mirrors Intl.DateTimeFormat resolved option "hour12".
	// Nil when ECMA-402 omits hour-cycle properties because no hour field is present.
	Hour12 *bool `json:"hour12,omitempty"`
	// Weekday is the resolved weekday style. Mirrors Intl.DateTimeFormat resolved option "weekday".
	// Empty when the weekday component is absent.
	Weekday FieldStyle `json:"weekday,omitempty"`
	// Era is the resolved era style. Mirrors Intl.DateTimeFormat resolved option "era".
	// Empty when the era component is absent.
	Era FieldStyle `json:"era,omitempty"`
	// Year is the resolved year style. Mirrors Intl.DateTimeFormat resolved option "year".
	// Empty when the year component is absent.
	Year NumericStyle `json:"year,omitempty"`
	// Month is the resolved month style. Mirrors Intl.DateTimeFormat resolved option "month".
	// Empty when the month component is absent.
	Month MonthStyle `json:"month,omitempty"`
	// Day is the resolved day style. Mirrors Intl.DateTimeFormat resolved option "day".
	// Empty when the day component is absent.
	Day NumericStyle `json:"day,omitempty"`
	// DayPeriod is the resolved day-period style. Mirrors Intl.DateTimeFormat resolved option "dayPeriod".
	// Empty when the day-period component is absent.
	DayPeriod FieldStyle `json:"dayPeriod,omitempty"`
	// Hour is the resolved hour style. Mirrors Intl.DateTimeFormat resolved option "hour".
	// Empty when the hour component is absent.
	Hour NumericStyle `json:"hour,omitempty"`
	// Minute is the resolved minute style. Mirrors Intl.DateTimeFormat resolved option "minute".
	// Empty when the minute component is absent.
	Minute NumericStyle `json:"minute,omitempty"`
	// Second is the resolved second style. Mirrors Intl.DateTimeFormat resolved option "second".
	// Empty when the second component is absent.
	Second NumericStyle `json:"second,omitempty"`
	// FractionalSecondDigits is the resolved fractional second digit count. Mirrors Intl.DateTimeFormat resolved option "fractionalSecondDigits".
	// Zero when the fractional-second component is absent.
	FractionalSecondDigits int `json:"fractionalSecondDigits,omitempty"`
	// TimeZoneName is the resolved time-zone name style. Mirrors Intl.DateTimeFormat resolved option "timeZoneName".
	// Empty when the time-zone name component is absent.
	TimeZoneName TimeZoneName `json:"timeZoneName,omitempty"`
	// DateStyle is the resolved date style. Mirrors Intl.DateTimeFormat resolved option "dateStyle".
	// Empty when dateStyle was not used.
	DateStyle Style `json:"dateStyle,omitempty"`
	// TimeStyle is the resolved time style. Mirrors Intl.DateTimeFormat resolved option "timeStyle".
	// Empty when timeStyle was not used.
	TimeStyle Style `json:"timeStyle,omitempty"`
}

type Style 

type Style string

Style selects date or time style width. Mirrors Intl.DateTimeFormat options "dateStyle" and "timeStyle".

type TimeZoneName 

type TimeZoneName string

TimeZoneName selects time-zone name width. Mirrors Intl.DateTimeFormat option "timeZoneName".

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.