date

README

date

Provides a data type Date that represents a day-precision point in time.

Date is conceptually similar to Unix time (also known as POSIX time or Unix Epoch time). But rather than operating at second-level precision, it operates at day-level precision. Under the hood, Date is an integer type that represents the number of days elapsed since the epoch date 1970-01-01.

date.Date leverages much of its functionality from the time package.

Features

• Since Date is an integer type, the normal integer comparison and equality/inequality operators all work out of the box.

• Conversions to and from ISO8601 (YYYY-MM-DD) string format.

• Conversion to and from time.Time values.

• Day, month, and year arithmetic (can add or subtract years, months, days from a Date).

• Common date related operations, such as finding the start of a month, start of a quarter etc.

• JSON marshal/unmarshal support.

• SQL marshal/unmarshal support.

Documentation

Index

• func Diff(d1, d2 Date) (year int, month int, day int)
• type Date
  • func FromString(str string) (Date, error)
  • func FromTime(t time.Time) Date
  • func Max(d1, d2 Date) Date
  • func Min(d1, d2 Date) Date
  • func MustFromString(str string) Date
  • func New(year int, month time.Month, day int) Date
  • func Today() Date
  • func TodayIn(loc *time.Location) Date
  • func Tomorrow() Date
  • func TomorrowIn(loc *time.Location) Date
  • func Yesterday() Date
  • func YesterdayIn(loc *time.Location) Date
  • func (d Date) AddCalendarMonths(months int) Date
  • func (d Date) AddDays(days int) Date
  • func (d Date) AddMonths(months int) Date
  • func (d Date) AddYears(years int) Date
  • func (d Date) Day() int
  • func (d Date) DaysInMonth() int
  • func (d Date) DaysInYear() int
  • func (d Date) EndOfMonth() Date
  • func (d Date) MarshalJSON() ([]byte, error)
  • func (d Date) Month() time.Month
  • func (d *Date) Scan(src any) error
  • func (d Date) StartOfMonth() Date
  • func (d Date) StartOfNextQuarter() Date
  • func (d Date) StartOfQuarter() Date
  • func (d Date) String() string
  • func (d Date) Time() time.Time
  • func (d Date) TimeIn(loc *time.Location) time.Time
  • func (d *Date) UnmarshalJSON(p []byte) error
  • func (d Date) Value() (driver.Value, error)
  • func (d Date) Weekday() time.Weekday
  • func (d Date) Year() int
  • func (d Date) YearDay() int
• type NullDate
  • func NewNullDate(d Date) NullDate
  • func (d NullDate) MarshalJSON() ([]byte, error)
  • func (d NullDate) Scan(value any) error
  • func (d NullDate) UnmarshalJSON(dateBytes []byte) error
  • func (d NullDate) Value() (driver.Value, error)
• type NullDateJsonField
• type NullDateSqlField

Functions

func Diff

func Diff(d1, d2 Date) (year int, month int, day int)

Diff finds the difference in years, months, and days between two provided dates. The dates can be provided in any order, or can be equal.

Returns 3 integers representing the number of years, months, and days separating the two dates. These values are non-contiguous and should be taken as standalone values, e.g., the diff between Feb 1st 2001 and March 1st 2002 would be 1 year, 13 months, and 393 days.

Types

type Date

type Date int

Date represents a calendar day (and thus has day precision). It's stored as the number of days since the epoch date 1970-01-01. It can be negative, to represent dates before the epoch. Because it's a date, it doesn't exist within any particular timezone.

func FromString

func FromString(str string) (Date, error)

FromString creates a date from its ISO8601 (YYYY-MM-DD) representation.

func FromTime

func FromTime(t time.Time) Date

FromTime creates a Date by truncating away the time of day portion of a time.Time.

func Max

func Max(d1, d2 Date) Date

Max finds the maximum date (furthest in the direction of the future) out of the two given dates.

func Min

func Min(d1, d2 Date) Date

Min finds the minimum date (furthest in the direction of the past) out of the two given dates.

func MustFromString

func MustFromString(str string) Date

MustFromString creates a date from its ISO8601 (YYYY-MM-DD) representation. It panics if str is not in the right format.

func New

func New(year int, month time.Month, day int) Date

New creates a day given a year, month, and day.

func Today

func Today() Date

Today gives today's date.

func TodayIn

func TodayIn(loc *time.Location) Date

TodayIn gives today's date in given timezone.

func Tomorrow

func Tomorrow() Date

Tomorrow gives tomorrow's date.

