Skip to content

Commit 053680b

Browse files
author
Danny Hermes
authored
Add more time.Time{} methods to Date{}. (#4)
- Added new methods that are also present on `time.Time{}`: `Compare()`, `ISOWeek()`, `Weekday()`, `GoString()`, `UnmarshalText()`, `MarshalText()` - Added other new method: `MonthStart()` (goes with `MonthEnd()`) - Allow setting **ALL** fields in `time.Date()` via `ConvertConfig{}` (new options + fields for hour, minute, second, nanosecond) - Stop handling `nil` pointer / allowing pointer receiver in `String()` (matches `time.Time{}.String()` and lots of other types) - Rearrange code and tests by logical grouping (e.g. Add + Sub together) - Use "direct" implementation for `AddYears()` and `AddYearsStdlib()` - Update `README.md` with examples and context about `pgtype.Date` - This is a "sync" PR (from internal an codebase to this one)
1 parent ef655e9 commit 053680b

File tree

7 files changed

+658
-142
lines changed

7 files changed

+658
-142
lines changed

‎README.md

+193-2
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ standard library `time.Time{}` behavior.
1212
This package provides helpers for:
1313

1414
- conversion: `ToTime()`, `date.FromTime()`, `date.FromString()`
15-
- serialization: JSON and SQL
15+
- serialization: text, JSON, and SQL
1616
- emulating `time.Time{}`: `After()`, `Before()`, `Sub()`, etc.
1717
- explicit null handling: `NullDate{}` and an analog of `sql.NullTime{}`
1818
- emulating `time` helpers: `Today()` as an analog of `time.Now()`
@@ -22,7 +22,190 @@ This package provides helpers for:
2222
The Go standard library contains no native type for dates without times.
2323
Instead, common convention is to use a `time.Time{}` with only the year, month,
2424
and day set. For example, this convention is followed when a timestamp of the
25-
form YYYY-MM-DD is parsed via `time.Parse(time.DateOnly, s)`.
25+
form YYYY-MM-DD is parsed via `time.Parse(time.DateOnly, value)`.
26+
27+
## Conversion
28+
29+
For cases where existing code produces a "conventional"
30+
`time.Date(YYYY, MM, DD, 0, 0, 0, 0, time.UTC)` value, it can be validated
31+
and converted to a `Date{}` via:
32+
33+
```go
34+
t := time.Date(2024, time.March, 1, 0, 0, 0, 0, time.UTC)
35+
d, err := date.FromTime(t)
36+
fmt.Println(d, err)
37+
// 2024-03-01 <nil>
38+
```
39+
40+
If there is any deviation from the "conventional" format, this will error.
41+
For example:
42+
43+
```text
44+
timestamp contains more than just date information; 2020-05-11T01:00:00Z
45+
timestamp contains more than just date information; 2022-01-31T00:00:00-05:00
46+
```
47+
48+
For cases where we have a discrete timestamp (e.g. "last updated datetime") and
49+
a relevant timezone for a given request, we can extract the date within that
50+
timezone:
51+
52+
```go
53+
t := time.Date(2023, time.April, 14, 3, 55, 4, 777000100, time.UTC)
54+
tz, _ := time.LoadLocation("America/Chicago")
55+
d := date.InTimezone(t, tz)
56+
fmt.Println(d)
57+
// 2023-04-13
58+
```
59+
60+
For conversion in the **other** direction, a `Date{}` can be converted back
61+
into a `time.Time{}`:
62+
63+
```go
64+
d := date.NewDate(2017, time.July, 3)
65+
t := d.ToTime()
66+
fmt.Println(t)
67+
// 2017-07-03 00:00:00 +0000 UTC
68+
```
69+
70+
By default this will use the "conventional" format, but any of the values
71+
(other than year, month, day) can also be set:
72+
73+
```go
74+
d := date.NewDate(2017, time.July, 3)
75+
tz, _ := time.LoadLocation("America/Chicago")
76+
t := d.ToTime(date.OptConvertHour(12), date.OptConvertTimezone(tz))
77+
fmt.Println(t)
78+
// 2017-07-03 12:00:00 -0500 CDT
79+
```
80+
81+
## Equivalent methods
82+
83+
There are a number of methods from `time.Time{}` that directly translate over:
84+
85+
```go
86+
d := date.NewDate(2020, time.February, 29)
87+
fmt.Println(d.Year)
88+
// 2020
89+
fmt.Println(d.Month)
90+
// February
91+
fmt.Println(d.Day)
92+
// 29
93+
fmt.Println(d.ISOWeek())
94+
// 2020 9
95+
fmt.Println(d.Weekday())
96+
// Saturday
97+
98+
fmt.Println(d.IsZero())
99+
// false
100+
fmt.Println(d.String())
101+
// 2020-02-29
102+
fmt.Println(d.Format("Jan 2006"))
103+
// Feb 2020
104+
fmt.Println(d.GoString())
105+
// date.NewDate(2020, time.February, 29)
106+
107+
d2 := date.NewDate(2021, time.February, 28)
108+
fmt.Println(d2.Equal(d))
109+
// false
110+
fmt.Println(d2.Before(d))
111+
// false
112+
fmt.Println(d2.After(d))
113+
// true
114+
fmt.Println(d2.Compare(d))
115+
// 1
116+
```
117+
118+
However, some methods translate over only approximately. For example, it's much
119+
more natural for `Sub()` to return the **number of days** between two dates:
120+
121+
```go
122+
d := date.NewDate(2020, time.February, 29)
123+
d2 := date.NewDate(2021, time.February, 28)
124+
fmt.Println(d2.Sub(d))
125+
// 365
126+
```
127+
128+
## Divergent methods
129+
130+
We've elected to **translate** the `time.Time{}.AddDate()` method rather
131+
than providing it directly:
132+
133+
```go
134+
d := date.NewDate(2020, time.February, 29)
135+
fmt.Println(d.AddDays(1))
136+
// 2020-03-01
137+
fmt.Println(d.AddDays(100))
138+
// 2020-06-08
139+
fmt.Println(d.AddMonths(1))
140+
// 2020-03-29
141+
fmt.Println(d.AddMonths(3))
142+
// 2020-05-29
143+
fmt.Println(d.AddYears(1))
144+
// 2021-02-28
145+
```
146+
147+
This is in part because of the behavior of the standard library's
148+
`AddDate()`. In particular, it "overflows" a target month if the number
149+
of days in that month is less than the number of desired days. As a result,
150+
we provide `*Stdlib()` variants of the date addition helpers:
151+
152+
```go
153+
d := date.NewDate(2020, time.February, 29)
154+
fmt.Println(d.AddMonths(12))
155+
// 2021-02-28
156+
fmt.Println(d.AddMonthsStdlib(12))
157+
// 2021-03-01
158+
fmt.Println(d.AddYears(1))
159+
// 2021-02-28
160+
fmt.Println(d.AddYearsStdlib(1))
161+
// 2021-03-01
162+
```
163+
164+
In the same line of thinking as the divergent `AddMonths()` behavior, a
165+
`MonthEnd()` method is provided that can pinpoint the number of days in
166+
the current month:
167+
168+
```go
169+
d := date.NewDate(2022, time.January, 14)
170+
fmt.Println(d.MonthEnd())
171+
// 2022-01-31
172+
fmt.Println(d.MonthStart())
173+
// 2022-01-01
174+
```
175+
176+
## Integrating with `sqlc`
177+
178+
Out of the box, the `sqlc` [library][10] uses a Go `time.Time{}` both for
179+
columns of type `TIMESTAMPTZ` and `DATE`. When reading `DATE` values (which come
180+
over the wire in the form YYYY-MM-DD), the Go standard library produces values
181+
of the form:
182+
183+
```go
184+
time.Date(YYYY, MM, DD, 0, 0, 0, 0, time.UTC)
185+
```
186+
187+
Instead, we can instruct `sqlc` to **globally** use `date.Date` and
188+
`date.NullDate` when parsing `DATE` columns:
189+
190+
```yaml
191+
---
192+
version: '2'
193+
overrides:
194+
go:
195+
overrides:
196+
- go_type:
197+
import: github.com/hardfinhq/go-date
198+
package: date
199+
type: NullDate
200+
db_type: date
201+
nullable: true
202+
- go_type:
203+
import: github.com/hardfinhq/go-date
204+
package: date
205+
type: Date
206+
db_type: date
207+
nullable: false
208+
```
26209
27210
## Alternatives
28211
@@ -37,6 +220,12 @@ historical date ranges.) Some existing packages:
37220
- `github.com/fxtlabs/date` [package][7]
38221
- `github.com/rickb777/date` [package][5]
39222

