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) AddDays ¶
AddDays adds calendar days, rejecting absent dates and results outside supported years.
func (Date) MarshalText ¶
MarshalText encodes the date as text, rejecting an absent date.
func (*Date) UnmarshalJSON ¶
UnmarshalJSON decodes a JSON date, replacing the receiver only on success.
func (*Date) UnmarshalText ¶
UnmarshalText parses date text, replacing the receiver only on success.
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 NewDateTime ¶
NewDateTime converts an instant to UTC at microsecond precision, stripping monotonic time and checking supported years.
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 ¶
ParseDateTime parses an RFC3339 date-time with an explicit offset and normalizes it through NewDateTime.
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) LocalIn ¶
func (v DateTime) LocalIn(zone *time.Location) (LocalDateTime, error)
LocalIn returns local wall-clock fields in the supplied nonnil time zone.
func (DateTime) MarshalText ¶
MarshalText encodes the instant's RFC3339 string as text.
func (DateTime) String ¶
String returns the UTC instant in RFC3339 format with fractional seconds as needed.
func (*DateTime) UnmarshalJSON ¶
UnmarshalJSON decodes a JSON date-time, replacing the receiver only on success.
func (*DateTime) UnmarshalText ¶
UnmarshalText parses date-time text, replacing the receiver only on success.
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 ¶
MarshalText encodes the interval's string representation as text.
func (*Interval) UnmarshalJSON ¶
UnmarshalJSON decodes a JSON interval, replacing the receiver only on success.
func (*Interval) UnmarshalText ¶
UnmarshalText parses interval text, replacing the receiver only on success.
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)
NewLocalDateTime combines a present calendar date with a wall-clock time.
func ParseLocalDateTime ¶
func ParseLocalDateTime(text string) (LocalDateTime, error)
ParseLocalDateTime parses local date and time fields separated by T or a space.
func (LocalDateTime) Add ¶
func (v LocalDateTime) Add(duration time.Duration) (LocalDateTime, error)
Add adds a duration to wall-clock fields, rejecting an absent value or unsupported result year.
func (LocalDateTime) Date ¶
func (v LocalDateTime) Date() Date
Date returns the calendar date component.
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
IsZero reports whether the local date-time is absent.
func (LocalDateTime) MarshalText ¶
func (v LocalDateTime) MarshalText() ([]byte, error)
MarshalText encodes the local date-time as text, rejecting an absent value.
func (LocalDateTime) String ¶
func (v LocalDateTime) String() string
String returns date and time fields separated by T without a time zone.
func (LocalDateTime) Time ¶
func (v LocalDateTime) Time() Time
Time returns the wall-clock time component.
func (*LocalDateTime) UnmarshalJSON ¶
func (v *LocalDateTime) UnmarshalJSON(data []byte) error
UnmarshalJSON decodes a JSON local date-time, replacing the receiver only on success.
func (*LocalDateTime) UnmarshalText ¶
func (v *LocalDateTime) UnmarshalText(data []byte) error
UnmarshalText parses local date-time text, replacing the receiver only on success.
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 NewService ¶
NewService validates a clock and resolves the named time zone for a date service.
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) Local ¶
func (s Service) Local(instant DateTime) (LocalDateTime, error)
Local returns the instant's local fields in the service's time zone.
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.
func NewTime ¶
NewTime validates wall-clock fields and truncates fractional seconds to microsecond precision.
func ParseTime ¶
ParseTime parses HH:MM:SS with optional fractional seconds and normalizes through NewTime.
func (Time) MarshalText ¶
MarshalText encodes the wall-clock time as text.
func (Time) Nanosecond ¶
Nanosecond returns the fractional second in nanoseconds.
func (*Time) UnmarshalJSON ¶
UnmarshalJSON decodes a JSON wall-clock time, replacing the receiver only on success.
func (*Time) UnmarshalText ¶
UnmarshalText parses wall-clock text, replacing the receiver only on success.
Source Files