func TomorrowIn

func TomorrowIn(loc *time.Location) Date

Tomorrow gives tomorrow's date in given timezone.

func Yesterday

func Yesterday() Date

Yesterday gives yesterday's date.

func YesterdayIn

func YesterdayIn(loc *time.Location) Date

Yesterday gives yesterday's date in given timezone.

func (Date) AddCalendarMonths

func (d Date) AddCalendarMonths(months int) Date

AddCalendarMonths adds the number of specified months to create a new date. This function does not allow rollover and dates are clamped to the end of the month. e.g. adding 1 month to 2025-03-31 will result in 2025-04-30 rather than 2025-05-01 with the AddMonths function.

func (Date) AddDays

func (d Date) AddDays(days int) Date

AddDays adds the number of specified days to create a new date. Since Dates are just integers representing the number of days since 1970-01-01, the usual `+` operator can be used instead.

func (Date) AddMonths

func (d Date) AddMonths(months int) Date

AddMonths adds the number of specified months to create a new date. Dates are normalized in the same way as `AddDate` in the `time` package.

func (Date) AddYears

func (d Date) AddYears(years int) Date

AddYears adds the number of specified years to create a new date. Dates are normalized in the same way as `AddDate` in the `time` package.

func (Date) Day

func (d Date) Day() int

Day gives the day of the month (1-31).

func (Date) DaysInMonth

func (d Date) DaysInMonth() int

DaysInMonth gives the number of days in the current month

func (Date) DaysInYear

func (d Date) DaysInYear() int

DaysInYear gives how many total days the year has (365/366)

func (Date) EndOfMonth

func (d Date) EndOfMonth() Date

EndOfMonth gives the date that is the last day of the current month.

func (Date) MarshalJSON

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

MarshalJSON marshals the date into a JSON string in ISO8601 format.

func (Date) Month

func (d Date) Month() time.Month

Month gives the month the date is in.

func (*Date) Scan

func (d *Date) Scan(src any) error

Scan implements the sql.Scanner interface, allowing the sql package to read sql dates into Date.

func (Date) StartOfMonth

func (d Date) StartOfMonth() Date

StartOfMonth gives the date that is the 1st day of the current month.

func (Date) StartOfNextQuarter

func (d Date) StartOfNextQuarter() Date

StartOfNextQuarter gives the date that is the 1st day of the next quarter (starting in Jan, Apr, Jul, or Oct).

func (Date) StartOfQuarter

func (d Date) StartOfQuarter() Date

StartOfQuarter gives the date that is the 1st day of the current quarter (starting in Jan, Apr, Jul, or Oct).

func (Date) String

func (d Date) String() string

String returns the ISO8601 representation (YYYY-MM-DD).

func (Date) Time

func (d Date) Time() time.Time

Time returns a time.Time at midnight at the start of the date in the UTC timezone.

func (Date) TimeIn

func (d Date) TimeIn(loc *time.Location) time.Time

TimeIn returns a time.Time at midnight at the start of the date in the Location specified.

func (*Date) UnmarshalJSON

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

UnmarshalJSON unmarshals a JSON string in the ISO8601 format into a date.

func (Date) Value

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

Value implements the driver.Valuer interface, allowing sql drivers to send Dates to sql databases.

func (Date) Weekday

func (d Date) Weekday() time.Weekday

Weekday gives the day of the week that the date falls on.

func (Date) Year

func (d Date) Year() int

Year gives the year the date is in.

func (Date) YearDay

func (d Date) YearDay() int

YearDay gives how many days into the year the date is (1-365).

type NullDate

type NullDate struct {
	Date  Date
	Valid bool
}

NullDate represents a nullable date with compatibility for scanning null values from the database.

func NewNullDate

func NewNullDate(d Date) NullDate

func (NullDate) MarshalJSON

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

MarshalJSON implements the json.Marshaler interface.

func (NullDate) Scan

func (d NullDate) Scan(value any) error

Scan implements the sql.Scanner interface for database deserialization.

func (NullDate) UnmarshalJSON

func (d NullDate) UnmarshalJSON(dateBytes []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

func (NullDate) Value

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

Value implements the driver.Valuer interface for database serialization.

type NullDateJsonField

type NullDateJsonField interface {
	json.Unmarshaler
	json.Marshaler
}

NullDate should properly implement UnmarshalJSON and MarshalJSON

type NullDateSqlField

type NullDateSqlField interface {
	sql.Scanner
	driver.Valuer
}

NullDate should properly implement Scan and Value