Documentation
¶
Overview ¶
Package temporal separates UTC instants, calendar dates, wall times, and local date-times. Value operations return new values; decoding replaces the receiver only on success. Application time comes from the clock package.
Index ¶
- func LoadTimeZone(name string) (*time.Location, error)
- func ParseTimeZone(text string) (*time.Location, error)
- type Date
- func (d Date) AddDays(days int) (Date, error)
- func (d Date) Day() int
- func (d Date) IsZero() bool
- func (d Date) MarshalText() ([]byte, error)
- func (d Date) Month() time.Month
- func (d Date) String() string
- func (d *Date) UnmarshalJSON(data []byte) error
- func (d *Date) UnmarshalText(data []byte) error
- func (d Date) Year() int
- type DateTime
- func (v DateTime) Add(duration time.Duration) (DateTime, error)
- func (v DateTime) DateIn(zone *time.Location) (Date, error)
- func (v DateTime) FormatIn(zone *time.Location) (string, error)
- func (v DateTime) IsZero() bool
- func (v DateTime) LocalIn(zone *time.Location) (LocalDateTime, error)
- func (v DateTime) MarshalText() ([]byte, error)
- func (v DateTime) String() string
- func (v DateTime) UTC() time.Time
- func (v DateTime) UnixMicro() int64
- func (v DateTime) UnixMilli() int64
- func (v *DateTime) UnmarshalJSON(data []byte) error
- func (v *DateTime) UnmarshalText(data []byte) error
- type Interval
- type LocalDateTime
- func (v LocalDateTime) Add(duration time.Duration) (LocalDateTime, error)
- func (v LocalDateTime) Date() Date
- func (v LocalDateTime) In(zone *time.Location) (DateTime, error)
- func (v LocalDateTime) IsZero() bool
- func (v LocalDateTime) MarshalText() ([]byte, error)
- func (v LocalDateTime) String() string
- func (v LocalDateTime) Time() Time
- func (v *LocalDateTime) UnmarshalJSON(data []byte) error
- func (v *LocalDateTime) UnmarshalText(data []byte) error
- type Service
- func (s Service) AddDays(instant DateTime, days int) (DateTime, error)
- func (s Service) Date(instant DateTime) (Date, error)
- func (s Service) Format(instant DateTime) (string, error)
- func (s Service) In(name ZoneName) (Service, error)
- func (s Service) Local(instant DateTime) (LocalDateTime, error)
- func (s Service) Location() *time.Location
- func (s Service) Now() (DateTime, error)
- func (s Service) Parse(text string) (DateTime, error)
- func (s Service) StartOfDay(instant DateTime) (DateTime, error)
- func (s Service) TimeZone() ZoneName
- func (s Service) Today() (Date, error)
- type Time
- type ZoneName
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LoadTimeZone ¶
LoadTimeZone resolves a bounded, explicit IANA name or UTC. It excludes fixed offsets, empty names and the process-dependent Local value. Use ParseTimeZone when a boundary accepts both named zones and fixed offsets.
func ParseTimeZone ¶
ParseTimeZone resolves UTC, an IANA location or a fixed +/-HH:MM offset. Named locations use Go's configured timezone database. Empty and Local are rejected so application behavior does not silently depend on the host zone. The returned standard Go location works directly with DateTime.LocalIn and LocalDateTime.In. Fixed offsets must be smaller than 24 hours.
Types ¶
type Date ¶
type Date struct {
// contains filtered or unexported fields
}
Date is a calendar date without a time or timezone. The zero value is absent and cannot be serialized. Supported years are 1 through 9999.
func (Date) MarshalText ¶
func (*Date) UnmarshalJSON ¶
func (*Date) UnmarshalText ¶
type DateTime ¶
type DateTime struct {
// contains filtered or unexported fields
}
DateTime is an immutable UTC instant at microsecond precision, normalized without a monotonic reading. Its zero value is Go's zero time (0001-01-01T00:00:00Z), not database null.
func Now ¶
Now reads an explicit application clock. It does not change the system clock or consult a process-global timezone. Callback failure returns no instant.
func ParseDateTime ¶
func ParseDateTimeIn ¶
ParseDateTimeIn accepts an explicit RFC3339 offset first, otherwise resolves a local wall time using the existing strict gap/overlap policy for zone.
func (DateTime) MarshalText ¶
func (*DateTime) UnmarshalJSON ¶
func (*DateTime) UnmarshalText ¶
type Interval ¶
type Interval struct {
// contains filtered or unexported fields
}
Interval keeps calendar months/days separate from elapsed time. A calendar day need not be 24 hours when applied to an instant in a timezone. Zero is a zero interval. Values are immutable and retain signed components.
func NewInterval ¶
NewInterval constructs calendar and elapsed components without normalizing them into one another. Sub-microsecond precision is rejected.
func ParseInterval ¶
ParseInterval accepts String's canonical representation, ISO 8601 designator intervals and PostgreSQL's four output styles. Calendar components are whole numbers; only seconds may be fractional, to whole-microsecond precision. Input is bounded and components are checked without floating-point rounding.
func (Interval) MarshalText ¶
func (*Interval) UnmarshalJSON ¶
func (*Interval) UnmarshalText ¶
type LocalDateTime ¶
type LocalDateTime struct {
// contains filtered or unexported fields
}
LocalDateTime preserves a calendar date and wall time at microsecond precision without assuming any timezone. Zero is absent. Converting to an instant requires an explicit zone.
func NewLocalDateTime ¶
func NewLocalDateTime(date Date, clock Time) (LocalDateTime, error)
func ParseLocalDateTime ¶
func ParseLocalDateTime(text string) (LocalDateTime, error)
func (LocalDateTime) Add ¶
func (v LocalDateTime) Add(duration time.Duration) (LocalDateTime, error)
func (LocalDateTime) Date ¶
func (v LocalDateTime) Date() Date
func (LocalDateTime) In ¶
func (v LocalDateTime) In(zone *time.Location) (DateTime, error)
In resolves a unique instant. DST gaps fail with Invalid; repeated wall times fail with Conflict. Supply an explicit offset to ParseDateTime to disambiguate. Zone offsets outside +/-24 hours are rejected; standard IANA zones fit within this bound. No machine-local timezone or arbitrary DST choice is used.
func (LocalDateTime) IsZero ¶
func (v LocalDateTime) IsZero() bool
func (LocalDateTime) MarshalText ¶
func (v LocalDateTime) MarshalText() ([]byte, error)
func (LocalDateTime) String ¶
func (v LocalDateTime) String() string
func (LocalDateTime) Time ¶
func (v LocalDateTime) Time() Time
func (*LocalDateTime) UnmarshalJSON ¶
func (v *LocalDateTime) UnmarshalJSON(data []byte) error
func (*LocalDateTime) UnmarshalText ¶
func (v *LocalDateTime) UnmarshalText(data []byte) error
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service binds immutable calendar helpers to one application clock and zone. Retain it in domain constructors. Instants and their JSON remain UTC; local parsing, presentation and calendar arithmetic use this service's timezone.
func (Service) AddDays ¶
AddDays preserves local wall time across calendar days, which need not be 24 elapsed hours. A resulting DST gap/overlap remains an explicit error.
func (Service) Location ¶
Location returns an owned standard Go location for APIs needing explicit zones.
func (Service) StartOfDay ¶
StartOfDay resolves local midnight with the existing strict DST policy. Historical midnight gaps/overlaps return errors instead of guessing an instant.
type Time ¶
type Time struct {
// contains filtered or unexported fields
}
Time is a wall-clock time at microsecond precision without a date or offset. Zero means midnight. Leap seconds and a 24:00 representation are rejected.
Source Files