chrono

package module
v0.0.0-...-f79ce8d Latest Latest
Warning

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

 Go to latest Published: Sep 13, 2024 License: MIT Imports: 5 Imported by: 2

README

chrono

A simple Go package for dividing time.Time into datetime, time, and date such that it becomes difficult to use any of these types incorrectly to access the excluded portions.

It is a goal of this package to expose an API surface that is very similar to the time.Time type, and re-use things like time.Duration and time.Month.

In addition to Marshaling/Unmarshaling interfaces, it also supports SQL interfaces directly, rather than relying on the driver's time.Time handling behavior.

Formatting

This package defaults to RFC3339 (ISO8601 compatible) inputs and outputs with the exception of SQL handling in which case it attempts to be closer to the SQL standard dialect of ISO8601.

Examples

// Creating values
datetime := chrono.NewDateTime(2000, 1, 2, 3, 4, 5, 10, time.UTC)
date := chrono.NewDate(2000, 1, 2)
time := chrono.NewDateTime(3, 4, 5, 10, time.UTC)

// Unix timestamp interop
datetime = chrono.DateTimeFromUnix(1655610143, 0)
date = chrono.DateFromUnix(1655610143, 0)
time = chrono.TimeFromUnix(1655610143, 0)

// Creating values from strings (RFC3339), see 'Layout' variant functions for
// functionality from the std library for parsing custom formats.
datetime = chrono.DateTimeFromString("2000-01-02T03:04:05Z")
date = chrono.DateTimeFromString("2000-01-02")
time = chrono.DateTimeFromString("03:04:05Z")

// Conversion from/to time.Time
datetime = chrono.DateTimeFromStdTime(time.Now())
date = chrono.DateFromStdTime(time.Now())
time = chrono.TimeFromStdTime(time.Now())
datetime.ToStdTime()
date.ToStdTime()
time.ToStdTime()

// Conversions between DateTime/Date/Time
datetime = chrono.DateTimeFromStdTime(time.Now())
date = datetime.ToDate()
time = datetime.ToTime()

// Additional comparisons on top of the stdlib After/Before/Equal
datetime.AfterOrEqual(datetime)
datetime.BeforeOrEqual(datetime)
datetime.Between(datetime)
datetime.BetweenOrEqual(datetime)

// Formatting is all done with RFC3339 parts
datetime.String() // "2000-01-02T03:04:05Z"
date.String()     // "2000-01-02"
time.String()     // "03:04:05Z"

Documentation

Index

Constants

