timestamp

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
  • func (optional Optional) MarshalJSON() ([]byte, error)
  • func (optional *Optional) Scan(value any) error
  • func (optional *Optional) UnmarshalJSON(data []byte) error
  • func (optional Optional) Value() (value driver.Value, err error)
• type UnixSeconds
  • func DeadlineFromTime(value time.Time) (UnixSeconds, error)
  • func FromTime(value time.Time) (UnixSeconds, error)
  • func FromUnix(seconds int64) (UnixSeconds, error)
  • func MustFromTime(value time.Time) 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)

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

func (optional Optional) MarshalJSON() ([]byte, error)

MarshalJSON encodes a present timestamp as a number and an absent one as null.

func (*Optional) Scan

func (optional *Optional) Scan(value any) error

Scan stores SQL NULL as absent and validates a present signed integer.

func (*Optional) UnmarshalJSON

func (optional *Optional) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes null as absent and a valid integer as present.

func (Optional) Value

func (optional Optional) Value() (value driver.Value, err error)

Value returns nil for an absent timestamp and a signed integer when 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.

func (UnixSeconds) Value

func (timestamp UnixSeconds) Value() (driver.Value, error)

Value returns a signed integer suitable for database/sql and SQLite.