Documentation
¶
Overview ¶
Package timestamp provides compact durable wall-clock timestamps.
UnixSeconds stores a UTC instant as whole seconds since 1970-01-01T00:00:00Z. Its range is 0 through 4294967295, ending at 2106-02-07T06:28:15Z. Observed instants are floored to their containing second, while deadlines and duration additions are rounded upward so they are never encoded earlier than the source instant. Zero is the Unix epoch, not an absent value; use Optional when absence is meaningful.
Index ¶
- type Optional
- type UnixSeconds
- func (timestamp UnixSeconds) Add(duration time.Duration) (UnixSeconds, error)
- func (timestamp UnixSeconds) After(other UnixSeconds) bool
- func (timestamp UnixSeconds) Before(other UnixSeconds) bool
- func (timestamp UnixSeconds) Compare(other UnixSeconds) int
- func (timestamp UnixSeconds) Equal(other UnixSeconds) bool
- func (timestamp UnixSeconds) Format(layout string) string
- func (timestamp UnixSeconds) MarshalJSON() ([]byte, error)
- func (timestamp *UnixSeconds) Scan(value any) error
- func (timestamp UnixSeconds) Sub(other UnixSeconds) time.Duration
- func (timestamp UnixSeconds) Time() time.Time
- func (timestamp UnixSeconds) Unix() int64
- func (timestamp *UnixSeconds) UnmarshalJSON(data []byte) error
- func (timestamp UnixSeconds) Value() (driver.Value, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Optional ¶
type Optional struct {
UnixSeconds UnixSeconds
Valid bool
}
Optional represents a UnixSeconds value that may be absent. Its zero value is absent; a present Unix epoch has Valid set to true.
func (Optional) MarshalJSON ¶
MarshalJSON encodes a present timestamp as a number and an absent one as null.
func (*Optional) UnmarshalJSON ¶
UnmarshalJSON decodes null as absent and a valid integer as present.
type UnixSeconds ¶
type UnixSeconds uint32
UnixSeconds is a compact UTC Unix timestamp with one-second resolution.
const (
Max UnixSeconds = 1<<32 - 1
)
Max is the latest instant representable by UnixSeconds.
func DeadlineFromTime ¶
func DeadlineFromTime(value time.Time) (UnixSeconds, error)
DeadlineFromTime converts a deadline by rounding it up to the next second when it has a fractional component. It rejects source instants outside the representable range, even when rounding could move them into range.
func FromTime ¶
func FromTime(value time.Time) (UnixSeconds, error)
FromTime converts an observed instant by flooring it to its containing second.
func FromUnix ¶
func FromUnix(seconds int64) (UnixSeconds, error)
FromUnix validates seconds before converting them to UnixSeconds.
func MustFromTime ¶
func MustFromTime(value time.Time) UnixSeconds
MustFromTime converts an observed instant or panics. It is intended for static fixtures and tests whose timestamps are known to be in range.
func (UnixSeconds) Add ¶
func (timestamp UnixSeconds) Add(duration time.Duration) (UnixSeconds, error)
Add returns the timestamp plus duration, rounded upward to whole seconds. It rejects exact results outside the UnixSeconds range before narrowing.
func (UnixSeconds) After ¶
func (timestamp UnixSeconds) After(other UnixSeconds) bool
After reports whether timestamp occurs after other.
func (UnixSeconds) Before ¶
func (timestamp UnixSeconds) Before(other UnixSeconds) bool
Before reports whether timestamp occurs before other.
func (UnixSeconds) Compare ¶
func (timestamp UnixSeconds) Compare(other UnixSeconds) int
Compare compares timestamp with other and returns -1, 0, or 1.
func (UnixSeconds) Equal ¶
func (timestamp UnixSeconds) Equal(other UnixSeconds) bool
Equal reports whether timestamp and other represent the same instant.
func (UnixSeconds) Format ¶
func (timestamp UnixSeconds) Format(layout string) string
Format formats the timestamp in UTC for presentation using a time layout.
func (UnixSeconds) MarshalJSON ¶
func (timestamp UnixSeconds) MarshalJSON() ([]byte, error)
MarshalJSON encodes timestamp as a JSON number.
func (*UnixSeconds) Scan ¶
func (timestamp *UnixSeconds) Scan(value any) error
Scan validates and stores a signed SQL integer. NULL and all other SQL storage classes are invalid for a required timestamp.
func (UnixSeconds) Sub ¶
func (timestamp UnixSeconds) Sub(other UnixSeconds) time.Duration
Sub returns the signed duration from other to timestamp.
func (UnixSeconds) Time ¶
func (timestamp UnixSeconds) Time() time.Time
Time returns the UTC standard-library representation for presentation and APIs that require time.Time.
func (UnixSeconds) Unix ¶
func (timestamp UnixSeconds) Unix() int64
Unix returns the timestamp as signed Unix seconds for boundary operations.
func (*UnixSeconds) UnmarshalJSON ¶
func (timestamp *UnixSeconds) UnmarshalJSON(data []byte) error
UnmarshalJSON decodes a JSON integer after validating its range.
Source Files