timex

README

timex

Better time package for Go.

Rationale

TODO

Features

• Simple.

See GUIDE.md for more details.

Install

Go version 1.17+

go get github.com/cristalhq/timex

Example

TODO

Documentation

See these docs.

License

MIT License.

Documentation

Index

• Constants
• func Compare(a, b time.Time) int
• func DropDate(t time.Time) time.Time
• func DropTime(t time.Time) time.Time
• func Max(values ...time.Time) time.Time
• func Min(values ...time.Time) time.Time
• func Now() time.Time
• func Parse(value string, layouts ...string) (time.Time, error)
• func ParseInZone(zone *Zone, value string, layouts ...string) (time.Time, error)
• type Clock
• type Dur
• type ManualClock
  • func NewManualClock(curr time.Time) *ManualClock
  • func (c *ManualClock) Add(d time.Duration)
  • func (c *ManualClock) Now() time.Time
  • func (c *ManualClock) Set(t time.Time)
• type Range
  • func NewRange(start, finish time.Time) (Range, error)
  • func ParseRange(s string) (Range, error)
  • func ParseRangeInZone(s string, zone *time.Location) (Range, error)
  • func (r Range) Has(t time.Time) bool
  • func (r Range) Intersect(other Range) (Range, bool)
  • func (r Range) IsEmpty() bool
  • func (r Range) IsValid() bool
  • func (r Range) MarshalJSON() ([]byte, error)
  • func (r Range) MarshalText() ([]byte, error)
  • func (r Range) Overlaps(other Range) bool
  • func (r Range) Span() Span
  • func (r Range) String() string
  • func (r *Range) UnmarshalJSON(data []byte) error
  • func (r *Range) UnmarshalText(data []byte) error
• type Span
  • func ParseSpan(s string) (Span, error)
  • func (s Span) Dur() time.Duration
  • func (s Span) MarshalJSON() ([]byte, error)
  • func (s Span) MarshalText() ([]byte, error)
  • func (s Span) Mul(x float64) Span
  • func (s Span) String() string
  • func (s *Span) UnmarshalJSON(data []byte) error
  • func (s *Span) UnmarshalText(text []byte) error
• type Spans
  • func (ss Spans) Durs() []time.Duration
  • func (ss Spans) String() string
  • func (ss Spans) Strings() []string
• type SystemClock
  • func (SystemClock) Now() time.Time
• type Timestamp
  • func AsTimestamp(t time.Time) Timestamp
  • func TimestampFromMilli(msec int64) Timestamp
  • func TimestampFromString(s string) (Timestamp, error)
  • func (ts Timestamp) MarshalJSON() ([]byte, error)
  • func (ts *Timestamp) UnmarshalJSON(b []byte) error
• type UTCClock
  • func (UTCClock) Now() time.Time
• type Zone
  • func MustZone(zone string) *Zone

Constants

const (
	Week        = 7 * Day
	Day         = 24 * Hour
	HalfDay     = 12 * Hour
	Hour        = time.Hour
	Minute      = time.Minute
	Second      = time.Second
	Millisecond = time.Millisecond
	Microsecond = time.Microsecond
	Nanosecond  = time.Nanosecond
)

Functions

func Compare

func Compare(a, b time.Time) int

Compare function for two time.Time instances.

func DropDate

func DropDate(t time.Time) time.Time

DropDate replaces the date with January 1, year 0. It preserves the clock components and location.

func DropTime

func DropTime(t time.Time) time.Time

DropTime replaces the clock components with midnight. It preserves the date and location.

func Max

func Max(values ...time.Time) time.Time

Max returns the latest nonzero time. It returns the zero time if there are no nonzero values.

func Min

func Min(values ...time.Time) time.Time

Min returns the earliest nonzero time. It returns the zero time if there are no nonzero values.

func Now

func Now() time.Time

Now returns currect time.

func Parse

func Parse(value string, layouts ...string) (time.Time, error)

Parse value using the first matching layout. At least one layout is required.

func ParseInZone

func ParseInZone(zone *Zone, value string, layouts ...string) (time.Time, error)

ParseInZone value using the first matching layout. At least one layout is required.

Types

type Clock

type Clock interface {
	Now() time.Time
}

Clock provides the current time.

type Dur

type Dur = time.Duration

Dur is an alias for time.Duration.

type ManualClock

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

ManualClock is a clock that can be controlled manually. Its zero value returns the zero time. Methods are safe for concurrent use. A ManualClock must not be copied after first use.

func NewManualClock

func NewManualClock(curr time.Time) *ManualClock

NewManualClock returns a manual clock initialized to curr.

func (*ManualClock) Add

func (c *ManualClock) Add(d time.Duration)

Add advances the clock by the given duration.

func (*ManualClock) Now

func (c *ManualClock) Now() time.Time

Now returns the clock's current time.

func (*ManualClock) Set

func (c *ManualClock) Set(t time.Time)

Set replaces the clock's current time.