View Source 
const (
	// DateTimeSQLLayout is exported so you can change this for your project
	// but the default should be sufficient. It used microsecond precision
	// to align with postgresq/mysql.
	DateTimeSQLLayout = "2006-01-02 15:04:05.999999-07"
)
View Source 
const (

	// TimeSQLLayout is exported so you can change this for your project
	// but the default should be sufficient. It used microsecond precision
	// to align with postgresq/mysql.
	TimeSQLLayout = "15:04:05.999999-07"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Date 

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

Date type, based on time.Time.

func DateFromLayout 

func DateFromLayout(layout, str string) (Date, error)

DateFromLayout parses a Date from layout

func DateFromNow 

func DateFromNow() Date

DateFromNow returns a new date using the current date. It uses time.Now() as a reference date, discarding time information.

func DateFromStdTime 

func DateFromStdTime(t time.Time) Date

FromTime converts from the stdlib time.Time type, discarding time information

func DateFromString 

func DateFromString(str string) (Date, error)

DateFromString parses a Date from RFC3339 full-date

func DateFromUnix 

func DateFromUnix(sec int64, nsec int64) Date

DateFromUnix converts a unix timestamp in seconds into a date.

func DateFromUnixMicro 

func DateFromUnixMicro(usec int64) Date

DateFromUnixMicro converts a unix timestamp in microseconds into a date.

func DateFromUnixMilli 

func DateFromUnixMilli(msec int64) Date

DateFromUnixMilli converts a unix timestamp in milliseconds into a date.

func NewDate 

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

NewDate constructs a new date object from its components

func (Date) AddDate 

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

AddDate to the current date

func (Date) After 

func (d Date) After(rhs Date) bool

After returns true if d is after rhs

func (Date) AfterOrEqual 

func (d Date) AfterOrEqual(rhs Date) bool

AfterOrEqual returns true if d is equal to or after rhs

func (Date) AppendFormat 

func (d Date) AppendFormat(b []byte, layout string) []byte

AppendFormat is like Format but appends the textual representation to b and returns the extended buffer. Due to this package using time.Time the layout string is not checked for time-like parts that could be leaked out but will be zero.

func (Date) Before 

func (d Date) Before(rhs Date) bool

Before returns true if d is before rhs

func (Date) BeforeOrEqual 

func (d Date) BeforeOrEqual(rhs Date) bool

BeforeOrEqual returns true if d is equal to or before rhs

func (Date) Between 

func (d Date) Between(start, end Date) bool

Between returns true if d is in the exclusive time range (start, end)

func (Date) BetweenOrEqual 

func (d Date) BetweenOrEqual(start, end Date) bool

BetweenOrEqual returns true if d is in the inclusive time range [start, end]

func (Date) Date 

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

Date returns the date's components

func (Date) Day 

func (d Date) Day() int

Day returns the day of the month

func (Date) Equal 

func (d Date) Equal(rhs Date) bool

Equal returns true if rhs == d

func (Date) Format 

func (d Date) Format(layout string) string

Format using a layout string from time.Time. This can accidentally pull zero'd time information from the underlying time.Time so caution must be used.

func (Date) GoString 

func (d Date) GoString() string

GoString implements fmt.GoStringer

func (Date) ISOWeek 

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

ISOWeek returns the ISO 8601 year and week numbers.

func (Date) IsZero 

func (d Date) IsZero() bool

IsZero returns true if the Date is the zero value.

func (Date) MarshalBinary 

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

MarshalBinary implements the encoding.BinaryMarshaler interface. Is always a width of 32 bits (4 bytes).

func (Date) MarshalJSON 

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

MarshalJSON implements json.Marshaller

func (Date) MarshalText 

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

MarshalText implements encoding.TextMarshaller

func (Date) Month 

func (d Date) Month() time.Month

Month returns the month

func (*Date) Scan 

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

Scan implements sql.Scanner. SQL requires the use of ISO8601.

func (Date) String 

func (d Date) String() string

String returns an ISO8601 Date, also an RFC3339 full-date

func (Date) ToStdTime 

func (d Date) ToStdTime() time.Time

ToStdTime returns a time.Time with the time component zero'd out in UTC location.

func (Date) Unix 

func (d Date) Unix() int64

Unix timestamp

func (Date) UnixMicro 

func (d Date) UnixMicro() int64

UnixMicro returns a unix timestamp in microseconds

func (Date) UnixMilli 

func (d Date) UnixMilli() int64

UnixMilli returns a unix timestamp in milliseconds

func (Date) UnixNano 

func (d Date) UnixNano() int64

UnixNano returns a unix timestamp in nanoseconds

func (*Date) UnmarshalBinary 

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

UnmarshalBinary

func (*Date) UnmarshalJSON 

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

UnmarshalJSON parses a quoted ISO8601 date / RFC3339 full-date

func (*Date) UnmarshalText 

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

UnmarshalText parses a byte string with ISO8601 date / RFC3339 full-date

func (Date) Value 

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

Value implements driver.Valuer. SQL requires the use of ISO8601.

func (Date) Weekday 

func (d Date) Weekday() time.Weekday

Weekday returns the day of the week

func (Date) Year 

func (d Date) Year() int

Year returns the year

func (Date) YearDay 

func (d Date) YearDay() int

YearDay returns the day of the year

type DateTime 

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

DateTime is mostly a pass-through wrapper for time.Time. This allows nicer interoperability with the Time and Date types as well as a couple additional utility methods.

func DateTimeFromLayout 

func DateTimeFromLayout(layout, str string) (DateTime, error)

DateTimeFromString parses a date time by layout in the local location.

func DateTimeFromLayoutLocation 

func DateTimeFromLayoutLocation(layout, str string, loc *time.Location) (DateTime, error)

DateTimeFromStringLocation parses a date time by layout in the specified location.

func DateTimeFromNow 

func DateTimeFromNow() DateTime

DateTimeFromNow creates a new date time from the current moment in time (local).

func DateTimeFromStdTime 

func DateTimeFromStdTime(t time.Time) DateTime

DateTimeFromStdTime converts a time.Time into a datetime

func DateTimeFromString 

func DateTimeFromString(str string) (DateTime, error)

DateTimeFromString parses a date time (ISO8601/RFC3339 date-time) in the local location.

func DateTimeFromStringLocation 

func DateTimeFromStringLocation(str string, loc *time.Location) (DateTime, error)

DateTimeFromStringLocation parses a date time (ISO8601/RFC3339 date-time) in the specified location.

func DateTimeFromUnix 

func DateTimeFromUnix(sec int64, nsec int64) DateTime

Unix returns the local Time corresponding to the given Unix time

func DateTimeFromUnixMicro 

func DateTimeFromUnixMicro(usec int64) DateTime

UnixMicro returns the local Time corresponding to the given Unix time in microseconds

func DateTimeFromUnixMilli 

func DateTimeFromUnixMilli(msec int64) DateTime

UnixMicro returns the local Time corresponding to the given Unix time in milliseconds

func NewDateTime 

func NewDateTime(year int, month time.Month, day, hour, min, sec, nsec int, loc *time.Location) DateTime

NewDateTime from all components

func (DateTime) Add 

func (d DateTime) Add(dur time.Duration) DateTime

Add returns the time t+d.

func (DateTime) AddDate 

func (d DateTime) AddDate(years int, months int, days int) DateTime

AddDate to t and return

func (DateTime) After 

func (d DateTime) After(rhs DateTime) bool

After returns true if rhs is after d

func (DateTime) AfterOrEqual 

func (d DateTime) AfterOrEqual(rhs DateTime) bool

AfterOrEqual returns true if rhs is equal to or after d

func (DateTime) AppendFormat 

func (d DateTime) AppendFormat(b []byte, layout string) []byte

AppendFormat passes through to the underlying time.Time but.

func (DateTime) Before 

func (d DateTime) Before(rhs DateTime) bool

Before returns true if rhs is before d

func (DateTime) BeforeOrEqual 

func (d DateTime) BeforeOrEqual(rhs DateTime) bool

BeforeOrEqual returns true if rhs is before d

func (DateTime) Between 

func (d DateTime) Between(start, end DateTime) bool

Between returns true if d is in the exclusive time range (start, end)

func (DateTime) BetweenOrEqual 

func (d DateTime) BetweenOrEqual(start, end DateTime) bool

BetweenOrEqual returns true if d is in the inclusive time range [start, end]

func (DateTime) Clock 

func (d DateTime) Clock() (hour, min, sec int)

Clock returns the time components

func (DateTime) Date 

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

Date returns the DateTime's components

func (DateTime) Day 

func (d DateTime) Day() int

Day returns the day of the month

func (DateTime) Equal 

func (d DateTime) Equal(rhs DateTime) bool

Equal returns true if rhs == d

func (DateTime) Format 

func (d DateTime) Format(layout string) string

Format using a layout string from, same as time.Time

func (DateTime) GoString 

func (d DateTime) GoString() string

GoString implements fmt.GoStringer

func (*DateTime) GobDecode 

func (d *DateTime) GobDecode(data []byte) error

GobDecode passthrough

func (DateTime) GobEncode 

func (d DateTime) GobEncode() ([]byte, error)

GobEncode passthrough

func (DateTime) Hour 

func (d DateTime) Hour() int

Hour returns the hour

func (DateTime) ISOWeek 

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

ISOWeek returns the iso week

func (DateTime) In 

func (d DateTime) In(loc *time.Location) DateTime

In returns the DateTime in the specified location

func (DateTime) IsDST 

func (d DateTime) IsDST() bool

IsDST returns true if DST is active

func (DateTime) IsZero 

func (d DateTime) IsZero() bool

IsZero returns true if the Date is the zero value.

func (DateTime) Local 

func (d DateTime) Local() DateTime

Local returns the current date time in the local location

func (DateTime) Location 

func (d DateTime) Location() *time.Location

Location returns the DateTime's location

func (DateTime) MarshalBinary 

func (d DateTime) MarshalBinary() ([]byte, error)

MarshalBinary implements the encoding.BinaryMarshaler interface.

func (DateTime) MarshalJSON 

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

MarshalJSON implements json.Marshaller

func (DateTime) MarshalText 

func (d DateTime) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaller

func (DateTime) Minute 

func (d DateTime) Minute() int

Minute returns the minute of the hour

func (DateTime) Month 

func (d DateTime) Month() time.Month

Month returns the month

func (DateTime) Nanosecond 

func (d DateTime) Nanosecond() int

Nanosecond returns the nanosecond offset

func (DateTime) Round 

func (d DateTime) Round(dur time.Duration) DateTime

Round to the duration unit specified

func (*DateTime) Scan 

func (d *DateTime) Scan(value any) error

Scan implements sql.Scanner. SQL requires the use of ISO8601.

func (DateTime) Second 

func (d DateTime) Second() int

Second returns the second of the minute

func (DateTime) String 

func (d DateTime) String() string

String returns an ISO8601 DateTime, also an RFC3339 date-time

func (DateTime) Sub 

func (d DateTime) Sub(u DateTime) time.Duration

Sub returns the duration between the two times

func (DateTime) ToDate 

func (d DateTime) ToDate() Date

ToDate discards the time component of this datetime to convert it into a date.

The timezone is discarded along with the time, so the date will be whatever it was in the timezone, it is not converted to UTC or anything before the conversion.

func (DateTime) ToStdTime 

func (d DateTime) ToStdTime() time.Time

ToStdTime returns the same moment in time as a time.Time

func (DateTime) ToTime 

func (d DateTime) ToTime() Time

ToTime discards the date component of this datetime to convert it into a time.

func (DateTime) Truncate 

func (d DateTime) Truncate(dur time.Duration) DateTime

Truncate to the duration unit specified

func (DateTime) UTC 

func (d DateTime) UTC() DateTime

UTC returns the date time in UTC

func (DateTime) Unix 

func (d DateTime) Unix() int64

Unix timestamp

func (DateTime) UnixMicro 

func (d DateTime) UnixMicro() int64

UnixMicro returns a unix timestamp in microseconds

func (DateTime) UnixMilli 

func (d DateTime) UnixMilli() int64

UnixMilli returns a unix timestamp in milliseconds

func (DateTime) UnixNano 

func (d DateTime) UnixNano() int64

UnixNano returns a unix timestamp in nanoseconds

func (*DateTime) UnmarshalBinary 

func (d *DateTime) UnmarshalBinary(data []byte) error

UnmarshalBinary

func (*DateTime) UnmarshalJSON 

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

UnmarshalJSON parses a quoted ISO8601 DateTime / RFC3339 full-DateTime

func (*DateTime) UnmarshalText 

func (d *DateTime) UnmarshalText(data []byte) error

UnmarshalText parses a byte string with ISO8601 DateTime / RFC3339 full-DateTime

func (DateTime) Value 

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

Value implements driver.Valuer. SQL requires the use of ISO8601.

func (DateTime) Weekday 

func (d DateTime) Weekday() time.Weekday

Weekday returns the day of the week

func (DateTime) Year 

func (d DateTime) Year() int

Year returns the year

func (DateTime) YearDay 

func (d DateTime) YearDay() int

YearDay returns the day of the year

func (DateTime) Zone 

func (d DateTime) Zone() (name string, offset int)

type Time 

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

Time is mostly a pass-through wrapper for time.Time. This allows nicer interoperability with the Time and Date types as well as a couple additional utility methods.

func NewTime 

func NewTime(hour, min, sec, nsec int, loc *time.Location) Time

NewTime from all components

func TimeFromLayout 

func TimeFromLayout(layout, str string) (Time, error)

TimeFromString parses a time from a layout in the local location.

func TimeFromLayoutLocation 

func TimeFromLayoutLocation(layout, str string, loc *time.Location) (Time, error)

TimeFromStringLocation parses a time from a layout in the specified location.

func TimeFromNow 

func TimeFromNow() Time

TimeFromNow creates a new date time from the current moment in time (local).

func TimeFromStdTime 

func TimeFromStdTime(t time.Time) Time

TimeFromStdTime creates a time object discarding the stdlib time.Time's date information.

func TimeFromString 

func TimeFromString(str string) (Time, error)

TimeFromString parses a date time (ISO8601/RFC3339 date-time) in the local location.

func TimeFromStringLocation 

func TimeFromStringLocation(str string, loc *time.Location) (Time, error)

TimeFromStringLocation parses a date time (ISO8601/RFC3339 date-time) in the specified location.

func TimeFromUnix 

func TimeFromUnix(sec int64, nsec int64) Time

Unix returns the local Time corresponding to the given Unix time, discards the date information.

func TimeFromUnixMicro 

func TimeFromUnixMicro(usec int64) Time

UnixMicro returns the local Time corresponding to the given Unix time in microseconds. Discards the date information.

func TimeFromUnixMilli 

func TimeFromUnixMilli(msec int64) Time

UnixMicro returns the local Time corresponding to the given Unix time in milliseconds. Discards the date information.

func (Time) Add 

func (t Time) Add(dur time.Duration) Time

Add returns the time t+d.

func (Time) After 

func (t Time) After(rhs Time) bool

After returns true if rhs is after d

func (Time) AfterOrEqual 

func (t Time) AfterOrEqual(rhs Time) bool

AfterOrEqual returns true if rhs is equal to or after d

func (Time) AppendFormat 

func (t Time) AppendFormat(b []byte, layout string) []byte

AppendFormat is like Format but appends the textual representation to b and returns the extended buffer. Due to this package using time.Time the layout string is not checked for date-like parts that could be leaked out but will be zero.

func (Time) Before 

func (t Time) Before(rhs Time) bool

Before returns true if rhs is before d

func (Time) BeforeOrEqual 

func (t Time) BeforeOrEqual(rhs Time) bool

BeforeOrEqual returns true if rhs is before d

func (Time) Between 

func (t Time) Between(start, end Time) bool

Between returns true if t is in the exclusive time range (start, end)

func (Time) BetweenOrEqual 

func (t Time) BetweenOrEqual(start, end Time) bool

BetweenOrEqual returns true if t is in the inclusive time range [start, end]

func (Time) Clock 

func (t Time) Clock() (hour, min, sec int)

Clock returns the time components

func (Time) Equal 

func (t Time) Equal(rhs Time) bool

Equal returns true if rhs == d

func (Time) Format 

func (t Time) Format(layout string) string

Format using a layout string from time.Time. This can accidentally pull zero'd date information from the underlying time.Time so caution must be used.

func (Time) GoString 

func (t Time) GoString() string

GoString implements fmt.GoStringer

func (Time) Hour 

func (t Time) Hour() int

Hour returns the hour

func (Time) In 

func (t Time) In(loc *time.Location) Time

In returns the Time in the specified location

func (Time) IsDST 

func (t Time) IsDST() bool

IsDST returns true if DST is active

func (Time) IsZero 

func (t Time) IsZero() bool

IsZero returns true if the Date is the zero value.

func (Time) Local 

func (t Time) Local() Time

Local returns the current date time in the local location

func (Time) Location 

func (t Time) Location() *time.Location

Location returns the Time's location

func (Time) MarshalBinary 

func (t Time) MarshalBinary() ([]byte, error)

MarshalBinary implements the encoding.BinaryMarshaler interface. This is inefficient because it actually will use time.Time's entire MarshalBinary method which means that it will be much larger due to date information also being stored.

func (Time) MarshalJSON 

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

MarshalJSON implements json.Marshaller

func (Time) MarshalText 

func (t Time) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaller

func (Time) Minute 

func (t Time) Minute() int

Minute returns the minute of the hour

func (Time) Nanosecond 

func (t Time) Nanosecond() int

Nanosecond returns the nanosecond offset

func (Time) Round 

func (t Time) Round(dur time.Duration) Time

Round to the duration unit specified

func (*Time) Scan 

func (t *Time) Scan(value any) error

Scan implements sql.Scanner. SQL requires the use of ISO8601.

func (Time) Second 

func (t Time) Second() int

Second returns the second of the minute

func (Time) String 

func (t Time) String() string

String returns an ISO8601 Time, also an RFC3339 date-time

func (Time) Sub 

func (t Time) Sub(u Time) time.Duration

Sub returns the duration between the two times

func (Time) ToStdTime 

func (t Time) ToStdTime() time.Time

ToStdTime returns the time as a time.Time

func (Time) Truncate 

func (t Time) Truncate(dur time.Duration) Time

Truncate to the duration unit specified

func (Time) UTC 

func (t Time) UTC() Time

UTC returns the date time in UTC

func (*Time) UnmarshalBinary 

func (d *Time) UnmarshalBinary(data []byte) error

UnmarshalBinary

func (*Time) UnmarshalJSON 

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

UnmarshalJSON parses a quoted ISO8601 Time / RFC3339 full-time

func (*Time) UnmarshalText 

func (d *Time) UnmarshalText(data []byte) error

UnmarshalText parses a byte string with ISO8601 Time / RFC3339 full-time

func (Time) Value 

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

Value implements driver.Valuer

func (Time) Zone 

func (t Time) Zone() (name string, offset int)

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.