timex

package module
v1.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 14, 2025 License: MIT Imports: 5 Imported by: 4

README

timex

Go Reference Go Report Card codecov

📅 A Go package that extends the standard library time with dedicated date and time-of-day types.

Why use timex?

timex is a lightweight and efficiently designed Go package that provides dedicated Date and TimeOfDay types. It's built with 100% unit test coverage and has no third-party dependencies, making it a reliable choice for time-related operations.

  • Missing Standard Library Types: Go's time package lacks distinct types for handling just a date or just a time of day. timex introduces Date and TimeOfDay to bridge this gap, offering a more intuitive and focused API for these specific use cases.
  • Simplicity and Clarity: Our Date type focuses exclusively on date operations (YYYY-MM-DD), avoiding timezone-related issues inherent in time.Time when only a calendar date matters. Similarly, TimeOfDay provides a clear HH:mm:ss format for operations strictly on time, independent of any particular date.
  • Lightweight & Efficient: timex is designed to be lean, with fast method implementations that often outperform time.Time for specific date and time-of-day calculations. It's built without any external dependencies, ensuring a minimal footprint.
  • Database & JSON Compatibility: Work directly with DATE and TIME types in databases like MySQL or PostgreSQL, and effortlessly serialize/deserialize these types to and from JSON.
  • Reliability: With 100% unit test coverage, you can be confident in the package's correctness and stability.

Getting Started

go get github.com/invzhi/timex

Reference

Documentation

Index

Constants