type Range

type Range struct {
	Start  time.Time
	Finish time.Time
}

Range represents a half-open interval [Start, Finish). Equal endpoints form a valid empty range. The zero value is a valid empty range.

func NewRange

func NewRange(start, finish time.Time) (Range, error)

NewRange returns an error if finish is before start.

func ParseRange

func ParseRange(s string) (Range, error)

func ParseRangeInZone

func ParseRangeInZone(s string, zone *time.Location) (Range, error)

func (Range) Has

func (r Range) Has(t time.Time) bool

Has reports whether t belongs to [Start, Finish). Invalid and empty ranges contain no instants.

func (Range) Intersect

func (r Range) Intersect(other Range) (Range, bool)

Intersect returns the non-empty intersection of the ranges. If there is no intersection, it returns Range{} and false.

func (Range) IsEmpty

func (r Range) IsEmpty() bool

IsEmpty reports whether the endpoints represent the same instant.

func (Range) IsValid

func (r Range) IsValid() bool

IsValid reports whether Finish is at or after Start.

func (Range) MarshalJSON

func (r Range) MarshalJSON() ([]byte, error)

MarshalJSON encodes the range as a JSON string in UTC.

func (Range) MarshalText

func (r Range) MarshalText() ([]byte, error)

MarshalText encodes the range with both endpoints in UTC.

func (Range) Overlaps

func (r Range) Overlaps(other Range) bool

Overlaps reports whether the ranges share a non-empty interval. Adjacent, empty, and invalid ranges do not overlap.

func (Range) Span

func (r Range) Span() Span

Span returns Finish.Sub(Start). Invalid ranges produce a negative duration. Results outside Span's range saturate, following time.Time.Sub.

func (Range) String

func (r Range) String() string

String formats the range using its endpoints' local dates and clocks.

The date is omitted when both endpoints have date 0001-01-01. A shared date is printed once; different dates are printed separately. Seconds are included for both endpoints if either has seconds or nanoseconds. Fractional seconds are printed only when non-zero.

Timezone information is omitted. Use endpoints in the same location when an unambiguous local display is required.

func (*Range) UnmarshalJSON

func (r *Range) UnmarshalJSON(data []byte) error

func (*Range) UnmarshalText

func (r *Range) UnmarshalText(data []byte) error

type Span

type Span time.Duration

Span represents a duration in nanoseconds. Similar to time.Duration but with improved marshaling.

func ParseSpan

func ParseSpan(s string) (Span, error)

ParseSpan parses a duration using time.ParseDuration.

func (Span) Dur

func (s Span) Dur() time.Duration

Dur returns a time.Duration.

func (Span) MarshalJSON

func (s Span) MarshalJSON() ([]byte, error)

func (Span) MarshalText

func (s Span) MarshalText() ([]byte, error)

func (Span) Mul

func (s Span) Mul(x float64) Span

Mul returns s multiplied by x.

The calculation uses float64 and may lose precision for large durations. Both x and the product must be finite, and the product must be in [-2^63, 2^63). These requirements are not checked.

func (Span) String

func (s Span) String() string

String returns the duration formatted like time.Duration.String Omits zero minutes and zero seconds. For example, 1h0m0s becomes 1h, and 1m0s becomes 1m.

func (*Span) UnmarshalJSON

func (s *Span) UnmarshalJSON(data []byte) error

func (*Span) UnmarshalText

func (s *Span) UnmarshalText(text []byte) error

type Spans

type Spans []Span

Spans is a slice of Span.

func (Spans) Durs

func (ss Spans) Durs() []time.Duration

Durs returns each span as a time.Duration.

func (Spans) String

func (ss Spans) String() string

func (Spans) Strings

func (ss Spans) Strings() []string

type SystemClock

type SystemClock struct{}

SystemClock provides the current local time, including its monotonic reading.

func (SystemClock) Now

func (SystemClock) Now() time.Time

Now returns the current local time.

type Timestamp

type Timestamp struct {
	time.Time
}

func AsTimestamp

func AsTimestamp(t time.Time) Timestamp

AsTimestamp returns time.Time wrapped as Timestamp.

func TimestampFromMilli

func TimestampFromMilli(msec int64) Timestamp

TimestampFromMilli returns Timestamp from the Unix time in milliseconds.

func TimestampFromString

func TimestampFromString(s string) (Timestamp, error)

TimestampFromString returns Timestamp fomr the string representing Unix time.

func (Timestamp) MarshalJSON

func (ts Timestamp) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler interface.

func (*Timestamp) UnmarshalJSON

func (ts *Timestamp) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler interface.

type UTCClock

type UTCClock struct{}

UTCClock provides the current time in UTC. Its results do not contain a monotonic clock reading.

func (UTCClock) Now

func (UTCClock) Now() time.Time

Now returns the current time in UTC.

type Zone

type Zone = time.Location

Zone is an alias for time.Location.

func MustZone

func MustZone(zone string) *Zone