223+
Additionally, there is a `Date{}` type provided by the `github.com/jackc/pgtype`
224+
[package][11] that is part of the `pgx` ecosystem. However, this type is very
225+
focused on being useful for database serialization and deserialization and
226+
doesn't implement a wider set of methods present on `time.Time{}` (e.g.
227+
`After()`).
228+
40229
[1]: https://godoc.org/github.com/hardfinhq/go-date?status.svg
41230
[2]: http://godoc.org/github.com/hardfinhq/go-date
42231
[3]: https://goreportcard.com/badge/hardfinhq/go-date
@@ -46,3 +235,5 @@ historical date ranges.) Some existing packages:
46235
[7]: https://pkg.go.dev/github.com/fxtlabs/date
47236
[8]: https://github.com/hardfinhq/go-date/actions/workflows/ci.yaml/badge.svg?branch=main
48237
[9]: https://github.com/hardfinhq/go-date/actions/workflows/ci.yaml
238+
[10]: https://docs.sqlc.dev
239+
[11]: https://pkg.go.dev/github.com/jackc/pgtype

‎convert.go

+43-1
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,55 @@ import (
2222

2323
// ConvertConfig helps customize the behavior of conversion functions like
2424
// `NullTimeFromPtr()`.
25+
//
26+
// It allows setting the fields in a `time.Time{}` **other** than year, month,
27+
// and day (i.e. the fields that aren't present in a date). By default, these
28+
// are:
29+
// - hour=0
30+
// - minute=0
31+
// - second=0
32+
// - nanosecond=0
33+
// - timezone/loc=time.UTC
2534
type ConvertConfig struct {
26-
Timezone *time.Location
35+
Hour int
36+
Minute int
37+
Second int
38+
Nanosecond int
39+
Timezone *time.Location
2740
}
2841

2942
// ConvertOption defines a function that will be applied to a convert config.
3043
type ConvertOption func(*ConvertConfig)
3144

45+
// OptConvertHour returns an option that sets the hour on a convert config.
46+
func OptConvertHour(hour int) ConvertOption {
47+
return func(cc *ConvertConfig) {
48+
cc.Hour = hour
49+
}
50+
}
51+
52+
// OptConvertMinute returns an option that sets the minute on a convert config.
53+
func OptConvertMinute(minute int) ConvertOption {
54+
return func(cc *ConvertConfig) {
55+
cc.Minute = minute
56+
}
57+
}
58+
59+
// OptConvertSecond returns an option that sets the second on a convert config.
60+
func OptConvertSecond(second int) ConvertOption {
61+
return func(cc *ConvertConfig) {
62+
cc.Second = second
63+
}
64+
}
65+
66+
// OptConvertNanosecond returns an option that sets the nanosecond on a convert
67+
// config.
68+
func OptConvertNanosecond(nanosecond int) ConvertOption {
69+
return func(cc *ConvertConfig) {
70+
cc.Nanosecond = nanosecond
71+
}
72+
}
73+
3274
// OptConvertTimezone returns an option that sets the timezone on a convert
3375
// config.
3476
func OptConvertTimezone(tz *time.Location) ConvertOption {

‎convert_test.go

+30-4
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,16 @@ func TestNullTimeFromPtr(t *testing.T) {
5959
nt = date.NullTimeFromPtr(d, date.OptConvertTimezone(tz))
6060
expected = sql.NullTime{Time: time.Date(2000, time.January, 1, 0, 0, 0, 0, tz), Valid: true}
6161
assert.Equal(expected, nt)
62+
63+
nt = date.NullTimeFromPtr(
64+
d,
65+
date.OptConvertHour(12),
66+
date.OptConvertMinute(30),
67+
date.OptConvertSecond(35),
68+
date.OptConvertNanosecond(123456789),
69+
)
70+
expected = sql.NullTime{Time: time.Date(2000, time.January, 1, 12, 30, 35, 123456789, time.UTC), Valid: true}
71+
assert.Equal(expected, nt)
6272
}
6373

6474
func TestFromTime(base *testing.T) {
@@ -71,18 +81,34 @@ func TestFromTime(base *testing.T) {
7181
}
7282

7383
cases := []testCase{
74-
{
75-
Time: "2020-05-11T07:10:55.209309302Z",
76-
Error: "timestamp contains more than just date information; 2020-05-11T07:10:55.209309302Z",
77-
},
7884
{
7985
Time: "2022-01-31T00:00:00.000Z",
8086
Date: date.Date{Year: 2022, Month: time.January, Day: 31},
8187
},
88+
{
89+
Time: "2020-05-11T07:10:55.209309302Z",
90+
Error: "timestamp contains more than just date information; 2020-05-11T07:10:55.209309302Z",
91+
},
8292
{
8393
Time: "2022-01-31T00:00:00.000-05:00",
8494
Error: "timestamp contains more than just date information; 2022-01-31T00:00:00-05:00",
8595
},
96+
{
97+
Time: "2020-05-11T00:00:00.000000001Z",
98+
Error: "timestamp contains more than just date information; 2020-05-11T00:00:00.000000001Z",
99+
},
100+
{
101+
Time: "2020-05-11T00:00:01Z",
102+
Error: "timestamp contains more than just date information; 2020-05-11T00:00:01Z",
103+
},
104+
{
105+
Time: "2020-05-11T00:01:00Z",
106+
Error: "timestamp contains more than just date information; 2020-05-11T00:01:00Z",
107+
},
108+
{
109+
Time: "2020-05-11T01:00:00Z",
110+
Error: "timestamp contains more than just date information; 2020-05-11T01:00:00Z",
111+
},
86112
}
87113

88114
for i := range cases {

0 commit comments

Comments
 (0)