View Source 
const (
	// Deprecated: Use [RFC3339Date] instead.
	RFC3339 = RFC3339Date

	RFC3339Date = "YYYY-MM-DD"
)
View Source 
const (
	RFC3339Time = "HH:mm:ss"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Date 

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

Date represents a specific day in Gregorian calendar.

The zero value of type Date is January 1 of year 1.

func DateFromOrdinalDate 

func DateFromOrdinalDate(year, dayOfYear int) (Date, error)

DateFromOrdinalDate returns the date corresponding to year, day of year.

func DateFromTime 

func DateFromTime(t time.Time) Date

DateFromTime returns the date specified by t.

func MustDateFromOrdinalDate 

func MustDateFromOrdinalDate(year, dayOfYear int) Date

MustDateFromOrdinalDate is like DateFromOrdinalDate but panics if the date cannot be created.

func MustNewDate 

func MustNewDate(year, month, day int) Date

MustNewDate is like NewDate but panics if the date cannot be created.

func NewDate 

func NewDate(year, month, day int) (Date, error)

NewDate returns the date corresponding to year, month, and day.

func ParseDate 

func ParseDate(layout, value string) (Date, error)

ParseDate parses a formatted string and returns the date it represents. 

YY       01             Two-digit year
YYYY   2001             Four-digit year
M      1-12             Month, beginning at 1
MM    01-12             Month, 2-digits
MMM   Jan-Dec           The abbreviated month name
MMMM  January-December  The full month name
D      1-31             Day of month
DD    01-31             Day of month, 2-digits

func Today 

func Today(location *time.Location) Date

Today returns the current date in the given location.

func (Date) Add 

func (d Date) Add(years, months, days int) Date

Add returns the date corresponding to adding the given number of years, months, and days to d.

func (Date) AddDays 

func (d Date) AddDays(days int) Date

AddDays returns the date corresponding to adding the given number of days to d.

func (Date) After 

func (d Date) After(dd Date) bool

After reports whether the date d is after dd.

func (Date) Before 

func (d Date) Before(dd Date) bool

Before reports whether the date d is before dd.

func (Date) Date 

func (d Date) Date() (year, month, day int)

Date returns the year, month and day specified by d.

func (Date) Day 

func (d Date) Day() int

Day returns the day of month specified by d.

func (Date) DayOfYear 

func (d Date) DayOfYear() int

DayOfYear returns the day of year specified by d.

func (Date) Equal 

func (d Date) Equal(dd Date) bool

Equal reports whether the date d and dd is the same date.

func (Date) Format 

func (d Date) Format(layout string) string

Format returns a textual representation of the date. 

YY       01             Two-digit year
YYYY   2001             Four-digit year
M      1-12             Month, beginning at 1
MM    01-12             Month, 2-digits
MMM   Jan-Dec           The abbreviated month name
MMMM  January-December  The full month name
D      1-31             Day of month
DD    01-31             Day of month, 2-digits

func (Date) GoString 

func (d Date) GoString() string

GoString returns the Go syntax of the date.

func (Date) ISOWeek 

func (d Date) ISOWeek() (year, week int)

ISOWeek returns the ISO 8601 year and week number specified by d.

func (Date) IsZero 

func (d Date) IsZero() bool

IsZero reports whether the date d is the zero value, January 1 of year 1.

func (Date) MarshalJSON 

func (d Date) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface. The date is a quoted string in RFC 3339 format.

func (Date) Month 

func (d Date) Month() int

Month returns the month specified by d.

func (Date) OrdinalDate 

func (d Date) OrdinalDate() (year, dayOfYear int)

OrdinalDate returns the ordinal date specified by d.

func (Date) Quarter 

func (d Date) Quarter() int

Quarter returns the quarter specified by d.

func (*Date) Scan 

func (d *Date) Scan(value interface{}) (err error)

Scan implements the sql.Scanner interface.

func (Date) String 

func (d Date) String() string

String returns the textual representation of the date.

func (Date) Sub 

func (d Date) Sub(dd Date) int

Sub returns the days d-dd. If the result exceeds the integer scope, the maximum (or minimum) integer will be returned.

func (Date) Time 

func (d Date) Time(location *time.Location) time.Time

Time returns the time.Time specified by d in the given location.

func (*Date) UnmarshalJSON 

func (d *Date) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface. The date is expected to be a quoted string in RFC 3339 format.

func (Date) Value 

func (d Date) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

func (Date) Weekday 

func (d Date) Weekday() time.Weekday

Weekday returns the day of week specified by d.

func (Date) Year 

func (d Date) Year() int

Year returns the year specified by d.

type NullDate 

type NullDate struct {
	Date  Date
	Valid bool // Valid is true if Date is not NULL.
}

NullDate represents a specific day in Gregorian calendar that may be null. NullDate implements the sql.Scanner interface, so it can be used as a scan destination, similar to sql.NullString.

func (*NullDate) Scan 

func (d *NullDate) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

func (NullDate) Value 

func (d NullDate) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

type NullTimeOfDay added in v1.1.0 

type NullTimeOfDay struct {
	TimeOfDay TimeOfDay
	Valid     bool // Valid is true if TimeOfDay is not NULL.
}

NullTimeOfDay represents a specific time in a day that may be null. NullTimeOfDay implements the sql.Scanner interface, so it can be used as a scan destination, similar to sql.NullString.

func (*NullTimeOfDay) Scan added in v1.1.0 

func (t *NullTimeOfDay) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

func (NullTimeOfDay) Value added in v1.1.0 

func (t NullTimeOfDay) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

type ParseError 

type ParseError struct {
	Layout     string
	Value      string
	LayoutElem string
	ValueElem  string
}

ParseError describes a problem parsing a string.

func (*ParseError) Error 

func (e *ParseError) Error() string

Error returns the string representation of a ParseError.

type StringDate added in v1.1.0 

type StringDate struct {
	Date Date
}

StringDate is a wrapper of Date that represents zero date as empty string in JSON.

func (StringDate) MarshalJSON added in v1.1.0 

func (d StringDate) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface. The string date is an empty string or a quoted string in RFC 3339 format.

func (*StringDate) UnmarshalJSON added in v1.1.0 

func (d *StringDate) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface. The string date is expected to be an empty string or a quoted string in RFC 3339 format.

type TimeOfDay added in v1.1.0 

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

TimeOfDay represents a specific time in a day.

func MustNewTimeOfDay added in v1.1.0 

func MustNewTimeOfDay(hour, min, sec, nsec int) TimeOfDay

MustNewTimeOfDay is like NewTimeOfDay but panics if the time of day cannot be created.

func NewTimeOfDay added in v1.1.0 

func NewTimeOfDay(hour, min, sec, nsec int) (TimeOfDay, error)

NewTimeOfDay returns the time of day corresponding to hour, minute, second, and nanosecond.

func ParseTimeOfDay added in v1.1.0 

func ParseTimeOfDay(layout, value string) (TimeOfDay, error)

ParseTimeOfDay parses a formatted string and returns the time of day it represents. 

a   am/pm  ante meridiem or post meridiem
A   AM/PM  ante meridiem or post meridiem
H    0-23  Two-digit hour, 24-hour clock
HH  00-23  Hour, 24-hour clock
h    1-12  Two-digit hour, 12-hour clock
hh  01-12  Hour, 12-hour clock
m    0-59  Minute
mm  00-59  Minute, 2-digits
s    0-59  Second, including fraction
ss  00-59  Second, 2-digits, including fraction

func TimeOfDayFromTime added in v1.1.0 

func TimeOfDayFromTime(t time.Time) TimeOfDay

TimeOfDayFromTime returns the time of day specified by t.

func TimeOfDayNow added in v1.1.0 

func TimeOfDayNow(location *time.Location) TimeOfDay

TimeOfDayNow returns the current time of day in the given location.

func (TimeOfDay) Add added in v1.1.0 

func (t TimeOfDay) Add(hours, mins, secs, nsecs int) (int, TimeOfDay)

Add returns the exceeded days and the time of day corresponding to adding the given number of hours, minutes, seconds and nanoseconds to t.

func (TimeOfDay) AddDuration added in v1.1.0 

func (t TimeOfDay) AddDuration(d time.Duration) (int, TimeOfDay)

AddDuration returns the exceeded days and the time of day corresponding to adding the given time.Duration to t.

func (TimeOfDay) After added in v1.1.0 

func (t TimeOfDay) After(tt TimeOfDay) bool

After reports whether the time of day t is after tt.

func (TimeOfDay) Before added in v1.1.0 

func (t TimeOfDay) Before(tt TimeOfDay) bool

Before reports whether the time of day t is before tt.

func (TimeOfDay) Clock added in v1.1.0 

func (t TimeOfDay) Clock() (hour, min, sec, nsec int)

Clock returns the hour, minute, second and nanosecond specified by t.

func (TimeOfDay) Equal added in v1.1.0 

func (t TimeOfDay) Equal(tt TimeOfDay) bool

Equal reports whether the time of day t and tt is the same time.

func (TimeOfDay) Format added in v1.1.0 

func (t TimeOfDay) Format(layout string) string

Format returns a textual representation of the time of day. 

a   am/pm  ante meridiem or post meridiem
A   AM/PM  ante meridiem or post meridiem
H    0-23  Two-digit hour, 24-hour clock
HH  00-23  Hour, 24-hour clock
h    1-12  Two-digit hour, 12-hour clock
hh  01-12  Hour, 12-hour clock
m    0-59  Minute
mm  00-59  Minute, 2-digits
s    0-59  Second
ss  00-59  Second, 2-digits

func (TimeOfDay) GoString added in v1.1.0 

func (t TimeOfDay) GoString() string

GoString returns the Go syntax of the time of day.

func (TimeOfDay) Hour added in v1.1.0 

func (t TimeOfDay) Hour() int

Hour returns the hour specified by t.

func (TimeOfDay) IsZero added in v1.1.0 

func (t TimeOfDay) IsZero() bool

IsZero reports whether the time of day t is the zero value, 00:00:00.

func (TimeOfDay) MarshalJSON added in v1.1.0 

func (t TimeOfDay) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface. The time of day is a quoted string in RFC 3339 format.

func (TimeOfDay) Minute added in v1.1.0 

func (t TimeOfDay) Minute() int

Minute returns the minute specified by t.

func (TimeOfDay) Nanosecond added in v1.1.0 

func (t TimeOfDay) Nanosecond() int

Nanosecond returns the nanosecond specified by t.

func (*TimeOfDay) Scan added in v1.1.0 

func (t *TimeOfDay) Scan(value interface{}) (err error)

Scan implements the sql.Scanner interface.

func (TimeOfDay) Second added in v1.1.0 

func (t TimeOfDay) Second() int

Second returns the second specified by t.

func (TimeOfDay) String added in v1.1.0 

func (t TimeOfDay) String() string

String returns the textual representation of the time of day.

func (TimeOfDay) Sub added in v1.1.0 

func (t TimeOfDay) Sub(tt TimeOfDay) time.Duration

Sub returns the duration t-tt.

func (*TimeOfDay) UnmarshalJSON added in v1.1.0 

func (t *TimeOfDay) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface. The time of day is expected to be a quoted string in RFC 3339 format.

func (TimeOfDay) Value added in v1.1.0 

func (t TimeOfDay) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.